Overview
This module provides core type definitions used throughout the WebCodecs API. These types ensure type safety and compatibility with the W3C WebCodecs specification while adapting to Node.js environments.Type Aliases
Common type definitions like BufferSource and CodecState
Classes
DOMRectReadOnly and WebCodecsDOMException classes
Error Handling
DOM exception types with standard error codes
Codec States
State machine for encoder and decoder lifecycles
BufferSource
A union type representing binary data that can be passed to WebCodecs APIs.BufferSource accepts any typed array (Uint8Array, Float32Array, etc.) or raw ArrayBuffer. This is the standard way to pass binary data like encoded video frames or audio samples.Examples
CodecState
Represents the current state of a video or audio encoder/decoder.State Values
Terminal state after
close() is called. The codec cannot be used again and resources are released.State Transitions
The codec follows a strict state machine:1
unconfigured to configured
Call
configure() with a valid configuration object. The codec validates the configuration and prepares internal resources.2
configured to unconfigured
Call
reset() to return to the unconfigured state. This clears any pending work and allows reconfiguration with different parameters.3
Any state to closed
Call
close() from any state to permanently shut down the codec and release all resources. This is irreversible.Usage Example
WebCodecsDOMException
A DOM-style exception class for WebCodecs errors. Extends the standardError class with a numeric code property for compatibility with browser APIs.
Constructor
Optional error name (e.g., “NotSupportedError”, “InvalidStateError”). Determines the numeric code.
Instance Properties
Common Error Codes
The following table lists the error codes most frequently encountered when using WebCodecs:NotSupportedError (code 9) is thrown when:
- The codec string is invalid or not recognized
- The codec is not available on the current platform
- The configuration parameters are outside supported ranges
InvalidStateError (code 11) is thrown when:
- Calling
encode()/decode()beforeconfigure() - Calling any method on a closed codec
- Calling
configure()on an already closed codec
AbortError (code 20) is thrown when:
reset()is called while operations are pendingclose()is called while operations are pending- The codec encounters an unrecoverable internal error
All Error Codes
Complete DOM Exception Code Reference
Complete DOM Exception Code Reference
Error Handling Example
DOMRectReadOnly
An immutable rectangle class representing position and dimensions. Used byVideoFrame.visibleRect to describe the visible region of a video frame.
Constructor
Properties
Methods
toJSON()
Returns a plain object representation of the rectangle.Usage Example
Helper Functions
createDOMException()
Factory function to create aWebCodecsDOMException instance.
Type Aliases
WebCodecsError
An alias forWebCodecsDOMException for convenience.
DOMException
Re-export ofWebCodecsDOMException for browser API compatibility.
See Also
VideoEncoder
Encode raw video frames to compressed chunks
VideoDecoder
Decode compressed video to raw frames
AudioEncoder
Encode raw audio samples to compressed data
AudioDecoder
Decode compressed audio to raw samples