Types - node-webcodecs

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                    |
    +----------------------------------------------+

unconfigured to configured

Call configure() with a valid configuration object. The codec validates the configuration and prepares internal resources.

configured to unconfigured

Call reset() to return to the unconfigured state. This clears any pending work and allows reconfiguration with different parameters.

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:

Code	Name	Constant	Description
9	NotSupportedError	`NOT_SUPPORTED_ERR`	The requested codec or configuration is not supported
11	InvalidStateError	`INVALID_STATE_ERR`	Operation attempted in wrong codec state
20	AbortError	`ABORT_ERR`	Operation 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

Complete DOM Exception Code Reference

Code	Constant	Description
1	`INDEX_SIZE_ERR`	Index out of bounds
2	`DOMSTRING_SIZE_ERR`	String size error (deprecated)
3	`HIERARCHY_REQUEST_ERR`	Invalid hierarchy
4	`WRONG_DOCUMENT_ERR`	Wrong document
5	`INVALID_CHARACTER_ERR`	Invalid character
6	`NO_DATA_ALLOWED_ERR`	No data allowed (deprecated)
7	`NO_MODIFICATION_ALLOWED_ERR`	Modification not allowed
8	`NOT_FOUND_ERR`	Not found
9	`NOT_SUPPORTED_ERR`	Not supported
10	`INUSE_ATTRIBUTE_ERR`	Attribute in use
11	`INVALID_STATE_ERR`	Invalid state
12	`SYNTAX_ERR`	Syntax error
13	`INVALID_MODIFICATION_ERR`	Invalid modification
14	`NAMESPACE_ERR`	Namespace error
15	`INVALID_ACCESS_ERR`	Invalid access
16	`VALIDATION_ERR`	Validation error (deprecated)
17	`TYPE_MISMATCH_ERR`	Type mismatch
18	`SECURITY_ERR`	Security error
19	`NETWORK_ERR`	Network error
20	`ABORT_ERR`	Aborted
21	`URL_MISMATCH_ERR`	URL mismatch
22	`QUOTA_EXCEEDED_ERR`	Quota exceeded
23	`TIMEOUT_ERR`	Timeout
24	`INVALID_NODE_TYPE_ERR`	Invalid node type
25	`DATA_CLONE_ERR`	Data 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

number

default:"0"

The x-coordinate of the rectangle’s origin.

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

number

required

The x-coordinate of the rectangle’s origin (left edge for positive width).

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

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

​Overview

Type Aliases

Classes

Error Handling

Codec States

​BufferSource

​Examples

​CodecState

​State Values

​State Transitions

​Usage Example

​WebCodecsDOMException

​Constructor

​Instance Properties

​Common Error Codes

​All Error Codes

​Error Handling Example

​DOMRectReadOnly

​Constructor

​Properties

​Methods

​toJSON()

​Usage Example

​Helper Functions

​createDOMException()

​Type Aliases

​WebCodecsError

​DOMException

​See Also

VideoEncoder

VideoDecoder

AudioEncoder

AudioDecoder

Overview

BufferSource

Examples

CodecState

State Values

State Transitions

Usage Example

WebCodecsDOMException

Constructor

Instance Properties

Common Error Codes

All Error Codes

Error Handling Example

DOMRectReadOnly

Constructor

Properties

Methods

toJSON()

Usage Example

Helper Functions

createDOMException()

Type Aliases

WebCodecsError

DOMException

See Also