@banou/media-player 0.8.21 → 0.10.0

package/README.md

@@ -22,9 +22,9 @@ import MediaPlayer from '@banou/media-player'
   publicPath="/"
   libavWorkerUrl="/libav-worker.js"
   jassubWorkerUrl={jassubWorkerUrl}
-  jassubWasmUrl="/jassub-worker-modern.wasm"
-  jassubLegacyWasmUrl="/jassub-worker.wasm"
-  defaultFontUrl="/default.woff2"
+  jassubWasmUrl={jassubWasmUrl}
+  jassubLegacyWasmUrl={jassubLegacyWasmUrl}
+  defaultFontUrl={defaultFontUrl}
   title="episode.mkv"
   autoplay
 />
@@ -58,15 +58,23 @@ player.play()
 
 `useSeekThumbnails` and `usePictureInPicture` are exported for reuse outside the bundled chrome.
 
+`useSeekThumbnails` returns `{ thumbnails, requestThumbnail }`. Previews are generated from the start
+of the file to the end, which is right until somebody points at the seekbar: `requestThumbnail(time)`
+moves the preview covering `time` to the front of that queue, and the walk carries on behind it from
+wherever it had got to. Pass `undefined` when the pointer leaves. The bundled seekbar calls it for
+you, so this is only for a chrome you draw yourself. It cannot interrupt a decode already in flight,
+so the wait is the tail of that one rather than the whole backlog.
+
 `downloadedRanges` paints byte spans you already hold onto the seekbar, mapped through the keyframe
 index rather than by percentage, because a file's download progress is not its playback progress:
 containers carry headers, fonts and attachments that occupy no time at all.
 
 ### The assets your app has to serve
 
-Nothing is bundled: the workers and the wasm are fetched at runtime from urls you provide, so they have
-to be copied out of `node_modules` and hosted. `src/asset-urls.ts` is a worked example, and the
-`copy-assets` script is what puts them in `public/`.
+The workers and the wasm are fetched at runtime from urls you provide, never from anything this
+package resolves for itself. libav's are plain files to copy out of `node_modules`, which is what the
+`copy-assets` script does. jassub's cannot be copied and have to be built by your bundler; see below.
+`src/asset-urls.ts` is the worked example for both.
 
 `publicPath` is the directory **libav's two wasm files** are served from, and both have to be there:
 
