BlueGit

timfa filemanager

Add adaptive subtitle prefetch stepping

Image subtitle prefetching now supports adaptive step sizing and adaptive pacing so the walker uses smaller strides near playback and larger strides when cache lead is high.\n\nApp and share playback are configured to run this adaptive mode (1s near playback up to 5s far ahead) to improve cache fill throughput while reducing backend request pressure. Shared-player tests include regression coverage that verifies stride growth in adaptive mode.

timfa Tim Falken · pushed by timfa

Authored 2026-05-27 · 5 months ago

Hash
c0bdead8c7b5195d9ceb986d4ce9c2d9d935d02f
Parent
8c62bee0
5 files changed +132 −22
.github/technical-reference.md +3 −3
@@ -199,14 +199,14 @@
199 199 - Standalone public share page served at /share/:token; no auth required.
200 200 - Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
201 201 - tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
202 - Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (configured with a 2-second subtitle prefetch stride to reduce walker request volume), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
202 - Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (adaptive subtitle prefetch stride: smaller near playback, larger when cache lead is high), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
203 203 - Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
204 204 - Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
205 205
206 206 ## public/shared-video-player.js
207 207 - applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
208 208 - bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
209 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports configurable prefetch stride (`prefetchStepSeconds`, default 0.5s, capped at 5s) to trade subtitle walker request volume vs sampling density, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
209 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports fixed prefetch stride (`prefetchStepSeconds`) and adaptive stride mode (`prefetchAdaptiveStepEnabled` with `prefetchStepSecondsMin`/`prefetchStepSecondsMax`) plus optional adaptive pacing (`prefetchAdaptivePacingEnabled`) to balance cache fill speed against backend request pressure, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
210 210 - bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle, fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead, and duration metadata hints now extend lookahead prefetch to the known video end even before playback advances.
211 211 - bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
212 212 - bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
@@ -295,7 +295,7 @@
295 295 - buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
296 296 - renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup.
297 297 - bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
298 - renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures image-subtitle walker stride to 2 seconds in app playback.
298 - renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures adaptive image-subtitle walker stepping in app playback (1s near playback, up to 5s when far ahead).
299 299 - modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
300 300 - loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
301 301 - modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
@@ -199,14 +199,14 @@
199- Standalone public share page served at /share/:token; no auth required.
199- Standalone public share page served at /share/:token; no auth required.
200- Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
200- Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
201- tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
201- tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
202- Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (configured with a 2-second subtitle prefetch stride to reduce walker request volume), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
202- Share video preview - Uses the shared browser video-player helper used by app previews: VOD UI enforcement, long forward buffer, forced caption overrides (text background opacity transparent + text edge style uniform), subtitle/audio track restore/save by matching track names, image-subtitle overlay support (adaptive subtitle prefetch stride: smaller near playback, larger when cache lead is high), background stream-ahead prefetch (session playlist/variant/segment fetches continue towards video end while playback reads cache), seek-bar cache frontier marker (`:`) for walker progress, service-worker-backed HLS segment cache enablement during playback (with per-session cache cleanup on close), and explicit backend session release on unload.
203- Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
203- Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
204- Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
204- Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
205
205
206## public/shared-video-player.js
206## public/shared-video-player.js
207- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
207- applyDefaultTextTrackPrefs() - Writes the default Video.js caption override settings (transparent background, uniform edge style) so all streamed players start from the same text-track baseline.
208- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
208- bindTrackPrefs(player, prefs, savePrefs) - Restores subtitle/audio track selections by track name and persists later track changes; shared by the authenticated player and the share page so both resolve track matches the same way.
209- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports configurable prefetch stride (`prefetchStepSeconds`, default 0.5s, capped at 5s) to trade subtitle walker request volume vs sampling density, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
209- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Adds the shared IM button/menu/overlay for bitmap subtitle tracks, restores saved image-subtitle selections, fetches rendered frames through a caller-supplied request builder, keeps a separate rolling lookahead-prefetch worker alive across timeupdates (including gaps where no subtitle is currently visible), supports cache-only foreground playback with `currentFetchEnabled: false` (foreground uses cached frames while walker owns server fetches), supports startup warmup with `initialPrefetchSeconds` (default 60s) so early timeline subtitle frames are requested immediately on player load before playback advances, supports fixed prefetch stride (`prefetchStepSeconds`) and adaptive stride mode (`prefetchAdaptiveStepEnabled` with `prefetchStepSecondsMin`/`prefetchStepSecondsMax`) plus optional adaptive pacing (`prefetchAdaptivePacingEnabled`) to balance cache fill speed against backend request pressure, extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), merges buffered-end signals from both Video.js/player APIs and underlying media buffered ranges so under-reported player values do not cap subtitle prefetch early, keeps the prefetch frontier pinned to at least current playback time so it chases buffered-ahead range instead of replaying stale lag after video/session changes, coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), applies per-request timeouts (`currentRequestTimeoutMs`, `prefetchRequestTimeoutMs`) so hung subtitle frame requests cannot stall updates indefinitely, paces prefetch polling (`prefetchRequestIntervalMs`) to reduce request bursts, logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, caches received subtitle PNG frames client-side for the lifetime of the player session (including prefetched frames) so rewind playback can render from local cache even after server-side purge, ensures force-seek aborts still clear in-flight current-request state so subtitle refreshes continue instead of deadlocking, updates seek-bar bracket markers only after responses resolve (no in-flight jump-back flicker), keeps both marker positions forward-only (never regressing to earlier times), allows the two bracket glyphs to overlap naturally when positions match, advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
210- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle, fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead, and duration metadata hints now extend lookahead prefetch to the known video end even before playback advances.
210- bindImageSubtitleOverlay(player, videojs, prefs, session, opts) - Cache-frame time matching now uses a small epsilon window around start/end timestamps to avoid boundary misses; cache-only mode can also perform a throttled direct current-frame fallback fetch on cache miss (`cacheMissFallbackEnabled`, `cacheMissFallbackIntervalMs`) so subtitles recover without waiting for another seek/timeupdate cycle, fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead, and duration metadata hints now extend lookahead prefetch to the known video end even before playback advances.
211- bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
211- bindStreamAheadPrefetch(opts) - Starts a background HLS walker that repeatedly fetches the session playlist, discovers variant playlists and media segments, and prefetches those assets into the browser cache so playback can read already-fetched segments while the backend prunes old files; tracks cached-through timeline progress (primary from playlist segment durations, with filename-based segment-index fallback for `.ts/.m4s` naming and a section-ratio fallback from fetched segments/total discovered segments when absolute timing metadata is missing) and returns a controller with stop()/done()/getStatus()/subscribe().
212- bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
212- bindStreamAheadSeekMarker(player, streamAheadPrefetch, opts) - Renders a non-interactive `:` marker on the playback seek bar showing how far the stream-ahead walker has cached through the timeline; subscribes to walker progress updates, updates tooltip text with formatted cached-through time, and removes itself on detach.
@@ -295,7 +295,7 @@
295- buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
295- buildAuthHeaders() - Builds the authenticated fetch headers used by preview-side API calls that need the bearer token plus fingerprint header.
296- renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup.
296- renderStreamedVideoPreview(item) - For authenticated video previews, creates a backend stream session and starts the background stream-ahead prefetch worker so playlist/segment requests can continue independently of playback reads until cleanup.
297- bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
297- bindImageSubtitleOverlay(player, videojs, prefs, session, item) - Adds the fullscreen-safe image-subtitle button, menu, and bottom overlay used to fetch and display subtitle frames for image-based tracks; keeps subtitle bitmaps horizontally centred at the bottom, highlights the currently selected IM menu option, persists per-user image subtitle stream index + track name, restores by saved track name first (then stream index), batches subtitle timing diagnostics to `/api/files/video-stream-subtitle-log`, and reads X-Subtitle-Frame-* headers from server responses to properly upscale downscaled frames while maintaining proportions.
298- renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures image-subtitle walker stride to 2 seconds in app playback.
298- renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source/track config, enables service-worker-backed HLS segment caching for the active stream session (and clears that cache on close), enforces non-live playback UI for file streams, uses container-fill sizing to keep previews within bounds, restores per-user video prefs (volume + subtitle/audio track names when present), wires the image-subtitle overlay controller, forces caption overrides on each open (text background opacity transparent + text edge style uniform), reports watch progress, warns when subtitle streams exist but none are web-compatible, releases the backend stream session on close/unload, uses a preview initialisation token guard so stale async player/walker setup from a previously closed preview is discarded immediately, and configures adaptive image-subtitle walker stepping in app playback (1s near playback, up to 5s when far ahead).
299- modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
299- modelPreviewType(name) - Classifies direct client-side 3D preview support for `.stl` and `.obj`.
300- loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
300- loadThreePreviewModules() - Lazy-loads Three.js plus OrbitControls/STLLoader/OBJLoader via import map aliases.
301- modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
301- modelThumbnailDataUrl(item, blob) - Builds a blue SVG thumbnail for STL/OBJ files by parsing their geometry client-side; falls back to a badge when parsing fails.
public/app.js +6 −2
@@ -116,7 +116,8 @@ const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
116 116 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
117 117 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
118 118 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
119 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS = 2;
119 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
120 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
120 121 let videoJsLoaderPromise = null;
121 122 let threePreviewModulesPromise = null;
122 123
@@ -436,7 +437,10 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
436 437 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
437 438 initialPrefetchSeconds: IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS,
438 439 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
439 prefetchStepSeconds: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS,
440 prefetchAdaptiveStepEnabled: true,
441 prefetchAdaptivePacingEnabled: true,
442 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
443 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
440 444 sendSubtitleLogBatch,
441 445 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
442 446 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
@@ -116,7 +116,8 @@ const VIDEO_FORWARD_BUFFER_OVERRIDE_ENABLED = false;
116const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
116const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
117const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
117const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
118const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
118const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
119const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS = 2;
119const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
120const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
120let videoJsLoaderPromise = null;
121let videoJsLoaderPromise = null;
121let threePreviewModulesPromise = null;
122let threePreviewModulesPromise = null;
122
123
@@ -436,7 +437,10 @@ function bindImageSubtitleOverlay (player, videojs, prefs, session, item)
436 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
437 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
437 initialPrefetchSeconds: IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS,
438 initialPrefetchSeconds: IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS,
438 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
439 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
439 prefetchStepSeconds: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS,
440 prefetchAdaptiveStepEnabled: true,
441 prefetchAdaptivePacingEnabled: true,
442 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
443 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
440 sendSubtitleLogBatch,
444 sendSubtitleLogBatch,
441 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
445 buildFrameRequest: ({ currentTime, streamIndex, session: activeSession }) => ({
442 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
446 url: `/api/files/video-stream-subtitle-frame?filePath=${encodeURIComponent(item.path)}&streamIndex=${streamIndex}&timeSeconds=${encodeURIComponent(String(currentTime))}&videoWidth=${encodeURIComponent(String(activeSession.videoWidth || ''))}&videoHeight=${encodeURIComponent(String(activeSession.videoHeight || ''))}`,
public/share.html +6 −2
@@ -252,7 +252,8 @@
252 252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
253 253 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
254 254 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS = 2;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
256 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
256 257 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
257 258 let expiresAt = null;
258 259 let timerInterval = null;
@@ -512,7 +513,10 @@
512 513 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
513 514 initialPrefetchSeconds: IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS,
514 515 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
515 prefetchStepSeconds: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS,
516 prefetchAdaptiveStepEnabled: true,
517 prefetchAdaptivePacingEnabled: true,
518 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
519 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
516 520 sendSubtitleLogBatch: (entries) =>
517 521 {
518 522 if (!Array.isArray(entries) || !entries.length) return Promise.resolve();
@@ -252,7 +252,8 @@
252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
252 const IMAGE_SUBTITLE_LOOKAHEAD_SECONDS = 15;
253 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
253 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS = 60;
254 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
254 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS = 40;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS = 2;
255 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR = 1;
256 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR = 5;
256 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
257 const SHARE_VIDEO_PREFS_KEY = 'filemanager.share-video-prefs.v1';
257 let expiresAt = null;
258 let expiresAt = null;
258 let timerInterval = null;
259 let timerInterval = null;
@@ -512,7 +513,10 @@
512 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
513 lookaheadSeconds: IMAGE_SUBTITLE_LOOKAHEAD_SECONDS,
513 initialPrefetchSeconds: IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS,
514 initialPrefetchSeconds: IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS,
514 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
515 prefetchRequestIntervalMs: IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS,
515 prefetchStepSeconds: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS,
516 prefetchAdaptiveStepEnabled: true,
517 prefetchAdaptivePacingEnabled: true,
518 prefetchStepSecondsMin: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_NEAR,
519 prefetchStepSecondsMax: IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_FAR,
516 sendSubtitleLogBatch: (entries) =>
520 sendSubtitleLogBatch: (entries) =>
517 {
521 {
518 if (!Array.isArray(entries) || !entries.length) return Promise.resolve();
522 if (!Array.isArray(entries) || !entries.length) return Promise.resolve();
public/shared-video-player.js +71 −15
@@ -14,6 +14,7 @@
14 14 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_DEFAULT = 60;
15 15 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_MAX = 120;
16 16 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
17 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN = 0.25;
17 18 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 5;
18 19 const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.05;
19 20 const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
@@ -307,9 +308,20 @@
307 308 ? Math.max(0, requestedPrefetchRequestIntervalMs)
308 309 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
309 310 const requestedPrefetchStepSeconds = Number(opts.prefetchStepSeconds);
310 const prefetchStepSeconds = Number.isFinite(requestedPrefetchStepSeconds)
311 ? Math.max(0.25, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
312 : IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT;
311 const prefetchStepSecondsFixed = Number.isFinite(requestedPrefetchStepSeconds)
312 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
313 : null;
314 const prefetchAdaptiveStepEnabled = opts.prefetchAdaptiveStepEnabled === true;
315 const prefetchAdaptivePacingEnabled = opts.prefetchAdaptivePacingEnabled === true;
316 const requestedPrefetchStepSecondsMin = Number(opts.prefetchStepSecondsMin);
317 const requestedPrefetchStepSecondsMax = Number(opts.prefetchStepSecondsMax);
318 const prefetchStepSecondsMin = Number.isFinite(requestedPrefetchStepSecondsMin)
319 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSecondsMin))
320 : (prefetchStepSecondsFixed || IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT);
321 const prefetchStepSecondsMaxRaw = Number.isFinite(requestedPrefetchStepSecondsMax)
322 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSecondsMax))
323 : (prefetchStepSecondsFixed || prefetchStepSecondsMin);
324 const prefetchStepSecondsMax = Math.max(prefetchStepSecondsMin, prefetchStepSecondsMaxRaw);
313 325 const requestedCacheMissFallbackIntervalMs = Number(opts.cacheMissFallbackIntervalMs);
314 326 const cacheMissFallbackIntervalMs = Number.isFinite(requestedCacheMissFallbackIntervalMs)
315 327 ? Math.max(500, requestedCacheMissFallbackIntervalMs)
@@ -506,7 +518,7 @@
506 518 cachedSubtitleFrames.clear();
507 519 };
508 520
509 const parseFrameMetadata = (res, fallbackStartTimeSeconds) =>
521 const parseFrameMetadata = (res, fallbackStartTimeSeconds, fallbackSpanSeconds = prefetchStepSecondsMin) =>
510 522 {
511 523 const rawStart = parseHeaderFloat(res, 'X-Subtitle-Frame-Start-Time');
512 524 const startTimeSeconds = Number.isFinite(rawStart) && rawStart >= 0
@@ -516,7 +528,7 @@
516 528 const rawEnd = parseHeaderFloat(res, 'X-Subtitle-Frame-End-Time');
517 529 const endTimeSeconds = Number.isFinite(rawEnd)
518 530 ? rawEnd
519 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + prefetchStepSeconds : null);
531 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + fallbackSpanSeconds : null);
520 532
521 533 const frameWidth = Number.parseInt(String(res.headers.get('X-Subtitle-Frame-Width') || ''), 10);
522 534 const frameHeight = Number.parseInt(String(res.headers.get('X-Subtitle-Frame-Height') || ''), 10);
@@ -548,7 +560,7 @@
548 560 const startTimeSeconds = Number.isFinite(metadata && metadata.startTimeSeconds) ? metadata.startTimeSeconds : null;
549 561 const endTimeSeconds = Number.isFinite(metadata && metadata.endTimeSeconds)
550 562 ? metadata.endTimeSeconds
551 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + prefetchStepSeconds : null);
563 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + prefetchStepSecondsMin : null);
552 564 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
553 565 {
554 566 return null;
@@ -601,6 +613,46 @@
601 613 return best;
602 614 };
603 615
616 const getAdaptivePrefetchStepSeconds = (currentTimeSeconds) =>
617 {
618 if (!prefetchAdaptiveStepEnabled || prefetchStepSecondsMax <= prefetchStepSecondsMin)
619 {
620 return prefetchStepSecondsMax;
621 }
622
623 const nowSeconds = Number(currentTimeSeconds);
624 const leadSeconds = Number.isFinite(prefetchedThroughTimeSeconds) && Number.isFinite(nowSeconds)
625 ? Math.max(0, prefetchedThroughTimeSeconds - nowSeconds)
626 : 0;
627 const targetLeadSeconds = Math.max(2, lookaheadSeconds * 0.75);
628 const highLeadSeconds = Math.max(targetLeadSeconds + prefetchStepSecondsMax, lookaheadSeconds * 2);
629 const ratio = highLeadSeconds > targetLeadSeconds
630 ? Math.max(0, Math.min(1, (leadSeconds - targetLeadSeconds) / (highLeadSeconds - targetLeadSeconds)))
631 : 1;
632 const rawStep = prefetchStepSecondsMin + ((prefetchStepSecondsMax - prefetchStepSecondsMin) * ratio);
633
634 // Keep walker increments predictable while still allowing adaptation.
635 return Math.max(
636 prefetchStepSecondsMin,
637 Math.min(prefetchStepSecondsMax, Math.round(rawStep * 4) / 4),
638 );
639 };
640
641 const getPrefetchDelayMs = (currentTimeSeconds) =>
642 {
643 if (!prefetchAdaptivePacingEnabled) return prefetchRequestIntervalMs;
644
645 const nowSeconds = Number(currentTimeSeconds);
646 const leadSeconds = Number.isFinite(prefetchedThroughTimeSeconds) && Number.isFinite(nowSeconds)
647 ? Math.max(0, prefetchedThroughTimeSeconds - nowSeconds)
648 : 0;
649 const softLeadSeconds = Math.max(lookaheadSeconds, prefetchStepSecondsMax * 2);
650 if (leadSeconds <= softLeadSeconds) return prefetchRequestIntervalMs;
651
652 const excessRatio = Math.max(0, Math.min(1, (leadSeconds - softLeadSeconds) / Math.max(softLeadSeconds, 1)));
653 return Math.round(prefetchRequestIntervalMs + (excessRatio * 250));
654 };
655
604 656 const renderSubtitleFrame = (frame) =>
605 657 {
606 658 if (!overlayEl || !overlayImgEl || !frame || !frame.objectUrl) return;
@@ -907,7 +959,7 @@
907 959
908 960 const startTime = includeCurrentTime
909 961 ? currentTime
910 : currentTime + prefetchStepSeconds;
962 : currentTime + prefetchStepSecondsMin;
911 963 const uncappedEndTime = Math.max(
912 964 currentTime + lookaheadSeconds,
913 965 Number.isFinite(bufferedVideoEndSeconds) ? bufferedVideoEndSeconds : -1,
@@ -925,7 +977,7 @@
925 977 {
926 978 cancelPrefetchRequests({ resetProgress: true });
927 979 prefetchedThroughTimeSeconds = includeCurrentTime
928 ? currentTime - prefetchStepSeconds
980 ? currentTime - prefetchStepSecondsMin
929 981 : currentTime;
930 982 } else if (prefetchedThroughTimeSeconds < currentTime)
931 983 {
@@ -949,9 +1001,11 @@
949 1001 if (selectedStreamIndex === null || trackDisabled) return;
950 1002 if (workerToken !== prefetchWorkerToken || workerLifecycleToken !== lifecycleToken) return;
951 1003
1004 const stepSeconds = getAdaptivePrefetchStepSeconds(Number(player.currentTime()));
1005
952 1006 const nextTime = prefetchedThroughTimeSeconds < 0
953 1007 ? startTime
954 : prefetchedThroughTimeSeconds + prefetchStepSeconds;
1008 : prefetchedThroughTimeSeconds + stepSeconds;
955 1009 if (!Number.isFinite(nextTime) || nextTime > prefetchTargetTimeSeconds + 1e-6) return;
956 1010
957 1011 const request = buildFrameRequest({
@@ -1022,9 +1076,10 @@
1022 1076 });
1023 1077 if (frameStatus === 'error') return;
1024 1078 prefetchedThroughTimeSeconds = nextTime;
1025 if (prefetchRequestIntervalMs > 0)
1079 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1080 if (waitMs > 0)
1026 1081 {
1027 await new Promise((resolve) => window.setTimeout(resolve, prefetchRequestIntervalMs));
1082 await new Promise((resolve) => window.setTimeout(resolve, waitMs));
1028 1083 }
1029 1084 continue;
1030 1085 }
@@ -1032,7 +1087,7 @@
1032 1087 if (!res.ok) return;
1033 1088 const payload = await res.arrayBuffer();
1034 1089 const receivedAtMs = Date.now();
1035 const metadata = parseFrameMetadata(res, nextTime);
1090 const metadata = parseFrameMetadata(res, nextTime, stepSeconds);
1036 1091 const blob = new Blob([payload], {
1037 1092 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1038 1093 });
@@ -1067,9 +1122,10 @@
1067 1122 blobBytes: Number(payload && payload.byteLength || 0),
1068 1123 });
1069 1124 prefetchedThroughTimeSeconds = nextTime;
1070 if (prefetchRequestIntervalMs > 0)
1125 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1126 if (waitMs > 0)
1071 1127 {
1072 await new Promise((resolve) => window.setTimeout(resolve, prefetchRequestIntervalMs));
1128 await new Promise((resolve) => window.setTimeout(resolve, waitMs));
1073 1129 }
1074 1130 } catch (error)
1075 1131 {
@@ -1281,7 +1337,7 @@
1281 1337 const cachedFrameEntry = cacheSubtitleFrame({
1282 1338 streamIndex: selectedStreamIndex,
1283 1339 blob,
1284 metadata: parseFrameMetadata(res, currentTime),
1340 metadata: parseFrameMetadata(res, currentTime, prefetchStepSecondsMin),
1285 1341 });
1286 1342 if (cachedFrameEntry) renderSubtitleFrame(cachedFrameEntry);
1287 1343
@@ -14,6 +14,7 @@
14 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_DEFAULT = 60;
14 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_DEFAULT = 60;
15 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_MAX = 120;
15 const IMAGE_SUBTITLE_INITIAL_PREFETCH_SECONDS_MAX = 120;
16 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
16 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
17 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN = 0.25;
17 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 5;
18 const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 5;
18 const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.05;
19 const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.05;
19 const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
20 const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
@@ -307,9 +308,20 @@
307 ? Math.max(0, requestedPrefetchRequestIntervalMs)
308 ? Math.max(0, requestedPrefetchRequestIntervalMs)
308 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
309 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
309 const requestedPrefetchStepSeconds = Number(opts.prefetchStepSeconds);
310 const requestedPrefetchStepSeconds = Number(opts.prefetchStepSeconds);
310 const prefetchStepSeconds = Number.isFinite(requestedPrefetchStepSeconds)
311 const prefetchStepSecondsFixed = Number.isFinite(requestedPrefetchStepSeconds)
311 ? Math.max(0.25, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
312 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
312 : IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT;
313 : null;
314 const prefetchAdaptiveStepEnabled = opts.prefetchAdaptiveStepEnabled === true;
315 const prefetchAdaptivePacingEnabled = opts.prefetchAdaptivePacingEnabled === true;
316 const requestedPrefetchStepSecondsMin = Number(opts.prefetchStepSecondsMin);
317 const requestedPrefetchStepSecondsMax = Number(opts.prefetchStepSecondsMax);
318 const prefetchStepSecondsMin = Number.isFinite(requestedPrefetchStepSecondsMin)
319 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSecondsMin))
320 : (prefetchStepSecondsFixed || IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT);
321 const prefetchStepSecondsMaxRaw = Number.isFinite(requestedPrefetchStepSecondsMax)
322 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSecondsMax))
323 : (prefetchStepSecondsFixed || prefetchStepSecondsMin);
324 const prefetchStepSecondsMax = Math.max(prefetchStepSecondsMin, prefetchStepSecondsMaxRaw);
313 const requestedCacheMissFallbackIntervalMs = Number(opts.cacheMissFallbackIntervalMs);
325 const requestedCacheMissFallbackIntervalMs = Number(opts.cacheMissFallbackIntervalMs);
314 const cacheMissFallbackIntervalMs = Number.isFinite(requestedCacheMissFallbackIntervalMs)
326 const cacheMissFallbackIntervalMs = Number.isFinite(requestedCacheMissFallbackIntervalMs)
315 ? Math.max(500, requestedCacheMissFallbackIntervalMs)
327 ? Math.max(500, requestedCacheMissFallbackIntervalMs)
@@ -506,7 +518,7 @@
506 cachedSubtitleFrames.clear();
518 cachedSubtitleFrames.clear();
507 };
519 };
508
520
509 const parseFrameMetadata = (res, fallbackStartTimeSeconds) =>
521 const parseFrameMetadata = (res, fallbackStartTimeSeconds, fallbackSpanSeconds = prefetchStepSecondsMin) =>
510 {
522 {
511 const rawStart = parseHeaderFloat(res, 'X-Subtitle-Frame-Start-Time');
523 const rawStart = parseHeaderFloat(res, 'X-Subtitle-Frame-Start-Time');
512 const startTimeSeconds = Number.isFinite(rawStart) && rawStart >= 0
524 const startTimeSeconds = Number.isFinite(rawStart) && rawStart >= 0
@@ -516,7 +528,7 @@
516 const rawEnd = parseHeaderFloat(res, 'X-Subtitle-Frame-End-Time');
528 const rawEnd = parseHeaderFloat(res, 'X-Subtitle-Frame-End-Time');
517 const endTimeSeconds = Number.isFinite(rawEnd)
529 const endTimeSeconds = Number.isFinite(rawEnd)
518 ? rawEnd
530 ? rawEnd
519 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + prefetchStepSeconds : null);
531 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + fallbackSpanSeconds : null);
520
532
521 const frameWidth = Number.parseInt(String(res.headers.get('X-Subtitle-Frame-Width') || ''), 10);
533 const frameWidth = Number.parseInt(String(res.headers.get('X-Subtitle-Frame-Width') || ''), 10);
522 const frameHeight = Number.parseInt(String(res.headers.get('X-Subtitle-Frame-Height') || ''), 10);
534 const frameHeight = Number.parseInt(String(res.headers.get('X-Subtitle-Frame-Height') || ''), 10);
@@ -548,7 +560,7 @@
548 const startTimeSeconds = Number.isFinite(metadata && metadata.startTimeSeconds) ? metadata.startTimeSeconds : null;
560 const startTimeSeconds = Number.isFinite(metadata && metadata.startTimeSeconds) ? metadata.startTimeSeconds : null;
549 const endTimeSeconds = Number.isFinite(metadata && metadata.endTimeSeconds)
561 const endTimeSeconds = Number.isFinite(metadata && metadata.endTimeSeconds)
550 ? metadata.endTimeSeconds
562 ? metadata.endTimeSeconds
551 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + prefetchStepSeconds : null);
563 : (Number.isFinite(startTimeSeconds) ? startTimeSeconds + prefetchStepSecondsMin : null);
552 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
564 if (!Number.isFinite(startTimeSeconds) || !Number.isFinite(endTimeSeconds) || endTimeSeconds <= startTimeSeconds)
553 {
565 {
554 return null;
566 return null;
@@ -601,6 +613,46 @@
601 return best;
613 return best;
602 };
614 };
603
615
616 const getAdaptivePrefetchStepSeconds = (currentTimeSeconds) =>
617 {
618 if (!prefetchAdaptiveStepEnabled || prefetchStepSecondsMax <= prefetchStepSecondsMin)
619 {
620 return prefetchStepSecondsMax;
621 }
622
623 const nowSeconds = Number(currentTimeSeconds);
624 const leadSeconds = Number.isFinite(prefetchedThroughTimeSeconds) && Number.isFinite(nowSeconds)
625 ? Math.max(0, prefetchedThroughTimeSeconds - nowSeconds)
626 : 0;
627 const targetLeadSeconds = Math.max(2, lookaheadSeconds * 0.75);
628 const highLeadSeconds = Math.max(targetLeadSeconds + prefetchStepSecondsMax, lookaheadSeconds * 2);
629 const ratio = highLeadSeconds > targetLeadSeconds
630 ? Math.max(0, Math.min(1, (leadSeconds - targetLeadSeconds) / (highLeadSeconds - targetLeadSeconds)))
631 : 1;
632 const rawStep = prefetchStepSecondsMin + ((prefetchStepSecondsMax - prefetchStepSecondsMin) * ratio);
633
634 // Keep walker increments predictable while still allowing adaptation.
635 return Math.max(
636 prefetchStepSecondsMin,
637 Math.min(prefetchStepSecondsMax, Math.round(rawStep * 4) / 4),
638 );
639 };
640
641 const getPrefetchDelayMs = (currentTimeSeconds) =>
642 {
643 if (!prefetchAdaptivePacingEnabled) return prefetchRequestIntervalMs;
644
645 const nowSeconds = Number(currentTimeSeconds);
646 const leadSeconds = Number.isFinite(prefetchedThroughTimeSeconds) && Number.isFinite(nowSeconds)
647 ? Math.max(0, prefetchedThroughTimeSeconds - nowSeconds)
648 : 0;
649 const softLeadSeconds = Math.max(lookaheadSeconds, prefetchStepSecondsMax * 2);
650 if (leadSeconds <= softLeadSeconds) return prefetchRequestIntervalMs;
651
652 const excessRatio = Math.max(0, Math.min(1, (leadSeconds - softLeadSeconds) / Math.max(softLeadSeconds, 1)));
653 return Math.round(prefetchRequestIntervalMs + (excessRatio * 250));
654 };
655
604 const renderSubtitleFrame = (frame) =>
656 const renderSubtitleFrame = (frame) =>
605 {
657 {
606 if (!overlayEl || !overlayImgEl || !frame || !frame.objectUrl) return;
658 if (!overlayEl || !overlayImgEl || !frame || !frame.objectUrl) return;
@@ -907,7 +959,7 @@
907
959
908 const startTime = includeCurrentTime
960 const startTime = includeCurrentTime
909 ? currentTime
961 ? currentTime
910 : currentTime + prefetchStepSeconds;
962 : currentTime + prefetchStepSecondsMin;
911 const uncappedEndTime = Math.max(
963 const uncappedEndTime = Math.max(
912 currentTime + lookaheadSeconds,
964 currentTime + lookaheadSeconds,
913 Number.isFinite(bufferedVideoEndSeconds) ? bufferedVideoEndSeconds : -1,
965 Number.isFinite(bufferedVideoEndSeconds) ? bufferedVideoEndSeconds : -1,
@@ -925,7 +977,7 @@
925 {
977 {
926 cancelPrefetchRequests({ resetProgress: true });
978 cancelPrefetchRequests({ resetProgress: true });
927 prefetchedThroughTimeSeconds = includeCurrentTime
979 prefetchedThroughTimeSeconds = includeCurrentTime
928 ? currentTime - prefetchStepSeconds
980 ? currentTime - prefetchStepSecondsMin
929 : currentTime;
981 : currentTime;
930 } else if (prefetchedThroughTimeSeconds < currentTime)
982 } else if (prefetchedThroughTimeSeconds < currentTime)
931 {
983 {
@@ -949,9 +1001,11 @@
949 if (selectedStreamIndex === null || trackDisabled) return;
1001 if (selectedStreamIndex === null || trackDisabled) return;
950 if (workerToken !== prefetchWorkerToken || workerLifecycleToken !== lifecycleToken) return;
1002 if (workerToken !== prefetchWorkerToken || workerLifecycleToken !== lifecycleToken) return;
951
1003
1004 const stepSeconds = getAdaptivePrefetchStepSeconds(Number(player.currentTime()));
1005
952 const nextTime = prefetchedThroughTimeSeconds < 0
1006 const nextTime = prefetchedThroughTimeSeconds < 0
953 ? startTime
1007 ? startTime
954 : prefetchedThroughTimeSeconds + prefetchStepSeconds;
1008 : prefetchedThroughTimeSeconds + stepSeconds;
955 if (!Number.isFinite(nextTime) || nextTime > prefetchTargetTimeSeconds + 1e-6) return;
1009 if (!Number.isFinite(nextTime) || nextTime > prefetchTargetTimeSeconds + 1e-6) return;
956
1010
957 const request = buildFrameRequest({
1011 const request = buildFrameRequest({
@@ -1022,9 +1076,10 @@
1022 });
1076 });
1023 if (frameStatus === 'error') return;
1077 if (frameStatus === 'error') return;
1024 prefetchedThroughTimeSeconds = nextTime;
1078 prefetchedThroughTimeSeconds = nextTime;
1025 if (prefetchRequestIntervalMs > 0)
1079 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1080 if (waitMs > 0)
1026 {
1081 {
1027 await new Promise((resolve) => window.setTimeout(resolve, prefetchRequestIntervalMs));
1082 await new Promise((resolve) => window.setTimeout(resolve, waitMs));
1028 }
1083 }
1029 continue;
1084 continue;
1030 }
1085 }
@@ -1032,7 +1087,7 @@
1032 if (!res.ok) return;
1087 if (!res.ok) return;
1033 const payload = await res.arrayBuffer();
1088 const payload = await res.arrayBuffer();
1034 const receivedAtMs = Date.now();
1089 const receivedAtMs = Date.now();
1035 const metadata = parseFrameMetadata(res, nextTime);
1090 const metadata = parseFrameMetadata(res, nextTime, stepSeconds);
1036 const blob = new Blob([payload], {
1091 const blob = new Blob([payload], {
1037 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1092 type: String(res.headers.get('Content-Type') || '').trim() || 'image/png',
1038 });
1093 });
@@ -1067,9 +1122,10 @@
1067 blobBytes: Number(payload && payload.byteLength || 0),
1122 blobBytes: Number(payload && payload.byteLength || 0),
1068 });
1123 });
1069 prefetchedThroughTimeSeconds = nextTime;
1124 prefetchedThroughTimeSeconds = nextTime;
1070 if (prefetchRequestIntervalMs > 0)
1125 const waitMs = getPrefetchDelayMs(Number(player.currentTime()));
1126 if (waitMs > 0)
1071 {
1127 {
1072 await new Promise((resolve) => window.setTimeout(resolve, prefetchRequestIntervalMs));
1128 await new Promise((resolve) => window.setTimeout(resolve, waitMs));
1073 }
1129 }
1074 } catch (error)
1130 } catch (error)
1075 {
1131 {
@@ -1281,7 +1337,7 @@
1281 const cachedFrameEntry = cacheSubtitleFrame({
1337 const cachedFrameEntry = cacheSubtitleFrame({
1282 streamIndex: selectedStreamIndex,
1338 streamIndex: selectedStreamIndex,
1283 blob,
1339 blob,
1284 metadata: parseFrameMetadata(res, currentTime),
1340 metadata: parseFrameMetadata(res, currentTime, prefetchStepSecondsMin),
1285 });
1341 });
1286 if (cachedFrameEntry) renderSubtitleFrame(cachedFrameEntry);
1342 if (cachedFrameEntry) renderSubtitleFrame(cachedFrameEntry);
1287
1343
tests/shared-video-player.test.js +46 −0
@@ -341,6 +341,52 @@ describe('shared image subtitle prefetching', () =>
341 341 window.close();
342 342 });
343 343
344 test('adaptive prefetch step increases stride when cache lead grows', async () =>
345 {
346 const window = createWindow();
347 const helper = loadSharedVideoPlayer(window);
348 const { player, videojs } = buildPlayerHarness(window);
349 const requestedTimes = [];
350
351 player.duration(40);
352
353 window.fetch = jest.fn(async (url) =>
354 {
355 const parsed = new URL(url, 'http://localhost/');
356 requestedTimes.push(Number(parsed.searchParams.get('timeSeconds')));
357 return new Response(null, {
358 status: 204,
359 headers: { 'X-Subtitle-Frame-Status': 'none' },
360 });
361 });
362
363 helper.bindImageSubtitleOverlay(player, videojs, {}, {
364 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
365 }, {
366 lookaheadSeconds: 20,
367 initialPrefetchSeconds: 0,
368 prefetchAdaptiveStepEnabled: true,
369 prefetchStepSecondsMin: 1,
370 prefetchStepSecondsMax: 5,
371 buildFrameRequest: ({ currentTime, streamIndex }) => ({
372 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
373 }),
374 });
375
376 await flushAsyncWork(window, 20);
377
378 const strideSamples = [];
379 for (let i = 1; i < requestedTimes.length; i++)
380 {
381 const stride = requestedTimes[i] - requestedTimes[i - 1];
382 if (Number.isFinite(stride) && stride > 0) strideSamples.push(Number(stride.toFixed(3)));
383 }
384
385 expect(strideSamples.some((stride) => stride > 1.25)).toBe(true);
386
387 window.close();
388 });
389
344 390 test('prefetch uses furthest buffered end when player.bufferedEnd under-reports', async () =>
345 391 {
346 392 const window = createWindow();
@@ -341,6 +341,52 @@ describe('shared image subtitle prefetching', () =>
341 window.close();
341 window.close();
342 });
342 });
343
343
344 test('adaptive prefetch step increases stride when cache lead grows', async () =>
345 {
346 const window = createWindow();
347 const helper = loadSharedVideoPlayer(window);
348 const { player, videojs } = buildPlayerHarness(window);
349 const requestedTimes = [];
350
351 player.duration(40);
352
353 window.fetch = jest.fn(async (url) =>
354 {
355 const parsed = new URL(url, 'http://localhost/');
356 requestedTimes.push(Number(parsed.searchParams.get('timeSeconds')));
357 return new Response(null, {
358 status: 204,
359 headers: { 'X-Subtitle-Frame-Status': 'none' },
360 });
361 });
362
363 helper.bindImageSubtitleOverlay(player, videojs, {}, {
364 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
365 }, {
366 lookaheadSeconds: 20,
367 initialPrefetchSeconds: 0,
368 prefetchAdaptiveStepEnabled: true,
369 prefetchStepSecondsMin: 1,
370 prefetchStepSecondsMax: 5,
371 buildFrameRequest: ({ currentTime, streamIndex }) => ({
372 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
373 }),
374 });
375
376 await flushAsyncWork(window, 20);
377
378 const strideSamples = [];
379 for (let i = 1; i < requestedTimes.length; i++)
380 {
381 const stride = requestedTimes[i] - requestedTimes[i - 1];
382 if (Number.isFinite(stride) && stride > 0) strideSamples.push(Number(stride.toFixed(3)));
383 }
384
385 expect(strideSamples.some((stride) => stride > 1.25)).toBe(true);
386
387 window.close();
388 });
389
344 test('prefetch uses furthest buffered end when player.bufferedEnd under-reports', async () =>
390 test('prefetch uses furthest buffered end when player.bufferedEnd under-reports', async () =>
345 {
391 {
346 const window = createWindow();
392 const window = createWindow();