@banou/media-player 0.8.21 → 0.9.0

package/src/lib/engine/subtitles.ts

@@ -1,4 +1,4 @@
-import type { ASS_Event } from 'jassub'
+import type { ASSEvent } from 'jassub/dist/worker/util'
 import type { Attachment, SubtitleFragment } from 'libav-wasm/build/worker'
 
 import JASSUB from 'jassub'
@@ -9,30 +9,32 @@ export type SubtitleStream = { streamIndex: number, title: string, language: str
 /** -1 turns subtitles off. It frees the track and matches no header, so nothing is set. */
 export const SUBTITLES_OFF = -1
 
-/**
- * jassub's `ASS_Event` types `Style` as a string, which the library it wraps does not agree with:
- * the field is written straight through to libass's `int Style`, an index into the track's style
- * list. Corrected once, here, so a name cannot end up in it again.
- */
-type StyledEvent = Omit<ASS_Event, 'Style'> & { Style: number }
-
-const createEvent = (jassub: JASSUB, event: StyledEvent) => jassub.createEvent(event as unknown as ASS_Event)
-
 type SubtitleHeaderPart = { type: 'header', streamIndex: number, content: string, eventsContent: string, styles: Map<string, number> }
-type SubtitleDialoguePart = { type: 'dialogue', streamIndex: number, index: number, assEvent: StyledEvent }
+type SubtitleDialoguePart = { type: 'dialogue', streamIndex: number, index: number, assEvent: ASSEvent }
 
 export type SubtitleRendererOptions = {
   video: HTMLVideoElement
-  canvas: HTMLCanvasElement
+  /**
+   * Where the subtitle surface is mounted.
+   *
+   * A container, not the canvas itself. From jassub 2 the canvas belongs to the renderer: the
+   * constructor transfers it to a worker, which an element accepts exactly once for its whole life,
+   * and `destroy()` removes it from the document. Neither is survivable for an element someone else
+   * owns, and this pipeline is rebuilt in place on an audio track change and on an element recovery.
+   * So one canvas is created here per jassub instance, inside this container.
+   *
+   * The live canvas is `container.querySelector('canvas')`, and it is replaced on every rebuild.
+   */
+  container: HTMLElement
   workerUrl: string
   /** The SIMD build, `jassub-worker-modern.wasm`. Used wherever WebAssembly SIMD is available. */
   wasmUrl: string
   /**
-   * The non-SIMD build, `jassub-worker.wasm`, for Safari before 16.4 and anything else without SIMD.
+   * The non-SIMD build, `jassub-worker.wasm`, for anything without WebAssembly SIMD.
    *
-   * Not optional in practice, only in the type. jassub picks `wasmUrl ?? 'jassub-worker.wasm'` when SIMD
-   * is missing, and that bare relative name resolves against the blob: url the worker is built from,
-   * which throws. So leaving this unset does not degrade to the slower build, it fails outright.
+   * Optional in practice as well as in the type, unlike under jassub 1: v2 defaults both wasm urls to
+   * its own files resolved against `import.meta.url`, so leaving this unset degrades to whatever the
+   * bundler emitted rather than failing outright.
    */
   legacyWasmUrl?: string
   /**
@@ -48,10 +50,10 @@ export type SubtitleRendererOptions = {
 /**
  * A url the WORKER will fetch, resolved against the document first.
  *
- * jassub's worker is built from a `blob:` url, so a relative url handed to it resolves against that
- * blob inside the worker and the fetch never lands. For the wasm that fails loudly. For the fallback
- * font it fails in SILENCE: libass is left with no face to draw with, so the track renders nothing at
- * all and the picture simply has no subtitles on it, with no error anywhere to say why.
+ * A relative url handed to the worker resolves against the worker's own url inside it, which is not
+ * the document's. For the wasm that fails loudly. For the fallback font it fails in SILENCE: libass
+ * is left with no face to draw with, so the track renders nothing at all and the picture simply has
+ * no subtitles on it, with no error anywhere to say why.
  *
  * `workerUrl` is deliberately not passed through here. `new Worker()` is called on the main thread,
  * where a relative url already resolves against the document.
@@ -78,9 +80,11 @@ const headerStyles = (content: string) =>
 /**
  * The index libass will resolve this event's style to.
  *
- * jassub types `ASS_Event.Style` as a string and writes it straight through to an `int`, so handing
- * it a style NAME stores 0, which is libass's own default: Arial at size 18, with margins and a drop
- * shadow of its own. Subtitles still appear, in a face and a size the file never asked for.
+ * `ASSEvent.Style` is written straight through to an `int`, so handing it a style NAME stores 0,
+ * which is libass's own default: Arial at size 18, with margins and a drop shadow of its own.
+ * Subtitles still appear, in a face and a size the file never asked for. jassub 1 typed the field as
+ * a string, which is what made that easy to do; jassub 2 types it `number` and agrees with libass,
+ * but the resolution still has to happen somewhere and this is it.
  *
  * Falling back to the header's own "Default", then to 0, is what libass does for a name it cannot
  * find. The leading-`*` strip and the case fold on "Default" are its normalisation, kept so a
@@ -123,23 +127,30 @@ const toDialoguePart = (header: SubtitleHeaderPart, fragment: SubtitleFragment &
     streamIndex: fragment.streamIndex,
     index: dialogueIndex,
     assEvent: {
-      ...event,
+      Name: event.Name ?? '',
+      // libass wants the raw effect field and ass-compiler has already destructured it into an
+      // object, so only the name survives the round trip. That is parity rather than a regression:
+      // jassub 1 was handed the object itself, which reached libass's `char*` as "[object Object]",
+      // and libass matches an effect by a "Banner;" or "Scroll up;" prefix, so neither form has ever
+      // selected one.
+      Effect: event.Effect?.name ?? '',
+      Layer: event.Layer,
+      MarginL: event.MarginL,
+      MarginR: event.MarginR,
+      MarginV: event.MarginV,
       Style: styleIndex(header, event.Style),
-      Effect: event.Effect ?? '',
       Text: event.Text.raw,
-      Duration: (event.End - event.Start) * 1000,
       Start: event.Start * 1000,
-      End: event.End * 1000,
+      Duration: (event.End - event.Start) * 1000,
       ReadOrder: dialogueIndex,
-      _index: dialogueIndex,
-    } as StyledEvent,
+    },
   }
 }
 
 export type SubtitleRenderer = ReturnType<typeof createSubtitleRenderer>
 
 export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
-  const { video, canvas, workerUrl } = options
+  const { video, container, workerUrl } = options
   const wasmUrl = workerFetched(options.wasmUrl)!
   const legacyWasmUrl = workerFetched(options.legacyWasmUrl)
   const defaultFontUrl = workerFetched(options.defaultFontUrl)
@@ -150,31 +161,157 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
   const dialogues = new Map<number, Map<number, SubtitleDialoguePart>>()
   let selected: number | undefined
   let onStreams = options.onStreams
+  /**
+   * Terminal, unlike a null `jassub`.
+   *
+   * `pushFragments` boots on the first header it sees and tests `!jassub` to decide, so a fragment
+   * that lands after teardown (a demuxer read resolving into a torn-down pipeline, which is ordinary
+   * on the `./engine` surface) would start a SECOND worker with a second canvas inside a container
+   * nobody is watching any more. The live canvas is found with `querySelector`, so the stale one
+   * would win and picture in picture would composite a surface that is never painted again.
+   */
+  let destroyed = false
+
+  const rendererFailed = (error: unknown) => {
+    console.warn('the subtitle renderer failed; the file plays without subtitles', error)
+  }
+
+  /**
+   * Run something against the worker, once there is a worker to run it against.
+   *
+   * `instance.renderer` is assigned by the promise `ready` resolves, so nothing can be called before
+   * then and a call made too early throws on `undefined`. Ordering after that is free rather than
+   * something this has to arrange: abslink posts each call synchronously from its proxy's `apply`
+   * trap, and the worker runs the method synchronously in its own message handler, so calls land in
+   * the order they were made whether or not each one is awaited. Reactions registered on one
+   * already-settled promise also run in registration order, so this preserves it too.
+   *
+   * The identity check is what stops a teardown that happened during the boot from talking to a
+   * worker that is on its way out.
+   *
+   * `run` RETURNS its calls rather than dropping them. Every proxied call is a promise that rejects
+   * when the worker throws, which libass does on a header it will not take and once it is over its
+   * glyph or memory limit, and a dropped one surfaces as a bare `unhandledrejection` in the host app
+   * with nothing naming subtitles in it.
+   */
+  const onRenderer = (run: (renderer: JASSUB['renderer']) => unknown) => {
+    const instance = jassub
+    if (!instance) return
+    void instance.ready
+      .then(() => (jassub === instance ? run(instance.renderer) : undefined))
+      .catch(rendererFailed)
+  }
 
-  const tick = setInterval(() => {
-    jassub?.setCurrentTime(video.paused, video.currentTime, video.playbackRate)
-  }, 100)
+  let repaintQueued = false
+  /**
+   * Ask for one frame.
+   *
+   * jassub 2 draws only from `requestVideoFrameCallback`, so a PAUSED video presents no frames and
+   * nothing repaints. Anything that changes what libass would draw has to ask for a frame itself, or
+   * a track switch and a seek while paused both leave the previous line on screen until playback
+   * resumes. jassub 1 needed none of this because the 100ms `setCurrentTime` tick this replaces
+   * redrew unconditionally.
+   *
+   * Coalesced through a microtask because events arrive in bursts of hundreds and one frame covers
+   * the whole burst. The burst is synchronous, so the microtask always runs after all of it, and a
+   * playing video therefore costs at most one extra draw per burst.
+   */
+  const repaint = () => {
+    if (repaintQueued) return
+    repaintQueued = true
+    queueMicrotask(() => {
+      repaintQueued = false
+      const instance = jassub
+      // `videoWidth` is 0 until metadata arrives, and asking jassub to draw then sizes its surface to
+      // nothing. Nothing else is required: this deliberately does NOT skip the draw when the element
+      // is playing. "Playing" is not "presenting frames", and the gap between them is exactly where
+      // subtitles get stuck. A torrent-backed source whose SourceBuffer runs dry keeps `paused` false
+      // while presenting nothing, so a viewer who turns subtitles off mid-stall would watch the line
+      // stay on screen until the buffer refilled. One forced draw per change is far cheaper than
+      // reasoning about which stalls count.
+      if (!instance || !video.videoWidth) return
+      void instance.ready
+        .then(() => {
+          if (jassub !== instance) return undefined
+          return instance.manualRender({
+            expectedDisplayTime: performance.now(),
+            width: video.videoWidth,
+            height: video.videoHeight,
+            mediaTime: video.currentTime,
+          }, true)
+        })
+        .catch(rendererFailed)
+    })
+  }
 
-  const onRateChange = () => jassub?.setRate(video.playbackRate)
+  /**
+   * The element events that change what should be on screen without presenting a frame.
+   *
+   * `loadedmetadata` is the one that is easy to miss and fatal to leave out: the first subtitle
+   * fragments arrive BEFORE the element has parsed metadata, so the repaint they ask for is skipped
+   * for having no `videoWidth` to size a surface from, and if nothing asks again a paused player
+   * shows no subtitles at all. `seeked` covers scrubbing while paused, and `pause` covers landing on
+   * a frame whose line arrived after it was presented.
+   *
+   * Trimming this list was tried and reverted. `['loadedmetadata']` alone fails
+   * `subtitle-paused-repaint.browser.test.tsx`'s turn-off case four runs out of four, while adding
+   * back EITHER of the other two passes. Neither of those events fires in that test, so what the
+   * extra listener buys is timing rather than a trigger, and the honest conclusion is that the clear
+   * after a `freeTrack` is more delicate than it looks. Do not shorten this list without running that
+   * case several times.
+   */
+  const REPAINT_ON = ['loadedmetadata', 'seeked', 'pause'] as const
+  const onRepaintEvent = () => repaint()
 
   const bootJassub = (header: SubtitleHeaderPart) => {
-    jassub = new JASSUB({
-      onDemandRender: false,
-      video,
-      canvas,
-      subContent: header.content,
-      workerUrl,
-      modernWasmUrl: wasmUrl,
-      ...legacyWasmUrl ? { wasmUrl: legacyWasmUrl } : {},
-      fonts: attachments.map(([, data]) => data),
-      availableFonts: {
-        ...Object.fromEntries(attachments),
-        ...(defaultFontUrl ? { 'liberation sans': defaultFontUrl } : {}),
-      },
-    })
-    // jassub 1.8.x binds setRate as the ratechange listener, so the Event becomes the rate
-    video.removeEventListener('ratechange', (jassub as unknown as { _boundSetRate: EventListener })._boundSetRate)
-    video.addEventListener('ratechange', onRateChange)
+    const canvas = document.createElement('canvas')
+    container.append(canvas)
+    try {
+      jassub = new JASSUB({
+        video,
+        canvas,
+        subContent: header.content,
+        workerUrl,
+        modernWasmUrl: wasmUrl,
+        ...legacyWasmUrl ? { wasmUrl: legacyWasmUrl } : {},
+        fonts: attachments.map(([, data]) => data),
+        availableFonts: {
+          ...Object.fromEntries(attachments),
+          ...(defaultFontUrl ? { 'liberation sans': defaultFontUrl } : {}),
+        },
+        // jassub 2 defaults this to 'local', which asks the browser for the local-fonts permission
+        // the first time libass reports a face it does not have. The container ships its own fonts
+        // and a player has no business raising that prompt.
+        queryFonts: false,
+      })
+    } catch (error) {
+      canvas.remove()
+      rendererFailed(error)
+      return
+    }
+    // A boot that fails worker-side rejects `ready`, and jassub's own ResizeObserver awaits `ready`
+    // on every layout change, so an instance left in that state throws a fresh unhandled rejection
+    // for the rest of the session.
+    void jassub.ready.catch(rendererFailed)
+    for (const type of REPAINT_ON) video.addEventListener(type, onRepaintEvent)
+    /*
+     * The default face is the one font jassub loads LAZILY. Attachments are handed to the constructor
+     * and `ready` waits for them, but `availableFonts` is consulted only when libass reports a
+     * missing face part way through a draw, and the fetch that follows lands after the frame that
+     * needed it. Driven by rVFC the next frame picks it up and the cost is one frame of unstyled
+     * text; PAUSED there is no next frame, so the first line stays unpainted until the viewer presses
+     * play. Measured as a RACE rather than a certainty: three runs of subtitle-header.browser.test.tsx
+     * against one repaint scored two blank and one painted.
+     *
+     * `addFonts` is the fix because it is a signal rather than a delay: it resolves when the face is
+     * in libass, which is the moment a repaint is worth asking for.
+     */
+    if (defaultFontUrl) {
+      onRenderer((renderer) => {
+        void Promise.resolve(renderer.addFonts([defaultFontUrl])).then(repaint, rendererFailed)
+      })
+    }
+    repaint()
   }
 
   const pushAttachments = (incoming: Attachment[]) => {
@@ -182,6 +319,7 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
   }
 
   const pushFragments = (fragments: SubtitleFragment[]) => {
+    const incoming: ASSEvent[] = []
     for (const fragment of fragments) {
       if (fragment.type === 'header') {
         if (headers.has(fragment.streamIndex)) continue
@@ -191,7 +329,7 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
         streams.push({ streamIndex: fragment.streamIndex, title: fragment.title, language: fragment.language })
         onStreams?.([...streams])
         if (selected === undefined) selected = fragment.streamIndex
-        if (!jassub) bootJassub(header)
+        if (!jassub && !destroyed) bootJassub(header)
       } else {
         const header = headers.get(fragment.streamIndex)
         if (!header) continue
@@ -200,21 +338,31 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
         const part = toDialoguePart(header, fragment)
         if (byIndex.has(part.index)) continue
         byIndex.set(part.index, part)
-        if (selected === fragment.streamIndex && jassub) createEvent(jassub, part.assEvent)
+        if (selected === fragment.streamIndex) incoming.push(part.assEvent)
       }
     }
+    if (!incoming.length) return
+    // one hop for the whole burst rather than one per event
+    onRenderer((renderer) => Promise.all(incoming.map((event) => renderer.createEvent(event))))
+    repaint()
   }
 
   const selectStream = (streamIndex: number | undefined) => {
     const next = streamIndex ?? SUBTITLES_OFF
     if (next === selected || !jassub) return
     selected = next
-    jassub.freeTrack()
     const header = headers.get(next)
-    if (!header) return
-    jassub.setTrack(header.content)
-    for (const part of dialogues.get(next)?.values() ?? []) createEvent(jassub, part.assEvent)
-    jassub.setCurrentTime(video.paused, video.currentTime, video.playbackRate)
+    const events = [...dialogues.get(next)?.values() ?? []].map((part) => part.assEvent)
+    onRenderer((renderer) => {
+      const calls: unknown[] = [renderer.freeTrack()]
+      if (header) {
+        calls.push(renderer.setTrack(header.content))
+        for (const event of events) calls.push(renderer.createEvent(event))
+      }
+      return Promise.all(calls)
+    })
+    // outside the callback so that turning subtitles OFF while paused clears the picture too
+    repaint()
   }
 
   return {
@@ -225,10 +373,14 @@ export const createSubtitleRenderer = (options: SubtitleRendererOptions) => {
     getSelectedStream: () => selected,
     setOnStreams: (cb: (streams: SubtitleStream[]) => void) => { onStreams = cb },
     destroy: () => {
-      clearInterval(tick)
-      video.removeEventListener('ratechange', onRateChange)
-      jassub?.destroy()
+      destroyed = true
+      const instance = jassub
       jassub = undefined
+      for (const type of REPAINT_ON) video.removeEventListener(type, onRepaintEvent)
+      // jassub removes its own canvas at the top of destroy(), before it awaits anything, so the
+      // element is gone synchronously. The rest is a worker round trip that a dead worker never
+      // answers, which is why nothing here waits for it.
+      void instance?.destroy().catch(() => {})
     },
   }
 }

package/src/lib/react/components/chrome.tsx

@@ -49,6 +49,19 @@ const style = css`
     z-index: 2;
   }
 
+  /* The subtitle layer sits UNDER the title and the spinner, where the canvas itself used to sit.
+     As a plain child div it is matched by the rule above and raised to the overlay items' level,
+     which paints subtitles over the title's gradient, over the spinner and over the error text.
+     Naming the type as well is what takes it back: :not() carries the specificity of its argument,
+     so the rule above is (0,2,1) and a bare .subtitles at (0,2,0) loses to it whatever the source
+     order, while div.subtitles ties at (0,2,1) and second place in the same block then wins.
+     subtitle-layering.browser.test.tsx measures the computed value rather than trusting this. */
+  & > div.subtitles {
+    inset: 0;
+    z-index: 1;
+    pointer-events: none;
+  }
+
   canvas {
     height: 100%;
     width: 100%;
@@ -93,7 +106,7 @@ export type ChromeProps = {
   ref?: Ref<HTMLDivElement> | ((element: HTMLDivElement | null) => void)
   /** Absent means render no video element: the media belongs to someone else and arrives as children. */
   onVideoRef?: (element: HTMLVideoElement | null) => void
-  onCanvasRef: (element: HTMLCanvasElement | null) => void
+  onSubtitleRef: (element: HTMLDivElement | null) => void
   /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
   overlay?: ReactNode
   /** False draws no control bar at all, leaving the picture, the title and the overlay. */
@@ -101,7 +114,7 @@ export type ChromeProps = {
   children?: ReactNode
 }
 
-export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, controls, children }: ChromeProps) => {
+export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, children }: ChromeProps) => {
   const player = usePlayer()
   const hideUI = usePlayer((state) => state.hideUI)
   const setHideUI = usePlayer((state) => state.setHideUI)
@@ -207,7 +220,7 @@ export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, controls, childr
       onMouseOut={onMouseOut}
       className={hideUI ? 'hide' : ''}
     >
-      <Overlay onCanvasRef={onCanvasRef} />
+      <Overlay onSubtitleRef={onSubtitleRef} />
       {overlayItems(overlay).map(({ key, item }) => (
         <div
           key={key}

package/src/lib/react/components/overlay.tsx

@@ -6,13 +6,32 @@ import { css, keyframes } from '@emotion/react'
 import { usePlayer } from '../player'
 import { fonts } from '../../utils/fonts'
 
+/**
+ * The subtitle layer.
+ *
+ * A container rather than the `<canvas>` this used to render. From jassub 2 the canvas belongs to
+ * the renderer: the constructor transfers it to a worker, which an element accepts exactly once for
+ * its whole life, and `destroy()` removes it from the document. React can own neither, and this
+ * pipeline is rebuilt in place on an audio track change and on an element recovery, so the canvas is
+ * created per jassub instance inside this box instead.
+ *
+ * The geometry is unchanged. The layer covers the picture and centres its child the way the chrome
+ * root centred the canvas directly, so jassub's inline pixel size still wins over the percentages
+ * and its inline `top` and `left` are still neutralised.
+ */
 const style = css`
-  top: unset !important;
-  left: unset !important;
-  width: 100%;
-  height: 100%;
-  margin: auto;
-  pointer-events: none;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+
+  canvas {
+    top: unset !important;
+    left: unset !important;
+    width: 100%;
+    height: 100%;
+    margin: auto;
+    pointer-events: none;
+  }
 `
 
 const titleStyle = css`
@@ -88,7 +107,7 @@ const errorMessage = (error: unknown) =>
     ? error.message
     : typeof error === 'string' ? error : 'Playback failed'
 
-export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElement | null) => void }) => {
+export const Overlay = ({ onSubtitleRef }: { onSubtitleRef: (element: HTMLDivElement | null) => void }) => {
   const title = usePlayer((state) => state.title)
   const hideUI = usePlayer((state) => state.hideUI)
   const playbackError = usePlayer((state) => state.playbackError)
@@ -120,7 +139,7 @@ export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElem
       {playbackError
         ? <div css={errorStyle}>{errorMessage(playbackError)}</div>
         : undefined}
-      <canvas ref={onCanvasRef} css={style} />
+      <div className="subtitles" ref={onSubtitleRef} css={style} />
     </>
   )
 }

