@banou/media-player 0.8.5 → 0.8.7

package/dist/react/components/burn-in-hint.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Says what to do next, because turning burn-in on looks like nothing happening.
+ *
+ * The composite is pixel identical to the picture it replaces, so without this the click has no
+ * visible result at all and the viewer has no way to learn that the browser's own picture in picture
+ * control is now the thing to press.
+ */
+export declare const BurnInHint: () => import("@emotion/react/jsx-runtime").JSX.Element | null;
+export default BurnInHint;

package/dist/react/components/icons.d.ts

@@ -2,3 +2,11 @@ import type { SVGProps } from 'react';
 export declare const Captions: (props: SVGProps<SVGSVGElement>) => import("@emotion/react/jsx-runtime").JSX.Element;
 /** The slash is Feather's own convention for an off state, the line `MicOff` and `BellOff` draw. */
 export declare const CaptionsOff: (props: SVGProps<SVGSVGElement>) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * Subtitles inside the picture: the picture-in-picture frame with caption bars in the inset.
+ *
+ * A separate glyph on purpose. The control means something different on a browser that cannot open
+ * a window, and the same icon doing two things silently is the thing to avoid. It is not the plain
+ * captions glyph either, because the button beside it already is one.
+ */
+export declare const SubtitlesInPicture: (props: SVGProps<SVGSVGElement>) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/react/hooks/use-picture-in-picture.d.ts

@@ -1,2 +1,17 @@
-/** Picture in picture with the subtitles composited in. */
-export declare const usePictureInPicture: (video: HTMLVideoElement | null, canvas: HTMLCanvasElement | null) => (() => void) | null;
+import type { PictureInPictureMode } from '../../engine';
+export type PictureInPicture = {
+    /** null when nothing here can work, and the chrome then offers no control at all. */
+    toggle: (() => void) | null;
+    mode: PictureInPictureMode | null;
+    /** Burn-in only. True while the composite is the picture on screen. */
+    burnedIn: boolean;
+};
+/**
+ * Picture in picture with the subtitles composited in.
+ *
+ * Two shapes, because two kinds of browser. Where the W3C API exists this opens a real window off a
+ * 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.
+ */
+export declare const usePictureInPicture: (video: HTMLVideoElement | null, canvas: HTMLCanvasElement | null) => PictureInPicture;

package/dist/react/player.d.ts

@@ -15,6 +15,8 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     hideUI: boolean;
     setHideUI: (hide: boolean) => void;
     togglePictureInPicture: (() => void) | null;
+    pictureInPictureMode: import("../engine").PictureInPictureMode | null;
+    burnedInSubtitles: boolean;
     playbackError: unknown;
     ready: boolean;
     setSourceState: (partial: Partial<import("./source-feature").SourceState>) => void;

package/dist/react/source-feature.d.ts

@@ -1,4 +1,4 @@
-import type { MediaIndex, ThumbnailImage } from '../engine';
+import type { MediaIndex, PictureInPictureMode, ThumbnailImage } from '../engine';
 /**
  * One row of a track menu, already named.
  *
@@ -78,6 +78,14 @@ export type SourceState = {
      * button that toggles nothing and never lights up is worse than no button.
      */
     togglePictureInPicture: (() => void) | null;
+    /**
+     * Which shape the control takes. `window` opens one. `burn-in` cannot, and instead paints the
+     * subtitles into the picture so the BROWSER'S own control carries them; the viewer presses that
+     * one afterwards, so the button has to say something different. null means no control.
+     */
+    pictureInPictureMode: PictureInPictureMode | null;
+    /** Burn-in only. True while the composite is the picture on screen. */
+    burnedInSubtitles: boolean;
     /** Set when the pipeline fails. Cleared when it recovers. */
     playbackError: unknown;
     /** Whether the engine has produced its first media segment. */
@@ -136,6 +144,14 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
      * button that toggles nothing and never lights up is worse than no button.
      */
     togglePictureInPicture: (() => void) | null;
+    /**
+     * Which shape the control takes. `window` opens one. `burn-in` cannot, and instead paints the
+     * subtitles into the picture so the BROWSER'S own control carries them; the viewer presses that
+     * one afterwards, so the button has to say something different. null means no control.
+     */
+    pictureInPictureMode: PictureInPictureMode | null;
+    /** Burn-in only. True while the composite is the picture on screen. */
+    burnedInSubtitles: boolean;
     /** Set when the pipeline fails. Cleared when it recovers. */
     playbackError: unknown;
     /** Whether the engine has produced its first media segment. */

