Skip to main content

​
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. 
type BufferSource = ArrayBuffer | ArrayBufferView
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

import { VideoDecoder, EncodedVideoChunk, AudioData } from 'node-webcodecs';

// Using Uint8Array (most common)
const chunk = new EncodedVideoChunk({
  type: 'key',
  timestamp: 0,
  data: new Uint8Array([0x00, 0x00, 0x01, ...])
});

// Using ArrayBuffer directly
const buffer = new ArrayBuffer(1024);
const audioData = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: 256,
  numberOfChannels: 2,
  timestamp: 0,
  data: buffer
});

// Using a view into an existing buffer
const largeBuffer = new ArrayBuffer(10000);
const slice = new Uint8Array(largeBuffer, 100, 500);

​
CodecState

Represents the current state of a video or audio encoder/decoder. 
type CodecState = "unconfigured" | "configured" | "closed"

​
State Values

​
unconfigured
string
Initial state before configure() is called. The codec cannot process data in this state.
​
configured
string
Active state after successful configure() call. The codec is ready to encode or decode data.
​
closed
string
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: 
                    configure()
    +---------------+------------>+---------------+
    | unconfigured  |             |  configured   |
    +---------------+<------------+---------------+
           |            reset()          |
           |                             |
           |  close()                    |  close()
           v                             v
    +----------------------------------------------+
    |                    closed                    |
    +----------------------------------------------+
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.
Attempting to call encode(), decode(), or configure() on a closed codec will throw an InvalidStateError. Always check the state property before performing operations.

​
Usage Example

const decoder = new VideoDecoder({
  output: (frame) => handleFrame(frame),
  error: (e) => console.error(e)
});

console.log(decoder.state); // "unconfigured"

await decoder.configure({
  codec: 'avc1.42E01E',
  codedWidth: 1920,
  codedHeight: 1080
});

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

// Process video chunks...

decoder.close();
console.log(decoder.state); // "closed"

​
WebCodecsDOMException

A DOM-style exception class for WebCodecs errors. Extends the standard Error class with a numeric code property for compatibility with browser APIs.

​
Constructor

new WebCodecsDOMException(message?: string, name?: string): WebCodecsDOMException
​
message
string
Optional error message describing what went wrong.
​
name
string
Optional error name (e.g., “NotSupportedError”, “InvalidStateError”). Determines the numeric code.

​
Instance Properties

​
name
string
required
The name of the error (e.g., “NotSupportedError”, “InvalidStateError”, “AbortError”).
​
code
number
required
Numeric error code matching the W3C DOM exception codes.
​
message
string
required
Human-readable description of the error.

​
Common Error Codes

The following table lists the error codes most frequently encountered when using WebCodecs:
CodeNameConstantDescription
9NotSupportedErrorNOT_SUPPORTED_ERRThe requested codec or configuration is not supported
11InvalidStateErrorINVALID_STATE_ERROperation attempted in wrong codec state
20AbortErrorABORT_ERROperation was aborted (e.g., by reset() or close())
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() before configure()
  • 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 pending
  • close() is called while operations are pending
  • The codec encounters an unrecoverable internal error

​
All Error Codes

CodeConstantDescription
1INDEX_SIZE_ERRIndex out of bounds
2DOMSTRING_SIZE_ERRString size error (deprecated)
3HIERARCHY_REQUEST_ERRInvalid hierarchy
4WRONG_DOCUMENT_ERRWrong document
5INVALID_CHARACTER_ERRInvalid character
6NO_DATA_ALLOWED_ERRNo data allowed (deprecated)
7NO_MODIFICATION_ALLOWED_ERRModification not allowed
8NOT_FOUND_ERRNot found
9NOT_SUPPORTED_ERRNot supported
10INUSE_ATTRIBUTE_ERRAttribute in use
11INVALID_STATE_ERRInvalid state
12SYNTAX_ERRSyntax error
13INVALID_MODIFICATION_ERRInvalid modification
14NAMESPACE_ERRNamespace error
15INVALID_ACCESS_ERRInvalid access
16VALIDATION_ERRValidation error (deprecated)
17TYPE_MISMATCH_ERRType mismatch
18SECURITY_ERRSecurity error
19NETWORK_ERRNetwork error
20ABORT_ERRAborted
21URL_MISMATCH_ERRURL mismatch
22QUOTA_EXCEEDED_ERRQuota exceeded
23TIMEOUT_ERRTimeout
24INVALID_NODE_TYPE_ERRInvalid node type
25DATA_CLONE_ERRData clone error

