AudioEncoder

The AudioEncoder class encodes raw AudioData objects into compressed EncodedAudioChunk objects. It supports common audio codecs like AAC, MP3, Opus, FLAC, and Vorbis through FFmpeg.

This class follows the W3C WebCodecs AudioEncoder specification.

Quick Example

import { AudioEncoder, AudioData } from 'node-webcodecs';

// Create an AAC encoder
const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    console.log(`Encoded ${chunk.byteLength} bytes at ${chunk.timestamp}μs`);

    // First chunk includes decoder config
    if (metadata?.decoderConfig) {
      console.log('Decoder config:', metadata.decoderConfig);
    }
  },
  error: (err) => console.error('Encoding error:', err)
});

// Configure for AAC-LC at 128kbps
encoder.configure({
  codec: 'mp4a.40.2',      // AAC-LC
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 128_000
});

// Create audio data from raw samples
const audioData = new AudioData({
  format: 'f32-planar',
  sampleRate: 48000,
  numberOfFrames: 1024,
  numberOfChannels: 2,
  timestamp: 0,
  data: audioSamples
});

// Encode and close the source data
encoder.encode(audioData);
audioData.close();  // Important: prevent memory leaks

// Wait for encoding to complete
await encoder.flush();
encoder.close();

Always call audioData.close() after passing it to encode(). Failing to close AudioData objects will cause memory leaks as the underlying buffers are not automatically released.

Supported Audio Codecs

Codec	WebCodecs String	Typical Bitrate
AAC-LC	mp4a.40.2	128-256 kbps
MP3	mp3	128-320 kbps
Opus	opus	64-256 kbps
FLAC	flac	Lossless
Vorbis	vorbis	128-320 kbps

Constructor

Creates a new AudioEncoder with output and error callbacks.

new AudioEncoder(init: AudioEncoderInit)

init

AudioEncoderInit

required

Initialization callbacks for the encoder.

Show AudioEncoderInit properties

output

(chunk: EncodedAudioChunk, metadata?: AudioEncoderOutputMetadata) => void

required

Callback invoked when an encoded audio chunk is ready. The first chunk typically includes decoder configuration in the metadata.

error

(error: DOMException) => void

required

Callback invoked when an encoding error occurs. The encoder transitions to the 'closed' state after an error.

Throws: TypeError if callbacks are not functions.

Example: Creating an encoder

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    // Handle encoded chunk
    const data = new Uint8Array(chunk.byteLength);
    chunk.copyTo(data);

    // Check for decoder config (usually on first chunk)
    if (metadata?.decoderConfig) {
      console.log('Codec:', metadata.decoderConfig.codec);
      console.log('Sample rate:', metadata.decoderConfig.sampleRate);
      console.log('Channels:', metadata.decoderConfig.numberOfChannels);
    }
  },
  error: (err) => {
    console.error('Encoding failed:', err.message);
  }
});

Properties

state

CodecState

required

Current encoder state. One of:

'unconfigured' - Not configured yet, or reset() was called
'configured' - Ready to encode audio data
'closed' - Encoder has been closed and cannot be used

encodeQueueSize

number

required

Number of pending encode operations. Useful for backpressure management when encoding large amounts of audio data.

Static Methods

isConfigSupported()

Check if an audio encoder configuration is supported on this platform.

static isConfigSupported(config: AudioEncoderConfig): Promise<AudioEncoderSupport>

config

AudioEncoderConfig

required

Configuration to test for support.

Returns: Promise<AudioEncoderSupport> - Resolves with support status and normalized config.

Example: Checking codec support

const aacSupport = await AudioEncoder.isConfigSupported({
  codec: 'mp4a.40.2',
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 128_000
});

if (aacSupport.supported) {
  console.log('AAC encoding is supported');
  encoder.configure(aacSupport.config);
} else {
  console.log('AAC encoding is NOT supported');
}

Example: Fallback codec selection

// Try preferred codecs in order
const codecs = ['mp4a.40.2', 'opus', 'mp3'];

for (const codec of codecs) {
  const support = await AudioEncoder.isConfigSupported({
    codec,
    sampleRate: 48000,
    numberOfChannels: 2,
    bitrate: 128_000
  });

  if (support.supported) {
    console.log(`Using codec: ${codec}`);
    encoder.configure(support.config);
    break;
  }
}

