Skip to content

Latest commit

 

History

History
489 lines (371 loc) · 12.9 KB

AudioDecoder.mdx

File metadata and controls

489 lines (371 loc) · 12.9 KB
title AudioDecoder
description Decode EncodedAudioChunk objects into AudioData for playback and processing
icon volume-high

AudioDecoder

The AudioDecoder class decodes compressed audio data (EncodedAudioChunk) into raw audio samples (AudioData). It supports common audio codecs like AAC, MP3, Opus, and FLAC.

This class follows the [W3C WebCodecs AudioDecoder specification](https://www.w3.org/TR/webcodecs/#audiodecoder-interface).

Quick Example

import { AudioDecoder, EncodedAudioChunk } from 'node-webcodecs';

// Create decoder with callbacks
const decoder = new AudioDecoder({
  output: (audioData) => {
    console.log(`Decoded ${audioData.numberOfFrames} samples`);
    console.log(`Format: ${audioData.format}, Rate: ${audioData.sampleRate}Hz`);

    // Process the audio data...

    // IMPORTANT: Always close AudioData when done
    audioData.close();
  },
  error: (e) => console.error('Decode error:', e)
});

// Configure for AAC decoding
decoder.configure({
  codec: 'mp4a.40.2',      // AAC-LC
  sampleRate: 48000,
  numberOfChannels: 2
});

// Decode encoded chunks
const chunk = new EncodedAudioChunk({
  type: 'key',
  timestamp: 0,
  data: aacFrameData
});

decoder.decode(chunk);

// Flush remaining data when done
await decoder.flush();
decoder.close();
Always call `audioData.close()` in your output callback after processing. AudioData objects hold native memory that JavaScript's garbage collector cannot reclaim automatically. Failing to close them will cause memory leaks.

Constructor

Creates a new AudioDecoder instance.

new AudioDecoder(init: AudioDecoderInit)
Initialization object containing callback functions. Callback invoked for each decoded audio frame. The `AudioData` object contains raw PCM samples ready for playback or processing. You **must** call `audioData.close()` when finished with each frame.
<ParamField body="error" type="(error: DOMException) => void" required>
  Callback invoked when a decoding error occurs. After an error, the decoder
  transitions to the `'closed'` state and cannot be used further.
</ParamField>

Properties

Current state of the decoder. One of: - `'unconfigured'` - Initial state, call `configure()` before decoding - `'configured'` - Ready to decode chunks - `'closed'` - Decoder has been closed and cannot be used Number of chunks waiting to be decoded. Use this for backpressure management - if the queue grows too large, pause feeding new chunks until it decreases.

Static Methods

isConfigSupported()

Checks whether a given configuration is supported by the decoder without creating an instance.

static isConfigSupported(config: AudioDecoderConfig): Promise<AudioDecoderSupport>
The configuration to test for support.

Returns: Promise<AudioDecoderSupport> - Object indicating whether the config is supported.

```typescript import { AudioDecoder } from 'node-webcodecs';

async function checkAACSupport() { const support = await AudioDecoder.isConfigSupported({ codec: 'mp4a.40.2', sampleRate: 48000, numberOfChannels: 2 });

if (support.supported) { console.log('AAC decoding is supported!'); } else { console.log('AAC decoding is NOT supported'); } }

</Accordion>

---

## Instance Methods

### configure()

Configures the decoder with codec parameters. Must be called before `decode()`.

```typescript
configure(config: AudioDecoderConfig): void
Configuration object specifying the codec and audio parameters. The codec string. Common values: - `'mp4a.40.2'` - AAC-LC (Low Complexity) - `'mp4a.40.5'` - AAC-HE (High Efficiency) - `'mp3'` - MP3 / MPEG-1 Audio Layer 3 - `'opus'` - Opus - `'flac'` - FLAC - `'vorbis'` - Vorbis
<ParamField body="sampleRate" type="number" required>
  Sample rate in Hz (e.g., 44100, 48000). Must match the encoded audio.
</ParamField>

<ParamField body="numberOfChannels" type="number" required>
  Number of audio channels (1 for mono, 2 for stereo, etc.).
</ParamField>

<ParamField body="description" type="BufferSource">
  Codec-specific configuration data (e.g., AudioSpecificConfig for AAC).
  Required for some codecs when container metadata is not embedded in the stream.
</ParamField>

Throws: InvalidStateError if the decoder is closed.

```typescript decoder.configure({ codec: 'mp4a.40.2', // AAC-LC sampleRate: 48000, numberOfChannels: 2 });

console.log(decoder.state); // 'configured'

</Accordion>

<Accordion title="Example: Configure with AudioSpecificConfig">
```typescript
// For AAC from MP4 container, you may need the AudioSpecificConfig
const audioSpecificConfig = new Uint8Array([0x11, 0x90]); // Example for 48kHz stereo AAC-LC

decoder.configure({
  codec: 'mp4a.40.2',
  sampleRate: 48000,
  numberOfChannels: 2,
  description: audioSpecificConfig
});

decode()

Queues an encoded audio chunk for decoding. Decoded frames will be delivered asynchronously to the output callback.

decode(chunk: EncodedAudioChunk): void
The encoded audio chunk to decode. Unlike video, most audio chunks are keyframes and can be decoded independently.

Throws:

  • InvalidStateError if the decoder is not configured
  • DataError if the chunk data is malformed
```typescript import { AudioDecoder, EncodedAudioChunk } from 'node-webcodecs';

// Assuming you have an array of AAC frames from a parser const aacFrames: Uint8Array[] = parseAACStream(audioData);

for (let i = 0; i < aacFrames.length; i++) { const chunk = new EncodedAudioChunk({ type: 'key', // Audio frames are typically keyframes timestamp: i * 21333, // ~21ms per AAC frame at 48kHz duration: 21333, data: aacFrames[i] });

decoder.decode(chunk); }

</Accordion>

---

### flush()

Completes all pending decode operations. Call this when you've submitted all chunks and need to ensure all output has been delivered.

```typescript
flush(): Promise<void>

Returns: Promise<void> - Resolves when all queued chunks have been decoded and output.

Throws: InvalidStateError if the decoder is not configured.

```typescript // After submitting all chunks await decoder.flush(); console.log('All audio decoded');

// Safe to close now decoder.close();

</Accordion>

---

### reset()

Resets the decoder to the `'unconfigured'` state, discarding any pending work. The decoder can be reconfigured after reset.

```typescript
reset(): void

Throws: InvalidStateError if the decoder is closed.

```typescript // Reset current decoding state decoder.reset(); console.log(decoder.state); // 'unconfigured'

// Reconfigure for different audio decoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 1 });

</Accordion>

---

### close()

Closes the decoder and releases all resources. The decoder cannot be used after calling `close()`.

```typescript
close(): void
```typescript async function decodeAudioFile(chunks: EncodedAudioChunk[]) { const decoder = new AudioDecoder({ output: (data) => { processAudio(data); data.close(); }, error: console.error });

decoder.configure({ codec: 'mp4a.40.2', sampleRate: 48000, numberOfChannels: 2 });

for (const chunk of chunks) { decoder.decode(chunk); }

await decoder.flush(); decoder.close(); // Clean up resources }

</Accordion>

---

## Interfaces

### AudioDecoderConfig

Configuration for the audio decoder.

```typescript
interface AudioDecoderConfig {
  codec: string;                    // Required: codec identifier
  sampleRate: number;               // Required: sample rate in Hz
  numberOfChannels: number;         // Required: number of channels
  description?: BufferSource;       // Optional: codec-specific config
}
Property Type Required Description
codec string Yes Codec string (e.g., 'mp4a.40.2', 'opus')
sampleRate number Yes Sample rate in Hz (e.g., 44100, 48000)
numberOfChannels number Yes Number of channels (1=mono, 2=stereo)
description BufferSource No Codec-specific configuration data

AudioDecoderInit

Initialization object for creating an AudioDecoder.

interface AudioDecoderInit {
  output: (data: AudioData) => void;           // Required: decoded frame callback
  error: (error: DOMException) => void;        // Required: error callback
}
Property Type Required Description
output (data: AudioData) => void Yes Called with each decoded AudioData
error (error: DOMException) => void Yes Called when an error occurs

AudioDecoderSupport

Result from isConfigSupported().

interface AudioDecoderSupport {
  supported: boolean;               // Whether the config is supported
  config: AudioDecoderConfig;       // The config that was tested
}
Property Type Description
supported boolean true if the configuration is supported
config AudioDecoderConfig The configuration that was tested

Common Codec Strings

Codec String Description
AAC-LC 'mp4a.40.2' AAC Low Complexity - most common
AAC-HE 'mp4a.40.5' AAC High Efficiency (SBR)
AAC-HEv2 'mp4a.40.29' AAC High Efficiency v2 (SBR+PS)
MP3 'mp3' MPEG-1 Audio Layer 3
Opus 'opus' Opus codec
FLAC 'flac' Free Lossless Audio Codec
Vorbis 'vorbis' Ogg Vorbis

Complete Decoding Example

import { AudioDecoder, EncodedAudioChunk } from 'node-webcodecs';

async function decodeAACStream(aacFrames: Uint8Array[]): Promise<Float32Array[]> {
  const decodedSamples: Float32Array[] = [];

  const decoder = new AudioDecoder({
    output: (audioData) => {
      // Allocate buffer for all channels interleaved
      const samples = new Float32Array(audioData.numberOfFrames * audioData.numberOfChannels);

      // Copy samples for each channel
      for (let ch = 0; ch < audioData.numberOfChannels; ch++) {
        const channelData = new Float32Array(audioData.numberOfFrames);
        audioData.copyTo(channelData, { planeIndex: ch, format: 'f32-planar' });

        // Interleave into output
        for (let i = 0; i < audioData.numberOfFrames; i++) {
          samples[i * audioData.numberOfChannels + ch] = channelData[i];
        }
      }

      decodedSamples.push(samples);
      audioData.close();  // Always close!
    },
    error: (e) => {
      throw new Error(`Decode error: ${e.message}`);
    }
  });

  // Configure decoder
  decoder.configure({
    codec: 'mp4a.40.2',
    sampleRate: 48000,
    numberOfChannels: 2
  });

  // Decode all frames
  let timestamp = 0;
  const frameDuration = 21333; // ~21ms for AAC at 48kHz

  for (const frame of aacFrames) {
    const chunk = new EncodedAudioChunk({
      type: 'key',
      timestamp,
      duration: frameDuration,
      data: frame
    });

    decoder.decode(chunk);
    timestamp += frameDuration;
  }

  // Wait for all decoding to complete
  await decoder.flush();
  decoder.close();

  return decodedSamples;
}

See Also

Raw audio sample data produced by decoding Encode AudioData into EncodedAudioChunks Compressed audio data for decoding Full list of supported codecs