elsmr/mp3-mediarecorder
elsmr/mp3-mediarecorder has 90 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:41 UTC. Last push 2026-09-25.
What you can do
- Standard MediaRecorder API, including timeslice, requestData(), pause()/resume() and audioBitsPerSecond
- Zero configuration: new Mp3MediaRecorder(stream).start()
- Mono or joint stereo, ABR encoding at any bitrate from 8 to 320 kbps
- Audio capture in an AudioWorklet, encoding in a Web Worker — nothing heavy on the main thread
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
🎙MediaRecorder ponyfill that records audio as mp3
Creative & MediaREADME.md
Original🎙 mp3-mediarecorder
A MediaRecorder ponyfill that records audio as mp3, using a minimal build of LAME compiled to WebAssembly.
View the live demo
Features
- Standard MediaRecorder API, including
timeslice,requestData(),pause()/resume()andaudioBitsPerSecond - Zero configuration:
new Mp3MediaRecorder(stream).start() - Mono or joint stereo, ABR encoding at any bitrate from 8 to 320 kbps
- Audio capture in an AudioWorklet, encoding in a Web Worker — nothing heavy on the main thread
- Consistent MP3 output in all supported browsers, with an exact duration header
- Typed events, ESM only, ~3 kB main library, 78 kB wasm (34 kB brotli) loaded lazily in the worker
Browser Support
Chrome 85+, Firefox 114+, Safari 15+, Edge 85+. The binding constraints are module workers (Firefox 114, Safari 15) and the untranspiled ES2021 output (Chrome 85); the wasm itself only needs non-trapping float-to-int conversions (Chrome 75, Firefox 64, Safari 15).
Installation
npm install mp3-mediarecorder
Usage
import { Mp3MediaRecorder } from 'mp3-mediarecorder';
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const recorder = new Mp3MediaRecorder(stream);
recorder.ondataavailable = (event) => {
const url = URL.createObjectURL(event.data); // audio/mpeg Blob
};
recorder.start();
// later
recorder.stop();
That's it. The library spawns a module worker next to itself with new Worker(new URL('./worker.js', import.meta.url), { type: 'module' }), and the worker fetches mp3.wasm the same way. Vite 8+, webpack 5, Parcel 2 and plain <script type="module"> resolve this without configuration. For a full example, see examples/basic or examples/react.
Some bundlers need a hand. If the worker cannot be found, the recorder fires error with an UnknownError ("Worker error") and a 404 for worker.js shows in the network tab.
Vite 7 and older,
vite devonly (vite buildis fine): dependency pre-bundling moves the library into.vite/depsand the worker path along with it. Skip it:// vite.config.js export default { optimizeDeps: { exclude: ['mp3-mediarecorder'] } };esbuild and Bun do not follow
new URL(..., import.meta.url); copy the two files next to your bundle:cp node_modules/mp3-mediarecorder/dist/{worker.js,mp3.wasm} dist/
Rollup without Vite needs a plugin for the same reason as esbuild, or the copy above. Anything else: pass your own worker and wasmUrl (below).
Without a bundler
The built files have no imports, so any static host that serves the package as-is works. Bundling CDNs such as esm.sh rewrite the module and lose the sibling worker.js.
<script type="module">
import { Mp3MediaRecorder } from 'https://cdn.jsdelivr.net/npm/mp3-mediarecorder@beta/dist/index.js';
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const recorder = new Mp3MediaRecorder(stream);
</script>
Stereo and bitrate
Recordings are mono at 64 kbps by default. Channel count is not auto-detected, because browsers report 2 channels for tracks whose audio processing already mixed them to mono, which would only double the file size.
const recorder = new Mp3MediaRecorder(stream, {
channelCount: 2, // joint stereo; default bitrate becomes 128 kbps
audioBitsPerSecond: 192_000, // any value from 8_000 to 320_000
});
For a true stereo microphone, disable the browser's voice processing so both channels reach the recorder:
navigator.mediaDevices.getUserMedia({
audio: { channelCount: 2, echoCancellation: false, noiseSuppression: false, autoGainControl: false },
});
Chunks while recording
recorder.start(1000); // dataavailable every second
recorder.requestData(); // or on demand
Each chunk is a Blob of complete MP3 frames; concatenating them in order (new Blob(chunks)) yields a valid file. Chunked recordings omit the duration header, since it has to be written at the start of the file once the recording is over. Players estimate the length from the bitrate instead — the same trade-off native MediaRecorder makes when streaming.
Recording a Web Audio graph
To put a filter, compressor, gain or your own worklet in front of the encoder, end the graph in a MediaStreamAudioDestinationNode and record its stream on the same context:
const context = new AudioContext();
const source = context.createMediaStreamSource(stream);
const highpass = new BiquadFilterNode(context, { type: 'highpass', frequency: 80 });
const sink = new MediaStreamAudioDestinationNode(context);
source.connect(highpass).connect(sink);
const recorder = new Mp3MediaRecorder(sink.stream, { audioContext: context });
Own worker or wasm location
The defaults cover most setups. If your CSP forbids workers from the library's origin, or you host the wasm elsewhere:
const recorder = new Mp3MediaRecorder(stream, {
worker: new Worker('/vendor/mp3-mediarecorder/worker.js', { type: 'module' }), // a copy of mp3-mediarecorder/worker
wasmUrl: 'https://cdn.example.com/mp3.wasm', // a copy of mp3-mediarecorder/mp3.wasm
});
A worker you pass in is yours: it is not terminated after the recording and can be reused across recordings. The default worker is spawned per start() and terminated after the final dataavailable.
API
new Mp3MediaRecorder(stream, options?)
stream: MediaStream— audio tracks only; video tracks makestart()throwNotSupportedError, as the spec requires for a container that cannot hold them.options.mimeType?: string—""(default),audio/mpegoraudio/mpeg;codecs=mp3; anything else throwsNotSupportedError.options.audioBitsPerSecond?: number/options.bitsPerSecond?: number— ABR target, 8 000–320 000. Default 64 000 mono / 128 000 stereo.bitsPerSecondwins, as in the spec.options.channelCount?: 1 | 2— mono or joint stereo. Default 1.options.audioContext?: AudioContext— reuse a context. Chrome and Safari limit the number of live contexts.options.worker?: Worker— a module worker runningmp3-mediarecorder/worker.options.wasmUrl?: string— where the worker fetchesmp3.wasm.
Everything else follows the MediaStream Recording spec, including the parts most ponyfills skip (the only step not implemented is the SecurityError for isolated streams, which no cross-browser API can detect):
statechanges synchronously instart()/stop()/pause()/resume(); events fire asynchronously.startfires once audio is actually being captured, so the moment to show a "recording" indicator isonstart, not the return ofstart().stop()followed immediately bystart()works — the previous recording still delivers itsdataavailableandstop.mimeTypeis the constrained type (""unless you passed one) until recording actually starts, thenaudio/mpeg(or the type you passed), then back — exactly like Chrome.- Wrong-state calls throw
DOMExceptionInvalidStateError;stop()on an inactive recorder is a no-op. start(timeslice)coerces like WebIDLunsigned long(no throwing); slices shorter than 100 ms are rounded up because the worklet batches ~85 ms of audio.- When all audio tracks end (
track.stop(), device unplugged) the recording stops by itself withdataavailableandstop. Adding or removing a track fireserror(InvalidModificationError), thendataavailablewith what was recorded, thenstop. - Chunks requested with
requestData()on a recording started withouttimesliceare clean too: the placeholder LAME reserves for the duration header is dropped from the first chunk instead of being left in as a silent frame. - Encoder or setup failures fire
error(UnknownError), thendataavailablewith everything encoded so far, thenstop. errorevents areErrorEvents whose.erroris aDOMExceptionwith the spec name;dataavailableevents areBlobEvents whosetimecodeis 0 for the first blob and the offset of each later blob's first chunk.audioBitsPerSecond,videoBitsPerSecond(0),audioBitrateMode("variable"),streamand the sixon*handlers exist, andaddEventListeneris typed per event.
Mp3MediaRecorder.isTypeSupported(type) returns true for "", audio/mpeg and audio/mp3 with an optional codecs=mp3 parameter. (Read literally, the spec would return false for codecs=mp3 because mp3 is not a "synchronously exposed" identifier; that hedge exists for hardware detection and does not apply here.)
mp3-mediarecorder/worker
The worker script. Importing it has side effects: it starts listening for messages from Mp3MediaRecorder. You only reference it when supplying your own worker.
mp3-mediarecorder/mp3.wasm
The encoder binary, for hosting it yourself and pointing wasmUrl at it.
Migrating from v4
Browser support is now Chrome 85+, Firefox 114+, Safari 15+, Edge 85+.
No worker file needed. Delete your worker.js and the worker option; new Mp3MediaRecorder(stream) is enough. initMp3MediaEncoder is gone: if you still want your own worker, point new Worker(url, { type: 'module' }) at a copy of mp3-mediarecorder/worker and pass it as worker. The wasm location, previously vmsgWasmUrl, is the recorder's wasmUrl option.
ESM only. The UMD, ES5 and CommonJS builds are gone. Bundler users need no change. Without a bundler, replace
<script src="https://unpkg.com/mp3-mediarecorder"></script>
<script>
const { Mp3MediaRecorder } = window.mp3MediaRecorder;
</script>
with
<script type="module">
import { Mp3MediaRecorder } from 'https://cdn.jsdelivr.net/npm/mp3-mediarecorder@beta/dist/index.js';
</script>
Entry points are declared in exports: mp3-mediarecorder, mp3-mediarecorder/worker and mp3-mediarecorder/mp3.wasm. Deep imports like mp3-mediarecorder/dist/index.es.js no longer resolve.
Encoding changed from vmsg's mono VBR (quality 5) to ABR at 64 kbps mono. Files are a similar size; pass audioBitsPerSecond to tune it. Stereo is new.
pause() no longer suspends the AudioContext; the worklet just drops input. Sharing a context with other audio is now safe.
Spec behaviour replaces v4's approximations: state flips synchronously, stop() on an inactive recorder no longer throws, wrong-state calls throw DOMExceptions instead of Errors, mimeType is "" until recording starts, dataavailable is always a BlobEvent, error is an ErrorEvent carrying a DOMException, streams with video tracks are rejected, and ended tracks stop the recording.
Limitations
- Start-up gap.
stateis"recording"as soon asstart()returns, but audio is only captured once the AudioWorklet module has loaded and the graph is connected — typically tens of milliseconds. Listen forstartif the exact moment matters. Native recorders have the same gap, just shorter. - No duration header for chunked output. With
timesliceorrequestData()the Xing/LAME frame cannot be written, because it belongs at byte 0 and the first bytes have already left. Players estimate the length from the bitrate and gapless trimming is unavailable. Same trade-off as nativeMediaRecorderwhen streaming. - Encoder delay. Every MP3 starts with roughly 25 ms of encoder delay, inherent to the format. The info frame declares it, so gapless-aware players trim it from unchunked recordings.
- ABR only.
audioBitsPerSecondis the single knob; there are no CBR or VBR quality presets. - Mono unless asked.
channelCountis not auto-detected (see Stereo and bitrate). - Track end is polled. A locally stopped track (
track.stop()) fires no event, soreadyStateis checked every 250 ms; a track ended by its source (endedevent) stops the recording immediately. - Memory. Without
timeslicethe whole recording is held in worker memory untilstop()— about 29 MB per hour at 64 kbps. - Spec gaps. The
SecurityErrorfor isolated streams is not implemented (no API can detect them), andisTypeSupported('audio/mpeg;codecs=mp3')returnstruewhere a literal reading of the spec saysfalse(see API).
Why
Browser support for MediaRecorder is lacking.
Even in browsers with support for MediaRecorder, the available audio formats differ between browsers, and are not always compatible with other browsers. MP3 is the only audio format that can be played by all modern browsers. No browser can encode it natively, neither through MediaRecorder nor WebCodecs, so the encoder ships as WebAssembly.
Develop
bun install
bun run dev # basic example at http://localhost:5173
bun run test # unit, including the wasm encoder
bun run test:e2e # records a tone through the demo in headless Chromium
bun run build
Rebuilding the encoder
src/mp3.wasm is committed. It is LAME 3.100 compiled with wasi-sdk and wrapped by native/encoder.c. The decoder, ID3 writer, ReplayGain, the CBR/VBR quantizers, VBR presets, CRC, stdio and libm are left out — via linker --wrap where possible and the small native/lame.patch for static functions — and math comes from JS Math, memory from a bump arena. That is what gets it to 78 kB:
native/build.sh # downloads wasi-sdk and the LAME tarball into native/.cache on first run; needs wasm-opt (binaryen) on PATH
Only needed when changing native/ or bumping LAME. The build re-extracts the pinned tarball every time and fails if lame.patch no longer applies.
Releases are managed with Changesets: add a changeset with bunx changeset in your PR.
License
MIT. LAME is LGPL-2.0; native/build.sh fetches its source, applies native/lame.patch and links it into mp3.wasm.