Registry / data / audio-decode

audio-decode

library3.9.3jsnpmunverified

audio-decode is a JavaScript/WASM library designed for decoding various audio formats into raw PCM samples, suitable for both Node.js and browser environments. Currently at version 3.9.3, it maintains an active release cadence with frequent updates introducing new codec support, performance improvements, and API refinements. A key differentiator is its independence from external tools like FFmpeg, relying solely on JS and WASM implementations for a small footprint and near-native performance. It supports a wide array of formats including MP3, WAV, OGG Vorbis, FLAC, Opus, M4A/AAC, and more, offering both whole-file and chunked/streaming decoding capabilities. The library provides a unified API, and individual codec modules can be selectively loaded in browsers to optimize bundle size, making it highly versatile for diverse audio processing needs.

data

npm install audio-decode

github ↗package ↗

INSTALL

IMPORT

SIG · AUDIO-DECODE

audio-decode

datajavascriptv3.9.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

decode

✓ import decode from 'audio-decode';

✗ const decode = require('audio-decode');

The library is ESM-only since v3.0.0. Use `import` syntax.

decode.mp3

✓ import decode from 'audio-decode'; const mp3Decoder = await decode.mp3();

✗ import { mp3 } from 'audio-decode';

Format-specific decoders are properties of the default `decode` export and are used for chunked/streaming decoding. As of v3.4.0, `decode.mp3(buf)` is deprecated in favor of `decode(buf)` for whole files, or `await decode.mp3()` to get a chunked decoder.

AudioData

✓ import type { AudioData } from 'audio-decode';

Type import for the returned audio data structure `{ channelData: Float32Array[], sampleRate: number }`.

Demonstrates how to decode an audio file from a buffer and access its `channelData` and `sampleRate`.

import decode from 'audio-decode'; import { promises as fs } from 'fs'; import path from 'path'; async function decodeAudioFile(filePath: string) { const audioBuffer = await fs.readFile(filePath); console.log(`Decoding ${path.basename(filePath)}...`); try { const { channelData, sampleRate } = await decode(audioBuffer); console.log(`Successfully decoded audio.`); console.log(`Sample Rate: ${sampleRate} Hz`); console.log(`Channels: ${channelData.length}`); console.log(`Duration: ${channelData[0].length / sampleRate} seconds`); // You can now process channelData (an array of Float32Array for each channel) } catch (error) { console.error(`Error decoding audio:`, error); } } // Example usage (replace with a real audio file path) decodeAudioFile('path/to/your/audio.mp3'); // Or for a streaming example: // import { Readable } from 'stream'; // async function decodeStreamExample() { // const readableStream = Readable.from(new Uint8Array([/* your audio bytes */])); // for await (const { channelData, sampleRate } of decode.mp3(readableStream)) { // console.log(`Received chunk: ${channelData[0].length} samples at ${sampleRate}Hz`); // } // } // decodeStreamExample();

Debug

Known issues

breakingVersion 3.0.0 introduced significant breaking changes. The `decode` function now returns a plain object `{ channelData, sampleRate }` instead of an `AudioBuffer` object, removing the `audio-buffer` dependency. Additionally, the library transitioned to ESM-only with an explicit `exports` field, meaning CommonJS `require()` is no longer supported.

fix

Update import statements to ESM (`import decode from 'audio-decode'`) and adjust code to expect a plain object `{ channelData: Float32Array[], sampleRate: number }` instead of an `AudioBuffer`.

affects: >=3.0.0

deprecatedIn v3.4.0, direct calling of format factories like `decode.mp3(buf)` for whole-file decoding was deprecated. Use the top-level `decode(buf)` for automatic format detection and whole-file decoding.

fix

Replace `decode.mp3(myBuffer)` with `decode(myBuffer)`. For chunked decoding, first get a decoder instance: `let dec = await decode.mp3(); await dec(chunk);`.

affects: >=3.4.0

deprecatedThe `dec.decode(chunk)` method for chunked decoding was deprecated in v3.4.0 in favor of calling the decoder instance directly, i.e., `dec(chunk)`.

fix

Change calls from `myDecoder.decode(chunk)` to `myDecoder(chunk)`.

affects: >=3.4.0

deprecatedThe `decodeStream` function and `decoders` exports were deprecated in v3.3.0, though they might still work. The recommended approach for streaming decoding is now through format-specific decoders (`decode.mp3(response.body)`) or by obtaining a chunked decoder (`await decode.mp3()`).

fix

Migrate streaming logic to use `for await (let chunk of decode.mp3(stream))` or obtain a chunked decoder with `let dec = await decode.mp3()` and feed it chunks.

affects: >=3.3.0

gotchaInternal submodule names were renamed from `@audio/*-decode` to `@audio/decode-*` in v3.6.0. While this primarily affects monorepo structure, ensure correct import paths if directly referencing specific internal decoders.

fix

When using selective loading in browsers via import maps, ensure the paths reflect the new naming convention (e.g., `@audio/decode-mp3`).

affects: >=3.6.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use `import` syntax in a CommonJS environment (e.g., a Node.js script without `"type": "module"` in `package.json` or a `.mjs` extension).

fix

Ensure your project is configured for ESM. For Node.js, add `"type": "module"` to your `package.json` or save your file with a `.mjs` extension. If using an older Node.js environment, `audio-decode` v3.x is not compatible.

TypeError: Cannot read properties of undefined (reading 'channelData')

This error often occurs when code expects an `AudioBuffer` object (which was returned in v2.x) but receives the plain object `{ channelData, sampleRate }` returned by v3.x, and attempts to access `buffer.channelData` instead of `result.channelData`.

fix

Update your code to destructure the result directly or access properties on the returned plain object: `const { channelData, sampleRate } = await decode(buf);`.

Error: Unknown audio format

The `decode(buffer)` function failed to automatically detect the audio format from the provided `ArrayBuffer` or `Uint8Array` data, or the format is not supported by the library.

fix

Verify that the input `buffer` actually contains valid audio data for one of the supported formats. If you are certain of the format, consider using a format-specific decoder (e.g., `decode.mp3()`) for better error diagnostics, or ensure the necessary codec sub-package is available (e.g., in a browser import map).

Upgrade

Version history

3.9.3latest on npm

Audit

Dependencies

@audio/decode-mp3optionalInternal codec for MP3 decoding, dynamically loaded.

@audio/decode-wavoptionalInternal codec for WAV decoding, dynamically loaded.

@audio/decode-vorbisoptionalInternal codec for OGG Vorbis decoding, dynamically loaded.

@audio/decode-flacoptionalInternal codec for FLAC decoding, dynamically loaded.

@audio/decode-opusoptionalInternal codec for Opus decoding, dynamically loaded.

@audio/decode-aacoptionalInternal codec for M4A/AAC decoding, dynamically loaded.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/audiojs/audio-decode ↗

packagehttps://www.npmjs.com/package/audio-decode ↗