# audiobox **Audio decoding, editing and encoding for TypeScript and JavaScript — with zero dependencies.** One API that reads and writes MP3, WAV, FLAC, AIFF, CAF and AU, and edits and converts between them. The same code runs unchanged in the browser, Node, Deno, Bun and edge runtimes. No native build step, no WebAssembly blob, nothing installed alongside it. [![npm](https://img.shields.io/npm/v/audiobox.svg)](https://www.npmjs.com/package/audiobox) [![core size](https://img.shields.io/badge/core-22.9%20kB%20gzip-blue.svg)](#bundle-size) [![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-dependencies-really) [![types](https://img.shields.io/badge/types-included-blue.svg)](#typescript) [![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) ```bash npm install audiobox ``` ```ts import { decode, encode } from 'audiobox'; const audio = await decode(await file.arrayBuffer()); // format detected from content const clip = audio .cut({ from: '0:12', to: '1:30' }) // keep 78 seconds .toMono() // downmix .resample(16_000) // 16 kHz for speech-to-text .normalize({ to: -1 }); // peak to -1 dBFS const wav = await encode(clip, 'wav', { bitDepth: 16 }); ``` --- ## Contents - [What it does](#what-it-does) · [Format support](#format-support) - [Recipes](#recipes) — the things people actually build - [API](#api) - [Correctness](#correctness) · [Security](#security) · [Bundle size](#bundle-size) - [Runtime support](#runtime-support) · [Roadmap](#roadmap) - [Support and sponsorship](#support-and-sponsorship) --- ## What it does **Read** — MP3, WAV (including RF64/BW64, `WAVE_FORMAT_EXTENSIBLE`, A-law, µ-law, IMA ADPCM), FLAC, AIFF/AIFF-C, CAF, AU. **Write** — WAV, FLAC, AIFF/AIFF-C, CAF, AU. **Edit** — cut, trim, concatenate, pad, reverse, mix, crossfade. **Convert** — sample rate, bit depth, channel layout, sample format. **Process** — gain, fades, normalisation (peak / true-peak / **LUFS**), biquad filters, lookahead limiter, silence trimming, DC-offset removal, time-stretch and pitch-shift. **Measure** — peak, true peak, RMS, EBU R128 loudness, waveform peaks, FFT and spectrogram. ### Format support | Format | Read | Write | Notes | | --- | :---: | :---: | --- | | **MP3** | ✅ | ✅ | Read: MPEG-1/2/2.5 · 8–48 kHz · CBR + VBR · joint stereo · gapless. Write: MPEG-1 · 32/44.1/48 kHz · 32–320 kbit/s · CBR + VBR | | **WAV** / RF64 / BW64 | ✅ | ✅ | PCM 8/16/24/32, float 32/64, A-law, µ-law; IMA ADPCM read | | **FLAC** | ✅ | ✅ | Lossless | | **AIFF** / AIFF-C | ✅ | ✅ | Including `sowt` (little-endian PCM), `fl32`, `fl64` | | **CAF** | ✅ | ✅ | 64-bit sizes, for files over 4 GB | | **AU** / SND | ✅ | ✅ | Sun/NeXT | | Ogg, MP4/M4A, WebM | — | — | Detected and named in the error, not decoded | MP3 decoding covers every sample rate from 8 to 48 kHz, constant and variable bitrate, mono, stereo, dual-channel and joint stereo (both mid/side and intensity), and honours Xing/VBRI/LAME tags so playback is gapless — the encoder's priming and padding are removed rather than showing up as a click at each end. There is also `probeMp3()`, which reads duration, bitrate, channel mode and tags **without** decoding. It is near-instant even on a large file and never allocates a decode buffer, which makes it the right tool for validating an upload. **MP3 encoding** writes MPEG-1 Layer III at 32–320 kbit/s, mono or stereo, at 32 / 44.1 / 48 kHz, constant or variable bitrate. It has a psychoacoustic model, switches to short blocks on transients to control pre-echo, uses the bit reservoir, and writes a Xing/Info tag so `decode(encode(x))` returns exactly the samples it was given. Measured, on this machine, at 44.1 kHz: | | | | --- | --- | | ffmpeg's decode of our output, against the source | **73 dB** on tonal material | | Noise shaping, on dense material at 128 kbit/s | noise-to-mask **−6.7 → −10.5 dB**; audible bands 49% → 20% | | Short blocks, on transients | pre-echo **−27 → −34 dB** | | VBR against CBR at matched quality | **15–25% smaller** on easy material, no saving on noise | | Throughput | ~26×realtime CBR, ~13× VBR, ~110× decoding | Encoding is not the equal of a mature encoder at low bitrates — the model is a simplification, and stereo is coded as two independent channels rather than jointly. Above about 192 kbit/s that stops being the limiting factor. The figures above are what the tests assert, not estimates. --- ## Recipes ### Convert a file a user uploaded ```ts import { decode, encode } from 'audiobox'; const audio = await decode(await file.arrayBuffer()); const flac = await encode(audio, 'flac', { compressionLevel: 5 }); // lossless, ~50% of WAV const wav = await encode(audio, 'wav', { bitDepth: 24 }); ``` `decode()` identifies the format from its **contents**, not its extension — uploads are routinely mislabelled, and a `.wav` that is really an MP3 is common enough that content sniffing is the only reliable approach. ### Record from the mic, upload something compact ```ts import { Audio, encode } from 'audiobox'; // ...capture into a Float32Array per channel, then: const audio = new Audio([left, right], audioContext.sampleRate); const flac = await encode( audio.trimSilence({ paddingMs: 100 }).normalize({ to: -1 }), 'flac', ); await fetch('/upload', { method: 'POST', body: flac }); ``` FLAC is lossless and typically 40–60 % of the WAV size, so nothing is thrown away on the way to your server. When the upload has to be small rather than exact — a voice note, a preview, anything a user will listen to once — MP3 is the format everything already plays: ```ts const mp3 = await encode(audio.normalize({ to: -1 }), 'mp3', { vbr: true, quality: 4 }); ``` Variable bitrate spends bits where the material needs them and stops where it does not, so a quiet recording comes out considerably smaller than a fixed bitrate would give you at the same quality. Pass `{ bitrate: 128 }` instead when something downstream needs a predictable size. ### Prepare audio for speech-to-text Whisper, Deepgram and most ASR APIs want 16 kHz mono 16-bit PCM. Sending 48 kHz stereo wastes bandwidth and makes them resample it anyway. ```ts const ready = audio.toMono().resample(16_000).normalize({ to: -3 }); const wav = await encode(ready, 'wav', { bitDepth: 16 }); ``` The resampler is a windowed-sinc design with a proper anti-aliasing cutoff. Downsampling without one folds high frequencies back into the speech band as noise, which measurably hurts transcription accuracy. ### Trim, fade and normalise a podcast episode ```ts const episode = audio .trimSilence({ threshold: -50, paddingMs: 250 }) .fade({ in: 0.5, out: 2, curve: 'equalPower' }) .normalize({ to: -16, unit: 'LUFS' }); // the podcast standard ``` `-16 LUFS` is *loudness*, not peak — two episodes normalised this way sound equally loud, which peak normalisation does not achieve. A true-peak ceiling of -1 dBTP is applied automatically so the result cannot clip. ```ts // Did it actually reach the target? const { audio: out, report } = audio.normalizeWithReport({ to: -16, unit: 'LUFS' }); if (report.limitedByPeak) { console.warn(`Held back to protect the peak ceiling; measured ${report.measured.toFixed(1)} LUFS`); } ``` ### Draw a waveform ```ts const { min, max } = audio.waveform(canvas.width); for (let x = 0; x < canvas.width; x++) { const top = (0.5 - max[x] / 2) * canvas.height; const bottom = (0.5 - min[x] / 2) * canvas.height; ctx.fillRect(x, top, 1, Math.max(1, bottom - top)); } ``` Returns per-bucket **extremes**, not averages. Averaging flattens transients and produces the lifeless waveform displays where you cannot see where the beats are. ### Validate an upload without decoding it ```ts import { probeMp3 } from 'audiobox/mp3'; const info = probeMp3(bytes); if (info.duration > 600) throw new Error('Too long'); ``` ### Batch-convert a folder in Node ```ts import { readAudioFile, writeAudioFile } from 'audiobox/node'; import { readdir } from 'node:fs/promises'; for (const name of await readdir('./in')) { const audio = await readAudioFile(`./in/${name}`); await writeAudioFile(`./out/${name.replace(/\.\w+$/, '.flac')}`, audio); } ``` The output format is inferred from the extension. ### Keep the UI responsive Encoding is seconds of solid CPU, and on the main thread that means a frozen page. ```ts import { runChunked } from 'audiobox/worker'; await runChunked(items, (item) => processOne(item), { onProgress: (p) => setProgress(p), signal: controller.signal, }); ``` `runChunked` slices work into ~8 ms bursts and yields between them, so the browser can paint and handle input. For true parallelism, `audiobox/worker` also exports a message protocol (`handleWorkerMessage`) to drop into your own worker file — your bundler controls the worker URL, so the library cannot create one for you without guessing wrong. ### Process a long file in constant memory ```ts import { createPcmDecodeStream, createResampleStream, createPcmEncodeStream } from 'audiobox/stream'; await source .pipeThrough(createPcmDecodeStream({ sampleFormat: 's16', channels: 2, sampleRate: 48000 })) .pipeThrough(createResampleStream(16_000)) .pipeThrough(createPcmEncodeStream({ sampleFormat: 's16' })) .pipeTo(destination); ``` Chunk boundaries that fall mid-frame are handled — a decoder that assumes whole frames per chunk clicks at every boundary. --- ## API ### `decode(input, options?) → Promise