Instance Methods

configure()

Configure the encoder with codec parameters. Must be called before encoding.

configure(config: AudioEncoderConfig): void

config

AudioEncoderConfig

required

Encoder configuration specifying codec and audio parameters.

Show AudioEncoderConfig properties

codec

string

required

Audio codec string. Common values:

'mp4a.40.2' - AAC-LC (most compatible)
'opus' - Opus (best quality/size ratio)
'mp3' - MP3 (legacy compatibility)
'flac' - FLAC (lossless)
'vorbis' - Vorbis (open source)

sampleRate

number

required

Sample rate in Hz. Common values: 44100, 48000, 96000.

numberOfChannels

number

required

Number of audio channels. Typically 1 (mono) or 2 (stereo).

bitrate

number

Target bitrate in bits per second. For example, 128_000 for 128 kbps. Not used for lossless codecs like FLAC.

bitrateMode

AudioBitrateMode

Bitrate control mode:

'constant' - Constant bitrate (CBR)
'variable' - Variable bitrate (VBR, default)

Throws:

InvalidStateError if encoder is closed
NotSupportedError if codec is not supported

Example: Configuring for AAC

encoder.configure({
  codec: 'mp4a.40.2',
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 256_000,
  bitrateMode: 'variable'
});

Example: Configuring for Opus

encoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 96_000  // Opus is very efficient
});

encode()

Queue an AudioData object for encoding.

encode(data: AudioData): void

data

AudioData

required

The raw audio data to encode. Must have a valid format and timestamp.

Throws:

InvalidStateError if encoder is not configured
TypeError if data is invalid

Always call audioData.close() after encoding to prevent memory leaks. The encoder makes an internal copy of the data, so closing the source is safe.

Example: Encoding audio frames

// Encode multiple audio frames
for (let i = 0; i < audioFrames.length; i++) {
  const audioData = new AudioData({
    format: 'f32-planar',
    sampleRate: 48000,
    numberOfFrames: 1024,
    numberOfChannels: 2,
    timestamp: i * 21333,  // ~21ms per AAC frame
    data: audioFrames[i]
  });

  encoder.encode(audioData);
  audioData.close();  // Always close after encode
}

Example: Backpressure handling

for (const samples of audioSamples) {
  const audioData = new AudioData({
    format: 'f32-planar',
    sampleRate: 48000,
    numberOfFrames: 1024,
    numberOfChannels: 2,
    timestamp,
    data: samples
  });

  encoder.encode(audioData);
  audioData.close();

  // Wait if queue gets too large
  if (encoder.encodeQueueSize > 10) {
    await new Promise(resolve => {
      encoder.addEventListener('dequeue', resolve, { once: true });
    });
  }
}

addEventListener()

Add an event listener for encoder events.

addEventListener(type: string, listener: () => void, options?: { once?: boolean }): void

type

string

required

Event type. Currently supports 'dequeue' which fires when the encode queue size decreases.

listener

() => void

required

Callback function to invoke when the event fires.

options

object

Event listener options.

Show Options

once

boolean

If true, the listener is automatically removed after being invoked once.

Example: Listening for dequeue events

// Monitor queue size
encoder.addEventListener('dequeue', () => {
  console.log('Queue size:', encoder.encodeQueueSize);
});

// One-time listener for flow control
await new Promise(resolve => {
  encoder.addEventListener('dequeue', resolve, { once: true });
});

removeEventListener()

Remove a previously added event listener.

removeEventListener(type: string, listener: () => void): void

type

string

required

Event type (e.g., 'dequeue').

listener

() => void

required

The callback function to remove. Must be the same function reference that was added.

Example: Removing a listener

const onDequeue = () => {
  console.log('Dequeue event fired');
};

encoder.addEventListener('dequeue', onDequeue);

// Later, remove the listener
encoder.removeEventListener('dequeue', onDequeue);

flush()

Wait for all pending encode operations to complete.

flush(): Promise<void>

Returns: Promise<void> - Resolves when all queued audio data has been encoded. Throws:

InvalidStateError if encoder is not configured
Rejects if encoding fails

Example: Flushing the encoder

// Encode all audio data
for (const frame of audioFrames) {
  encoder.encode(frame);
  frame.close();
}

