From c6227cea5a2049e29c0403f9637165c6bec8c201 Mon Sep 17 00:00:00 2001
From: Vanilagy <1696106+Vanilagy@users.noreply.github.com>
Date: Sun, 10 Aug 2025 02:06:09 +0200
Subject: [PATCH] Write mp3-encoder docs
---
README.md | 7 ++
docs/.vitepress/config.mts | 6 ++
docs/guide/extensions/mp3-encoder.md | 90 ++++++++++++++++++
docs/guide/output-formats.md | 4 +
packages/mp3-encoder/README.md | 134 +++++++++++++++++++++++++--
packages/mp3-encoder/logo.svg | 38 ++++++++
6 files changed, 273 insertions(+), 6 deletions(-)
create mode 100644 docs/guide/extensions/mp3-encoder.md
create mode 100644 packages/mp3-encoder/logo.svg
diff --git a/README.md b/README.md
index 833746f..2c8a726 100644
--- a/README.md
+++ b/README.md
@@ -49,10 +49,17 @@ Core features include:
### Installation
+Install it via npm:
+
```bash
npm install mediabunny
```
+Alternatively, include it directly with a script tag using one of the [builds](https://github.com/Vanilagy/mediabunny/releases). Doing so exposes a global `Mediabunny` object.
+```html
+
+```
+
Requires any JavaScript environment that can run ECMAScript 2021 or later. Mediabunny is expected to be run in modern browsers. For types, TypeScript 5.7 or later is required.
### Read file metadata
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index c47ab5e..bcb0330 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -75,6 +75,12 @@ export default withMermaid({
{ text: 'Supported formats & codecs', link: '/guide/supported-formats-and-codecs' },
],
},
+ {
+ text: 'Extensions',
+ items: [
+ { text: 'mp3-encoder', link: '/guide/extensions/mp3-encoder' },
+ ],
+ },
],
socialLinks: [
diff --git a/docs/guide/extensions/mp3-encoder.md b/docs/guide/extensions/mp3-encoder.md
new file mode 100644
index 0000000..64a32b4
--- /dev/null
+++ b/docs/guide/extensions/mp3-encoder.md
@@ -0,0 +1,90 @@
+# @mediabunny/mp3-encoder
+
+Browsers typically have no support for MP3 encoding in their WebCodecs implementations. Given the ubiquity of the format, this extension package provides an MP3 encoder for use with Mediabunny. It is implemented using Mediabunny's [custom coder API](../supported-formats-and-codecs#custom-coders) and uses a highly-performant WASM build of the [LAME MP3 Encoder](https://lame.sourceforge.io/) under the hood.
+
+
+ GitHub page
+
+
+
+## Installation
+
+This library peer-depends on Mediabunny. Install both using npm:
+```bash
+npm install mediabunny @mediabunny/mp3-encoder
+```
+
+Alternatively, directly include them using a script tag:
+```html
+
+
+```
+
+This will expose the global objects `Mediabunny` and `MediabunnyMp3Encoder`. Use `mediabunny-mp3-encoder.d.ts` to provide types for these globals. You can download the built distribution files from the [releases page](https://github.com/Vanilagy/mediabunny/releases).
+
+## Usage
+
+```ts
+import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+
+registerMp3Encoder();
+```
+That's it - Mediabunny now uses the registered MP3 encoder automatically.
+
+If you want to be more correct, check for native browser support first:
+```ts
+import { canEncodeAudio } from 'mediabunny';
+import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+
+if (!(await canEncodeAudio('mp3'))) {
+ registerMp3Encoder();
+}
+```
+
+## Example
+
+Here, we convert an input file to an MP3:
+
+```ts
+import {
+ Input,
+ ALL_FORMATS,
+ BlobSource,
+ Output,
+ BufferTarget,
+ Mp3OutputFormat,
+ canEncodeAudio,
+ Conversion,
+} from 'mediabunny';
+import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+
+if (!(await canEncodeAudio('mp3'))) {
+ // Only register the custom encoder if there's no native support
+ registerMp3Encoder();
+}
+
+const input = new Input({
+ source: new BlobSource(file), // From a file picker, for example
+ formats: ALL_FORMATS,
+});
+const output = new Output({
+ format: new Mp3OutputFormat(),
+ target: new BufferTarget(),
+});
+
+const conversion = await Conversion.init({
+ input,
+ output,
+});
+await conversion.execute();
+
+output.target.buffer; // => ArrayBuffer containing the MP3 file
+```
+
+## Implementation details
+
+This library implements an MP3 encoder by registering a custom encoder class with Mediabunny. This class, when initialized, spawns a worker which then immediately loads a WASM build of the LAME MP3 encoder. Then, raw data is sent to the worker and encoded data is received from it. These encoded chunks are then concatenated in the main thread and properly split into separate MP3 frames.
+
+Great care was put into ensuring maximum compatibility of this package; it works with bundlers, directly in the browser, as well as in Node, Deno, and Bun. All code (including worker & WASM) are bundled into a single file, eliminating the need for CDNs or WASM path arguments. This packages therefore serves as a reference implementation of WASM-based encoder extensions for Mediabunny.
+
+The WASM build itself is a performance-optimized, SIMD-enabled build of LAME 3.100, with all unneeded features disabled. Because maximum performance was the priority, the build is slighter bigger, but ~130 kB gzipped is still very reasonable in my opinion. In my tests, it encodes 5 seconds of audio in ~90 milliseconds (55x real-time speed).
\ No newline at end of file
diff --git a/docs/guide/output-formats.md b/docs/guide/output-formats.md
index cc116a8..a086fb7 100644
--- a/docs/guide/output-formats.md
+++ b/docs/guide/output-formats.md
@@ -212,6 +212,10 @@ type Mp3OutputFormatOptions = {
- `onXingFrame`\
Will be called once the Xing metadata frame is finalized, which happens at the end of the writing process.
+::: info
+Most browsers don't support encoding MP3. Use the official [`@mediabunny/mp3-encoder`](./extensions/mp3-encoder) package to polyfill an encoder.
+:::
+
## WAVE
This output format creates WAVE (.wav) files.
diff --git a/packages/mp3-encoder/README.md b/packages/mp3-encoder/README.md
index d8ae514..4251d05 100644
--- a/packages/mp3-encoder/README.md
+++ b/packages/mp3-encoder/README.md
@@ -1,7 +1,120 @@
-Build
+# @mediabunny/mp3-encoder
-Compiling LAME:
+[](https://www.npmjs.com/package/@mediabunny/mp3-encoder)
+[](https://bundlephobia.com/package/@mediabunny/mp3-encoder)
+[](https://www.npmjs.com/package/@mediabunny/mp3-encoder)
+
+
+
+
+
+Browsers typically have no support for MP3 encoding in their WebCodecs implementations. Given the ubiquity of the format, this extension package provides an MP3 encoder for use with [Mediabunny](https://github.com/Vanilagy/mediabunny). It is implemented using Mediabunny's [custom coder API](https://mediabunny.dev/guide/supported-formats-and-codecs#custom-coders) and uses a highly-performant WASM build of the [LAME MP3 Encoder](https://lame.sourceforge.io/) under the hood.
+
+> This package, like the rest of Mediabunny, is enabled by its [sponsors](https://mediabunny.dev/#sponsors) and their donations. If you've derived value from this package, please consider leaving a donation! 💘
+
+## Installation
+
+This library peer-depends on Mediabunny. Install both using npm:
+```bash
+npm install mediabunny @mediabunny/mp3-encoder
```
+
+Alternatively, directly include them using a script tag:
+```html
+
+
+```
+
+This will expose the global objects `Mediabunny` and `MediabunnyMp3Encoder`. Use `mediabunny-mp3-encoder.d.ts` to provide types for these globals. You can download the built distribution files from the [releases page](https://github.com/Vanilagy/mediabunny/releases).
+
+## Usage
+
+```ts
+import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+
+registerMp3Encoder();
+```
+That's it - Mediabunny now uses the registered MP3 encoder automatically.
+
+If you want to be more correct, check for native browser support first:
+```ts
+import { canEncodeAudio } from 'mediabunny';
+import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+
+if (!(await canEncodeAudio('mp3'))) {
+ registerMp3Encoder();
+}
+```
+
+## Example
+
+Here, we convert an input file to an MP3:
+
+```ts
+import {
+ Input,
+ ALL_FORMATS,
+ BlobSource,
+ Output,
+ BufferTarget,
+ Mp3OutputFormat,
+ canEncodeAudio,
+ Conversion,
+} from 'mediabunny';
+import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+
+if (!(await canEncodeAudio('mp3'))) {
+ // Only register the custom encoder if there's no native support
+ registerMp3Encoder();
+}
+
+const input = new Input({
+ source: new BlobSource(file), // From a file picker, for example
+ formats: ALL_FORMATS,
+});
+const output = new Output({
+ format: new Mp3OutputFormat(),
+ target: new BufferTarget(),
+});
+
+const conversion = await Conversion.init({
+ input,
+ output,
+});
+await conversion.execute();
+
+output.target.buffer; // => ArrayBuffer containing the MP3 file
+```
+
+For more ways of using Mediabunny, refer to its [guide](https://mediabunny.dev/guide/introduction).
+
+## License
+
+`@mediabunny/mp3-encoder` uses [the same MPL-2.0 license](https://sourceforge.net/projects/lame/files/lame/) as Mediabunny. The LAME MP3 Encoder is licensed under LGPL. On their [license page](https://lame.sourceforge.io/license.txt), they ask that you give them a shoutout with a link.
+
+## Implementation details
+
+This library implements an MP3 encoder by registering a custom encoder class with Mediabunny. This class, when initialized, spawns a worker which then immediately loads a WASM build of the LAME MP3 encoder. Then, raw data is sent to the worker and encoded data is received from it. These encoded chunks are then concatenated in the main thread and properly split into separate MP3 frames.
+
+Great care was put into ensuring maximum compatibility of this package; it works with bundlers, directly in the browser, as well as in Node, Deno, and Bun. All code (including worker & WASM) are bundled into a single file, eliminating the need for CDNs or WASM path arguments. This packages therefore serves as a reference implementation of WASM-based encoder extensions for Mediabunny.
+
+The WASM build itself is a performance-optimized, SIMD-enabled build of LAME 3.100, with all unneeded features disabled. Because maximum performance was the priority, the build is slighter bigger, but ~130 kB gzipped is still very reasonable in my opinion. In my tests, it encodes 5 seconds of audio in ~90 milliseconds (55x real-time speed).
+
+## Building and development
+
+Building this library is done using the build commands in the [Mediabunny root](https://github.com/Vanilagy/mediabunny).
+
+For simplicity, all built WASM artifacts are included in the repo, since these rarely change. However, here are the instructions for building them from scratch:
+
+### Prerequisites
+
+[Install Emscripten](https://emscripten.org/docs/getting_started/downloads.html). The recommended way is using the emsdk, which involves cloning a repo and running a few commands.
+
+### Compiling LAME:
+
+[Download the LAME source code](https://sourceforge.net/projects/lame/files/lame/) from SourceForge. Then, in the folder:
+
+```bash
emconfigure ./configure \
CFLAGS="-DNDEBUG -DNO_STDIO -O3 -msimd128" \
--disable-dependency-tracking \
@@ -15,10 +128,13 @@ emmake make clean
emmake make
```
-Then extract the file `libmp3lame/.libs/libmp3lame.a`, which you'll need to build the LAME bridge.
+This generates `libmp3lame.a`, located in `libmp3lame/.libs`.
-Compiling the LAME bridge:
-```
+### Compiling the LAME bridge:
+
+Now with LAME built, we must build the C code at `src/lame-bridge.c` containing a lean bridge interface between JavaScript and LAME's API. Clone Mediabunny, and then, in `packages/mp3-encoder` and with `build/libmp3lame.a` in place, run:
+
+```bash
emcc src/lame-bridge.c build/libmp3lame.a \
-s MODULARIZE=1 \
-s EXPORT_ES6=1 \
@@ -29,4 +145,10 @@ emcc src/lame-bridge.c build/libmp3lame.a \
-msimd128 \
-O3 \
-o build/lame.js
-```
\ No newline at end of file
+```
+
+This generates `build/lame.js`, which contains both the JavaScript "glue code" as well as the compiled WASM encoded with Base64.
+
+### Building the package
+
+Then, the complete JavaScript package can be built alongside the rest of Mediabunny by running `npm run build` in Mediabunny's root.
\ No newline at end of file
diff --git a/packages/mp3-encoder/logo.svg b/packages/mp3-encoder/logo.svg
new file mode 100644
index 0000000..78a881f
--- /dev/null
+++ b/packages/mp3-encoder/logo.svg
@@ -0,0 +1,38 @@
+
\ No newline at end of file
+