BlueGit

timfa filemanager

Add periodic subtitle drift resync

Image subtitle timing now performs a periodic resync every 10 seconds during playback to recover from drift after transient startup stutter.

If a caption is visible at the resync tick, the refresh is deferred until captions are no longer active, avoiding disruptive mid-caption refreshes while still correcting long-run drift.

Includes a regression test that verifies defer-while-visible and run-after-caption-end behaviour.

timfa Tim Falken · pushed by timfa

Authored 2026-05-29 · 5 months ago

Hash
275f660d02b4acb43cf110cae06477287c8ec873
Parent
2574f0c8
2 files changed +128 −0
public/shared-video-player.js +58 −0
@@ -21,6 +21,7 @@
21 21 const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
22 22 const IMAGE_SUBTITLE_PREFETCH_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
23 23 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT = 0;
24 const IMAGE_SUBTITLE_PERIODIC_RESYNC_INTERVAL_MS_DEFAULT = 10000;
24 25 const VIDEO_STREAM_CACHE_SW_URL = '/stream-cache-sw.js';
25 26 const VIDEO_STREAM_CACHE_NAME = 'filemanager-stream-cache-v1';
26 27 const VIDEO_STREAM_AHEAD_PREFETCH_POLL_MS_DEFAULT = 750;
@@ -329,6 +330,10 @@
329 330 const prefetchRequestIntervalMs = Number.isFinite(requestedPrefetchRequestIntervalMs)
330 331 ? Math.max(0, requestedPrefetchRequestIntervalMs)
331 332 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
333 const requestedPeriodicResyncIntervalMs = Number(opts.periodicResyncIntervalMs);
334 const periodicResyncIntervalMs = Number.isFinite(requestedPeriodicResyncIntervalMs)
335 ? Math.max(100, requestedPeriodicResyncIntervalMs)
336 : IMAGE_SUBTITLE_PERIODIC_RESYNC_INTERVAL_MS_DEFAULT;
332 337 const requestedPrefetchStepSeconds = Number(opts.prefetchStepSeconds);
333 338 const prefetchStepSecondsFixed = Number.isFinite(requestedPrefetchStepSeconds)
334 339 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
@@ -390,6 +395,8 @@
390 395 let lastCacheMissFallbackAtMs = 0;
391 396 let playbackClockSyncHandle = null;
392 397 let cueBoundarySyncHandle = null;
398 let periodicResyncHandle = null;
399 let periodicResyncPending = false;
393 400 const cachedSubtitleFrames = new Map();
394 401
395 402 const requestFrame = (fn) =>
@@ -560,6 +567,7 @@
560 567 cancelFrameRequest(playbackClockSyncHandle);
561 568 playbackClockSyncHandle = null;
562 569 stopCueBoundarySync();
570 stopPeriodicResync();
563 571 };
564 572
565 573 const stopCueBoundarySync = () =>
@@ -569,6 +577,16 @@
569 577 cueBoundarySyncHandle = null;
570 578 };
571 579
580 const stopPeriodicResync = () =>
581 {
582 if (periodicResyncHandle)
583 {
584 window.clearInterval(periodicResyncHandle);
585 periodicResyncHandle = null;
586 }
587 periodicResyncPending = false;
588 };
589
572 590 const closeObjectUrl = () =>
573 591 {
574 592 activeObjectUrl = null;
@@ -866,6 +884,37 @@
866 884 renderSubtitleFrameOnBuffer(nextFrame, secondaryIdx);
867 885 };
868 886
887 const runPeriodicResyncTick = () =>
888 {
889 if (selectedStreamIndex === null || trackDisabled) return;
890 if (typeof player.paused === 'function' && player.paused()) return;
891
892 const currentTime = Number(player.currentTime());
893 if (!Number.isFinite(currentTime) || currentTime < 0) return;
894
895 const cachedFrame = findCachedFrameForTime(selectedStreamIndex, currentTime);
896 if (cachedFrame)
897 {
898 periodicResyncPending = true;
899 return;
900 }
901
902 periodicResyncPending = false;
903 void refreshFrame(true, false, true);
904 };
905
906 const ensurePeriodicResync = () =>
907 {
908 if (selectedStreamIndex === null || trackDisabled) return;
909 if (typeof player.paused === 'function' && player.paused()) return;
910 if (periodicResyncHandle) return;
911
912 periodicResyncHandle = window.setInterval(() =>
913 {
914 runPeriodicResyncTick();
915 }, periodicResyncIntervalMs);
916 };
917
869 918 const scheduleCueBoundarySync = (streamIndex, currentTime, currentFrame = null) =>
870 919 {
871 920 stopCueBoundarySync();
@@ -930,6 +979,11 @@
930 979 } else
931 980 {
932 981 hideOverlay();
982 if (periodicResyncPending)
983 {
984 periodicResyncPending = false;
985 void refreshFrame(true, false, true);
986 }
933 987 scheduleCueBoundarySync(selectedStreamIndex, currentTime, null);
934 988 }
935 989 }
@@ -941,6 +995,7 @@
941 995 {
942 996 if (selectedStreamIndex === null || trackDisabled) return;
943 997 if (playbackClockSyncHandle) return;
998 ensurePeriodicResync();
944 999 playbackClockSyncHandle = requestFrame(syncOverlayToPlaybackClock);
945 1000 };
946 1001
@@ -1131,6 +1186,7 @@
1131 1186 selectedStreamIndex = null;
1132 1187 activeBucket = -1;
1133 1188 stopPlaybackClockSync();
1189 stopPeriodicResync();
1134 1190 setSeekMarkerTime('requested', null);
1135 1191 setSeekMarkerTime('received', null);
1136 1192 updateSeekBarMarkers();
@@ -1180,6 +1236,7 @@
1180 1236 }
1181 1237 else
1182 1238 {
1239 stopPeriodicResync();
1183 1240 stopPlaybackClockSync();
1184 1241 }
1185 1242 };
@@ -1734,6 +1791,7 @@
1734 1791 {
1735 1792 stopPlaybackClockSync();
1736 1793 stopCueBoundarySync();
1794 stopPeriodicResync();
1737 1795 resetRequestState();
1738 1796 flushSubtitleLogs();
1739 1797 closeMenu();
@@ -21,6 +21,7 @@
21 const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
21 const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
22 const IMAGE_SUBTITLE_PREFETCH_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
22 const IMAGE_SUBTITLE_PREFETCH_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
23 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT = 0;
23 const IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT = 0;
24 const IMAGE_SUBTITLE_PERIODIC_RESYNC_INTERVAL_MS_DEFAULT = 10000;
24 const VIDEO_STREAM_CACHE_SW_URL = '/stream-cache-sw.js';
25 const VIDEO_STREAM_CACHE_SW_URL = '/stream-cache-sw.js';
25 const VIDEO_STREAM_CACHE_NAME = 'filemanager-stream-cache-v1';
26 const VIDEO_STREAM_CACHE_NAME = 'filemanager-stream-cache-v1';
26 const VIDEO_STREAM_AHEAD_PREFETCH_POLL_MS_DEFAULT = 750;
27 const VIDEO_STREAM_AHEAD_PREFETCH_POLL_MS_DEFAULT = 750;
@@ -329,6 +330,10 @@
329 const prefetchRequestIntervalMs = Number.isFinite(requestedPrefetchRequestIntervalMs)
330 const prefetchRequestIntervalMs = Number.isFinite(requestedPrefetchRequestIntervalMs)
330 ? Math.max(0, requestedPrefetchRequestIntervalMs)
331 ? Math.max(0, requestedPrefetchRequestIntervalMs)
331 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
332 : IMAGE_SUBTITLE_PREFETCH_REQUEST_INTERVAL_MS_DEFAULT;
333 const requestedPeriodicResyncIntervalMs = Number(opts.periodicResyncIntervalMs);
334 const periodicResyncIntervalMs = Number.isFinite(requestedPeriodicResyncIntervalMs)
335 ? Math.max(100, requestedPeriodicResyncIntervalMs)
336 : IMAGE_SUBTITLE_PERIODIC_RESYNC_INTERVAL_MS_DEFAULT;
332 const requestedPrefetchStepSeconds = Number(opts.prefetchStepSeconds);
337 const requestedPrefetchStepSeconds = Number(opts.prefetchStepSeconds);
333 const prefetchStepSecondsFixed = Number.isFinite(requestedPrefetchStepSeconds)
338 const prefetchStepSecondsFixed = Number.isFinite(requestedPrefetchStepSeconds)
334 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
339 ? Math.max(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN, Math.min(IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX, requestedPrefetchStepSeconds))
@@ -390,6 +395,8 @@
390 let lastCacheMissFallbackAtMs = 0;
395 let lastCacheMissFallbackAtMs = 0;
391 let playbackClockSyncHandle = null;
396 let playbackClockSyncHandle = null;
392 let cueBoundarySyncHandle = null;
397 let cueBoundarySyncHandle = null;
398 let periodicResyncHandle = null;
399 let periodicResyncPending = false;
393 const cachedSubtitleFrames = new Map();
400 const cachedSubtitleFrames = new Map();
394
401
395 const requestFrame = (fn) =>
402 const requestFrame = (fn) =>
@@ -560,6 +567,7 @@
560 cancelFrameRequest(playbackClockSyncHandle);
567 cancelFrameRequest(playbackClockSyncHandle);
561 playbackClockSyncHandle = null;
568 playbackClockSyncHandle = null;
562 stopCueBoundarySync();
569 stopCueBoundarySync();
570 stopPeriodicResync();
563 };
571 };
564
572
565 const stopCueBoundarySync = () =>
573 const stopCueBoundarySync = () =>
@@ -569,6 +577,16 @@
569 cueBoundarySyncHandle = null;
577 cueBoundarySyncHandle = null;
570 };
578 };
571
579
580 const stopPeriodicResync = () =>
581 {
582 if (periodicResyncHandle)
583 {
584 window.clearInterval(periodicResyncHandle);
585 periodicResyncHandle = null;
586 }
587 periodicResyncPending = false;
588 };
589
572 const closeObjectUrl = () =>
590 const closeObjectUrl = () =>
573 {
591 {
574 activeObjectUrl = null;
592 activeObjectUrl = null;
@@ -866,6 +884,37 @@
866 renderSubtitleFrameOnBuffer(nextFrame, secondaryIdx);
884 renderSubtitleFrameOnBuffer(nextFrame, secondaryIdx);
867 };
885 };
868
886
887 const runPeriodicResyncTick = () =>
888 {
889 if (selectedStreamIndex === null || trackDisabled) return;
890 if (typeof player.paused === 'function' && player.paused()) return;
891
892 const currentTime = Number(player.currentTime());
893 if (!Number.isFinite(currentTime) || currentTime < 0) return;
894
895 const cachedFrame = findCachedFrameForTime(selectedStreamIndex, currentTime);
896 if (cachedFrame)
897 {
898 periodicResyncPending = true;
899 return;
900 }
901
902 periodicResyncPending = false;
903 void refreshFrame(true, false, true);
904 };
905
906 const ensurePeriodicResync = () =>
907 {
908 if (selectedStreamIndex === null || trackDisabled) return;
909 if (typeof player.paused === 'function' && player.paused()) return;
910 if (periodicResyncHandle) return;
911
912 periodicResyncHandle = window.setInterval(() =>
913 {
914 runPeriodicResyncTick();
915 }, periodicResyncIntervalMs);
916 };
917
869 const scheduleCueBoundarySync = (streamIndex, currentTime, currentFrame = null) =>
918 const scheduleCueBoundarySync = (streamIndex, currentTime, currentFrame = null) =>
870 {
919 {
871 stopCueBoundarySync();
920 stopCueBoundarySync();
@@ -930,6 +979,11 @@
930 } else
979 } else
931 {
980 {
932 hideOverlay();
981 hideOverlay();
982 if (periodicResyncPending)
983 {
984 periodicResyncPending = false;
985 void refreshFrame(true, false, true);
986 }
933 scheduleCueBoundarySync(selectedStreamIndex, currentTime, null);
987 scheduleCueBoundarySync(selectedStreamIndex, currentTime, null);
934 }
988 }
935 }
989 }
@@ -941,6 +995,7 @@
941 {
995 {
942 if (selectedStreamIndex === null || trackDisabled) return;
996 if (selectedStreamIndex === null || trackDisabled) return;
943 if (playbackClockSyncHandle) return;
997 if (playbackClockSyncHandle) return;
998 ensurePeriodicResync();
944 playbackClockSyncHandle = requestFrame(syncOverlayToPlaybackClock);
999 playbackClockSyncHandle = requestFrame(syncOverlayToPlaybackClock);
945 };
1000 };
946
1001
@@ -1131,6 +1186,7 @@
1131 selectedStreamIndex = null;
1186 selectedStreamIndex = null;
1132 activeBucket = -1;
1187 activeBucket = -1;
1133 stopPlaybackClockSync();
1188 stopPlaybackClockSync();
1189 stopPeriodicResync();
1134 setSeekMarkerTime('requested', null);
1190 setSeekMarkerTime('requested', null);
1135 setSeekMarkerTime('received', null);
1191 setSeekMarkerTime('received', null);
1136 updateSeekBarMarkers();
1192 updateSeekBarMarkers();
@@ -1180,6 +1236,7 @@
1180 }
1236 }
1181 else
1237 else
1182 {
1238 {
1239 stopPeriodicResync();
1183 stopPlaybackClockSync();
1240 stopPlaybackClockSync();
1184 }
1241 }
1185 };
1242 };
@@ -1734,6 +1791,7 @@
1734 {
1791 {
1735 stopPlaybackClockSync();
1792 stopPlaybackClockSync();
1736 stopCueBoundarySync();
1793 stopCueBoundarySync();
1794 stopPeriodicResync();
1737 resetRequestState();
1795 resetRequestState();
1738 flushSubtitleLogs();
1796 flushSubtitleLogs();
1739 closeMenu();
1797 closeMenu();
tests/shared-video-player.test.js +70 −0
@@ -1002,6 +1002,76 @@ describe('shared image subtitle prefetching', () =>
1002 1002 window.close();
1003 1003 });
1004 1004
1005 test('defers periodic resync while caption is visible and runs it after caption ends', async () =>
1006 {
1007 const window = createWindow();
1008 const helper = loadSharedVideoPlayer(window);
1009 const { player, videojs } = buildPlayerHarness(window);
1010 const requestedTimes = [];
1011
1012 window.requestAnimationFrame = undefined;
1013 window.cancelAnimationFrame = undefined;
1014
1015 player.setCurrentTime(1.2);
1016
1017 window.fetch = jest.fn(async (url) =>
1018 {
1019 const parsed = new URL(url, 'http://localhost/');
1020 const timeSeconds = Number(parsed.searchParams.get('timeSeconds'));
1021 requestedTimes.push(timeSeconds);
1022
1023 const headers = {
1024 'Content-Type': 'image/png',
1025 'X-Subtitle-Frame-Width': '640',
1026 'X-Subtitle-Frame-Height': '80',
1027 'X-Subtitle-Frame-Canvas-Width': '1920',
1028 'X-Subtitle-Frame-Canvas-Height': '1080',
1029 };
1030
1031 if (Math.abs(timeSeconds - 1.2) < 0.01)
1032 {
1033 headers['X-Subtitle-Frame-Start-Time'] = '1.0';
1034 headers['X-Subtitle-Frame-End-Time'] = '2.0';
1035 return new Response(new Uint8Array([137, 80, 78, 71]), {
1036 status: 200,
1037 headers,
1038 });
1039 }
1040
1041 return new Response(null, {
1042 status: 204,
1043 headers: { 'X-Subtitle-Frame-Status': 'none' },
1044 });
1045 });
1046
1047 helper.bindImageSubtitleOverlay(player, videojs, {}, {
1048 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
1049 }, {
1050 lookaheadSeconds: 0,
1051 initialPrefetchSeconds: 0,
1052 periodicResyncIntervalMs: 120,
1053 buildFrameRequest: ({ currentTime, streamIndex }) => ({
1054 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
1055 }),
1056 });
1057
1058 await flushAsyncWork(window, 8);
1059 player.trigger('play');
1060 await new Promise((resolve) => window.setTimeout(resolve, 300));
1061 await flushAsyncWork(window, 2);
1062
1063 const fetchCallsDuringCaption = window.fetch.mock.calls.length;
1064
1065 player.setCurrentTime(20);
1066 await new Promise((resolve) => window.setTimeout(resolve, 160));
1067 await flushAsyncWork(window, 3);
1068
1069 expect(window.fetch.mock.calls.length).toBeGreaterThan(fetchCallsDuringCaption);
1070 expect(requestedTimes.some((time) => Math.abs(time - 20) < 0.01)).toBe(true);
1071
1072 window.close();
1073 });
1074
1005 1075 test('aborts in-flight prefetch requests when the overlay is detached', async () =>
1006 1076 {
1007 1077 const window = createWindow();
@@ -1002,6 +1002,76 @@ describe('shared image subtitle prefetching', () =>
1002 window.close();
1002 window.close();
1003 });
1003 });
1004
1004
1005 test('defers periodic resync while caption is visible and runs it after caption ends', async () =>
1006 {
1007 const window = createWindow();
1008 const helper = loadSharedVideoPlayer(window);
1009 const { player, videojs } = buildPlayerHarness(window);
1010 const requestedTimes = [];
1011
1012 window.requestAnimationFrame = undefined;
1013 window.cancelAnimationFrame = undefined;
1014
1015 player.setCurrentTime(1.2);
1016
1017 window.fetch = jest.fn(async (url) =>
1018 {
1019 const parsed = new URL(url, 'http://localhost/');
1020 const timeSeconds = Number(parsed.searchParams.get('timeSeconds'));
1021 requestedTimes.push(timeSeconds);
1022
1023 const headers = {
1024 'Content-Type': 'image/png',
1025 'X-Subtitle-Frame-Width': '640',
1026 'X-Subtitle-Frame-Height': '80',
1027 'X-Subtitle-Frame-Canvas-Width': '1920',
1028 'X-Subtitle-Frame-Canvas-Height': '1080',
1029 };
1030
1031 if (Math.abs(timeSeconds - 1.2) < 0.01)
1032 {
1033 headers['X-Subtitle-Frame-Start-Time'] = '1.0';
1034 headers['X-Subtitle-Frame-End-Time'] = '2.0';
1035 return new Response(new Uint8Array([137, 80, 78, 71]), {
1036 status: 200,
1037 headers,
1038 });
1039 }
1040
1041 return new Response(null, {
1042 status: 204,
1043 headers: { 'X-Subtitle-Frame-Status': 'none' },
1044 });
1045 });
1046
1047 helper.bindImageSubtitleOverlay(player, videojs, {}, {
1048 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
1049 }, {
1050 lookaheadSeconds: 0,
1051 initialPrefetchSeconds: 0,
1052 periodicResyncIntervalMs: 120,
1053 buildFrameRequest: ({ currentTime, streamIndex }) => ({
1054 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
1055 }),
1056 });
1057
1058 await flushAsyncWork(window, 8);
1059 player.trigger('play');
1060 await new Promise((resolve) => window.setTimeout(resolve, 300));
1061 await flushAsyncWork(window, 2);
1062
1063 const fetchCallsDuringCaption = window.fetch.mock.calls.length;
1064
1065 player.setCurrentTime(20);
1066 await new Promise((resolve) => window.setTimeout(resolve, 160));
1067 await flushAsyncWork(window, 3);
1068
1069 expect(window.fetch.mock.calls.length).toBeGreaterThan(fetchCallsDuringCaption);
1070 expect(requestedTimes.some((time) => Math.abs(time - 20) < 0.01)).toBe(true);
1071
1072 window.close();
1073 });
1074
1005 test('aborts in-flight prefetch requests when the overlay is detached', async () =>
1075 test('aborts in-flight prefetch requests when the overlay is detached', async () =>
1006 {
1076 {
1007 const window = createWindow();
1077 const window = createWindow();