From c366c8f33e11d8e4d0ef73b370e1254472790a1f Mon Sep 17 00:00:00 2001 From: Terry Jia Date: Mon, 31 Aug 2026 00:04:30 -0400 Subject: [PATCH 1/2] fix: retry filmstrip frame capture when the video frame is not yet decodable --- .../video/useVideoFilmstrip.test.ts | 36 +++++++++++++++---- src/composables/video/useVideoFilmstrip.ts | 28 ++++++++++++++- 2 files changed, 56 insertions(+), 8 deletions(-) diff --git a/src/composables/video/useVideoFilmstrip.test.ts b/src/composables/video/useVideoFilmstrip.test.ts index ba2e3778a3a..55ed505a301 100644 --- a/src/composables/video/useVideoFilmstrip.test.ts +++ b/src/composables/video/useVideoFilmstrip.test.ts @@ -356,13 +356,11 @@ describe('useVideoFilmstrip', () => { expect(bitmap.close).toHaveBeenCalledTimes(1) }) - it('leaves the thumbnail empty when the capture fails', async () => { - vi.stubGlobal( - 'createImageBitmap', - vi.fn(async () => { - throw new Error('decode failed') - }) - ) + it('leaves the thumbnail empty when every capture attempt fails', async () => { + const createImageBitmapMock = vi.fn(async () => { + throw new Error('decode failed') + }) + vi.stubGlobal('createImageBitmap', createImageBitmapMock) vi.stubGlobal('OffscreenCanvas', MockOffscreenCanvas) installVideoMocks() @@ -371,12 +369,36 @@ describe('useVideoFilmstrip', () => { useVideoFilmstrip(videoUrl) ) + await vi.advanceTimersByTimeAsync(6000) await vi.waitFor(() => expect(loading.value).toBe(false)) + expect(createImageBitmapMock.mock.calls.length).toBeGreaterThan(1) expect(thumbnail.value).toBe('') expect(error.value).toBeNull() }) + it('retries the capture when the frame is not yet decodable', async () => { + const bitmap = { width: 171, height: 96, close: vi.fn() } + const createImageBitmapMock = vi + .fn(async () => bitmap) + .mockRejectedValueOnce(new Error('The image source is not usable.')) + .mockRejectedValueOnce(new Error('The image source is not usable.')) + vi.stubGlobal('createImageBitmap', createImageBitmapMock) + vi.stubGlobal('OffscreenCanvas', MockOffscreenCanvas) + installVideoMocks() + + const videoUrl = ref('https://example.com/video.mp4') + const { thumbnail, loading } = runWithScope(() => + useVideoFilmstrip(videoUrl) + ) + + await vi.advanceTimersByTimeAsync(3000) + await vi.waitFor(() => expect(loading.value).toBe(false)) + + expect(createImageBitmapMock).toHaveBeenCalledTimes(3) + expect(thumbnail.value).not.toBe('') + }) + it('downscales the captured thumbnail to the filmstrip height', async () => { let canvas: HTMLCanvasElement | undefined installVideoMocks({ diff --git a/src/composables/video/useVideoFilmstrip.ts b/src/composables/video/useVideoFilmstrip.ts index 9c98dbd101d..45fb47b3d2a 100644 --- a/src/composables/video/useVideoFilmstrip.ts +++ b/src/composables/video/useVideoFilmstrip.ts @@ -1,3 +1,4 @@ +import { delay } from 'es-toolkit' import { onScopeDispose, ref, watch } from 'vue' import type { Ref } from 'vue' @@ -9,6 +10,8 @@ export const FILMSTRIP_THUMBNAIL_MAX_WIDTH = 384 const METADATA_EVENT_TIMEOUT_MS = 15000 const SEEK_EVENT_TIMEOUT_MS = 5000 +const FRAME_DECODE_TIMEOUT_MS = 5000 +const FRAME_DECODE_RETRY_INTERVAL_MS = 250 export type FilmstripError = 'canvas-unavailable' | 'load-failed' @@ -152,6 +155,28 @@ function representativeFrameTime(duration: number): number { : 0 } +async function waitForDecodableFrame( + video: HTMLVideoElement, + canvas: HTMLCanvasElement, + context: CanvasRenderingContext2D, + signal: AbortSignal +): Promise { + for ( + let waitedMs = 0; + waitedMs < FRAME_DECODE_TIMEOUT_MS; + waitedMs += FRAME_DECODE_RETRY_INTERVAL_MS + ) { + try { + await delay(FRAME_DECODE_RETRY_INTERVAL_MS, { signal }) + } catch { + throw new LoadAbortedError('Aborted waiting for a decodable frame') + } + const frame = await captureFrame(video, canvas, context) + if (frame) return frame + } + return '' +} + async function captureRepresentativeFrame( video: HTMLVideoElement, canvas: HTMLCanvasElement, @@ -168,7 +193,8 @@ async function captureRepresentativeFrame( if (!(waitError instanceof EventTimeoutError)) throw waitError } } - return captureFrame(video, canvas, context) + const frame = await captureFrame(video, canvas, context) + return frame || waitForDecodableFrame(video, canvas, context, signal) } export function useVideoFilmstrip( From 22e6561e8f34feaad3d1aa8c0b8ece8bbd9e900b Mon Sep 17 00:00:00 2001 From: Terry Jia Date: Mon, 31 Aug 2026 22:29:10 -0400 Subject: [PATCH 2/2] fix: enforce the frame decode timeout as a wall-clock deadline --- .../video/useVideoFilmstrip.test.ts | 39 +++++++++++++++++++ src/composables/video/useVideoFilmstrip.ts | 7 +--- 2 files changed, 41 insertions(+), 5 deletions(-) diff --git a/src/composables/video/useVideoFilmstrip.test.ts b/src/composables/video/useVideoFilmstrip.test.ts index 55ed505a301..90f2bcd6fdf 100644 --- a/src/composables/video/useVideoFilmstrip.test.ts +++ b/src/composables/video/useVideoFilmstrip.test.ts @@ -375,6 +375,45 @@ describe('useVideoFilmstrip', () => { expect(createImageBitmapMock.mock.calls.length).toBeGreaterThan(1) expect(thumbnail.value).toBe('') expect(error.value).toBeNull() + + const attemptsAtTimeout = createImageBitmapMock.mock.calls.length + await vi.advanceTimersByTimeAsync(5000) + expect(createImageBitmapMock.mock.calls.length).toBe(attemptsAtTimeout) + }) + + it('stops polling for a frame when the load is superseded', async () => { + const bitmap = { width: 171, height: 96, close: vi.fn() } + const videos: MockVideoElement[] = [] + const createImageBitmapMock = vi.fn(async () => { + if (videos.length === 1) throw new Error('decode failed') + return bitmap + }) + vi.stubGlobal('createImageBitmap', createImageBitmapMock) + vi.stubGlobal('OffscreenCanvas', MockOffscreenCanvas) + installVideoMocks({ + onVideoCreated: (video) => { + videos.push(video) + } + }) + + const videoUrl = ref('https://example.com/first.mp4') + const { thumbnail, error, loading } = runWithScope(() => + useVideoFilmstrip(videoUrl) + ) + await vi.advanceTimersByTimeAsync(500) + const attemptsBeforeSwitch = createImageBitmapMock.mock.calls.length + expect(attemptsBeforeSwitch).toBeGreaterThan(1) + + videoUrl.value = 'https://example.com/second.mp4' + await vi.waitFor(() => expect(loading.value).toBe(false)) + + expect(videos[0].src).toBe('') + expect(error.value).toBeNull() + expect(thumbnail.value).not.toBe('') + + const attemptsAfterSettle = createImageBitmapMock.mock.calls.length + await vi.advanceTimersByTimeAsync(5000) + expect(createImageBitmapMock.mock.calls.length).toBe(attemptsAfterSettle) }) it('retries the capture when the frame is not yet decodable', async () => { diff --git a/src/composables/video/useVideoFilmstrip.ts b/src/composables/video/useVideoFilmstrip.ts index 45fb47b3d2a..46b6cc8a3b2 100644 --- a/src/composables/video/useVideoFilmstrip.ts +++ b/src/composables/video/useVideoFilmstrip.ts @@ -161,11 +161,8 @@ async function waitForDecodableFrame( context: CanvasRenderingContext2D, signal: AbortSignal ): Promise { - for ( - let waitedMs = 0; - waitedMs < FRAME_DECODE_TIMEOUT_MS; - waitedMs += FRAME_DECODE_RETRY_INTERVAL_MS - ) { + const deadlineMs = Date.now() + FRAME_DECODE_TIMEOUT_MS + while (Date.now() < deadlineMs) { try { await delay(FRAME_DECODE_RETRY_INTERVAL_MS, { signal }) } catch {