@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 and uses a highly-performant WASM build of the LAME MP3 Encoder under the hood.

> This package, like the rest of Mediabunny, is enabled by its 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.

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.

License

@mediabunny/mp3-encoder uses the same MPL-2.0 license as Mediabunny. The LAME MP3 Encoder is licensed under LGPL. On their license page, 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.

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:

$3

Install Emscripten. The recommended way is using the emsdk, which involves cloning a repo and running a few commands. The following commands assume Emscripten is sourced in.

$3

Download the LAME source code from SourceForge. Then, in the folder:

`bash
emconfigure ./configure \
CFLAGS="-DNDEBUG -DNO_STDIO -O3 -msimd128" \
--disable-dependency-tracking \
--disable-shared \
--disable-gtktest \
--disable-analyzer-hooks \
--disable-decoder \
--disable-frontend

emmake make clean
emmake make
`

This generates libmp3lame.a, located in libmp3lame/.libs.

$3

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 \
-s SINGLE_FILE=1 \
-s ALLOW_MEMORY_GROWTH=1 \
-s ENVIRONMENT=web,worker \
-s EXPORTED_RUNTIME_METHODS=cwrap,HEAPU8 \
-s EXPORTED_FUNCTIONS=_malloc,_free \
-msimd128 \
-O3 \
-o build/lame.js
`

This generates build/lame.js, which contains both the JavaScript "glue code" as well as the compiled WASM encoded with Base64.

$3

Then, the complete JavaScript package can be built alongside the rest of Mediabunny by running npm run build` in Mediabunny's root.