// Wait for all encoding to complete
await encoder.flush();
console.log('All audio encoded!');

// Now safe to close
encoder.close();

reset()

Reset the encoder to the unconfigured state.

reset(): void

Aborts all pending encode operations and resets to the 'unconfigured' state. You must call configure() again before encoding more audio. Throws: InvalidStateError if encoder is closed

Example: Resetting and reconfiguring

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

encoder.encode(audioData);

// Abort and reconfigure with different settings
encoder.reset();

encoder.configure({
  codec: 'opus',
  sampleRate: 48000,
  numberOfChannels: 2
});

close()

Close the encoder and release all resources.

close(): void

The encoder cannot be used after calling close(). Any pending encode operations are aborted and the state transitions to 'closed'.

Example: Proper cleanup

// Encode all audio
for (const frame of audioFrames) {
  encoder.encode(frame);
  frame.close();
}

// Wait for encoding to complete
await encoder.flush();

// Release resources
encoder.close();

// encoder.encode() will now throw InvalidStateError

Type Definitions

AudioEncoderConfig

Configuration options for the audio encoder.

interface AudioEncoderConfig {
  codec: string;                     // Required: codec identifier
  sampleRate: number;                // Required: sample rate in Hz
  numberOfChannels: number;          // Required: channel count
  bitrate?: number;                  // Optional: target bitrate (bps)
  bitrateMode?: AudioBitrateMode;    // Optional: 'constant' | 'variable'
}

AudioEncoderInit

Initialization callbacks for creating an AudioEncoder.

interface AudioEncoderInit {
  output: (chunk: EncodedAudioChunk, metadata?: AudioEncoderOutputMetadata) => void;
  error: (error: DOMException) => void;
}

AudioEncoderOutputMetadata

Metadata provided with encoded audio chunks.

interface AudioEncoderOutputMetadata {
  decoderConfig?: {
    codec: string;              // Codec string for decoder
    sampleRate: number;         // Sample rate in Hz
    numberOfChannels: number;   // Channel count
    description?: ArrayBuffer;  // Codec-specific data (e.g., AudioSpecificConfig)
  };
}

AudioEncoderSupport

Result from isConfigSupported() indicating codec support.

interface AudioEncoderSupport {
  supported: boolean;           // Whether the config is supported
  config: AudioEncoderConfig;   // The tested (possibly normalized) config
}

AudioBitrateMode

Bitrate control mode for audio encoding.

type AudioBitrateMode = 'constant' | 'variable';

Value	Description
`'constant'`	Constant bitrate (CBR) - consistent file size, may waste bits on silence
`'variable'`	Variable bitrate (VBR) - better quality/size ratio, recommended for most uses

AudioData

Raw audio sample data for encoding

AudioDecoder

Decode EncodedAudioChunks back to AudioData

EncodedAudioChunk

Encoded audio chunk output

Getting Started

Migration Guides

API Reference

Guides

Cookbook

Examples

Help

AudioEncoder

AudioEncoder

Quick Example

Supported Audio Codecs

Constructor

Properties

Static Methods

isConfigSupported()

Instance Methods

configure()

encode()

addEventListener()

removeEventListener()

flush()

reset()

close()

Type Definitions

AudioEncoderConfig

AudioEncoderInit

AudioEncoderOutputMetadata

AudioEncoderSupport

AudioBitrateMode

See Also

AudioData

AudioDecoder

EncodedAudioChunk

​AudioEncoder

​Quick Example

​Supported Audio Codecs

​Constructor

​Properties

​Static Methods

​isConfigSupported()

​Instance Methods

​configure()

​encode()

​addEventListener()

​removeEventListener()

​flush()

​reset()

​close()

​Type Definitions

​AudioEncoderConfig

​AudioEncoderInit

​AudioEncoderOutputMetadata

​AudioEncoderSupport

​AudioBitrateMode

​See Also

AudioData

AudioDecoder

EncodedAudioChunk

AudioEncoder

Quick Example

Supported Audio Codecs

Constructor

Properties

Static Methods

isConfigSupported()

Instance Methods

configure()

encode()

addEventListener()

removeEventListener()

flush()

reset()

close()

Type Definitions

AudioEncoderConfig

AudioEncoderInit

AudioEncoderOutputMetadata

AudioEncoderSupport

AudioBitrateMode

See Also