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.

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)

init

AudioDecoderInit

required

Initialization object containing callback functions.

Show AudioDecoderInit properties

output

(data: AudioData) => void

required

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.

error

(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.

Properties

state

CodecState

required

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

decodeQueueSize

number

required

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>

config

AudioDecoderConfig

required

The configuration to test for support.

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

Example: Check codec support

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');
  }
}

Instance Methods

configure()

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

configure(config: AudioDecoderConfig): void

config

AudioDecoderConfig

required

Configuration object specifying the codec and audio parameters.

Show AudioDecoderConfig properties

codec

string

required

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

sampleRate

number

required

Sample rate in Hz (e.g., 44100, 48000). Must match the encoded audio.

numberOfChannels

number

required

Number of audio channels (1 for mono, 2 for stereo, etc.).

description

BufferSource

Codec-specific configuration data (e.g., AudioSpecificConfig for AAC). Required for some codecs when container metadata is not embedded in the stream.

Throws: InvalidStateError if the decoder is closed.

Example: Configure for AAC-LC

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

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

Example: Configure with AudioSpecificConfig

// 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

chunk

EncodedAudioChunk

required

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

Example: Decode audio stream

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);
}

flush()

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

flush(): Promise<void>

Returns: Promise<void> - Resolves when all queued chunks have been decoded and output. Throws: InvalidStateError if the decoder is not configured.

Example: Flush before closing

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

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

reset()

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

reset(): void

Throws: InvalidStateError if the decoder is closed.

Example: Reset and reconfigure

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

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

close()

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

close(): void

Example: Proper cleanup

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
}

Interfaces

AudioDecoderConfig

Configuration for the audio decoder.

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;
}

AudioData

Raw audio sample data produced by decoding

AudioEncoder

Encode AudioData into EncodedAudioChunks

EncodedAudioChunk

Compressed audio data for decoding

Codec Registry

Full list of supported codecs

Getting Started

Migration Guides

API Reference

Guides

Cookbook

Examples

Help

AudioDecoder

AudioDecoder

Quick Example

Constructor

Properties

Static Methods

isConfigSupported()

Instance Methods

configure()

decode()

flush()

reset()

close()

Interfaces

AudioDecoderConfig

AudioDecoderInit

AudioDecoderSupport

Common Codec Strings

Complete Decoding Example

See Also

AudioData

AudioEncoder

EncodedAudioChunk

Codec Registry

​AudioDecoder

​Quick Example

​Constructor

​Properties

​Static Methods

​isConfigSupported()

​Instance Methods

​configure()

​decode()

​flush()

​reset()

​close()

​Interfaces

​AudioDecoderConfig

​AudioDecoderInit

​AudioDecoderSupport

​Common Codec Strings

​Complete Decoding Example

​See Also

AudioData

AudioEncoder

EncodedAudioChunk

Codec Registry

AudioDecoder

Quick Example

Constructor

Properties

Static Methods

isConfigSupported()

Instance Methods

configure()

decode()

flush()

reset()

close()

Interfaces

AudioDecoderConfig

AudioDecoderInit

AudioDecoderSupport

Common Codec Strings

Complete Decoding Example

See Also