package/dist/utils/colors.d.ts

@@ -2,6 +2,8 @@ declare const colors: {
     primary: string;
     secondary: string;
     hover: string;
+    /** A control that is ON. Distinct from `hover`, which the pointer is already painting. */
+    accent: string;
     borderPrimary: string;
     backgroundTooltip: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",

package/src/lib/engine/index.ts

@@ -10,5 +10,5 @@ export type { ThumbnailGenerator, ThumbnailGeneratorOptions, ThumbnailImage } fr
 export { getTimeRanges, updateSourceBuffer } from './source-buffer'
 export type { TimeRange } from './source-buffer'
 
-export { createPictureInPicture } from './picture-in-picture'
-export type { PictureInPictureController, PictureInPictureOptions } from './picture-in-picture'
+export { createPictureInPicture, pictureInPictureMode } from './picture-in-picture'
+export type { PictureInPictureController, PictureInPictureOptions, PictureInPictureMode } from './picture-in-picture'

package/src/lib/engine/picture-in-picture.ts

@@ -8,26 +8,40 @@
  */
 
 const DEFAULT_MAX_WIDTH = 1280
+/**
+ * Burn-in becomes the picture the viewer actually watches, so it gets a higher ceiling than the
+ * thumbnail-sized window does. A 4K source is still halved; see the note on `compositeWidth`.
+ */
+const BURN_IN_MAX_WIDTH = 1920
 /** The frame callback fires only for presented frames, so a paused video needs its own repaint. */
 const PAUSED_REPAINT_INTERVAL = 250
+/** Long enough for a paused mirror to present one frame of a fresh seek before it stops again. */
+const FLUSH_FRAME_MS = 100
+
+/**
+ * `window` opens a real picture in picture window. `burn-in` cannot, and instead paints the
+ * composite into the player itself so the browser's OWN picture in picture control carries the
+ * subtitles with it.
+ */
+export type PictureInPictureMode = 'window' | 'burn-in'
 
 export type PictureInPictureOptions = {
   video: HTMLVideoElement
   /** The subtitle canvas. jassub sizes it to the video's content rect, so it maps 1:1. */
   canvas: HTMLCanvasElement
   maxWidth?: number
-  /** Where the hidden mirror is mounted. It must be in the document. Defaults to the video's parent. */
+  /** Where the mirror is mounted. It must be in the document. Defaults to the video's parent. */
   container?: HTMLElement
-  /**
-   * Toggle used when compositing is unavailable or fails. The React layer passes the player store's
-   * own action, which handles Safari and exits fullscreen first; the default here does neither.
-   */
-  fallback?: () => Promise<void>
+  /** Overrides detection. Passing a mode the browser cannot honour is the caller's problem. */
+  mode?: PictureInPictureMode
+  /** Burn-in only, so the chrome can light the control up and say what happened. */
+  onBurnedInChange?: (burnedIn: boolean) => void
 }
 
 export type PictureInPictureController = {
   toggle: () => Promise<void>
   destroy: () => void
+  mode: PictureInPictureMode
 }
 
 type Session = {
@@ -37,26 +51,64 @@ type Session = {
   mirror: HTMLVideoElement
 }
 
-const supportsCompositing = () =>
-  typeof HTMLCanvasElement !== 'undefined' &&
-  'captureStream' in HTMLCanvasElement.prototype &&
+const canComposite = () =>
+  typeof HTMLCanvasElement !== 'undefined' && 'captureStream' in HTMLCanvasElement.prototype
+
+/**
+ * `pictureInPictureEnabled` alone is not enough: a permissions policy can withhold it on a browser
+ * that implements the API perfectly well, and the prototype method is not suppressible. Requiring
+ * both keeps a restricted frame out of `burn-in`, which is for browsers that CANNOT open a window
+ * rather than for ones that are merely not allowed to.
+ */
+const canOpenWindow = () =>
   typeof document !== 'undefined' &&
-  document.pictureInPictureEnabled
+  typeof HTMLVideoElement !== 'undefined' &&
+  typeof HTMLVideoElement.prototype.requestPictureInPicture === 'function' &&
+  !!document.pictureInPictureEnabled
+
+/**
+ * Gecko, by a capability no other engine has and no policy can take away. A UA string would be
+ * wrong twice over: it lies, and this has to stop applying the day Firefox ships the real API.
+ */
+const isGecko = () =>
+  typeof HTMLVideoElement !== 'undefined' && 'mozCaptureStream' in HTMLVideoElement.prototype
+
+/**
+ * null means offer no control at all. That covers Safari, whose picture in picture is
+ * `webkitSetPresentationMode` and not the W3C API, so neither arm here can drive it. A dead button
+ * is worse than no button.
+ */
+export const pictureInPictureMode = (): PictureInPictureMode | null => {
+  if (!canComposite()) return null
+  if (canOpenWindow()) return 'window'
+  if (isGecko()) return 'burn-in'
+  return null
+}
 
 /** Takes over the document's Media Session play/pause handlers while a session is open. */
 export const createPictureInPicture = (options: PictureInPictureOptions): PictureInPictureController => {
-  const { video, canvas, maxWidth = DEFAULT_MAX_WIDTH } = options
+  const { video, canvas } = options
+  const mode = options.mode ?? pictureInPictureMode() ?? 'window'
+  const maxWidth = options.maxWidth ?? (mode === 'burn-in' ? BURN_IN_MAX_WIDTH : DEFAULT_MAX_WIDTH)
 
   let session: Session | undefined
   let handle: number | undefined
   let pausedRepaint: ReturnType<typeof setInterval> | undefined
   let syncing = false
+  /** Burn-in only: a deliberate play/pause pair to push one frame, which must not reach the video. */
+  let flushing = false
   // Nothing can tell a session is being built until `enter` resolves, so without this a second click
-  // starts a second pipeline whose timer and mirror are then unreachable.
-  let entering = false
+  // starts a second pipeline whose timer and mirror are then unreachable. It covers EVERY branch of
+  // `toggle`, not only the one that builds a session.
+  let busy = false
   let destroyed = false
+  let restore: (() => void) | undefined
 
-  const active = () => !!session && document.pictureInPictureElement === session.mirror
+  // In burn-in there is no window to be in: the session itself IS the mode being on.
+  const active = () =>
+    mode === 'burn-in'
+      ? !!session
+      : !!session && document.pictureInPictureElement === session.mirror
 
   const draw = (composite: HTMLCanvasElement, context: CanvasRenderingContext2D) => {
     context.drawImage(video, 0, 0, composite.width, composite.height)
@@ -98,15 +150,23 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
   }
 
   const onMirrorPlay = () => {
-    if (syncing || !video.paused) return
+    if (syncing || flushing || !video.paused) return
     void video.play().catch(() => {})
   }
 
-  // Reached on a browser whose window controls pause the mirror directly instead of going through the
-  // Media Session. Forward the intent, then put the mirror back to work.
+  /**
+   * Reached on a browser whose window controls drive the popped out element directly instead of going
+   * through the Media Session. Firefox is that browser, and in burn-in its window is driving the
+   * element the viewer is watching, so its pause IS the intent and has to stick.
+   *
+   * Both arms are idempotent by comparing against the video rather than by holding a flag: if the
+   * video is already paused this event is the echo of our own `mirror.pause()` and means nothing.
+   */
   const onMirrorPause = () => {
-    if (syncing) return
+    if (syncing || flushing) return
     if (!video.paused) video.pause()
+    // In window mode the mirror must never be left paused; see `onVideoPause`.
+    if (mode === 'burn-in') return
     syncing = true
     void session?.mirror.play().catch(() => {}).finally(() => { syncing = false })
   }
@@ -117,12 +177,34 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
   }
 
   /**
-   * NEVER pause the mirror. A paused element stops rendering its MediaStream, so the window freezes on
-   * its last frame: measured at 0 of 57,600 pixels moving on a seek. Transport state travels through
-   * the Media Session instead, which is what the window reads for its button.
+   * In WINDOW mode, never pause the mirror. A paused element stops rendering its MediaStream, so the
+   * window freezes on its last frame: measured at 0 of 57,600 pixels moving on a seek. Transport
+   * state travels through the Media Session instead, which is what the window reads for its button.
+   *
+   * In BURN-IN the mirror must follow the video exactly, or the browser's own window shows "playing"
+   * over a picture that is not moving and its pause button can never resume. A frozen mirror is
+   * correct there because the picture is not moving either; `onVideoSeeked` covers the one case where
+   * the frame has to change while paused.
    */
   const onVideoPause = () => {
     publishState()
+    if (mode === 'burn-in') session?.mirror.pause()
+  }
+
+  /** A paused mirror renders nothing, so a scrub would leave the old frame on screen forever. */
+  const onVideoSeeked = () => {
+    if (mode !== 'burn-in' || !session || !video.paused || flushing) return
+    flushing = true
+    const { mirror } = session
+    paint()
+    void mirror.play()
+      .then(() => new Promise<void>((resolve) => { setTimeout(resolve, FLUSH_FRAME_MS) }))
+      .catch(() => {})
+      .finally(() => {
+        mirror.pause()
+        // the pause event is queued, so the guard has to outlive this tick
+        setTimeout(() => { flushing = false }, FLUSH_FRAME_MS)
+      })
   }
 
   const mediaSessionActions: [MediaSessionAction, MediaSessionActionHandler][] = [
@@ -146,7 +228,12 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
     bindMediaSession(false)
     video.removeEventListener('play', onVideoPlay)
     video.removeEventListener('pause', onVideoPause)
-    if (!session) return
+    video.removeEventListener('seeked', onVideoSeeked)
+    if (!session) {
+      // a burn-in that never built a session can still have swapped the picture
+      restore?.()
+      return
+    }
     const { stream, mirror } = session
     mirror.removeEventListener('play', onMirrorPlay)
     mirror.removeEventListener('pause', onMirrorPause)
@@ -154,14 +241,33 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
     for (const track of stream.getTracks()) track.stop()
     mirror.remove()
     session = undefined
+    // AFTER the mirror is gone. Restoring first puts the real picture and the overlay back while the
+    // composite is still mounted and painting, which is the doubled subtitles this mode exists to avoid.
+    restore?.()
   }
 
   const onLeave = () => teardown()
 
-  const fallback = options.fallback ?? (async () => {
-    if (document.pictureInPictureElement === video) await document.exitPictureInPicture()
-    else await video.requestPictureInPicture()
-  })
+  /**
+   * Swap the composite in as the player's picture.
+   *
+   * The real element is dimmed, never `display: none`: jassub sizes the subtitle canvas from its
+   * `offsetWidth`/`offsetHeight`, and a collapsed box silently yields a composite with no subtitles
+   * in it, which is exactly the thing being asked for.
+   */
+  const present = (mirror: HTMLVideoElement) => {
+    const videoOpacity = video.style.opacity
+    const canvasDisplay = canvas.style.display
+    mirror.style.cssText =
+      'position:absolute;inset:0;width:100%;height:100%;object-fit:contain;background:#000;z-index:1'
+    video.style.opacity = '0'
+    canvas.style.display = 'none'
+    restore = () => {
+      restore = undefined
+      video.style.opacity = videoOpacity
+      canvas.style.display = canvasDisplay
+    }
+  }
 
   const enter = async () => {
     // Sized off the intrinsic dimensions, never the layout, so a resize cannot resize a canvas that a
@@ -180,13 +286,17 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
     const mirror = document.createElement('video')
     mirror.muted = true
     mirror.playsInline = true
-    mirror.style.cssText = 'position:fixed;width:1px;height:1px;opacity:0;pointer-events:none;left:-1px;top:-1px'
+    // Burn-in gets its real size from `present`. Firefox will not offer its own control below 140px
+    // in either dimension, so the 1px parking spot the window arm uses can never qualify.
+    if (mode === 'burn-in') present(mirror)
+    else mirror.style.cssText = 'position:fixed;width:1px;height:1px;opacity:0;pointer-events:none;left:-1px;top:-1px'
 
     // one frame before the capture starts, so the stream has content from its first moment
     draw(composite, context)
 
-    session = { composite, context, stream: composite.captureStream(), mirror }
-    mirror.srcObject = session.stream
+    const mine: Session = { composite, context, stream: composite.captureStream(), mirror }
+    session = mine
+    mirror.srcObject = mine.stream
     ;(options.container ?? video.parentElement ?? document.body).appendChild(mirror)
 
     schedule()
@@ -203,48 +313,72 @@ export const createPictureInPicture = (options: PictureInPictureOptions): Pictur
       })
     }
 