package/src/lib/react/hooks/use-picture-in-picture.ts

@@ -19,10 +19,14 @@ export type PictureInPicture = {
  * hidden mirror. Where it does not, and the engine is Gecko, the same composite becomes the picture
  * in the page so that the BROWSER'S own picture in picture control carries the subtitles with it,
  * which it otherwise cannot: it takes a video element, and the subtitles live on a canvas above one.
+ *
+ * The second argument is the subtitle LAYER, not that canvas. From jassub 2 the canvas belongs to the
+ * renderer and is replaced on every pipeline rebuild, so only the layer lives long enough to hold.
  */
 export const usePictureInPicture = (
   video: HTMLVideoElement | null,
-  canvas: HTMLCanvasElement | null,
+  /** The subtitle layer, not the canvas: see `PictureInPictureOptions.subtitles`. */
+  subtitles: HTMLElement | null,
 ): PictureInPicture => {
   const controller = useRef<PictureInPictureController | null>(null)
   const [burnedIn, setBurnedIn] = useState(false)
@@ -31,10 +35,10 @@ export const usePictureInPicture = (
   const [mode] = useState<PictureInPictureMode | null>(() => pictureInPictureMode())
 
   useEffect(() => {
-    if (!video || !canvas || !mode) return
+    if (!video || !subtitles || !mode) return
     const instance = createPictureInPicture({
       video,
-      canvas,
+      subtitles,
       mode,
       onBurnedInChange: setBurnedIn,
     })
@@ -44,7 +48,7 @@ export const usePictureInPicture = (
       controller.current = null
       setBurnedIn(false)
     }
-  }, [video, canvas, mode])
+  }, [video, subtitles, mode])
 
   const toggle = useCallback(() => {
     void controller.current?.toggle().catch((error) => {
@@ -53,6 +57,6 @@ export const usePictureInPicture = (
   }, [])
 
   // null rather than a dead callback: the chrome hides the control instead of offering one that
-  // cannot work, and there is nothing to composite without both an element and a canvas.
-  return { toggle: video && canvas && mode ? toggle : null, mode, burnedIn }
+  // cannot work, and there is nothing to composite without both a video and a subtitle layer.
+  return { toggle: video && subtitles && mode ? toggle : null, mode, burnedIn }
 }

package/src/lib/react/hooks/use-playback.ts

@@ -64,7 +64,7 @@ const causeChain = (error: unknown) => {
  */
 export const usePlayback = (
   video: HTMLVideoElement | null,
-  canvas: HTMLCanvasElement | null,
+  subtitles: HTMLElement | null,
   /** null when the media is remote: there are no bytes, so there is no pipeline to run. */
   options: MediaPlayerLocalOptions | null,
 ) => {
@@ -227,7 +227,7 @@ export const usePlayback = (
   }, [setSourceState, selectSubtitleTrack, selectAudioTrack, requestSeek])
 
   useEffect(() => {
-    if (!video || !canvas || !size || !read) return
+    if (!video || !subtitles || !size || !read) return
     let cancelled = false
     player.setSourceState({ playbackError: null, ready: false })
 
@@ -293,7 +293,7 @@ export const usePlayback = (
       try {
         const controller = await startPlayback({
           videoElement: video,
-          canvasElement: canvas,
+          subtitleContainer: subtitles,
           read: (offset, length) => readRef.current!(offset, length),
           length: size,
           publicPath,
@@ -355,7 +355,7 @@ export const usePlayback = (
     // identity. A streaming consumer passes a fresh closure on every state update, which is several
     // times a second, and the restart loop reads as "Loading metadata" forever at a flat 0 B/s.
   }, [
-    player, video, canvas, size, publicPath, libavWorkerUrl, jassubWorkerUrl, jassubWasmUrl,
+    player, video, subtitles, size, publicPath, libavWorkerUrl, jassubWorkerUrl, jassubWasmUrl,
     jassubLegacyWasmUrl, defaultFontUrl, bufferSize, audioStreamIndex, autoplay, restartToken,
   ])
 }

package/src/lib/react/video-player.tsx

@@ -194,7 +194,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   const setContainer = useContainerAttach()
 
   const [video, setVideo] = useState<HTMLVideoElement | null>(null)
-  const [canvas, setCanvas] = useState<HTMLCanvasElement | null>(null)
+  const [subtitleLayer, setSubtitleLayer] = useState<HTMLDivElement | null>(null)
 
   // Attaching is not optional in either arm: the store installs `setSourceState` in `attach`, and
   // video.js only runs attach once media is non-null, so skipping it would leave every write below a
@@ -235,7 +235,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
 
   // Each of these no-ops on null inputs, which is what a remote arm supplies: it renders no <video>,
   // so there is nothing for them to attach to and nothing to guard at the call site.
-  usePlayback(video, canvas, local)
+  usePlayback(video, subtitleLayer, local)
 
   const generatedThumbnails = useSeekThumbnails({
     publicPath,
@@ -249,7 +249,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     toggle: togglePictureInPicture,
     mode: pictureInPictureMode,
     burnedIn: burnedInSubtitles,
-  } = usePictureInPicture(video, canvas)
+  } = usePictureInPicture(video, subtitleLayer)
 
   // Subscribed rather than read off the store, because it is a no-op until the media element
   // attaches: when attach swaps in the real setter the identity changes and these publish again.
@@ -305,7 +305,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
       // No element in the remote arm: the media is somebody else's, and whatever renders it is
       // passed in as children. Rendering an idle <video> here would sit over it.
       onVideoRef={remote ? undefined : setVideo}
-      onCanvasRef={setCanvas}
+      onSubtitleRef={setSubtitleLayer}
       overlay={options.overlay}
       controls={options.controls}
     >