​
Error Handling Example

import { VideoDecoder, WebCodecsDOMException } from 'node-webcodecs';

const decoder = new VideoDecoder({
  output: (frame) => frame.close(),
  error: (e) => {
    if (e instanceof WebCodecsDOMException) {
      switch (e.code) {
        case WebCodecsDOMException.NOT_SUPPORTED_ERR:
          console.error('Codec not supported:', e.message);
          break;
        case WebCodecsDOMException.INVALID_STATE_ERR:
          console.error('Invalid state:', e.message);
          break;
        case WebCodecsDOMException.ABORT_ERR:
          console.error('Operation aborted:', e.message);
          break;
        default:
          console.error('Unknown error:', e.code, e.message);
      }
    }
  }
});

​
DOMRectReadOnly

An immutable rectangle class representing position and dimensions. Used by VideoFrame.visibleRect to describe the visible region of a video frame.

​
Constructor

new DOMRectReadOnly(x?: number, y?: number, width?: number, height?: number): DOMRectReadOnly
​
x
number
default:"0"
The x-coordinate of the rectangle’s origin.
​
y
number
default:"0"
The y-coordinate of the rectangle’s origin.
​
width
number
default:"0"
The width of the rectangle.
​
height
number
default:"0"
The height of the rectangle.

​
Properties

​
x
number
required
The x-coordinate of the rectangle’s origin (left edge for positive width).
​
y
number
required
The y-coordinate of the rectangle’s origin (top edge for positive height).
​
width
number
required
The width of the rectangle.
​
height
number
required
The height of the rectangle.
​
top
number
required
The y-coordinate of the top edge (minimum of y and y + height).
​
right
number
required
The x-coordinate of the right edge (maximum of x and x + width).
​
bottom
number
required
The y-coordinate of the bottom edge (maximum of y and y + height).
​
left
number
required
The x-coordinate of the left edge (minimum of x and x + width).

​
Methods

​
toJSON()

Returns a plain object representation of the rectangle. 
toJSON(): { x: number; y: number; width: number; height: number }

​
Usage Example

import { VideoFrame } from 'node-webcodecs';

// Create a video frame
const frame = new VideoFrame(imageData, {
  timestamp: 0,
  visibleRect: { x: 10, y: 10, width: 1900, height: 1060 }
});

// Access the visible rectangle
const rect = frame.visibleRect;
console.log(`Position: (${rect.x}, ${rect.y})`);
console.log(`Size: ${rect.width}x${rect.height}`);
console.log(`Bounds: top=${rect.top}, right=${rect.right}, bottom=${rect.bottom}, left=${rect.left}`);

// Serialize to JSON
const json = rect.toJSON();
// { x: 10, y: 10, width: 1900, height: 1060 }

​
Helper Functions

​
createDOMException()

Factory function to create a WebCodecsDOMException instance. 
function createDOMException(message?: string, name?: string): WebCodecsDOMException
​
message
string
Optional error message.
​
name
string
Optional error name that determines the numeric code.

​
Type Aliases

​
WebCodecsError

An alias for WebCodecsDOMException for convenience. 
type WebCodecsError = WebCodecsDOMException

​
DOMException

Re-export of WebCodecsDOMException for browser API compatibility. 
const DOMException = WebCodecsDOMException

​
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