+    // A destroy or a re-entered toggle can land inside that wait. Binding anyway would leave listeners
+    // and a Media Session handler pointing at a dead session for the rest of the page's life.
+    if (destroyed || session !== mine) {
+      mirror.remove()
+      return
+    }
+
     mirror.addEventListener('play', onMirrorPlay)
     mirror.addEventListener('pause', onMirrorPause)
     mirror.addEventListener('leavepictureinpicture', onLeave)
     video.addEventListener('play', onVideoPlay)
     video.addEventListener('pause', onVideoPause)
+    video.addEventListener('seeked', onVideoSeeked)
     bindMediaSession(true)
     publishState()
 
+    if (mode === 'burn-in') {
+      // No window to open: the browser's own control does that, on the element now on screen.
+      if (video.paused) mirror.pause()
+      options.onBurnedInChange?.(true)
+      return
+    }
+
     await mirror.requestPictureInPicture()
   }
 
   const toggle = async () => {
-    if (destroyed || entering) return
-    if (active()) {
-      await document.exitPictureInPicture().catch(() => {})
-      return
-    }
-    if (!supportsCompositing()) {
-      await fallback()
-      return
-    }
-    // another element, including our own last mirror, may still hold the single slot
-    if (document.pictureInPictureElement) await document.exitPictureInPicture().catch(() => {})
-
-    entering = true
+    if (destroyed || busy) return
+    busy = true
     try {
-      await enter()
-    } catch (error) {
-      console.warn('subtitle compositing for picture in picture failed, falling back', error)
-      teardown()
-      await fallback().catch(() => {})
+      if (active()) {
+        if (mode === 'burn-in') {
+          teardown()
+          options.onBurnedInChange?.(false)
+          return
+        }
+        await document.exitPictureInPicture().catch(() => {})
+        return
+      }
+      // another element, including our own last mirror, may still hold the single slot
+      if (mode !== 'burn-in' && document.pictureInPictureElement) {
+        await document.exitPictureInPicture().catch(() => {})
+      }
+
+      try {
+        await enter()
+      } catch (error) {
+        // There is nowhere left to fall back TO. The old fallback called the React layer's own
+        // toggle, which is this function, so an unsupported browser recursed until the stack blew.
+        console.warn('subtitle compositing for picture in picture failed', error)
+        teardown()
+        if (mode === 'burn-in') options.onBurnedInChange?.(false)
+      }
     } finally {
-      entering = false
+      busy = false
     }
   }
 
   return {
     toggle,
+    mode,
     destroy: () => {
       destroyed = true
-      if (active()) void document.exitPictureInPicture().catch(() => {})
+      if (mode !== 'burn-in' && active()) void document.exitPictureInPicture().catch(() => {})
       teardown()
+      if (mode === 'burn-in') options.onBurnedInChange?.(false)
     },
   }
 }

