{"id":12848,"library":"audio-decode","title":"Universal Audio Decoder","description":"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.","status":"active","version":"3.9.3","language":"javascript","source_language":"en","source_url":"https://github.com/audiojs/audio-decode","tags":["javascript","audio","decode","decoder","codec","mp3","wav","ogg","vorbis","typescript"],"install":[{"cmd":"npm install audio-decode","lang":"bash","label":"npm"},{"cmd":"yarn add audio-decode","lang":"bash","label":"yarn"},{"cmd":"pnpm add audio-decode","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal codec for MP3 decoding, dynamically loaded.","package":"@audio/decode-mp3","optional":true},{"reason":"Internal codec for WAV decoding, dynamically loaded.","package":"@audio/decode-wav","optional":true},{"reason":"Internal codec for OGG Vorbis decoding, dynamically loaded.","package":"@audio/decode-vorbis","optional":true},{"reason":"Internal codec for FLAC decoding, dynamically loaded.","package":"@audio/decode-flac","optional":true},{"reason":"Internal codec for Opus decoding, dynamically loaded.","package":"@audio/decode-opus","optional":true},{"reason":"Internal codec for M4A/AAC decoding, dynamically loaded.","package":"@audio/decode-aac","optional":true}],"imports":[{"note":"The library is ESM-only since v3.0.0. Use `import` syntax.","wrong":"const decode = require('audio-decode');","symbol":"decode","correct":"import decode from 'audio-decode';"},{"note":"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.","wrong":"import { mp3 } from 'audio-decode';","symbol":"decode.mp3","correct":"import decode from 'audio-decode'; const mp3Decoder = await decode.mp3();"},{"note":"Type import for the returned audio data structure `{ channelData: Float32Array[], sampleRate: number }`.","symbol":"AudioData","correct":"import type { AudioData } from 'audio-decode';"}],"quickstart":{"code":"import decode from 'audio-decode';\nimport { promises as fs } from 'fs';\nimport path from 'path';\n\nasync function decodeAudioFile(filePath: string) {\n  const audioBuffer = await fs.readFile(filePath);\n  console.log(`Decoding ${path.basename(filePath)}...`);\n  try {\n    const { channelData, sampleRate } = await decode(audioBuffer);\n    console.log(`Successfully decoded audio.`);\n    console.log(`Sample Rate: ${sampleRate} Hz`);\n    console.log(`Channels: ${channelData.length}`);\n    console.log(`Duration: ${channelData[0].length / sampleRate} seconds`);\n    // You can now process channelData (an array of Float32Array for each channel)\n  } catch (error) {\n    console.error(`Error decoding audio:`, error);\n  }\n}\n\n// Example usage (replace with a real audio file path)\ndecodeAudioFile('path/to/your/audio.mp3');\n// Or for a streaming example:\n// import { Readable } from 'stream';\n// async function decodeStreamExample() {\n//   const readableStream = Readable.from(new Uint8Array([/* your audio bytes */]));\n//   for await (const { channelData, sampleRate } of decode.mp3(readableStream)) {\n//     console.log(`Received chunk: ${channelData[0].length} samples at ${sampleRate}Hz`);\n//   }\n// }\n// decodeStreamExample();","lang":"typescript","description":"Demonstrates how to decode an audio file from a buffer and access its `channelData` and `sampleRate`."},"warnings":[{"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`.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `decode.mp3(myBuffer)` with `decode(myBuffer)`. For chunked decoding, first get a decoder instance: `let dec = await decode.mp3(); await dec(chunk);`.","message":"In 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.","severity":"deprecated","affected_versions":">=3.4.0"},{"fix":"Change calls from `myDecoder.decode(chunk)` to `myDecoder(chunk)`.","message":"The `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)`.","severity":"deprecated","affected_versions":">=3.4.0"},{"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.","message":"The `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()`).","severity":"deprecated","affected_versions":">=3.3.0"},{"fix":"When using selective loading in browsers via import maps, ensure the paths reflect the new naming convention (e.g., `@audio/decode-mp3`).","message":"Internal 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.","severity":"gotcha","affected_versions":">=3.6.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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).","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Update your code to destructure the result directly or access properties on the returned plain object: `const { channelData, sampleRate } = await decode(buf);`.","cause":"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`.","error":"TypeError: Cannot read properties of undefined (reading 'channelData')"},{"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).","cause":"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.","error":"Error: Unknown audio format"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}