| title | AudioEncoder |
|---|---|
| description | Encode AudioData objects into EncodedAudioChunk for AAC, Opus, MP3, and more |
| icon | microphone |
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.
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();| 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 |
Creates a new AudioEncoder with output and error callbacks.
new AudioEncoder(init: AudioEncoderInit)<ParamField body="error" type="(error: DOMException) => void" required>
Callback invoked when an encoding error occurs. The encoder transitions to
the `'closed'` state after an error.
</ParamField>
Throws: TypeError if callbacks are not functions.
// 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); } });
</Accordion>
---
## Properties
<ResponseField name="state" type="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
</ResponseField>
<ResponseField name="encodeQueueSize" type="number" required>
Number of pending encode operations. Useful for backpressure management
when encoding large amounts of audio data.
</ResponseField>
---
## Static Methods
### isConfigSupported()
Check if an audio encoder configuration is supported on this platform.
```typescript
static isConfigSupported(config: AudioEncoderConfig): Promise<AudioEncoderSupport>
Returns: Promise<AudioEncoderSupport> - Resolves with support status and normalized config.
if (aacSupport.supported) { console.log('AAC encoding is supported'); encoder.configure(aacSupport.config); } else { console.log('AAC encoding is NOT supported'); }
</Accordion>
<Accordion title="Example: Fallback codec selection">
```typescript
// 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;
}
}
Configure the encoder with codec parameters. Must be called before encoding.
configure(config: AudioEncoderConfig): void<ParamField body="sampleRate" type="number" required>
Sample rate in Hz. Common values: 44100, 48000, 96000.
</ParamField>
<ParamField body="numberOfChannels" type="number" required>
Number of audio channels. Typically 1 (mono) or 2 (stereo).
</ParamField>
<ParamField body="bitrate" type="number">
Target bitrate in bits per second. For example, `128_000` for 128 kbps.
Not used for lossless codecs like FLAC.
</ParamField>
<ParamField body="bitrateMode" type="AudioBitrateMode">
Bitrate control mode:
- `'constant'` - Constant bitrate (CBR)
- `'variable'` - Variable bitrate (VBR, default)
</ParamField>
Throws:
InvalidStateErrorif encoder is closedNotSupportedErrorif codec is not supported
Queue an AudioData object for encoding.
encode(data: AudioData): voidThrows:
InvalidStateErrorif encoder is not configuredTypeErrorif data is invalid
encoder.encode(audioData); audioData.close(); // Always close after encode }
</Accordion>
<Accordion title="Example: Backpressure handling">
```typescript
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 });
});
}
}
Add an event listener for encoder events.
addEventListener(type: string, listener: () => void, options?: { once?: boolean }): void// One-time listener for flow control await new Promise(resolve => { encoder.addEventListener('dequeue', resolve, { once: true }); });
</Accordion>
---
### removeEventListener()
Remove a previously added event listener.
```typescript
removeEventListener(type: string, listener: () => void): void
encoder.addEventListener('dequeue', onDequeue);
// Later, remove the listener encoder.removeEventListener('dequeue', onDequeue);
</Accordion>
---
### flush()
Wait for all pending encode operations to complete.
```typescript
flush(): Promise<void>
Returns: Promise<void> - Resolves when all queued audio data has been encoded.
Throws:
InvalidStateErrorif encoder is not configured- Rejects if encoding fails
// Wait for all encoding to complete await encoder.flush(); console.log('All audio encoded!');
// Now safe to close encoder.close();
</Accordion>
---
### reset()
Reset the encoder to the unconfigured state.
```typescript
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
encoder.encode(audioData);
// Abort and reconfigure with different settings encoder.reset();
encoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 2 });
</Accordion>
---
### close()
Close the encoder and release all resources.
```typescript
close(): void
The encoder cannot be used after calling close(). Any pending encode operations
are aborted and the state transitions to 'closed'.
// Wait for encoding to complete await encoder.flush();
// Release resources encoder.close();
// encoder.encode() will now throw InvalidStateError
</Accordion>
---
## Type Definitions
### AudioEncoderConfig
Configuration options for the audio encoder.
```typescript
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'
}
Initialization callbacks for creating an AudioEncoder.
interface AudioEncoderInit {
output: (chunk: EncodedAudioChunk, metadata?: AudioEncoderOutputMetadata) => void;
error: (error: DOMException) => void;
}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)
};
}Result from isConfigSupported() indicating codec support.
interface AudioEncoderSupport {
supported: boolean; // Whether the config is supported
config: AudioEncoderConfig; // The tested (possibly normalized) config
}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 |
Raw audio sample data for encoding Decode EncodedAudioChunks back to AudioData Encoded audio chunk output