libav-wasm 0.8.3 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -30,7 +30,7 @@ Timestamps are reported relative to the start of the content, so a format whose
30
30
  import { makeRemuxer } from 'libav-wasm'
31
31
 
32
32
  const remuxer = await makeRemuxer({
33
- // where libav.wasm is served from
33
+ // where libav.wasm AND libav-jspi.wasm are served from; the worker picks one at runtime
34
34
  publicPath: new URL('/dist/', new URL(import.meta.url).origin).toString(),
35
35
  workerUrl: new URL('../build/worker.js', import.meta.url).toString(),
36
36
  workerOptions: { type: 'module' },
@@ -45,7 +45,7 @@ const { data, info, indexes, subtitles, attachments, chapters } = await remuxer.
45
45
  const codecs = [info.output.videoMimeType, info.output.audioMimeType].filter(Boolean).join(',')
46
46
  const mime = `video/mp4; codecs="${codecs}"`
47
47
 
48
- // { data, pts, duration, offset, finished } — data appends straight to a SourceBuffer
48
+ // { data, pts, duration, offset, finished }: data appends straight to a SourceBuffer
49
49
  const chunk = await remuxer.read()
50
50
 
51
51
  // rebuilds the muxer and starts again from the keyframe at or before this timestamp
@@ -54,6 +54,22 @@ const seeked = await remuxer.seek(90)
54
54
  await remuxer.destroy()
55
55
  ```
56
56
 
57
+ ### `read` gives up the buffer it returns
58
+
59
+ The buffer `read` resolves with is **transferred** to the worker, not copied, so it is detached in your
60
+ code once you hand it over. Returning a fresh buffer per read is the normal shape and needs no thought: a
61
+ `fetch(...).arrayBuffer()`, a buffer transferred out of another worker, or a `slice` all qualify. Only a
62
+ consumer answering out of a cache it keeps has to do anything, and what it has to do is return a copy.
63
+
64
+ Copying the whole payload across the worker boundary on every read is not cheap: at the default 2.5 MB
65
+ buffer a session moves close to a gigabyte, and transferring instead measured 15% off a full remux
66
+ (2264.8 ms to 1918.3 ms, 382 reads, medians over 7 alternated rounds). Pass `transferReads: false` to go
67
+ back to copying.
68
+
69
+ Handing back bytes you kept detaches them, and a detached buffer reads as zero bytes, which ffmpeg takes
70
+ for EOF: the file would truncate silently at that offset. The first time a read comes back empty before
71
+ the end of the file, the library says so on the console.
72
+
57
73
  `makeThumbnailer` opens the same file with no muxer, no encoder and no stream map, for `readKeyframe(t)`
58
74
  alone. Use it rather than a remuxer: `readKeyframe` seeks backward on the input, which an output muxer
59
75
  cannot follow, and a thumbnailer has no muxer to damage.
@@ -64,6 +80,21 @@ cannot follow, and a thumbnailer has no muxer to damage.
64
80
  the library and the worker, and emits types. Only the last step re-runs when you touch C++, so the loop is
65
81
  about 25 seconds.
66
82
 
83
+ ### Two builds, one source
84
+
85
+ `make` emits **both** `libav.wasm` and `libav-jspi.wasm`, and the worker picks between them at runtime on
86
+ `typeof WebAssembly.Suspending === 'function'`. **Both files have to be reachable at `publicPath`**, since
87
+ the choice happens in the browser rather than at build time.
88
+
89
+ The JSPI build lets the engine switch stacks, so nothing is instrumented: it remuxes the same file in
90
+ 549.3ms against the Asyncify build's 641.5ms, and its wasm is 2.2 MB smaller. Chrome and Edge have had JSPI
91
+ since 137 and Firefox since 153; Safari has none, and iOS is Safari whatever the badge says, which is the
92
+ whole reason the Asyncify build still ships.
93
+
94
+ The Chrome-only suite would exercise JSPI and nothing else, so `tests/no-jspi-worker.js` blanks the
95
+ constructor before the worker evaluates and the `without JSPI` tests run the fallback for real. They assert
96
+ byte-identical output, not merely "it ran".
97
+
67
98
  ## Tests
68
99
 
69
100
  `npm test` runs a browser suite against fixtures it synthesizes with ffmpeg on first run. Nothing is
@@ -93,6 +124,15 @@ For C++ autocompletion, clone into the repo root:
93
124
  - `sourceBuffer.timestampOffset` with always-increasing timestamps, to avoid re-initialising on a backwards seek
94
125
  - video transcoding, the only thing that would make mpeg2, mpeg4 part 2 and theora playable
95
126
  - audio codec reference: https://cconcolato.github.io/media-mime-support/#audio_codecs
127
+ - `getIndexes()` on the remuxer, re-running the same keyframe walk `init` does, so the index can grow
128
+ as `read()` demuxes. `indexes` is the container's declared index rather than a scan, so a file with
129
+ no Cues comes back with about two entries and no way to tell that apart from a short file. Measured
130
+ on three 38MB matroska files differing only in Cues placement: at the front, 20 entries; at the end,
131
+ the same 20 at the cost of one read at the tail; with no Cues at all, 2. The C++ already has the
132
+ walk in `init` and `initThumbnail`, so the plumbing is small. **Not planned**, on two findings since:
133
+ `seek()` calls `destroy_input()`, so every accumulated entry is discarded on each seek and rebuilt
134
+ from Cues alone; and `Index.index` is the loop counter over the full AVIndexEntry array rather than a
135
+ keyframe ordinal, which matroska inserts into in timestamp order, so it shifts between calls.
96
136
 
97
137
  <!-- https://www.ffmpeg.org/doxygen/trunk/remuxing_8c-example.html -->
98
138
  <!-- https://github.com/leandromoreira/ffmpeg-libav-tutorial -->
package/build/index.d.ts CHANGED
@@ -11,6 +11,15 @@ export type MakeTransmuxerOptions = {
11
11
  bufferSize?: number;
12
12
  /** Input stream index of the audio track to mux; defaults to the first audio stream */
13
13
  audioStreamIndex?: number;
14
+ /**
15
+ * Set false to copy each read across to the worker instead of handing it over. Defaults to true.
16
+ *
17
+ * `read` gives up ownership of the buffer it returns: it is DETACHED once handed over, so a consumer
18
+ * answering out of its own cache has to return a copy rather than the bytes it keeps. That is the
19
+ * normal shape already (a fetch, a worker transfer, a slice all produce a fresh buffer), and moving
20
+ * rather than cloning measured 15% off a session, since the whole payload crosses the hop every read.
21
+ */
22
+ transferReads?: boolean;
14
23
  };
15
24
  export declare const makeRemuxer: (options: MakeTransmuxerOptions) => Promise<{
16
25
  worker: Worker;
package/build/index.js CHANGED
@@ -2405,7 +2405,7 @@ var abortSignalToPromise = (abortSignal) => new Promise((resolve, reject) => {
2405
2405
  * Split out because a thumbnailer and a remuxer need identical plumbing and nothing else in common: only
2406
2406
  * which wasm entry point they open the file with, and which calls they then expose.
2407
2407
  */
2408
- var makeSession = async ({ publicPath, workerUrl, workerOptions, read, length, bufferSize, audioStreamIndex }) => {
2408
+ var makeSession = async ({ publicPath, workerUrl, workerOptions, read, length, bufferSize, audioStreamIndex, transferReads = true }) => {
2409
2409
  const worker = new Worker(workerUrl, workerOptions);
2410
2410
  const { makeRemuxer } = await Lr({}, { transport: worker });
2411
2411
  const remuxer = await makeRemuxer({
@@ -2415,15 +2415,33 @@ var makeSession = async ({ publicPath, workerUrl, workerOptions, read, length, b
2415
2415
  audioStreamIndex
2416
2416
  });
2417
2417
  const queue = new PQueue({ concurrency: 1 });
2418
+ /**
2419
+ * The one way transferring can go wrong, said out loud instead of left to be debugged.
2420
+ *
2421
+ * A consumer that answers out of its own cache hands back a buffer we detached on an earlier read, and
2422
+ * a detached buffer reports zero bytes. ffmpeg reads zero bytes as EOF, so the file silently truncates
2423
+ * at whatever offset that happened rather than failing anywhere near the cause. Zero bytes at or past
2424
+ * the end of the file is ordinary EOF and says nothing, so only a short read BEFORE the end is a tell.
2425
+ */
2426
+ let warnedDetached = false;
2427
+ const warnIfDetached = (buffer, offset) => {
2428
+ if (warnedDetached || !transferReads || buffer.byteLength > 0 || offset >= length) return;
2429
+ warnedDetached = true;
2430
+ console.warn(`libav-wasm: read(${offset}) returned 0 bytes, ${length - offset} bytes before the end of the file. Reads are transferred, so the buffer read() returns is detached in the caller and handing back bytes you keep returns that same detached buffer. Return a copy, or pass transferReads: false.`);
2431
+ };
2418
2432
  const wasmRead = (abortController) => (offset, size) => {
2419
2433
  if (abortController.signal.aborted) return Promise.resolve({
2420
2434
  resolved: (/* @__PURE__ */ new Uint8Array(0)).buffer,
2421
2435
  rejected: true
2422
2436
  });
2423
- return Promise.race([read(Number(offset), Number(size)).then((buffer) => ({
2424
- resolved: new Uint8Array(buffer).buffer,
2425
- rejected: false
2426
- }), () => ({
2437
+ return Promise.race([read(Number(offset), Number(size)).then((buffer) => {
2438
+ warnIfDetached(buffer, Number(offset));
2439
+ const owned = new Uint8Array(buffer).buffer;
2440
+ return {
2441
+ resolved: transferReads ? Je(owned) : owned,
2442
+ rejected: false
2443
+ };
2444
+ }, () => ({
2427
2445
  resolved: (/* @__PURE__ */ new Uint8Array(0)).buffer,
2428
2446
  rejected: true
2429
2447
  })), abortSignalToPromise(abortController.signal).then(() => ({
Binary file
package/build/libav.wasm CHANGED
Binary file