@@ -79,25 +87,62 @@ libav-wasm picks between them at runtime on `typeof WebAssembly.Suspending === '
 only one does not fail everywhere: it fails on exactly the browsers that pick the missing file, which
 reads as a browser bug rather than a missing asset. Serve both.
 
-The rest are named individually: `libavWorkerUrl` (`libav-wasm/build/worker.js`) and the optional
-`defaultFontUrl`. jassub also has two builds, and the same warning applies:
+`libavWorkerUrl` (`libav-wasm/build/worker.js`) is named individually and still copies fine.
+
+### jassub's assets are imported, not copied
+
+jassub 2's worker is an ES module that imports `abslink` and `lfa-ponyfill` by bare specifier plus
+five relative siblings, and it spawns a nested worker of its own. Copying one file out of
+`node_modules` produces something no browser can load, so the bundler has to build that graph. With
+vite that is one query each, in your own source:
+
+```ts
+import jassubWorkerUrl from 'jassub/dist/worker/worker.js?worker&url'
+import jassubWasmUrl from 'jassub/dist/wasm/jassub-worker-modern.wasm?no-inline&url'
+import jassubLegacyWasmUrl from 'jassub/dist/wasm/jassub-worker.wasm?no-inline&url'
+import defaultFontUrl from 'jassub/dist/default.woff2?no-inline&url'
+```
+
+`?no-inline` is load bearing for anything built with `build.lib` set: vite inlines every asset as a
+base64 data url in library mode and ignores `assetsInlineLimit` while doing it, so without it the two
+wasm builds and the font land in your entry chunk as about 5.9 MB of base64. `src/asset-urls.ts` in
+this repo is the same four lines and is meant to be copied.
+
+**If you build with `build.lib` set, build these four in a separate pass with it UNSET.** `?no-inline`
+covers the assets you name, and it cannot cover the ones jassub names for itself: its emscripten glue
+resolves the wasm with `new URL('./wasm/...', import.meta.url)` inside the worker, and lib mode inlines
+those too. Measured on this version, one entry importing exactly the four lines above:
+
+| build | worker chunk | base64 wasm blobs |
+| --- | --- | --- |
+| `build.lib` set | 2,922,207 bytes | 2 |
+| no `build.lib` | 110,525 bytes | 0 |
+
+`assetsInlineLimit: 0` and the function form both make no difference, because lib mode decides to
+inline before it consults either. A second vite config with a single JS entry, no `lib`, and the same
+`outDir` produces the 110 KB worker, the 30 KB pthread glue and both wasm files as real files.
+
+`?no-inline&url` needs a type declaration, because vite's own ambient `*?url` only matches a specifier
+ENDING in `?url`. See `src/vite-env.d.ts`.
+
+The two wasm builds are picked at runtime:
 
 | option | file | when it is used |
 | --- | --- | --- |
-| `jassubWasmUrl` | `jassub/dist/jassub-worker-modern.wasm` | wherever WebAssembly SIMD exists |
-| `jassubLegacyWasmUrl` | `jassub/dist/jassub-worker.wasm` | Safari before 16.4, and anything else without SIMD |
+| `jassubWasmUrl` | `jassub/dist/wasm/jassub-worker-modern.wasm` | wherever RELAXED SIMD exists |
+| `jassubLegacyWasmUrl` | `jassub/dist/wasm/jassub-worker.wasm` | everywhere else |
 
-`jassubLegacyWasmUrl` is optional in the type and not in practice: jassub falls back to a bare
-`'jassub-worker.wasm'`, which it resolves against the `blob:` url its worker is built from, and that
-throws. Leaving it unset does not fall back to the slower build, it loses subtitles entirely.
+The test is RELAXED simd, not baseline simd: jassub validates a module using `i8x16.relaxed_swizzle`.
+That is a much later feature than plain SIMD, so the second file is not a museum piece for ancient
+Safari the way it was under jassub 1. Serve both.
 
-jassub ships a classic worker script, so wrap it:
+Serve the wasm as `application/wasm`: jassub instantiates it with `instantiateStreaming`, which
+refuses any other content type.
 
-```ts
-const jassubWorkerUrl = URL.createObjectURL(
-  new Blob([`importScripts("/jassub-worker.js")`], { type: 'application/javascript' }),
-)
-```
+No cross-origin isolation is needed. jassub allocates a shared `WebAssembly.Memory` unconditionally,
+which constructs on a plain origin in both engines (measured on Chrome 152 and Firefox 154), and its
+own thread count is gated on `crossOriginIsolated`, so without COOP and COEP it simply runs single
+threaded.
 
 The chrome brings its own scale and needs nothing from the host page's root font. Everything is sized
 against `--mp-unit`, which defaults to `10px` on the player element; set it there to rescale the whole
@@ -116,6 +161,11 @@ Subtitles are painted by jassub onto a canvas over the video, and picture in pic
 element and nothing else, so the browser has no way to composite the two: a plain
 `requestPictureInPicture()` puts the bare video in the window and leaves the subtitles on the page.
 
+That canvas belongs to jassub from version 2 on: the constructor transfers it to a worker, which an
+element accepts exactly once, and `destroy()` removes it from the document. So the player renders a
+subtitle LAYER and the engine mounts one canvas inside it per pipeline build. Anything reaching for
+the surface has to look it up through the layer each time rather than hold it.
+
 So the player composites them itself. Every presented frame is drawn to an offscreen canvas with the
 subtitle canvas on top, and `captureStream()` turns that into a MediaStream backing a hidden video
 element, which is the one that enters the window. The original element keeps playing and stays the

package/dist/engine/index.js

@@ -1,2 +1,2 @@
-import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, r as c, s as l, t as u, u as d } from "../engine-B8CKGIng.js";
+import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, r as c, s as l, t as u, u as d } from "../engine-YeMWShCv.js";
 export { i as DEFAULT_BUFFER_SIZE, e as MediaElementError, a as SUBTITLES_OFF, u as createPictureInPicture, d as createSubtitleRenderer, c as createThumbnailGenerator, n as getTimeRanges, s as isMediaElementError, o as pictureInPictureMode, l as startPlayback, t as terminateRemuxer, r as updateSourceBuffer };

package/dist/engine/picture-in-picture.d.ts

@@ -14,8 +14,15 @@
 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;
+    /**
+     * The subtitle LAYER, not the canvas inside it.
+     *
+     * From jassub 2 the canvas is created and removed by the subtitle renderer, one per pipeline
+     * build, so an element captured here would stop being the one being painted the moment the audio
+     * track changed. The layer is what React owns for the life of the player, so hiding and restoring
+     * it stays correct across a rebuild, and the canvas is looked up per frame.
+     */
+    subtitles: HTMLElement;
     maxWidth?: number;
     /** Where the mirror is mounted. It must be in the document. Defaults to the video's parent. */
     container?: HTMLElement;

package/dist/engine/playback.d.ts

@@ -8,7 +8,14 @@ export type MediaIndex = {
 };
 export type PlaybackOptions = {
     videoElement: HTMLVideoElement;
-    canvasElement: HTMLCanvasElement;
+    /**
+     * The subtitle layer. The renderer creates its own canvas inside it, one per jassub instance.
+     *
+     * Renamed from `canvasElement` in the jassub 2 migration, deliberately: passing a canvas here now
+     * means jassub transfers it to a worker and deletes it on teardown, so a caller that kept handing
+     * over an element it owns has to see a type error rather than a runtime one.
+     */
+    subtitleContainer: HTMLElement;
     read: (offset: number, size: number) => Promise<ArrayBuffer>;
     length: number;
     /** serves BOTH `libav.wasm` and `libav-jspi.wasm`; libav-wasm picks one on `WebAssembly.Suspending` */

package/dist/engine/subtitles.d.ts

@@ -8,16 +8,27 @@ export type SubtitleStream = {
 export declare const SUBTITLES_OFF = -1;
 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;
     /**

package/dist/engine/thumbnails.d.ts

@@ -17,6 +17,17 @@ export type ThumbnailGeneratorOptions = {
 export type ThumbnailGenerator = {
     /** Report which byte ranges are readable. Called with no argument when the whole file is. */
     update: (ranges?: [number, number][]) => void;
+    /**
+     * Where the viewer is pointing, so that preview is decoded next. `undefined` when they stop.
+     *
+     * Only the slot covering `time` jumps the queue, and only for as long as it is still waiting, so
+     * this moves one preview forward rather than re-ordering the run. Everything behind it keeps the
+     * order it was claimed in and carries on the moment the jumped slot is done.
+     *
+     * It cannot interrupt a decode that has already started, so the wait is the tail of the one in
+     * flight and not the whole backlog.
+     */
+    prioritize: (time: number | undefined) => void;
     destroy: () => void;
 };
 export declare const createThumbnailGenerator: (options: ThumbnailGeneratorOptions) => Promise<ThumbnailGenerator>;