Tolerate tight subtitle boundaries
Subtitle overlay timing now allows a slightly wider boundary window and prewarms against the active caption end time, which helps keep tightly packed PGS cues visible even when frame callbacks land just off the exact boundary. Adds a regression test covering a near-boundary sample so we keep this behaviour stable.
timfa Tim Falken · pushed by timfa
Authored 2026-05-29 · 5 months ago
- Hash
0dbcdf8c679cbe40ab33d0143497eda914f54911- Parent
b66da93d
2 files changed
+73
−2
@@ -16,7 +16,7 @@
16
16
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_DEFAULT = 0.5;
17
17
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MIN = 0.25;
18
18
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 30;
19
const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.005;
19
const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.02;
20
20
const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;
21
21
const IMAGE_SUBTITLE_CURRENT_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
22
22
const IMAGE_SUBTITLE_PREFETCH_REQUEST_TIMEOUT_MS_DEFAULT = 4000;
@@ -819,7 +819,10 @@
819
819
820
820
const secondaryIdx = primaryBufferIndex === 0 ? 1 : 0;
821
821
const secondaryKey = primaryBufferIndex === 0 ? secondaryFrameKey : primaryFrameKey;
822
const nextFrame = findNextCachedFrameAfterTime(streamIndex, currentTime);
822
const prewarmTime = Number.isFinite(currentFrame.endTimeSeconds) && currentFrame.endTimeSeconds >= 0
823
? currentFrame.endTimeSeconds
824
: currentTime;
825
const nextFrame = findNextCachedFrameAfterTime(streamIndex, prewarmTime);
823
826
if (!nextFrame || nextFrame.key === currentFrame.key || nextFrame.key === secondaryKey) return;
824
827
825
828
renderSubtitleFrameOnBuffer(nextFrame, secondaryIdx);
@@ -16,7 +16,7 @@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_MIN = 0.25;18
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 30;18
const IMAGE_SUBTITLE_PREFETCH_STEP_SECONDS_MAX = 30;19
const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.005;19
const IMAGE_SUBTITLE_TIME_MATCH_EPSILON_SECONDS = 0.02;20
const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;20
const IMAGE_SUBTITLE_CACHE_MISS_FALLBACK_INTERVAL_MS_DEFAULT = 2000;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;@@ -819,7 +819,10 @@819
819
820
const secondaryIdx = primaryBufferIndex === 0 ? 1 : 0;820
const secondaryIdx = primaryBufferIndex === 0 ? 1 : 0;821
const secondaryKey = primaryBufferIndex === 0 ? secondaryFrameKey : primaryFrameKey;821
const secondaryKey = primaryBufferIndex === 0 ? secondaryFrameKey : primaryFrameKey;822
const nextFrame = findNextCachedFrameAfterTime(streamIndex, currentTime);822
const prewarmTime = Number.isFinite(currentFrame.endTimeSeconds) && currentFrame.endTimeSeconds >= 0823
? currentFrame.endTimeSeconds824
: currentTime;825
const nextFrame = findNextCachedFrameAfterTime(streamIndex, prewarmTime);823
if (!nextFrame || nextFrame.key === currentFrame.key || nextFrame.key === secondaryKey) return;826
if (!nextFrame || nextFrame.key === currentFrame.key || nextFrame.key === secondaryKey) return;824
827
825
renderSubtitleFrameOnBuffer(nextFrame, secondaryIdx);828
renderSubtitleFrameOnBuffer(nextFrame, secondaryIdx);@@ -855,6 +855,74 @@ describe('shared image subtitle prefetching', () =>
855
855
window.close();
856
856
});
857
857
858
test('keeps tightly spaced captions renderable across near-boundary samples', async () =>
859
{
860
const window = createWindow();
861
const helper = loadSharedVideoPlayer(window);
862
const { player, videojs } = buildPlayerHarness(window);
863
864
let objectUrlSeq = 0;
865
window.URL.createObjectURL = () => `blob:subtitle-${++objectUrlSeq}`;
866
867
window.fetch = jest.fn(async (url) =>
868
{
869
const parsed = new URL(url, 'http://localhost/');
870
const timeSeconds = Number(parsed.searchParams.get('timeSeconds'));
871
const headers = {
872
'Content-Type': 'image/png',
873
'X-Subtitle-Frame-Width': '640',
874
'X-Subtitle-Frame-Height': '80',
875
'X-Subtitle-Frame-Canvas-Width': '1920',
876
'X-Subtitle-Frame-Canvas-Height': '1080',
877
};
878
879
if (Math.abs(timeSeconds - 8.351) < 0.02)
880
{
881
headers['X-Subtitle-Frame-Start-Time'] = '8.351';
882
headers['X-Subtitle-Frame-End-Time'] = '8.410';
883
} else
884
{
885
return new Response(null, {
886
status: 204,
887
headers: { 'X-Subtitle-Frame-Status': 'none' },
888
});
889
}
890
891
return new Response(new Uint8Array([137, 80, 78, 71]), {
892
status: 200,
893
headers,
894
});
895
});
896
897
helper.bindImageSubtitleOverlay(player, videojs, {}, {
898
imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
899
}, {
900
currentFetchEnabled: false,
901
cacheMissFallbackEnabled: false,
902
lookaheadSeconds: 0,
903
initialPrefetchSeconds: 0,
904
buildFrameRequest: ({ currentTime, streamIndex }) => ({
905
url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
906
}),
907
});
908
909
await flushAsyncWork(window, 8);
910
911
const overlay = player.el().querySelector('.video-subtitle-overlay');
912
const overlayImg = overlay && overlay.querySelector('img');
913
expect(overlay).toBeTruthy();
914
915
player.setCurrentTime(8.344);
916
player.trigger('play');
917
await new Promise((resolve) => window.setTimeout(resolve, 50));
918
await flushAsyncWork(window, 2);
919
920
expect(overlay.style.display).toBe('block');
921
expect(overlayImg.getAttribute('src')).toBe('blob:subtitle-1');
922
923
window.close();
924
});
925
858
926
test('aborts in-flight prefetch requests when the overlay is detached', async () =>
859
927
{
860
928
const window = createWindow();
@@ -855,6 +855,74 @@ describe('shared image subtitle prefetching', () =>855
window.close();855
window.close();856
});856
});857
857
858
test('keeps tightly spaced captions renderable across near-boundary samples', async () =>859
{860
const window = createWindow();861
const helper = loadSharedVideoPlayer(window);862
const { player, videojs } = buildPlayerHarness(window);863
864
let objectUrlSeq = 0;865
window.URL.createObjectURL = () => `blob:subtitle-${++objectUrlSeq}`;866
867
window.fetch = jest.fn(async (url) =>868
{869
const parsed = new URL(url, 'http://localhost/');870
const timeSeconds = Number(parsed.searchParams.get('timeSeconds'));871
const headers = {872
'Content-Type': 'image/png',873
'X-Subtitle-Frame-Width': '640',874
'X-Subtitle-Frame-Height': '80',875
'X-Subtitle-Frame-Canvas-Width': '1920',876
'X-Subtitle-Frame-Canvas-Height': '1080',877
};878
879
if (Math.abs(timeSeconds - 8.351) < 0.02)880
{881
headers['X-Subtitle-Frame-Start-Time'] = '8.351';882
headers['X-Subtitle-Frame-End-Time'] = '8.410';883
} else884
{885
return new Response(null, {886
status: 204,887
headers: { 'X-Subtitle-Frame-Status': 'none' },888
});889
}890
891
return new Response(new Uint8Array([137, 80, 78, 71]), {892
status: 200,893
headers,894
});895
});896
897
helper.bindImageSubtitleOverlay(player, videojs, {}, {898
imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],899
}, {900
currentFetchEnabled: false,901
cacheMissFallbackEnabled: false,902
lookaheadSeconds: 0,903
initialPrefetchSeconds: 0,904
buildFrameRequest: ({ currentTime, streamIndex }) => ({905
url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,906
}),907
});908
909
await flushAsyncWork(window, 8);910
911
const overlay = player.el().querySelector('.video-subtitle-overlay');912
const overlayImg = overlay && overlay.querySelector('img');913
expect(overlay).toBeTruthy();914
915
player.setCurrentTime(8.344);916
player.trigger('play');917
await new Promise((resolve) => window.setTimeout(resolve, 50));918
await flushAsyncWork(window, 2);919
920
expect(overlay.style.display).toBe('block');921
expect(overlayImg.getAttribute('src')).toBe('blob:subtitle-1');922
923
window.close();924
});925
858
test('aborts in-flight prefetch requests when the overlay is detached', async () =>926
test('aborts in-flight prefetch requests when the overlay is detached', async () =>859
{927
{860
const window = createWindow();928
const window = createWindow();