> ## Documentation Index
> Fetch the complete documentation index at: https://docs.node-webcodecs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> TypeScript type definitions and common types used across the WebCodecs API

## 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.

<CardGroup cols={2}>
  <Card title="Type Aliases" icon="hashtag" href="#buffersource">
    Common type definitions like BufferSource and CodecState
  </Card>

  <Card title="Classes" icon="cube" href="#domrectreadonly">
    DOMRectReadOnly and WebCodecsDOMException classes
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="#webcodecsdomexception">
    DOM exception types with standard error codes
  </Card>

  <Card title="Codec States" icon="diagram-project" href="#codecstate">
    State machine for encoder and decoder lifecycles
  </Card>
</CardGroup>

***

## BufferSource

A union type representing binary data that can be passed to WebCodecs APIs.

```typescript theme={null}
type BufferSource = ArrayBuffer | ArrayBufferView
```

<Info>
  `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.
</Info>

### Examples

```typescript theme={null}
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.

```typescript theme={null}
type CodecState = "unconfigured" | "configured" | "closed"
```

### State Values

<ResponseField name="unconfigured" type="string">
  Initial state before `configure()` is called. The codec cannot process data in this state.
</ResponseField>

<ResponseField name="configured" type="string">
  Active state after successful `configure()` call. The codec is ready to encode or decode data.
</ResponseField>

<ResponseField name="closed" type="string">
  Terminal state after `close()` is called. The codec cannot be used again and resources are released.
</ResponseField>

### State Transitions

The codec follows a strict state machine:

```
                    configure()
    +---------------+------------>+---------------+
    | unconfigured  |             |  configured   |
    +---------------+<------------+---------------+
           |            reset()          |
           |                             |
           |  close()                    |  close()
           v                             v
    +----------------------------------------------+
    |                    closed                    |
    +----------------------------------------------+
```

<Steps>
  <Step title="unconfigured to configured">
    Call `configure()` with a valid configuration object. The codec validates the configuration and prepares internal resources.
  </Step>

  <Step title="configured to unconfigured">
    Call `reset()` to return to the unconfigured state. This clears any pending work and allows reconfiguration with different parameters.
  </Step>

  <Step title="Any state to closed">
    Call `close()` from any state to permanently shut down the codec and release all resources. This is irreversible.
  </Step>
</Steps>

<Warning>
  Attempting to call `encode()`, `decode()`, or `configure()` on a closed codec will throw an `InvalidStateError`. Always check the `state` property before performing operations.
</Warning>

### Usage Example

```typescript theme={null}
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

```typescript theme={null}
new WebCodecsDOMException(message?: string, name?: string): WebCodecsDOMException
```

<ParamField path="message" type="string">
  Optional error message describing what went wrong.
</ParamField>

<ParamField path="name" type="string">
  Optional error name (e.g., "NotSupportedError", "InvalidStateError"). Determines the numeric code.
</ParamField>

### Instance Properties

<ResponseField name="name" type="string" required>
  The name of the error (e.g., "NotSupportedError", "InvalidStateError", "AbortError").
</ResponseField>

<ResponseField name="code" type="number" required>
  Numeric error code matching the W3C DOM exception codes.
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable description of the error.
</ResponseField>

### 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())   |

<Info>
  **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
</Info>

<Info>
  **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
</Info>

<Info>
  **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
</Info>

### All Error Codes

<Accordion title="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               |
</Accordion>

### Error Handling Example

```typescript theme={null}
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

```typescript theme={null}
new DOMRectReadOnly(x?: number, y?: number, width?: number, height?: number): DOMRectReadOnly
```

<ParamField path="x" type="number" default="0">
  The x-coordinate of the rectangle's origin.
</ParamField>

<ParamField path="y" type="number" default="0">
  The y-coordinate of the rectangle's origin.
</ParamField>

<ParamField path="width" type="number" default="0">
  The width of the rectangle.
</ParamField>

<ParamField path="height" type="number" default="0">
  The height of the rectangle.
</ParamField>

### Properties

<ResponseField name="x" type="number" required>
  The x-coordinate of the rectangle's origin (left edge for positive width).
</ResponseField>

<ResponseField name="y" type="number" required>
  The y-coordinate of the rectangle's origin (top edge for positive height).
</ResponseField>

<ResponseField name="width" type="number" required>
  The width of the rectangle.
</ResponseField>

<ResponseField name="height" type="number" required>
  The height of the rectangle.
</ResponseField>

<ResponseField name="top" type="number" required>
  The y-coordinate of the top edge (minimum of y and y + height).
</ResponseField>

<ResponseField name="right" type="number" required>
  The x-coordinate of the right edge (maximum of x and x + width).
</ResponseField>

<ResponseField name="bottom" type="number" required>
  The y-coordinate of the bottom edge (maximum of y and y + height).
</ResponseField>

<ResponseField name="left" type="number" required>
  The x-coordinate of the left edge (minimum of x and x + width).
</ResponseField>

### Methods

#### toJSON()

Returns a plain object representation of the rectangle.

```typescript theme={null}
toJSON(): { x: number; y: number; width: number; height: number }
```

### Usage Example

```typescript theme={null}
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.

```typescript theme={null}
function createDOMException(message?: string, name?: string): WebCodecsDOMException
```

<ParamField path="message" type="string">
  Optional error message.
</ParamField>

<ParamField path="name" type="string">
  Optional error name that determines the numeric code.
</ParamField>

***

## Type Aliases

### WebCodecsError

An alias for `WebCodecsDOMException` for convenience.

```typescript theme={null}
type WebCodecsError = WebCodecsDOMException
```

### DOMException

Re-export of `WebCodecsDOMException` for browser API compatibility.

```typescript theme={null}
const DOMException = WebCodecsDOMException
```

***

## See Also

<CardGroup cols={2}>
  <Card title="VideoEncoder" icon="film" href="/api-reference/VideoEncoder">
    Encode raw video frames to compressed chunks
  </Card>

  <Card title="VideoDecoder" icon="play" href="/api-reference/VideoDecoder">
    Decode compressed video to raw frames
  </Card>

  <Card title="AudioEncoder" icon="microphone" href="/api-reference/AudioEncoder">
    Encode raw audio samples to compressed data
  </Card>

  <Card title="AudioDecoder" icon="volume-high" href="/api-reference/AudioDecoder">
    Decode compressed audio to raw samples
  </Card>
</CardGroup>