BlueGit

timfa filemanager

Add timeout recovery regression coverage

Adds and documents regression coverage for hung current subtitle requests so playback resumes subtitle fetching after a timeout. This protects users from silent subtitle dropouts during long watch sessions.

timfa Tim Falken · pushed by timfa

Authored 2026-05-25 · 5 months ago

Hash
fe21a9fb51ddba90e579ae9344f0e76788aa8ff2
Parent
261cda41
2 files changed +157 −2
.github/technical-reference.md +1 −1
@@ -182,7 +182,7 @@
182 182 ## public/shared-video-player.js
183 183 - 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.
184 184 - 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.
185 - 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), coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, renders seek-bar triangle markers for last requested caption start time (`>`) and last received/ready caption start time (`<`), and disables the track after the first hard failure.
185 - 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), extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), 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, renders seek-bar bracket markers for last requested point (`]`) and last received/ready point (`[`), advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
186 186 - configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
187 187 - ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
188 188
@@ -182,7 +182,7 @@
182## public/shared-video-player.js
182## public/shared-video-player.js
183- 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.
183- 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.
184- 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.
184- 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.
185- 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), coalesces overlapping current-frame refreshes into a single in-flight fetch (only force-refresh paths abort/restart), logs current and prefetch subtitle request/send/receive/not-available timing to the browser console and optional batch sink, renders seek-bar triangle markers for last requested caption start time (`>`) and last received/ready caption start time (`<`), and disables the track after the first hard failure.
185- 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), extends prefetch target to at least the latest buffered video end (not only fixed lookahead seconds), 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, renders seek-bar bracket markers for last requested point (`]`) and last received/ready point (`[`), advances markers even when responses are 204/no-frame, and disables the track after the first hard failure.
186- configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
186- configureVideoJsBuffering(videojs, opts) - Applies the long forward-buffer settings used for file playback when VHS exposes those knobs.
187- ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
187- ensureVideoPlaybackUi(player, durationSeconds) - Forces file streams into VOD UI mode, normalises the reported duration, stops live-tracker state, and hides the live badge when present.
188
188
tests/shared-video-player.test.js +156 −1
@@ -67,6 +67,7 @@ function buildPlayerHarness (window)
67 67 playerEl.appendChild(progressControlEl);
68 68 let currentTime = 0;
69 69 let durationSeconds = 10;
70 let bufferedEndSeconds = null;
70 71
71 72 const player = {
72 73 ready (cb)
@@ -100,6 +101,14 @@ function buildPlayerHarness (window)
100 101 }
101 102 return durationSeconds;
102 103 },
104 bufferedEnd ()
105 {
106 return bufferedEndSeconds;
107 },
108 setBufferedEnd (next)
109 {
110 bufferedEndSeconds = Number.isFinite(next) ? Number(next) : null;
111 },
103 112 el ()
104 113 {
105 114 return playerEl;
@@ -183,6 +192,41 @@ describe('shared image subtitle prefetching', () =>
183 192 window.close();
184 193 });
185 194
195 test('prefetches at least through the buffered video end', async () =>
196 {
197 const window = createWindow();
198 const helper = loadSharedVideoPlayer(window);
199 const { player, videojs } = buildPlayerHarness(window);
200 const requestedTimes = [];
201
202 player.setBufferedEnd(3);
203
204 window.fetch = jest.fn(async (url) =>
205 {
206 const parsed = new URL(url, 'http://localhost/');
207 requestedTimes.push(Number(parsed.searchParams.get('timeSeconds')));
208 return new Response(null, {
209 status: 204,
210 headers: { 'X-Subtitle-Frame-Status': 'none' },
211 });
212 });
213
214 helper.bindImageSubtitleOverlay(player, videojs, {}, {
215 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
216 }, {
217 lookaheadSeconds: 0.5,
218 buildFrameRequest: ({ currentTime, streamIndex }) => ({
219 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
220 }),
221 });
222
223 await flushAsyncWork(window, 12);
224
225 expect(requestedTimes).toEqual(expect.arrayContaining([0, 0.5, 1, 1.5, 2, 2.5, 3]));
226
227 window.close();
228 });
229
186 230 test('does not restart current subtitle request while one is in flight', async () =>
187 231 {
188 232 const window = createWindow();
@@ -446,12 +490,123 @@ describe('shared image subtitle prefetching', () =>
446 490 expect(receivedMarker).toBeTruthy();
447 491 expect(requestedMarker.style.display).toBe('block');
448 492 expect(receivedMarker.style.display).toBe('block');
449 expect(requestedMarker.style.left).toBe('25.0000%');
493 expect(requestedMarker.style.left).toBe('0.0000%');
450 494 expect(receivedMarker.style.left).toBe('25.0000%');
495 expect(requestedMarker.textContent).toBe(']');
496 expect(receivedMarker.textContent).toBe('[');
497
498 controller.detach();
499 await new Promise((resolve) => window.setTimeout(resolve, 300));
500 await flushAsyncWork(window, 2);
501
502 window.close();
503 });
504
505 test('advances both seek markers when subtitle request returns 204 without frame timing headers', async () =>
506 {
507 const window = createWindow();
508 const helper = loadSharedVideoPlayer(window);
509 const { player, videojs } = buildPlayerHarness(window);
510
511 player.duration(10);
512 player.setCurrentTime(4);
513 window.fetch = jest.fn(async () =>
514 {
515 return new Response(null, {
516 status: 204,
517 headers: {
518 'X-Subtitle-Frame-Status': 'none',
519 'X-Subtitle-Request-Received-At-Ms': '1000',
520 'X-Subtitle-Response-Sent-At-Ms': '1010',
521 },
522 });
523 });
524
525 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
526 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
527 }, {
528 lookaheadSeconds: 0,
529 buildFrameRequest: ({ currentTime, streamIndex }) => ({
530 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
531 }),
532 });
533
534 await flushAsyncWork(window, 8);
535
536 const requestedMarker = player.el().querySelector('.vjs-image-subtitle-seek-marker-right');
537 const receivedMarker = player.el().querySelector('.vjs-image-subtitle-seek-marker-left');
538 expect(requestedMarker).toBeTruthy();
539 expect(receivedMarker).toBeTruthy();
540 expect(requestedMarker.style.left).toBe('40.0000%');
541 expect(receivedMarker.style.left).toBe('40.0000%');
542 expect(requestedMarker.textContent).toBe(']');
543 expect(receivedMarker.textContent).toBe('[');
451 544
452 545 controller.detach();
453 546 await flushAsyncWork(window, 2);
547 window.close();
548 });
549
550 test('recovers when a current subtitle request hangs and times out', async () =>
551 {
552 const window = createWindow();
553 const helper = loadSharedVideoPlayer(window);
554 const { player, videojs } = buildPlayerHarness(window);
555 const requestedTimes = [];
454 556
557 window.fetch = jest.fn((url, init = {}) =>
558 {
559 const parsed = new URL(url, 'http://localhost/');
560 const timeSeconds = Number(parsed.searchParams.get('timeSeconds'));
561 requestedTimes.push(timeSeconds);
562
563 if (requestedTimes.length === 1)
564 {
565 return new Promise((resolve, reject) =>
566 {
567 if (init.signal && typeof init.signal.addEventListener === 'function')
568 {
569 init.signal.addEventListener('abort', () =>
570 {
571 reject(new window.DOMException('Aborted', 'AbortError'));
572 }, { once: true });
573 }
574 });
575 }
576
577 return Promise.resolve(new Response(null, {
578 status: 204,
579 headers: { 'X-Subtitle-Frame-Status': 'none' },
580 }));
581 });
582
583 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
584 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
585 }, {
586 lookaheadSeconds: 0,
587 currentRequestTimeoutMs: 250,
588 logToConsole: false,
589 buildFrameRequest: ({ currentTime, streamIndex }) => ({
590 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
591 }),
592 });
593
594 await flushAsyncWork(window, 3);
595
596 player.setCurrentTime(1.5);
597 player.trigger('timeupdate');
598
599 await new Promise((resolve) => window.setTimeout(resolve, 320));
600 player.trigger('timeupdate');
601 await new Promise((resolve) => window.setTimeout(resolve, 220));
602 await flushAsyncWork(window, 20);
603
604 expect(window.fetch.mock.calls.length).toBeGreaterThanOrEqual(2);
605 expect(requestedTimes).toEqual(expect.arrayContaining([0, 1.5]));
606
607 controller.detach();
608 await new Promise((resolve) => window.setTimeout(resolve, 200));
609 await flushAsyncWork(window, 20);
455 610 window.close();
456 611 });
457 612 });
@@ -67,6 +67,7 @@ function buildPlayerHarness (window)
67 playerEl.appendChild(progressControlEl);
67 playerEl.appendChild(progressControlEl);
68 let currentTime = 0;
68 let currentTime = 0;
69 let durationSeconds = 10;
69 let durationSeconds = 10;
70 let bufferedEndSeconds = null;
70
71
71 const player = {
72 const player = {
72 ready (cb)
73 ready (cb)
@@ -100,6 +101,14 @@ function buildPlayerHarness (window)
100 }
101 }
101 return durationSeconds;
102 return durationSeconds;
102 },
103 },
104 bufferedEnd ()
105 {
106 return bufferedEndSeconds;
107 },
108 setBufferedEnd (next)
109 {
110 bufferedEndSeconds = Number.isFinite(next) ? Number(next) : null;
111 },
103 el ()
112 el ()
104 {
113 {
105 return playerEl;
114 return playerEl;
@@ -183,6 +192,41 @@ describe('shared image subtitle prefetching', () =>
183 window.close();
192 window.close();
184 });
193 });
185
194
195 test('prefetches at least through the buffered video end', async () =>
196 {
197 const window = createWindow();
198 const helper = loadSharedVideoPlayer(window);
199 const { player, videojs } = buildPlayerHarness(window);
200 const requestedTimes = [];
201
202 player.setBufferedEnd(3);
203
204 window.fetch = jest.fn(async (url) =>
205 {
206 const parsed = new URL(url, 'http://localhost/');
207 requestedTimes.push(Number(parsed.searchParams.get('timeSeconds')));
208 return new Response(null, {
209 status: 204,
210 headers: { 'X-Subtitle-Frame-Status': 'none' },
211 });
212 });
213
214 helper.bindImageSubtitleOverlay(player, videojs, {}, {
215 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
216 }, {
217 lookaheadSeconds: 0.5,
218 buildFrameRequest: ({ currentTime, streamIndex }) => ({
219 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
220 }),
221 });
222
223 await flushAsyncWork(window, 12);
224
225 expect(requestedTimes).toEqual(expect.arrayContaining([0, 0.5, 1, 1.5, 2, 2.5, 3]));
226
227 window.close();
228 });
229
186 test('does not restart current subtitle request while one is in flight', async () =>
230 test('does not restart current subtitle request while one is in flight', async () =>
187 {
231 {
188 const window = createWindow();
232 const window = createWindow();
@@ -446,12 +490,123 @@ describe('shared image subtitle prefetching', () =>
446 expect(receivedMarker).toBeTruthy();
490 expect(receivedMarker).toBeTruthy();
447 expect(requestedMarker.style.display).toBe('block');
491 expect(requestedMarker.style.display).toBe('block');
448 expect(receivedMarker.style.display).toBe('block');
492 expect(receivedMarker.style.display).toBe('block');
449 expect(requestedMarker.style.left).toBe('25.0000%');
493 expect(requestedMarker.style.left).toBe('0.0000%');
450 expect(receivedMarker.style.left).toBe('25.0000%');
494 expect(receivedMarker.style.left).toBe('25.0000%');
495 expect(requestedMarker.textContent).toBe(']');
496 expect(receivedMarker.textContent).toBe('[');
497
498 controller.detach();
499 await new Promise((resolve) => window.setTimeout(resolve, 300));
500 await flushAsyncWork(window, 2);
501
502 window.close();
503 });
504
505 test('advances both seek markers when subtitle request returns 204 without frame timing headers', async () =>
506 {
507 const window = createWindow();
508 const helper = loadSharedVideoPlayer(window);
509 const { player, videojs } = buildPlayerHarness(window);
510
511 player.duration(10);
512 player.setCurrentTime(4);
513 window.fetch = jest.fn(async () =>
514 {
515 return new Response(null, {
516 status: 204,
517 headers: {
518 'X-Subtitle-Frame-Status': 'none',
519 'X-Subtitle-Request-Received-At-Ms': '1000',
520 'X-Subtitle-Response-Sent-At-Ms': '1010',
521 },
522 });
523 });
524
525 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
526 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
527 }, {
528 lookaheadSeconds: 0,
529 buildFrameRequest: ({ currentTime, streamIndex }) => ({
530 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
531 }),
532 });
533
534 await flushAsyncWork(window, 8);
535
536 const requestedMarker = player.el().querySelector('.vjs-image-subtitle-seek-marker-right');
537 const receivedMarker = player.el().querySelector('.vjs-image-subtitle-seek-marker-left');
538 expect(requestedMarker).toBeTruthy();
539 expect(receivedMarker).toBeTruthy();
540 expect(requestedMarker.style.left).toBe('40.0000%');
541 expect(receivedMarker.style.left).toBe('40.0000%');
542 expect(requestedMarker.textContent).toBe(']');
543 expect(receivedMarker.textContent).toBe('[');
451
544
452 controller.detach();
545 controller.detach();
453 await flushAsyncWork(window, 2);
546 await flushAsyncWork(window, 2);
547 window.close();
548 });
549
550 test('recovers when a current subtitle request hangs and times out', async () =>
551 {
552 const window = createWindow();
553 const helper = loadSharedVideoPlayer(window);
554 const { player, videojs } = buildPlayerHarness(window);
555 const requestedTimes = [];
454
556
557 window.fetch = jest.fn((url, init = {}) =>
558 {
559 const parsed = new URL(url, 'http://localhost/');
560 const timeSeconds = Number(parsed.searchParams.get('timeSeconds'));
561 requestedTimes.push(timeSeconds);
562
563 if (requestedTimes.length === 1)
564 {
565 return new Promise((resolve, reject) =>
566 {
567 if (init.signal && typeof init.signal.addEventListener === 'function')
568 {
569 init.signal.addEventListener('abort', () =>
570 {
571 reject(new window.DOMException('Aborted', 'AbortError'));
572 }, { once: true });
573 }
574 });
575 }
576
577 return Promise.resolve(new Response(null, {
578 status: 204,
579 headers: { 'X-Subtitle-Frame-Status': 'none' },
580 }));
581 });
582
583 const controller = helper.bindImageSubtitleOverlay(player, videojs, {}, {
584 imageSubtitleTracks: [{ label: 'PGS English', streamIndex: 0, default: true }],
585 }, {
586 lookaheadSeconds: 0,
587 currentRequestTimeoutMs: 250,
588 logToConsole: false,
589 buildFrameRequest: ({ currentTime, streamIndex }) => ({
590 url: `/subtitle-frame?streamIndex=${streamIndex}&timeSeconds=${currentTime}`,
591 }),
592 });
593
594 await flushAsyncWork(window, 3);
595
596 player.setCurrentTime(1.5);
597 player.trigger('timeupdate');
598
599 await new Promise((resolve) => window.setTimeout(resolve, 320));
600 player.trigger('timeupdate');
601 await new Promise((resolve) => window.setTimeout(resolve, 220));
602 await flushAsyncWork(window, 20);
603
604 expect(window.fetch.mock.calls.length).toBeGreaterThanOrEqual(2);
605 expect(requestedTimes).toEqual(expect.arrayContaining([0, 1.5]));
606
607 controller.detach();
608 await new Promise((resolve) => window.setTimeout(resolve, 200));
609 await flushAsyncWork(window, 20);
455 window.close();
610 window.close();
456 });
611 });
457});
612});