| title | VideoEncoder |
|---|---|
| description | Encode VideoFrame objects into EncodedVideoChunk for H.264, VP8, VP9, and AV1 |
| icon | video |
The VideoEncoder class encodes raw VideoFrame objects into compressed EncodedVideoChunk objects. It supports multiple codecs including H.264, H.265/HEVC, VP8, VP9, and AV1, with optional hardware acceleration.
import { VideoEncoder, VideoFrame } from 'node-webcodecs';
// Create encoder with output callback
const encoder = new VideoEncoder({
output: (chunk, metadata) => {
console.log(`Encoded ${chunk.type} frame: ${chunk.byteLength} bytes`);
// Save decoder config on first keyframe
if (metadata?.decoderConfig) {
console.log('Codec:', metadata.decoderConfig.codec);
}
},
error: (err) => console.error('Encoding error:', err)
});
// Configure for H.264 at 1080p
encoder.configure({
codec: 'avc1.42E01E',
width: 1920,
height: 1080,
bitrate: 5_000_000,
framerate: 30
});
// Encode frames
const frame = new VideoFrame(rgbaBuffer, {
format: 'RGBA',
codedWidth: 1920,
codedHeight: 1080,
timestamp: 0
});
encoder.encode(frame);
frame.close(); // Always close frames after encoding!
await encoder.flush();
encoder.close();Use platform-specific codec names for hardware-accelerated encoding:
// Check for hardware encoder support
const hwSupport = await VideoEncoder.isConfigSupported({
codec: 'h264_videotoolbox', // macOS VideoToolbox
width: 1920,
height: 1080,
hardwareAcceleration: 'prefer-hardware'
});
if (hwSupport.supported) {
encoder.configure({
codec: 'h264_videotoolbox',
width: 1920,
height: 1080,
bitrate: 10_000_000
});
} else {
// Fallback to software encoder
encoder.configure({
codec: 'avc1.42E01E',
width: 1920,
height: 1080,
bitrate: 10_000_000
});
}| Codec | WebCodecs String | Hardware Options |
|---|---|---|
| H.264 | avc1.42E01E |
h264_videotoolbox, h264_nvenc |
| H.265 | hvc1.1.6.L93.B0 |
hevc_videotoolbox, hevc_nvenc |
| VP8 | vp8 |
- |
| VP9 | vp09.00.10.08 |
- |
| AV1 | av01.0.04M.08 |
- |
Creates a new VideoEncoder with output and error callbacks.
new VideoEncoder(init: VideoEncoderInit)<ParamField body="error" type="(error: DOMException) => void" required>
Callback invoked when an encoding error occurs.
</ParamField>
Throws: TypeError if callbacks are not functions.
const encoder = new VideoEncoder({ output: (chunk, metadata) => { chunks.push(chunk);
// Capture decoder config from first keyframe
if (metadata?.decoderConfig) {
decoderConfig = metadata.decoderConfig;
}
}, error: (err) => { console.error('Encoding failed:', err.message); } });
</Accordion>
---
## Properties
<ResponseField name="state" type="CodecState" required>
Current encoder state. One of:
- `'unconfigured'` - Not yet configured, or `reset()` was called
- `'configured'` - Ready to encode frames
- `'closed'` - Encoder has been closed and cannot be used
</ResponseField>
<ResponseField name="encodeQueueSize" type="number" required>
Number of pending encode operations in the queue. Useful for implementing backpressure to prevent memory exhaustion when encoding faster than output can be processed.
</ResponseField>
---
## Methods
### isConfigSupported()
Static method to check if a configuration is supported before creating an encoder.
```typescript
static VideoEncoder.isConfigSupported(config: VideoEncoderConfig): Promise<VideoEncoderSupport>
Returns: Promise<VideoEncoderSupport> with supported boolean and normalized config.
if (result.supported) { console.log('H.264 encoding is supported'); }
// Check hardware encoder with fallback const hwResult = await VideoEncoder.isConfigSupported({ codec: 'h264_videotoolbox', width: 3840, height: 2160, hardwareAcceleration: 'prefer-hardware' });
const codec = hwResult.supported ? 'h264_videotoolbox' : 'avc1.42E01E';
</Accordion>
---
### configure()
Configures the encoder with codec parameters. Must be called before encoding frames.
```typescript
encoder.configure(config: VideoEncoderConfig): void
<ParamField body="width" type="number" required>
Frame width in pixels. Must be greater than 0.
</ParamField>
<ParamField body="height" type="number" required>
Frame height in pixels. Must be greater than 0.
</ParamField>
<ParamField body="displayWidth" type="number">
Display width for pixel aspect ratio correction. Defaults to `width`.
</ParamField>
<ParamField body="displayHeight" type="number">
Display height for pixel aspect ratio correction. Defaults to `height`.
</ParamField>
<ParamField body="bitrate" type="number">
Target bitrate in bits per second. Example: `5_000_000` for 5 Mbps.
</ParamField>
<ParamField body="framerate" type="number">
Target framerate in frames per second. Defaults to `30`.
</ParamField>
<ParamField body="hardwareAcceleration" type="HardwareAcceleration">
Hardware acceleration preference:
- `'no-preference'` - Let encoder decide (default)
- `'prefer-hardware'` - Use hardware if available
- `'prefer-software'` - Force software encoding
</ParamField>
<ParamField body="latencyMode" type="LatencyMode">
Encoding latency optimization:
- `'quality'` - Optimize for compression ratio (default)
- `'realtime'` - Optimize for low latency
</ParamField>
<ParamField body="bitrateMode" type="BitrateMode">
Bitrate control mode:
- `'constant'` - Constant bitrate (CBR)
- `'variable'` - Variable bitrate (VBR)
- `'quantizer'` - Constant quality (CQP)
</ParamField>
<ParamField body="alpha" type="AlphaOption">
Alpha channel handling:
- `'discard'` - Remove alpha channel
- `'keep'` - Preserve alpha (if codec supports it)
</ParamField>
<ParamField body="scalabilityMode" type="string">
SVC/temporal layering mode. Example: `'L1T2'` for 1 spatial layer, 2 temporal layers.
</ParamField>
<ParamField body="colorSpace" type="VideoColorSpaceInit">
Color space metadata including `primaries`, `transfer`, `matrix`, and `fullRange`.
</ParamField>
<ParamField body="avc" type="object">
H.264-specific options.
<Expandable title="avc properties">
<ParamField body="format" type="'annexb' | 'avc'">
Output format:
- `'annexb'` - Annex B format with start codes (default)
- `'avc'` - AVC format with length-prefixed NALUs
</ParamField>
</Expandable>
</ParamField>
<ParamField body="useWorkerThread" type="boolean">
Use async encoding via worker thread. Defaults to `true`. Set to `false` for synchronous encoding (blocks event loop).
</ParamField>
Throws:
DOMExceptionif encoder is closedDOMExceptionif codec is not supportedDOMExceptionif dimensions are invalid
Encodes a video frame. The frame is queued for encoding and the output callback is invoked when complete.
encoder.encode(frame: VideoFrame, options?: VideoEncoderEncodeOptions): voidThrows:
DOMExceptionif encoder is not configuredDOMExceptionif frame is invalid or closed
encoder.encode(frames[i], { keyFrame: isKeyFrame }); frames[i].close(); // MUST close to prevent memory leak }
</Accordion>
---
### flush()
Waits for all pending encode operations to complete.
```typescript
encoder.flush(): Promise<void>
Returns: Promise<void> that resolves when all frames have been encoded.
Throws:
DOMExceptionif encoder is not configuredDOMExceptionif an encoding error occurs
// Wait for all encodes to complete await encoder.flush();
console.log('All frames encoded!'); encoder.close();
</Accordion>
---
### reset()
Resets the encoder to unconfigured state, aborting any pending operations.
```typescript
encoder.reset(): void
Throws: DOMException if encoder is closed.
// Abort and reconfigure with different settings encoder.reset();
encoder.configure({ codec: 'vp09.00.10.08', width: 1280, height: 720 }); encoder.encode(frame2); frame2.close();
</Accordion>
---
### close()
Closes the encoder and releases all resources. The encoder cannot be used after calling `close()`.
```typescript
encoder.close(): void
Adds an event listener for encoder events.
encoder.addEventListener(type: string, listener: () => void, options?: { once?: boolean }): voidRemoves an event listener.
encoder.removeEventListener(type: string, listener: () => void): voidWhen encoding video faster than it can be output (e.g., writing to disk), use encodeQueueSize and dequeue events to implement backpressure:
const MAX_QUEUE_SIZE = 10;
async function encodeWithBackpressure(frames: VideoFrame[]) {
for (const frame of frames) {
// Wait if queue is too large
while (encoder.encodeQueueSize >= MAX_QUEUE_SIZE) {
await new Promise<void>(resolve => {
encoder.addEventListener('dequeue', resolve, { once: true });
});
}
encoder.encode(frame);
frame.close();
}
await encoder.flush();
}Configuration options for the encoder.
interface VideoEncoderConfig {
codec: string; // Required
width: number; // Required
height: number; // Required
displayWidth?: number;
displayHeight?: number;
bitrate?: number;
framerate?: number;
hardwareAcceleration?: HardwareAcceleration;
alpha?: AlphaOption;
scalabilityMode?: string;
bitrateMode?: BitrateMode;
latencyMode?: LatencyMode;
colorSpace?: VideoColorSpaceInit;
avc?: { format?: 'annexb' | 'avc' };
useWorkerThread?: boolean;
}Callbacks for encoder initialization.
interface VideoEncoderInit {
output: (chunk: EncodedVideoChunk, metadata?: VideoEncoderOutputMetadata) => void;
error: (error: DOMException) => void;
}Metadata returned with encoded chunks.
interface VideoEncoderOutputMetadata {
decoderConfig?: {
codec: string;
codedWidth: number;
codedHeight: number;
description?: ArrayBuffer; // Codec extradata (SPS/PPS for H.264)
};
svc?: {
temporalLayerId: number; // 0 = base layer
};
}Options for encoding a single frame.
interface VideoEncoderEncodeOptions {
keyFrame?: boolean; // Force keyframe (default: false)
}Result from isConfigSupported().
interface VideoEncoderSupport {
supported: boolean;
config: VideoEncoderConfig;
}type LatencyMode = 'quality' | 'realtime';| Value | Description |
|---|---|
'quality' |
Optimize for compression ratio (may buffer frames) |
'realtime' |
Optimize for low latency encoding |
type BitrateMode = 'constant' | 'variable' | 'quantizer';| Value | Description |
|---|---|
'constant' |
Constant bitrate (CBR) - consistent file size |
'variable' |
Variable bitrate (VBR) - better quality/size ratio |
'quantizer' |
Constant quality (CQP) - consistent visual quality |
type AlphaOption = 'discard' | 'keep';| Value | Description |
|---|---|
'discard' |
Remove alpha channel from output |
'keep' |
Preserve alpha channel (codec must support transparency) |
Raw video frame data for encoding Decodes EncodedVideoChunks back to VideoFrames Compressed video data output from encoder Platform-specific hardware encoding setup