package/src/lib/engine/playback.ts

@@ -329,7 +329,35 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     videoElement.addEventListener('seeking', onSeeking)
     teardown.push(() => videoElement.removeEventListener('seeking', onSeeking))
 
+    /**
+     * A terminal failure of the media element, which NOTHING here used to observe.
+     *
+     * `MediaError` is set once and the element never plays again, but the pump below kept running,
+     * and every `appendBuffer` after it throws `InvalidStateError: The HTMLMediaElement.error
+     * attribute is not null`. `updateSourceBuffer`'s chain deliberately survives a rejection, so that
+     * repeated forever, and `flushPending` swallows four attempts and rethrows the fifth. What
+     * reached the viewer was therefore the FIFTH `InvalidStateError` rather than the real cause, and
+     * the real cause never appeared anywhere at all.
+     *
+     * That cost a session: a decode failure presented as an append bug, which is a completely
+     * different place to look. Report what actually happened, then stop.
+     */
+    let elementFailed = false
+    const onElementError = () => {
+      if (elementFailed) return
+      elementFailed = true
+      const error = videoElement.error
+      reportError(
+        new Error(`the media element failed: ${error?.message ?? 'unknown'}`, { cause: error }),
+        false,
+      )
+    }
+    videoElement.addEventListener('error', onElementError)
+    teardown.push(() => videoElement.removeEventListener('error', onElementError))
+
     const interval = setInterval(() => {
+      // Nothing below can succeed against a failed element, and retrying only buries the real error.
+      if (elementFailed || videoElement.error) return
       evict().catch(() => {})
       pump().catch((error) => reportError(error, false))
       // every remove() puts the MediaSource back to 'open', so the end has to be re-armed

package/src/lib/react/components/burn-in-hint.tsx

@@ -0,0 +1,105 @@
+import { useEffect, useState } from 'react'
+import { css } from '@emotion/react'
+
+import { fonts } from '../../utils/fonts'
+import { usePlayer } from '../player'
+
+/** Long enough to read twice, short enough not to sit over the picture. */
+const VISIBLE_MS = 9000
+
+const style = css`
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  pointer-events: none;
+
+  .card {
+    position: absolute;
+    /* Where Firefox draws its own toggle: right aligned, a little past the middle of the height. */
+    top: 52%;
+    right: calc(7 * var(--mp-unit));
+    transform: translateY(-50%);
+
+    display: flex;
+    align-items: center;
+    gap: calc(1.2 * var(--mp-unit));
+
+    max-width: min(calc(42 * var(--mp-unit)), 60%);
+    padding: calc(1.4 * var(--mp-unit)) calc(1.8 * var(--mp-unit));
+    border-radius: calc(0.8 * var(--mp-unit));
+    background-color: rgba(20, 20, 22, 0.94);
+    box-shadow: 0 0 calc(2 * var(--mp-unit)) rgba(0, 0, 0, 0.6);
+
+    opacity: 0;
+    transition: opacity 0.25s ease;
+  }
+
+  &.show .card {
+    opacity: 1;
+  }
+
+  .words {
+    display: flex;
+    flex-direction: column;
+    gap: calc(0.3 * var(--mp-unit));
+  }
+
+  .title {
+    ${fonts.bMedium.bold}
+    color: #fff;
+  }
+
+  .body {
+    ${fonts.bSmall.regular}
+    color: rgba(255, 255, 255, 0.75);
+  }
+
+  /* Points at the edge the browser's control lives on, which is the whole message. */
+  .arrow {
+    flex: none;
+    font-size: calc(2.6 * var(--mp-unit));
+    line-height: 1;
+    color: #6EA8FE;
+  }
+`
+
+/**
+ * Says what to do next, because turning burn-in on looks like nothing happening.
+ *
+ * The composite is pixel identical to the picture it replaces, so without this the click has no
+ * visible result at all and the viewer has no way to learn that the browser's own picture in picture
+ * control is now the thing to press.
+ */
+export const BurnInHint = () => {
+  const burnedInSubtitles = usePlayer((state) => state.burnedInSubtitles)
+  const mode = usePlayer((state) => state.pictureInPictureMode)
+  const [show, setShow] = useState(false)
+
+  useEffect(() => {
+    if (mode !== 'burn-in' || !burnedInSubtitles) {
+      setShow(false)
+      return
+    }
+    setShow(true)
+    const timer = setTimeout(() => setShow(false), VISIBLE_MS)
+    return () => clearTimeout(timer)
+  }, [mode, burnedInSubtitles])
+
+  if (mode !== 'burn-in' || !burnedInSubtitles) return null
+
+  return (
+    <div css={style} className={show ? 'show' : ''} role='status'>
+      <div className='card'>
+        <div className='words'>
+          <div className='title'>Subtitles are in the picture</div>
+          <div className='body'>
+            Now hover the video and click your browser&apos;s own pop out button
+          </div>
+        </div>
+        <div className='arrow' aria-hidden='true'>&rarr;</div>
+      </div>
+    </div>
+  )
+}
+
+export default BurnInHint

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

@@ -7,6 +7,7 @@ import { css } from '@emotion/react'
 import { usePlayer } from '../player'
 import { Overlay } from './overlay'
 import ControlBar from './control-bar'
+import BurnInHint from './burn-in-hint'
 
 const AUTO_HIDE_DELAY = 3_000
 
@@ -173,6 +174,8 @@ export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, controls, childr
         </div>
       ))}
       {controls === false ? null : <ControlBar />}
+      {/* Not tied to `hideUI`: it says what to do next, and it is on screen for nine seconds. */}
+      <BurnInHint />
       <div className="video" onClick={onVideoClick}>
         {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}
         {children}