@audio/decode

Decode any audio format to raw samples.
JS / WASM with no ffmpeg or native bindings; works in Node.js and browsers.
Small API, minimal size, near-native performance, lazy-loading, chunked decoding.

import decode from '@audio/decode';

const { channelData, sampleRate } = await decode(anyAudioBuffer);

Supported formats

Format	Package	Size	Engine
MP3	@audio/decode-mp3	92 KB	WASM
WAV	@audio/decode-wav	11 KB	JS
OGG Vorbis	@audio/decode-vorbis	166 KB	WASM
FLAC	@audio/decode-flac	135 KB	WASM
Opus	@audio/decode-opus	166 KB	WASM
M4A / AAC / ALAC	@audio/decode-aac	368 KB	WASM + JS
MP4 / MOV / M4V / 3GP video	@audio/decode-mp4	12 KB + codec	JS demux
QOA	@audio/decode-qoa	8 KB	JS
AIFF	@audio/decode-aiff	20 KB	JS
CAF	@audio/decode-caf	9 KB	JS
WebM / MKV video	@audio/decode-webm	250 KB	WASM
AVI video	@audio/decode-avi	8 KB + codec	JS demux
AC-3	@audio/decode-ac3	43 KB	WASM
DTS	@audio/decode-dts	200 KB	WASM
AMR	@audio/decode-amr	241 KB	WASM
WMA	@audio/decode-wma	91 KB	WASM

Whole-file

Auto-detects format. Input can be ArrayBuffer, Uint8Array, Buffer, or anything that materializes to bytes, including a Blob/File or fetch Response.

import decode from '@audio/decode'

let { channelData, sampleRate } = await decode(buf)
let fromFile = await decode(fileInput.files[0])   // File
let fromUrl  = await decode(await fetch(url))      // Response

Chunked

let dec = await decode.mp3()
let a = await dec(chunk1)    // { channelData, sampleRate }
let b = await dec(chunk2)
await dec()                  // close

Streaming

import decode from '@audio/decode'

for await (let { channelData, sampleRate } of decode.mp3(response.body)) {
  // process chunks
}

Works with ReadableStream, fetch body, Node stream, or any async iterable.

Formats: mp3, flac, opus, oga, m4a, mp4, mov, wav, qoa, aac, aiff, caf, webm, mkv, avi, ac3, dts, amr, wma.

Video files

Video containers decode straight to their audio track — the video stream is skipped, no ffmpeg involved:

let { channelData, sampleRate } = await decode(await fetch('trailer.mp4'))

Container	Package	Audio codecs
MP4, MOV, M4V, 3GP	@audio/decode-mp4	AAC, ALAC, MP3, FLAC, Opus, AC-3, DTS, AMR, PCM, G.711
WebM, MKV	@audio/decode-webm	Opus, Vorbis, AAC, ALAC, MP3, FLAC, AC-3, DTS, PCM
AVI	@audio/decode-avi	PCM, MP3, AAC, AC-3, DTS, G.711

Surround tracks keep their layout (up to 5.1, WAV channel order). E-AC-3 and TrueHD tracks throw an error naming the codec.

Browser

Works from a CDN without a bundler. Codecs load on demand via dynamic import, only for formats you decode:

<script type="module">
  import decode from 'https://esm.sh/@audio/decode'
  let { channelData, sampleRate } = await decode(buf)
</script>

For self-hosting, use an import map to point @audio/decode and each needed @audio/decode-* package to local files. Codec-internal files load by relative path.

Each codec package's main export works in an AudioWorklet without Blob, TextDecoder, Worker, or fetch. Import codec packages directly because @audio/decode uses dynamic imports.

Initialize WASM before rendering. Decoding runs on the worklet thread and can interrupt audio output.

Synchronous codecs

The umbrella remains async for detection, lazy imports, and Blob/Response inputs. Import a codec package directly for synchronous calls.

wav, qoa, aiff, and caf are synchronous:

import decode from '@audio/decode-wav'
let pcm = decode(wavBytes)

WASM codecs initialize asynchronously, then decode synchronously:

import { decoder } from '@audio/decode-flac'
let dec = await decoder()
let pcm = dec.decode(bytes)
let tail = dec.flush()
dec.free()

Metadata

Read tags, pictures, markers and regions without decoding samples. Available for wav, mp3, flac, oga (Ogg Vorbis), opus, and m4a.

import { wav, mp3, flac, oga, opus, m4a } from '@audio/decode/meta'

let { meta, sampleRate, markers, regions } = mp3(bytes)
// meta: { title, artist, album, year, bpm, key, comment, pictures, raw, ... }
// markers: [{ sample, label }]
// regions: [{ sample, length, label }]

Each codec sub-package also exposes its parser directly:

import { parseMeta } from '@audio/decode-wav/meta'
let info = parseMeta(wavBytes)

WebWorker

Each @audio/decode-* package is a self-contained ESM module that can run in a worker:

// decode-worker.js
import decode from '@audio/decode-mp3'

self.onmessage = async ({ data }) => {
  let pcm = await decode(data)
  self.postMessage(pcm, pcm.channelData.map(ch => ch.buffer))
}

// main.js
let worker = new Worker('./decode-worker.js', { type: 'module' })
worker.postMessage(mp3buf, [mp3buf])
worker.onmessage = ({ data }) => { /* { channelData, sampleRate } */ }

See also

• encode – encode PCM into any audio format.
• audio-type – detect audio format from buffer.

Licensing

The umbrella and most codec packages are MIT. Five codecs use another license: @audio/decode-aac GPL-2.0, @audio/decode-wma, @audio/decode-ac3 and @audio/decode-dts GPL-2.0-or-later, and @audio/decode-amr Apache-2.0. Install only the codecs whose licenses fit your project. The umbrella loads them on demand.

ॐ · MIT