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
@@ -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
} else979
} else931
{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
else1237
else1182
{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();@@ -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();