libav-wasm 0.8.2 → 0.8.4

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
@@ -1,61 +1,122 @@
1
- # LibAV WASM
1
+ # libav-wasm
2
2
 
3
- This library can be used to remux from MKV -> MP4, it could technically do any remux but i haven't had the need for it, create an issue if you'd like it.
3
+ Remuxes a video file into fragmented MP4 in the browser, a fragment at a time, from a `read(offset, size)`
4
+ you supply. Nothing is downloaded up front and nothing is written to disk, so it plays a file over HTTP
5
+ range requests, out of a torrent, or out of anything else that can answer for a byte range.
4
6
 
5
- [src/test.ts](https://github.com/Banou26/libav-wasm/blob/main/src/test.ts)
6
- Contains a full example of a MKV video player
7
+ ffmpeg 7.1 compiled to wasm with emscripten. [src/test.ts](./src/test.ts) is a working player.
8
+
9
+ ## What it accepts
10
+
11
+ Any container ffmpeg can demux: mkv, mp4, mov, webm, avi, mpegts, flv, 3gp and the rest. What decides
12
+ whether a file plays is the **codec**, not the extension.
13
+
14
+ | | passes through | re-encoded to aac | not playable |
15
+ | --- | --- | --- | --- |
16
+ | video | h264, hevc, vp9, av1 | | anything else |
17
+ | audio | aac, opus, flac | ac3, eac3, truehd, dts, mp3, vorbis, wma, pcm, … | codecs with no decoder |
18
+
19
+ Video is never re-encoded, so a codec no browser can decode (mpeg2, mpeg4 part 2, theora, vc1) cannot be
20
+ rescued and `init()` rejects saying so. Audio always can be, and is, so a track the mp4 muxer will not
21
+ carry never costs you the file. Thumbnails have none of these limits: they decode in wasm and hand back
22
+ pixels, so they work on files that cannot be remuxed at all.
23
+
24
+ Timestamps are reported relative to the start of the content, so a format whose clock starts elsewhere
25
+ (mpegts) still lines up with a player's timeline.
26
+
27
+ ## Usage
7
28
 
8
- Basic usage
9
29
  ```ts
30
+ import { makeRemuxer } from 'libav-wasm'
31
+
10
32
  const remuxer = await makeRemuxer({
11
- // the path at which the wasm file is getting served
33
+ // where libav.wasm AND libav-jspi.wasm are served from; the worker picks one at runtime
12
34
  publicPath: new URL('/dist/', new URL(import.meta.url).origin).toString(),
13
- // url of the worker file of libavWASM
14
35
  workerUrl: new URL('../build/worker.js', import.meta.url).toString(),
15
- // reads will be done in 2.5mb chunks
16
- bufferSize: 2_500_000,
17
- // byte length of the video file
36
+ workerOptions: { type: 'module' },
18
37
  length: contentLength,
19
- // fetch returning a ReadableStream
20
- getStream: async (offset, size) =>
21
- fetch(
22
- VIDEO_URL,
23
- {
24
- headers: {
25
- Range: `bytes=${offset}-${size ? Math.min(offset + size, contentLength) - 1 : ''}`
26
- }
27
- }
28
- ).then(res => res.body)
38
+ read: (offset, size) =>
39
+ fetch(VIDEO_URL, { headers: { Range: `bytes=${offset}-${offset + size - 1}` } })
40
+ .then(res => res.arrayBuffer()),
29
41
  })
30
42
 
31
- // returns the header of the video with all the metadata
32
- const header = await remuxer.init()
33
-
34
- // Returns a chunk that looks like {
35
- // offset: number,
36
- // buffer: Uint8Array,
37
- // pos: number,
38
- // pts: number, // timestamp
39
- // duration: number
40
- // }
41
- // buffer can be appended to the MediaSource API(MSE API)
43
+ // the mp4 init segment, plus every piece of metadata the file carries
44
+ const { data, info, indexes, subtitles, attachments, chapters } = await remuxer.init()
45
+ const codecs = [info.output.videoMimeType, info.output.audioMimeType].filter(Boolean).join(',')
46
+ const mime = `video/mp4; codecs="${codecs}"`
47
+
48
+ // { data, pts, duration, offset, finished }: data appends straight to a SourceBuffer
42
49
  const chunk = await remuxer.read()
43
50
 
44
- // allows you to seek to timestamp and start reading from there
45
- const seekChunk = await remuxer.seek(number)
46
- // ...
51
+ // rebuilds the muxer and starts again from the keyframe at or before this timestamp
52
+ const seeked = await remuxer.seek(90)
53
+
54
+ await remuxer.destroy()
47
55
  ```
48
56
 
57
+ `makeThumbnailer` opens the same file with no muxer, no encoder and no stream map, for `readKeyframe(t)`
58
+ alone. Use it rather than a remuxer: `readKeyframe` seeks backward on the input, which an output muxer
59
+ cannot follow, and a thumbnailer has no muxer to damage.
60
+
61
+ ## Building
62
+
63
+ `npm run build` compiles `src/main.cpp` in Docker (emsdk plus ffmpeg, cached after the first run), bundles
64
+ the library and the worker, and emits types. Only the last step re-runs when you touch C++, so the loop is
65
+ about 25 seconds.
66
+
67
+ ### Two builds, one source
68
+
69
+ `make` emits **both** `libav.wasm` and `libav-jspi.wasm`, and the worker picks between them at runtime on
70
+ `typeof WebAssembly.Suspending === 'function'`. **Both files have to be reachable at `publicPath`**, since
71
+ the choice happens in the browser rather than at build time.
72
+
73
+ The JSPI build lets the engine switch stacks, so nothing is instrumented: it remuxes the same file in
74
+ 549.3ms against the Asyncify build's 641.5ms, and its wasm is 2.2 MB smaller. Chrome and Edge have had JSPI
75
+ since 137 and Firefox since 153; Safari has none, and iOS is Safari whatever the badge says, which is the
76
+ whole reason the Asyncify build still ships.
77
+
78
+ The Chrome-only suite would exercise JSPI and nothing else, so `tests/no-jspi-worker.js` blanks the
79
+ constructor before the worker evaluates and the `without JSPI` tests run the fallback for real. They assert
80
+ byte-identical output, not merely "it ran".
81
+
82
+ ## Tests
83
+
84
+ `npm test` runs a browser suite against fixtures it synthesizes with ffmpeg on first run. Nothing is
85
+ committed and nothing is anyone's content, so there is no copyright question and no multi-megabyte blob in
86
+ git history: what matters for a remuxer is a file's structure, and every fixture exists because a real bug
87
+ needed exactly that structure to show up.
88
+
89
+ Each fixture encodes its own timestamp in the frame's colour, so a decoded thumbnail can be checked back to
90
+ the second it came from. Without that the only available assertion is "some bytes came back", which is how
91
+ hevc thumbnails silently returned frame one for every timestamp.
92
+
93
+ Drop real files in `fixtures/local/` to widen coverage. That directory is gitignored, and those tests
94
+ assert only what has to hold for any file. `npm run test:large` adds a fixture over 4 GB for the byte
95
+ offset tests.
96
+
97
+ Real Chrome is used rather than Playwright's bundled Chromium, because codec support is a property of the
98
+ binary: Chromium reports hevc unsupported where Chrome supports it. Set `LIBAV_CHROME_PATH` if Chrome is
99
+ not on `PATH`.
49
100
 
50
101
  ## Intellisense
51
- To have C++ autocompletion, put a ffmpeg repo clone folder in the root
52
- `git clone https://github.com/FFmpeg/FFmpeg` & `git clone https://github.com/emscripten-core/emscripten`
53
102
 
103
+ For C++ autocompletion, clone into the repo root:
104
+ `git clone https://github.com/FFmpeg/FFmpeg` and `git clone https://github.com/emscripten-core/emscripten`
105
+
106
+ ## Ideas
54
107
 
108
+ - `sourceBuffer.timestampOffset` with always-increasing timestamps, to avoid re-initialising on a backwards seek
109
+ - video transcoding, the only thing that would make mpeg2, mpeg4 part 2 and theora playable
110
+ - audio codec reference: https://cconcolato.github.io/media-mime-support/#audio_codecs
111
+ - `getIndexes()` on the remuxer, re-running the same keyframe walk `init` does, so the index can grow
112
+ as `read()` demuxes. `indexes` is the container's declared index rather than a scan, so a file with
113
+ no Cues comes back with about two entries and no way to tell that apart from a short file. Measured
114
+ on three 38MB matroska files differing only in Cues placement: at the front, 20 entries; at the end,
115
+ the same 20 at the cost of one read at the tail; with no Cues at all, 2. The C++ already has the
116
+ walk in `init` and `initThumbnail`, so the plumbing is small. **Not planned**, on two findings since:
117
+ `seek()` calls `destroy_input()`, so every accumulated entry is discarded on each seek and rebuilt
118
+ from Cues alone; and `Index.index` is the loop counter over the full AVIndexEntry array rather than a
119
+ keyframe ordinal, which matroska inserts into in timestamp order, so it shifts between calls.
55
120
 
56
- ## Issues to fix / features to implement
57
- - Try to play around with `sourceBuffer.timestampOffset = res.pts` and always increasing timestamps to not have to re-init on backwards seeks
58
- - Transcoding
59
- - Base transcoding off of https://cconcolato.github.io/media-mime-support/#audio_codecs
60
121
  <!-- https://www.ffmpeg.org/doxygen/trunk/remuxing_8c-example.html -->
61
122
  <!-- https://github.com/leandromoreira/ffmpeg-libav-tutorial -->
package/build/index.d.ts CHANGED
@@ -7,11 +7,12 @@ export type MakeTransmuxerOptions = {
7
7
  workerOptions?: WorkerOptions;
8
8
  read: (offset: number, size: number) => Promise<ArrayBuffer>;
9
9
  length: number;
10
- bufferSize: number;
10
+ /** how much the demuxer reads ahead; defaults to 2.5 MB for a remuxer and 1 MB for a thumbnailer */
11
+ bufferSize?: number;
11
12
  /** Input stream index of the audio track to mux; defaults to the first audio stream */
12
13
  audioStreamIndex?: number;
13
14
  };
14
- export declare const makeRemuxer: ({ publicPath, workerUrl, workerOptions, read, length, bufferSize, audioStreamIndex }: MakeTransmuxerOptions) => Promise<{
15
+ export declare const makeRemuxer: (options: MakeTransmuxerOptions) => Promise<{
15
16
  worker: Worker;
16
17
  init: () => Promise<{
17
18
  data: ArrayBuffer;
@@ -21,14 +22,14 @@ export declare const makeRemuxer: ({ publicPath, workerUrl, workerOptions, read,
21
22
  data: ArrayBuffer;
22
23
  }[];
23
24
  subtitles: ({
24
- type: "header";
25
+ type: 'header';
25
26
  streamIndex: number;
26
27
  content: string;
27
28
  format: string[];
28
29
  language: string;
29
30
  title: string;
30
31
  } | {
31
- type: "dialogue";
32
+ type: 'dialogue';
32
33
  streamIndex: any;
33
34
  start: number;
34
35
  end: number;
@@ -77,14 +78,14 @@ export declare const makeRemuxer: ({ publicPath, workerUrl, workerOptions, read,
77
78
  seek: (timestamp: number) => Promise<{
78
79
  data: ArrayBuffer;
79
80
  subtitles: ({
80
- type: "header";
81
+ type: 'header';
81
82
  streamIndex: number;
82
83
  content: string;
83
84
  format: string[];
84
85
  language: string;
85
86
  title: string;
86
87
  } | {
87
- type: "dialogue";
88
+ type: 'dialogue';
88
89
  streamIndex: any;
89
90
  start: number;
90
91
  end: number;
@@ -104,14 +105,14 @@ export declare const makeRemuxer: ({ publicPath, workerUrl, workerOptions, read,
104
105
  read: () => Promise<{
105
106
  data: ArrayBuffer;
106
107
  subtitles: ({
107
- type: "header";
108
+ type: 'header';
108
109
  streamIndex: number;
109
110
  content: string;
110
111
  format: string[];
111
112
  language: string;
112
113
  title: string;
113
114
  } | {
114
- type: "dialogue";
115
+ type: 'dialogue';
115
116
  streamIndex: any;
116
117
  start: number;
117
118
  end: number;
@@ -129,4 +130,28 @@ export declare const makeRemuxer: ({ publicPath, workerUrl, workerOptions, read,
129
130
  finished: boolean;
130
131
  }>;
131
132
  readKeyframe: (timestamp: number) => Promise<ArrayBuffer>;
133
+ /** Takes effect on the next seek */
134
+ setAudioStreamIndex: (index: number) => Promise<void>;
135
+ }>;
136
+ /**
137
+ * Open a file for thumbnails only. No output muxer, no encoder, no stream map, no header.
138
+ *
139
+ * `readKeyframe` seeks BACKWARD on the input, which an output muxer cannot follow, so a remuxer that also
140
+ * served thumbnails could only be kept correct by never doing both on one instance. There is no muxer here
141
+ * to damage. It also opens files whose audio the muxer refuses outright, which a remuxer cannot.
142
+ */
143
+ export declare const makeThumbnailer: (options: MakeTransmuxerOptions) => Promise<{
144
+ worker: Worker;
145
+ init: () => Promise<{
146
+ duration: number;
147
+ videoMimeType: string;
148
+ videoExtradata: ArrayBuffer;
149
+ indexes: {
150
+ index: number;
151
+ timestamp: number;
152
+ pos: number;
153
+ }[];
154
+ }>;
155
+ readKeyframe: (timestamp: number) => Promise<ArrayBuffer>;
156
+ destroy: () => Promise<void>;
132
157
  }>;