BlueGit

timfa filemanager

Merge fix/subtitle-fallback-prefetch-reset

timfa Tim Falken · pushed by timfa

Authored 2026-05-27 · 5 months ago

Hash
1f2d698252ff7f303f993d7af4d52fce4ed752d7
3 files changed +81 −8
.github/technical-reference.md +1 −1
@@ -207,7 +207,7 @@
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 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, 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.
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, and fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead.
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.
213 213 - enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning.
@@ -207,7 +207,7 @@
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, 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, 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.
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, and fallback fetches preserve prefetch progress so repeated cache misses do not keep resetting subtitle lookahead.
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.
213- enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning.
213- enableVideoStreamClientCache() - Registers a shared service worker (`/stream-cache-sw.js`) that caches HLS playlist/segment responses so already-downloaded stream assets remain playable on rewind after server-side segment pruning.
public/shared-video-player.js +8 −7
@@ -1099,7 +1099,7 @@
1099 1099 });
1100 1100 };
1101 1101
1102 const refreshFrame = async (force = false) =>
1102 const refreshFrame = async (force = false, allowCurrentFetchOverride = false, preservePrefetchState = false) =>
1103 1103 {
1104 1104 if (selectedStreamIndex === null) return;
1105 1105 if (!overlayEl || !overlayImgEl) return;
@@ -1129,7 +1129,7 @@
1129 1129 return;
1130 1130 }
1131 1131
1132 if (!currentFetchEnabled)
1132 if (!currentFetchEnabled && !allowCurrentFetchOverride)
1133 1133 {
1134 1134 hideOverlay();
1135 1135 const nowMs = Date.now();
@@ -1144,8 +1144,9 @@
1144 1144 requestedVideoTimeSeconds: roundLogNumber(currentTime),
1145 1145 });
1146 1146 // Safety net for occasional cache key/window mismatches.
1147 // Uses normal current-frame path but throttled to avoid request spam.
1148 return refreshFrame(true);
1147 // Uses normal current-frame path but does not reset prefetch state,
1148 // so background subtitle lead can continue growing while playing.
1149 return refreshFrame(true, true, true);
1149 1150 }
1150 1151 queueLookaheadPrefetch(currentTime, {
1151 1152 reset: force,
@@ -1166,7 +1167,7 @@
1166 1167 return;
1167 1168 }
1168 1169 cancelCurrentFrameRequest();
1169 if (force) cancelPrefetchRequests({ resetProgress: true });
1170 if (force && !preservePrefetchState) cancelPrefetchRequests({ resetProgress: true });
1170 1171
1171 1172 const token = ++currentFrameToken;
1172 1173 const requestId = `current-${token}`;
@@ -1245,7 +1246,7 @@
1245 1246 });
1246 1247 hideOverlay();
1247 1248 if (frameStatus === 'error') disableTrack();
1248 else queueLookaheadPrefetch(currentTime, { reset: force });
1249 else queueLookaheadPrefetch(currentTime, { reset: force && !preservePrefetchState });
1249 1250 return;
1250 1251 }
1251 1252
@@ -1294,7 +1295,7 @@
1294 1295 });
1295 1296 });
1296 1297
1297 queueLookaheadPrefetch(currentTime, { reset: force });
1298 queueLookaheadPrefetch(currentTime, { reset: force && !preservePrefetchState });
1298 1299 } catch (error)
1299 1300 {
1300 1301 clearRequestTimeout(timeoutId);
@@ -1099,7 +1099,7 @@
1099 });
1099 });
1100 };
1100 };
1101
1101
1102 const refreshFrame = async (force = false) =>
1102 const refreshFrame = async (force = false, allowCurrentFetchOverride = false, preservePrefetchState = false) =>
1103 {
1103 {
1104 if (selectedStreamIndex === null) return;
1104 if (selectedStreamIndex === null) return;
1105 if (!overlayEl || !overlayImgEl) return;
1105 if (!overlayEl || !overlayImgEl) return;
@@ -1129,7 +1129,7 @@
1129 return;
1129 return;
1130 }
1130 }
1131
1131
1132 if (!currentFetchEnabled)
1132 if (!currentFetchEnabled && !allowCurrentFetchOverride)
1133 {
1133 {
1134 hideOverlay();
1134 hideOverlay();
1135 const nowMs = Date.now();
1135 const nowMs = Date.now();
@@ -1144,8 +1144,9 @@
1144 requestedVideoTimeSeconds: roundLogNumber(currentTime),
1144 requestedVideoTimeSeconds: roundLogNumber(currentTime),
1145 });
1145 });
1146 // Safety net for occasional cache key/window mismatches.
1146 // Safety net for occasional cache key/window mismatches.
1147 // Uses normal current-frame path but throttled to avoid request spam.
1147 // Uses normal current-frame path but does not reset prefetch state,
1148 return refreshFrame(true);
1148 // so background subtitle lead can continue growing while playing.
1149 return refreshFrame(true, true, true);
1149 }
1150 }
1150 queueLookaheadPrefetch(currentTime, {
1151 queueLookaheadPrefetch(currentTime, {
1151 reset: force,
1152 reset: force,
@@ -1166,7 +1167,7 @@
1166 return;
1167 return;
1167 }
1168 }
1168 cancelCurrentFrameRequest();
1169 cancelCurrentFrameRequest();
1169 if (force) cancelPrefetchRequests({ resetProgress: true });
1170 if (force && !preservePrefetchState) cancelPrefetchRequests({ resetProgress: true });
1170
1171
1171 const token = ++currentFrameToken;
1172 const token = ++currentFrameToken;
1172 const requestId = `current-${token}`;
1173 const requestId = `current-${token}`;
@@ -1245,7 +1246,7 @@
1245 });
1246 });
1246 hideOverlay();
1247 hideOverlay();
1247 if (frameStatus === 'error') disableTrack();
1248 if (frameStatus === 'error') disableTrack();
1248 else queueLookaheadPrefetch(currentTime, { reset: force });
1249 else queueLookaheadPrefetch(currentTime, { reset: force && !preservePrefetchState });
1249 return;
1250 return;
1250 }
1251 }
1251
1252
@@ -1294,7 +1295,7 @@
1294 });
1295 });
1295 });
1296 });
1296
1297
1297 queueLookaheadPrefetch(currentTime, { reset: force });
1298 queueLookaheadPrefetch(currentTime, { reset: force && !preservePrefetchState });
1298 } catch (error)
1299 } catch (error)
1299 {
1300 {
1300 clearRequestTimeout(timeoutId);
1301 clearRequestTimeout(timeoutId);
tests/shared-video-player.test.js +72 −0
@@ -739,6 +739,78 @@ describe('shared image subtitle prefetching', () =>
739 739 window.close();
740 740 });
741 741
742 test('cache-miss fallback does not reset prefetch progress on repeated triggers', async () =>
743 {
744 const window = createWindow();
745 const helper = loadSharedVideoPlayer(window);
746 const { player, videojs } = buildPlayerHarness(window);
747
748 let nowMs = 1000;
749 const realNow = window.Date.now;
750 window.Date.now = () => nowMs;
751
752 let abortedCount = 0;
753 window.fetch = jest.fn((url, init = {}) =>
754 {
755 return new Promise((resolve, reject) =>
756 {
757 const signal = init && init.signal;
758 const onAbort = () =>
759 {
760 abortedCount += 1;
761 const err = new Error('aborted');
762 err.name = 'AbortError';
763 reject(err);
764 };
765
766 if (signal && typeof signal.addEventListener === 'function')
767 {
768 if (signal.aborted) return onAbort();
769 signal.addEventListener('abort', onAbort, { once: true });
770 }
771
772 window.setTimeout(() =>
773 {
774 if (signal && signal.aborted) return;
775 resolve(new Response(null, {
776 status: 204,
777 headers: { 'X-Subtitle-Frame-Status': 'none' },
778 }));
779 }, 80);
780 });
781 });
782
783 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
784 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
785 }, {
786 currentFetchEnabled: false,
787 cacheMissFallbackIntervalMs: 20,
788 lookaheadSeconds: 2,
789 initialPrefetchSeconds: 0,
790 buildFrameRequest: ({ currentTime, streamIndex }) => ({
791 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
792 }),
793 });
794
795 await flushAsyncWork(window, 4);
796
797 player.setCurrentTime(5);
798 player.trigger('timeupdate');
799 nowMs += 40;
800 player.setCurrentTime(5.5);
801 player.trigger('timeupdate');
802 nowMs += 40;
803 player.setCurrentTime(6);
804 player.trigger('timeupdate');
805
806 await flushAsyncWork(window, 12);
807 expect(abortedCount).toBe(0);
808
809 window.Date.now = realNow;
810 controller.detach();
811 window.close();
812 });
813
742 814 test('cache-only mode performs initial warmup prefetch window on load', async () =>
743 815 {
744 816 const window = createWindow();
@@ -739,6 +739,78 @@ describe('shared image subtitle prefetching', () =>
739 window.close();
739 window.close();
740 });
740 });
741
741
742 test('cache-miss fallback does not reset prefetch progress on repeated triggers', async () =>
743 {
744 const window = createWindow();
745 const helper = loadSharedVideoPlayer(window);
746 const { player, videojs } = buildPlayerHarness(window);
747
748 let nowMs = 1000;
749 const realNow = window.Date.now;
750 window.Date.now = () => nowMs;
751
752 let abortedCount = 0;
753 window.fetch = jest.fn((url, init = {}) =>
754 {
755 return new Promise((resolve, reject) =>
756 {
757 const signal = init && init.signal;
758 const onAbort = () =>
759 {
760 abortedCount += 1;
761 const err = new Error('aborted');
762 err.name = 'AbortError';
763 reject(err);
764 };
765
766 if (signal && typeof signal.addEventListener === 'function')
767 {
768 if (signal.aborted) return onAbort();
769 signal.addEventListener('abort', onAbort, { once: true });
770 }
771
772 window.setTimeout(() =>
773 {
774 if (signal && signal.aborted) return;
775 resolve(new Response(null, {
776 status: 204,
777 headers: { 'X-Subtitle-Frame-Status': 'none' },
778 }));
779 }, 80);
780 });
781 });
782
783 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
784 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
785 }, {
786 currentFetchEnabled: false,
787 cacheMissFallbackIntervalMs: 20,
788 lookaheadSeconds: 2,
789 initialPrefetchSeconds: 0,
790 buildFrameRequest: ({ currentTime, streamIndex }) => ({
791 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
792 }),
793 });
794
795 await flushAsyncWork(window, 4);
796
797 player.setCurrentTime(5);
798 player.trigger('timeupdate');
799 nowMs += 40;
800 player.setCurrentTime(5.5);
801 player.trigger('timeupdate');
802 nowMs += 40;
803 player.setCurrentTime(6);
804 player.trigger('timeupdate');
805
806 await flushAsyncWork(window, 12);
807 expect(abortedCount).toBe(0);
808
809 window.Date.now = realNow;
810 controller.detach();
811 window.close();
812 });
813
742 test('cache-only mode performs initial warmup prefetch window on load', async () =>
814 test('cache-only mode performs initial warmup prefetch window on load', async () =>
743 {
815 {
744 const window = createWindow();
816 const window = createWindow();