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

# API Reference

> Complete API reference for node-webcodecs

# API Reference

The node-webcodecs API follows the [W3C WebCodecs specification](https://www.w3.org/TR/webcodecs/), providing native video and audio encoding/decoding in Node.js.

<Info>
  All classes and types are exported from the main `node-webcodecs` package:

  ```typescript theme={null}
  import { VideoEncoder, VideoDecoder, VideoFrame, ... } from 'node-webcodecs';
  ```
</Info>

***

## Core Classes

### Video Processing

<CardGroup cols={2}>
  <Card title="VideoEncoder" icon="video" href="/api-reference/VideoEncoder">
    Encode raw `VideoFrame` objects into compressed video chunks (H.264, H.265, VP9, AV1)
  </Card>

  <Card title="VideoDecoder" icon="film" href="/api-reference/VideoDecoder">
    Decode compressed video chunks back into `VideoFrame` objects
  </Card>

  <Card title="VideoFrame" icon="image" href="/api-reference/VideoFrame">
    Raw video frame data with pixel format, dimensions, and color space
  </Card>

  <Card title="EncodedVideoChunk" icon="file-video" href="/api-reference/EncodedVideoChunk">
    A chunk of compressed video data (keyframe or delta frame)
  </Card>
</CardGroup>

### Audio Processing

<CardGroup cols={2}>
  <Card title="AudioEncoder" icon="microphone" href="/api-reference/AudioEncoder">
    Encode raw `AudioData` into compressed audio (AAC, MP3, Opus, FLAC)
  </Card>

  <Card title="AudioDecoder" icon="volume-high" href="/api-reference/AudioDecoder">
    Decode compressed audio chunks back into `AudioData` objects
  </Card>

  <Card title="AudioData" icon="waveform" href="/api-reference/AudioData">
    Raw audio samples with sample rate, channel count, and format
  </Card>

  <Card title="EncodedAudioChunk" icon="file-audio" href="/api-reference/EncodedAudioChunk">
    A chunk of compressed audio data
  </Card>
</CardGroup>

### Image & Color

<CardGroup cols={2}>
  <Card title="ImageDecoder" icon="image" href="/api-reference/ImageDecoder">
    Decode image files (JPEG, PNG, WebP, GIF) into `VideoFrame` objects
  </Card>

  <Card title="VideoColorSpace" icon="palette" href="/api-reference/VideoColorSpace">
    Color space information (primaries, transfer, matrix coefficients)
  </Card>
</CardGroup>

***

## Utility Functions

### FFmpeg Information

```typescript theme={null}
import { getFFmpegVersion, listCodecs, hasCodec, isNativeAvailable } from 'node-webcodecs';
```

<Accordion title="getFFmpegVersion()">
  Returns FFmpeg version information, or `null` if native module unavailable.

  ```typescript theme={null}
  const version = getFFmpegVersion();
  // { avcodec: 'libavcodec 60.31.102', avcodecVersion: '60.31.102' }
  ```
</Accordion>

<Accordion title="listCodecs()">
  Lists all available encoders and decoders.

  ```typescript theme={null}
  const codecs = listCodecs();
  // { encoders: [...], decoders: [...] }
  ```
</Accordion>

<Accordion title="hasCodec(codecName, type)">
  Check if a specific codec is available.

  ```typescript theme={null}
  hasCodec('libx264', 'encoder');  // true
  hasCodec('h264', 'decoder');     // true
  ```
</Accordion>

<Accordion title="isNativeAvailable()">
  Check if the native FFmpeg addon loaded successfully.

  ```typescript theme={null}
  if (isNativeAvailable()) {
    console.log('Native encoding available');
  }
  ```
</Accordion>

***

## Supported Codecs

### Video Codecs

| Codec      | WebCodecs String  | Encoding | Decoding | Hardware Accel        |
| ---------- | ----------------- | -------- | -------- | --------------------- |
| H.264/AVC  | `avc1.42001f`     | ✅        | ✅        | ✅ VideoToolbox, NVENC |
| H.265/HEVC | `hvc1.1.6.L93.B0` | ✅        | ✅        | ✅ VideoToolbox, NVENC |
| VP8        | `vp8`             | ✅        | ✅        | ❌                     |
| VP9        | `vp09.00.10.08`   | ✅        | ✅        | ❌                     |
| AV1        | `av01.0.04M.08`   | ✅        | ✅        | ❌                     |

### Audio Codecs

| Codec  | WebCodecs String | Encoding | Decoding |
| ------ | ---------------- | -------- | -------- |
| AAC    | `mp4a.40.2`      | ✅        | ✅        |
| MP3    | `mp3`            | ✅        | ✅        |
| Opus   | `opus`           | ✅        | ✅        |
| FLAC   | `flac`           | ✅        | ✅        |
| Vorbis | `vorbis`         | ✅        | ✅        |

***

## Type Definitions

For detailed type information, see the [Types Reference](/api-reference/types).

### Common Types

```typescript theme={null}
// Codec state lifecycle
type CodecState = 'unconfigured' | 'configured' | 'closed';

// Buffer input type
type BufferSource = ArrayBuffer | ArrayBufferView;

// Video pixel formats
type VideoPixelFormat =
  | 'I420' | 'I420A' | 'I422' | 'I444'
  | 'NV12' | 'RGBA' | 'RGBX' | 'BGRA' | 'BGRX';

// Audio sample formats
type AudioSampleFormat =
  | 'u8' | 's16' | 's32' | 'f32'
  | 'u8-planar' | 's16-planar' | 's32-planar' | 'f32-planar';
```

***

## Quick Reference

### Encoding Pipeline

```typescript theme={null}
// 1. Create encoder with output callback
const encoder = new VideoEncoder({
  output: (chunk, metadata) => { /* handle encoded chunk */ },
  error: (e) => console.error(e)
});

// 2. Configure codec settings
encoder.configure({
  codec: 'avc1.42001f',
  width: 1920,
  height: 1080,
  bitrate: 5_000_000
});

// 3. Feed frames
encoder.encode(frame);

// 4. Finish encoding
await encoder.flush();
encoder.close();
```

### Decoding Pipeline

```typescript theme={null}
// 1. Create decoder with output callback
const decoder = new VideoDecoder({
  output: (frame) => { /* handle decoded frame */ },
  error: (e) => console.error(e)
});

// 2. Configure with codec info
decoder.configure({
  codec: 'avc1.42001f',
  codedWidth: 1920,
  codedHeight: 1080
});

// 3. Feed chunks
decoder.decode(chunk);

// 4. Finish decoding
await decoder.flush();
decoder.close();
```