NodeAV

https://seydx.github.io/node-av/
Admin
NodeAV provides native Node.js bindings for FFmpeg with full TypeScript support, offering direct...
Tokens:785,167
Snippets:6,173
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Demuxer.startTime

Source: https://seydx.github.io/node-av/api/api/classes/Demuxer.html

Gets the media start time in seconds.

```APIDOC
## Demuxer.startTime

### Description
Gets the media start time in seconds. For device inputs (e.g., avfoundation), this reflects the system uptime at capture start. Pass this value to `Muxer.open()` via the `startTime` option to produce correct output timestamps. Returns 0 if start time is unknown or not available or input is closed.

### Accessor
get startTime(): number

### Returns
`number` - The start time in seconds.

### Example
```typescript
await using input = await Demuxer.open(source);
await using output = await Muxer.open('output.mp4', { startTime: input.startTime });
```
```

--------------------------------

### Audio Sample Format Utilities Example

Source: https://seydx.github.io/node-av/api/api/classes/SampleFormatUtils.html

Demonstrates common operations with SampleFormatUtils, including getting format names, byte sizes, checking for planar formats, and converting between packed and planar layouts.

```typescript
import { SampleFormat } from 'node-av';
import { AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';

// Get format information
console.log(SampleFormat.getName(AV_SAMPLE_FMT_S16));        // "s16"
console.log(SampleFormat.getBytesPerSample(AV_SAMPLE_FMT_S16)); // 2
console.log(SampleFormat.isPlanar(AV_SAMPLE_FMT_FLTP));      // true

// Convert between packed and planar formats
const packed = SampleFormat.getPackedFormat(AV_SAMPLE_FMT_FLTP);
const planar = SampleFormat.getPlanarFormat(AV_SAMPLE_FMT_FLT);

```

--------------------------------

### start()

Source: https://seydx.github.io/node-av/api/webrtc/classes/WebRTCStream.html

Starts streaming media to the WebRTC peer connection. This method initiates the media processing pipeline, sending RTP packets to the media tracks. It's often called implicitly by setOffer but can be invoked explicitly for finer control over the streaming start time.

```APIDOC
## start()

### Description
Start streaming media to WebRTC peer connection.
Begins the media processing pipeline, reading packets from input, transcoding if necessary, and sending RTP packets to media tracks. Note: The stream is automatically started by setOffer, so calling this method explicitly is optional. This method is provided for cases where you need explicit control over when streaming begins.

### Method
start(): `Promise`<`void`>

### Returns
`Promise`<`void`> - Promise that resolves when streaming completes

### Throws
If transcoding or muxing fails

### Example
```typescript
const session = await WebRTCStream.create('input.mp4');
await session.start();

// Stop after 10 seconds
setTimeout(async () => await session.stop(), 10000);
```
```

--------------------------------

### start()

Source: https://seydx.github.io/node-av/api/api/classes/FMP4Stream.html

Starts the media processing pipeline to generate fMP4 chunks. This method returns immediately after initiating the pipeline. Transcoding decisions are made based on supported codecs.

```APIDOC
## start()

### Description
Start streaming media to fMP4 chunks.
Begins the media processing pipeline, reading packets from input, transcoding based on supported codecs, and generating fMP4 chunks. Video transcodes to H.264 if H.264/H.265 not supported. Audio transcode to AAC if AAC/FLAC/Opus not supported. This method returns immediately after starting the pipeline.

### Returns
`Promise<void>`
Promise that resolves when pipeline is started

### Throws
If setup fails

### Example
```typescript
const stream = await FMP4Stream.create('input.mp4', {
  supportedCodecs: 'avc1.640029,mp4a.40.2',
  onData: (data) => sendToClient(data.data)
});

// Start streaming (returns immediately)
await stream.start();

// Later: stop streaming
await stream.stop();
```
```

--------------------------------

### Install Cross-Platform Binaries with npm

Source: https://seydx.github.io/node-av

Install native bindings and FFmpeg binaries for a different target platform (e.g., Windows x64 on a Linux CI runner) by passing npm's --os and --cpu flags.

```bash
# Install Windows x64 binaries while running on Linux
npm install --os=win32 --cpu=x64
```

--------------------------------

### Create WebRTC Session and Start Streaming

Source: https://seydx.github.io/node-av/api/webrtc/classes/WebRTCStream.html

Demonstrates creating a WebRTC session from a media source URL, configuring ICE servers, handling ICE candidates, processing an SDP offer, and starting the stream. Use this for initiating a WebRTC stream from a server-side perspective.

```typescript
import { WebRTCStream } from 'node-av/api';

// Create session from media source
const session = await WebRTCStream.create('rtsp://camera.local/stream', {
  mtu: 1200,
  hardware: 'auto',
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
  onIceCandidate: (candidate) => {
    sendToClient({ type: 'candidate', value: candidate });
  }
});

// Process SDP offer from client
const answer = await session.setOffer(clientOffer);
sendToClient({ type: 'answer', value: answer });

// Start streaming
await session.start();

```

--------------------------------

### Install node-av

Source: https://seydx.github.io/node-av

Install the node-av package using npm.

```bash
npm install node-av
```

--------------------------------

### Start and Stop FMP4Stream

Source: https://seydx.github.io/node-av/api/api/classes/FMP4Stream.html

Demonstrates starting the media processing pipeline and stopping it gracefully. The start() method returns immediately after initiating the pipeline.

```typescript
const stream = await FMP4Stream.create('input.mp4', {
  supportedCodecs: 'avc1.640029,mp4a.40.2',
  onData: (data) => sendToClient(data.data)
});

// Start streaming (returns immediately)
await stream.start();

// Later: stop streaming
await stream.stop();
```

--------------------------------

### Configure Codec Context Example

Source: https://seydx.github.io/node-av/api/api/interfaces/EncoderOptions.html

This example demonstrates how to use the 'configure' option to set the codec tag to 'hvc1' just before the codec context is opened.

```typescript
await Encoder.create(FF_ENCODER_LIBX265, {
  decoder,
  configure: (ctx) => {
    ctx.codecTag = 'hvc1';
  },
});
```

--------------------------------

### Stream Copy Example

Source: https://seydx.github.io/node-av/api/api/classes/Muxer.html

Illustrates how to copy streams from an input file to an output file using Demuxer and Muxer. This example shows how to configure the output streams based on the input streams and process packets efficiently.

```APIDOC
## Stream Copy with Muxer and Demuxer

### Description
Copies media streams from an input file to an output file. This process involves reading packets from the input using `Demuxer` and writing them to the output using `Muxer`, while automatically handling stream configuration and packet processing.

### Method
`async function copyStream(inputPath: string, outputPath: string): Promise<void>`

### Request Example
```typescript
import { Demuxer, Muxer } from 'node-av/api';

// Stream copy
await using input = await Demuxer.open('input.mp4');
await using output = await Muxer.open('output.mp4');

// Copy stream configuration
const videoIdx = output.addStream(input.video());

// Process packets - header/trailer handled automatically
for await (const packet of input.packets()) {
  await output.writePacket(packet, videoIdx);
  packet.free();
}
```
```

--------------------------------

### Start WebRTC Streaming

Source: https://seydx.github.io/node-av/api/webrtc/classes/WebRTCStream.html

Begin streaming media to the WebRTC peer connection. This method is optional as setOffer typically starts the stream automatically. It's provided for explicit control over when streaming begins.

```typescript
const session = await WebRTCStream.create('input.mp4');
session.onIceCandidate = (c) => sendToRemote(c);

const answer = await session.setOffer(remoteOffer);
sendToRemote(answer);
// Stream is already started by setOffer
```

--------------------------------

### Pick Supported Layout Example

Source: https://seydx.github.io/node-av/api/api/functions/pickSupportedLayout.html

Demonstrates how pickSupportedLayout selects a supported layout with the nearest channel count when the input layout is not directly supported. This example shows a 7.1 (8 channel) input being mapped to a 5.1 (6 channel) layout because it has the closest channel count among the supported options.

```typescript
import { avChannelLayoutDefault } from 'node-av';

// 7.1 (8ch) input into a codec supporting stereo + 5.1 -> nearest count is 5.1 (6ch)
const picked = pickSupportedLayout(avChannelLayoutDefault(8), [avChannelLayoutDefault(2), avChannelLayoutDefault(6)]);
console.log(picked.nbChannels); // 6
```

--------------------------------

### ffmpegVersion

Source: https://seydx.github.io/node-av/api/ffmpeg

Gets the version of the installed FFmpeg executable. This can be helpful for ensuring compatibility or for logging purposes.

```APIDOC
## ffmpegVersion

### Description
Gets the version of the installed FFmpeg executable.

### Usage
```javascript
import { ffmpegVersion } from 'node-av/ffmpeg';

const version = ffmpegVersion();
console.log(version);
```

### Returns
- `string` - The FFmpeg version string.
```

--------------------------------

### AudioFifo Usage Example

Source: https://seydx.github.io/node-av/api/lib/classes/AudioFifo.html

Demonstrates creating an AudioFifo, allocating space, writing stereo float planar audio samples, reading samples when available, and cleaning up the FIFO.

```typescript
import { AudioFifo, FFmpegError } from 'node-av';
import { AV_SAMPLE_FMT_FLTP } from 'node-av/constants';

// Create FIFO for stereo float planar audio
const fifo = new AudioFifo();
fifo.alloc(AV_SAMPLE_FMT_FLTP, 2, 4096);

// Write samples
const leftChannel = Buffer.alloc(1024 * 4);  // 1024 float samples
const rightChannel = Buffer.alloc(1024 * 4);
const written = await fifo.write([leftChannel, rightChannel], 1024);
FFmpegError.throwIfError(written, 'write');

// Read samples when enough available
if (fifo.size >= 512) {
  const outLeft = Buffer.alloc(512 * 4);
  const outRight = Buffer.alloc(512 * 4);
  const read = await fifo.read([outLeft, outRight], 512);
  FFmpegError.throwIfError(read, 'read');
}

// Cleanupifo.free();
```

--------------------------------

### Get Demuxer Start Time

Source: https://seydx.github.io/node-av/api/api/classes/Demuxer.html

Retrieves the media start time in seconds. This value is important for maintaining correct timestamps when creating output files, especially for device inputs. It should be passed to `Muxer.open()`.

```typescript
await using input = await Demuxer.open(source);
await using output = await Muxer.open('output.mp4', { startTime: input.startTime });
```

--------------------------------

### Create and Use HardwareDeviceContext

Source: https://seydx.github.io/node-av/api/lib/classes/HardwareDeviceContext.html

Demonstrates creating a hardware device context for CUDA acceleration, listing available hardware types, and associating it with a CodecContext. Also shows how to create a derived context and clean up resources.

```typescript
import { HardwareDeviceContext, FFmpegError } from 'node-av';
import { AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VIDEOTOOLBOX } from 'node-av/constants';

// Create hardware device
const device = new HardwareDeviceContext();
const ret = device.create(AV_HWDEVICE_TYPE_CUDA);
FFmpegError.throwIfError(ret, 'create');

// List available hardware types
const types = HardwareDeviceContext.iterateTypes();
for (const type of types) {
  const name = HardwareDeviceContext.getTypeName(type);
  console.log(`Available: ${name}`);
}

// Use with decoder
const codecContext = new CodecContext();
codecContext.hwDeviceCtx = device;

// Create derived context
const derived = new HardwareDeviceContext();
const ret2 = derived.createDerived(device, AV_HWDEVICE_TYPE_CUDA);
FFmpegError.throwIfError(ret2, 'createDerived');

// Cleanup
device.free();
```

--------------------------------

### startTime

Source: https://seydx.github.io/node-av/api/lib/classes/Stream.html

Gets or sets the start time of the stream in stream time base units. Returns AV_NOPTS_VALUE if unknown.

```APIDOC
## get startTime

### Description
Gets the first timestamp of the stream in stream time base units. Returns AV_NOPTS_VALUE if unknown.

### Signature
> **get** **startTime**(): `bigint`

### Returns
`bigint` - The start time.
```

```APIDOC
## set startTime

### Description
Sets the start time of the stream.

### Signature
> **set** **startTime**(`value`): `void`

### Parameters
#### value
`bigint` - The start time.

### Returns
`void`
```

--------------------------------

### Get Codec String

Source: https://seydx.github.io/node-av/api/api/classes/FMP4Stream.html

Retrieves the codec string after the stream has started. This string is used for addSourceBuffer() in MediaSource API.

```typescript
const stream = await FMP4Stream.create('input.mp4', {
  supportedCodecs: 'avc1.640029,mp4a.40.2'
});

await stream.start(); // Must start first
const codecString = stream.getCodecString();
console.log(codecString); // "avc1.640029,mp4a.40.2"
// Use this for: sourceBuffer = mediaSource.addSourceBuffer(`video/mp4; codecs="${codecString}"`);
```

--------------------------------

### Get Demuxer Instance

Source: https://seydx.github.io/node-av/api/api/classes/FMP4Stream.html

Retrieves the underlying Demuxer instance after the stream has started. Useful for accessing demuxer properties like bitRate.

```typescript
const stream = FMP4Stream.create('input.mp4', {
// ... options
});
const input = stream.getInput();
console.log('Bitrate:', input?.bitRate);
```

--------------------------------

### init()

Source: https://seydx.github.io/node-av/api/lib/classes/HardwareDeviceContext.html

Initializes an allocated hardware device context. This must be called after allocation and before the device can be used.

```APIDOC
## init()

### Description
Initialize allocated hardware device.
Initializes a previously allocated hardware device context. Must be called after alloc() and before using the device.
Direct mapping to av_hwdevice_ctx_init().

### Returns
- **number** - 0 on success, negative AVERROR on error: 
  * AVERROR_EINVAL: Invalid parameters
  * AVERROR_ENOMEM: Memory allocation failure
  * Device-specific errors

### Example
typescript
```typescript
import { FFmpegError } from 'node-av';

device.alloc(type);
const ret = device.init();
FFmpegError.throwIfError(ret, 'init');
```

### See
- alloc Must be called first
- create For combined operation
```

--------------------------------

### Get FFmpeg Binary Path

Source: https://seydx.github.io/node-av/api/ffmpeg/functions/ffmpegPath.html

Retrieves the absolute path to the FFmpeg binary. This path is specific to the operating system and the installed FFmpeg version.

```typescript
import { ffmpegPath } from 'node-av/ffmpeg';

const path = ffmpegPath();
console.log('FFmpeg binary at:', path);
// On Windows: C:\path\to\node_modules\node-av\binary\ffmpeg.exe
// On Unix: /path/to/node_modules/node-av/binary/ffmpeg
```

--------------------------------

### create()

Source: https://seydx.github.io/node-av/api/lib/classes/HardwareDeviceContext.html

Creates and initializes a hardware device context. This is the preferred method as it combines allocation and initialization. It supports specifying a device name/path and device-specific options. It is a direct mapping to av_hwdevice_ctx_create().

```APIDOC
## create(type, device?, options?)

### Description
Create and initialize hardware device. Combined allocation and initialization of a hardware device. This is the preferred method for creating hardware contexts. Direct mapping to av_hwdevice_ctx_create().

### Method
create

### Parameters
#### type
`AVHWDeviceType` - Hardware device type
#### device?
`string` | `null` - Device name/path (null for default)
#### options?
`Dictionary` | `null` - Device-specific options

### Returns
`number`
0 on success, negative AVERROR on error:
  * AVERROR_EINVAL: Invalid type or parameters
  * AVERROR_ENOMEM: Memory allocation failure
  * AVERROR_ENOSYS: Type not supported
  * Device-specific errors

### Example
typescript
```typescript
import { FFmpegError, Dictionary } from 'node-av';
import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';

// Create with default device
const device = new HardwareDeviceContext();
let ret = device.create(AV_HWDEVICE_TYPE_CUDA);
FFmpegError.throwIfError(ret, 'create');

// Create with specific device
const device2 = new HardwareDeviceContext();
ret = device2.create(AV_HWDEVICE_TYPE_VAAPI, '/dev/dri/renderD128');
FFmpegError.throwIfError(ret, 'create');

// Create with options
const opts = Dictionary.fromObject({ 'device_idx': '1' });
ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, opts);
FFmpegError.throwIfError(ret, 'create');
```

### See
createDerived To create from existing device
```

--------------------------------

### Get FFmpeg Version

Source: https://seydx.github.io/node-av/api/ffmpeg/functions/ffmpegVersion.html

Import and call the ffmpegVersion() function to retrieve the FFmpeg version string. This example shows how to log the version to the console.

```typescript
import { ffmpegVersion } from 'node-av/ffmpeg';

console.log('FFmpeg version:', ffmpegVersion());
// Output: FFmpeg version: 8.0
```

--------------------------------

### Initialize and Use CodecContext for Decoding

Source: https://seydx.github.io/node-av/api/lib/classes/CodecContext.html

Demonstrates how to create, configure, open, and use a CodecContext for decoding H.264 video streams. Includes error handling and cleanup.

```typescript
import { CodecContext, Codec, FFmpegError } from 'node-av';
import { AV_CODEC_ID_H264, AV_PIX_FMT_YUV420P } from 'node-av/constants';

// Create decoder
const decoder = new CodecContext();
const codec = Codec.findDecoder(AV_CODEC_ID_H264);
decoder.allocContext3(codec);

// Configure from stream parameters
decoder.parametersToContext(stream.codecpar);

// Open decoder
let ret = await decoder.open2(codec);
FFmpegError.throwIfError(ret, 'open2');

// Decode packets
ret = await decoder.sendPacket(packet);
if (ret >= 0) {
  ret = await decoder.receiveFrame(frame);
  if (ret >= 0) {
    // Process decoded frame
  }
}

// Cleanup
decoder.freeContext();
```

--------------------------------

### RTPStream.start

Source: https://seydx.github.io/node-av/api/webrtc/classes/RTPStream.html

Starts the RTP media streaming pipeline. This method initiates media processing and RTP packet callbacks, returning immediately after setup.

```APIDOC
## start()

> **start**(): `Promise`<`void`>

Start streaming media to RTP packets.

Begins the media processing pipeline, reading packets from input, transcoding if necessary, and invoking RTP packet callbacks. Automatically handles video and audio streams in parallel. This method returns immediately after starting the pipeline.

### Returns

`Promise`<`void`>

Promise that resolves when pipeline is started

### Throws

If no video stream found in input

### Throws

If setup fails

### Example

typescript
```
const stream = RTPStream.create('rtsp://camera.local/stream', {
  onVideoPacket: (rtp) => sendRtp(rtp)
});

// Start streaming (returns immediately)
await stream.start();

// Later: stop streaming
await stream.stop();
```
```

--------------------------------

### getCodecString()

Source: https://seydx.github.io/node-av/api/api/classes/FMP4Stream.html

Retrieves the codec string that will be used by the client. This method should be called after start() has been invoked to get the MIME type codec string for use with addSourceBuffer().

```APIDOC
## getCodecString()

### Description
Get the codec string that will be used by client.
Returns the MIME type codec string based on input codecs and transcoding decisions. Call this after start() is called to know what codec string to use for addSourceBuffer().

### Returns
`string`
MIME type codec string (e.g., "avc1.640029,mp4a.40.2")

### Throws
If called before start() is called

### Example
```typescript
const stream = await FMP4Stream.create('input.mp4', {
  supportedCodecs: 'avc1.640029,mp4a.40.2'
});

await stream.start(); // Must start first
const codecString = stream.getCodecString();
console.log(codecString); // "avc1.640029,mp4a.40.2"
// Use this for: sourceBuffer = mediaSource.addSourceBuffer(`video/mp4; codecs="${codecString}"`);
```
```

--------------------------------

### AudioSampleUtils alloc() Method Example

Source: https://seydx.github.io/node-av/api/api/classes/AudioSampleUtils.html

Illustrates allocating audio sample buffers for both planar and packed formats using the alloc() static method.

```typescript
import { AudioSampleUtils } from 'node-av';
import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16 } from 'node-av/constants';

// Allocate for planar format (separate buffer per channel)
const planar = AudioSampleUtils.alloc(2, 1024, AV_SAMPLE_FMT_FLTP, 0);
console.log(`Planar: ${planar.data.length} buffers`); // 2 buffers

// Allocate for packed format (single interleaved buffer)
const packed = AudioSampleUtils.alloc(2, 1024, AV_SAMPLE_FMT_S16, 0);
console.log(`Packed: ${packed.data.length} buffer`);  // 1 buffer
```

--------------------------------

### Rational toString() Example

Source: https://seydx.github.io/node-av/api/lib/classes/Rational.html

Use toString() to get a string representation of the rational number in 'num/den' format. This method is useful for displaying fractional values.

```typescript
const framerate = new Rational(30000, 1001);
console.log(framerate.toString()); // "30000/1001"

const timebase = new Rational(1, 90000);
console.log(`Timebase: ${timebase}`); // "Timebase: 1/90000"
```

--------------------------------

### Add Kisak-Mesa PPA

Source: https://seydx.github.io/node-av

Add the Kisak-Mesa PPA to your system to get newer Mesa versions with improved hardware support. This is a prerequisite for installing the recommended drivers.

```bash
sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt update
```

--------------------------------

### Pipeline with Multiple Filters

Source: https://seydx.github.io/node-av/api/api/functions/pipeline.html

This example demonstrates setting up a media pipeline with a decoder, two sequential filters, and an encoder. It's suitable for scenarios requiring multiple image or stream manipulations before encoding. Initialize all filter instances correctly.

```typescript
const decoder = await Decoder.create(input.video());
const scaleFilter = FilterAPI.create('scale=640:480', { ... });
const cropFilter = FilterAPI.create('crop=640:360', { ... });
const encoder = await Encoder.create(FF_ENCODER_LIBX264, { ... });
const control = pipeline(input, decoder, scaleFilter, cropFilter, encoder, output);
await control.completion;
```

--------------------------------

### Create and Use a Generic FIFO Buffer

Source: https://seydx.github.io/node-av/api/lib/classes/Fifo.html

Demonstrates creating a FIFO buffer, writing data to it, reading data from it, and cleaning up resources. This example shows how to initialize the FIFO, set auto-grow limits, and handle potential errors during read/write operations.

```typescript
import { Fifo, FFmpegError } from 'node-av';
import { AV_FIFO_FLAG_AUTO_GROW } from 'node-av/constants';

// Create FIFO for 32-bit integers
const fifo = new Fifo();
fifo.alloc(100, 4, AV_FIFO_FLAG_AUTO_GROW);
fifo.setAutoGrowLimit(1000);

// Write data
const data = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
const written = await fifo.write(data, 2); // Write 2 elements (8 bytes)
FFmpegError.throwIfError(written, 'write');

// Read data
const outBuffer = Buffer.alloc(8);
const read = await fifo.read(outBuffer, 2); // Read 2 elements
FFmpegError.throwIfError(read, 'read');

// Cleanupifo.free();

```

--------------------------------

### Get DASH MIME Type for Codec Parameters

Source: https://seydx.github.io/node-av/api/lib/functions/avGetMimeTypeDash.html

This snippet demonstrates how to use avGetMimeTypeDash to determine the MIME type for MPEG-DASH segments. It shows examples for H.264 (resulting in video/mp4) and VP9 (resulting in video/webm) codecs.

```typescript
import { avGetMimeTypeDash } from 'node-av/lib';

const stream = input.video();
const mimeType = avGetMimeTypeDash(stream.codecpar);
console.log(mimeType); // "video/mp4" for H.264

// VP9 codec
const mimeTypeVP9 = avGetMimeTypeDash(vp9Stream.codecpar);
console.log(mimeTypeVP9); // "video/webm"
```

--------------------------------

### Encoder.create (Video Encoding Example)

Source: https://seydx.github.io/node-av/api/api/classes/Encoder.html

Demonstrates how to create and use an H.264 video encoder synchronously. This includes setting up encoder options, encoding a single frame, and writing the resulting packet.

```APIDOC
## Encoder.create (Video Encoding Example)

### Description
Creates and configures an encoder instance for video streams, specifically demonstrating H.264 encoding with libx264. It shows the process of encoding a single frame and handling the output packet.

### Method
`Encoder.create(codec: Codec, options: EncoderOptions, encoderOptions?: EncoderOptions)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { Encoder } from 'node-av/api';
import { AV_CODEC_ID_H264, FF_ENCODER_LIBX264 } from 'node-av/constants';

// Assuming 'frame' is an AVFrame object
const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
  type: 'video',
  width: 1920,
  height: 1080,
  pixelFormat: AV_PIX_FMT_YUV420P,
  timeBase: { num: 1, den: 30 },
  frameRate: { num: 30, den: 1 }
}, {
  bitrate: '5M',
  gopSize: 60
});

const packet = await encoder.encode(frame);
if (packet) {
  // Assuming 'output' is an object with a writePacket method
  await output.writePacket(packet);
  packet.free();
}
```

### Response
#### Success Response (Encoder Instance)
- **encoder** (Encoder) - An initialized Encoder instance.

#### Response Example
(See Request Example for usage context)

### Error Handling
- Throws an error if encoder creation or encoding fails.
```

--------------------------------

### Get Planar Sample Format

Source: https://seydx.github.io/node-av/api/lib/functions/avGetPlanarSampleFmt.html

Demonstrates how to use avGetPlanarSampleFmt() to convert packed audio sample formats to their planar equivalents. Requires importing sample format constants.

```typescript
import { AV_SAMPLE_FMT_FLT, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';

const planar = avGetPlanarSampleFmt(AV_SAMPLE_FMT_FLT);   // Returns AV_SAMPLE_FMT_FLTP
const same = avGetPlanarSampleFmt(AV_SAMPLE_FMT_FLTP);    // Returns AV_SAMPLE_FMT_FLTP
```

--------------------------------

### Start and Stop RTP Stream

Source: https://seydx.github.io/node-av/api/webrtc/classes/RTPStream.html

Demonstrates starting an RTP stream and then stopping it. The start() method returns immediately after initiating the pipeline, and stop() cleans up resources.

```typescript
const stream = RTPStream.create('rtsp://camera.local/stream', {
  onVideoPacket: (rtp) => sendRtp(rtp)
});

// Start streaming (returns immediately)
await stream.start();

// Later: stop streaming
await stream.stop();
```

--------------------------------

### init()

Source: https://seydx.github.io/node-av/api/lib/classes/CodecParser.html

Initialize parser for specific codec. Sets up the parser to handle a specific codec format. Must be called before parsing data.

```APIDOC
## init(codecId)

### Description
Initialize parser for specific codec. Sets up the parser to handle a specific codec format. Must be called before parsing data. Direct mapping to av_parser_init().

### Parameters
#### codecId
* **codecId** (`AVCodecID`) - Required - Codec ID to parse

### Returns
`void`

### Throws
If codec parser not available

### Example
typescript
```javascript
import { AV_CODEC_ID_AAC } from 'node-av/constants';

const parser = new CodecParser();
parser.init(AV_CODEC_ID_AAC);
// Parser ready for AAC ADTS streams
```

### See
* parse2 To parse data
* close To cleanup
```

--------------------------------

### Create and Initialize Hardware Device Context

Source: https://seydx.github.io/node-av/api/lib/classes/HardwareDeviceContext.html

Use create() for a combined allocation and initialization of a hardware device. This is the preferred method. It can create devices with default settings, specific device paths, or custom options.

```typescript
import { FFmpegError, Dictionary } from 'node-av';
import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';

// Create with default device
const device = new HardwareDeviceContext();
let ret = device.create(AV_HWDEVICE_TYPE_CUDA);
FFmpegError.throwIfError(ret, 'create');

// Create with specific device
const device2 = new HardwareDeviceContext();
ret = device2.create(AV_HWDEVICE_TYPE_VAAPI, '/dev/dri/renderD128');
FFmpegError.throwIfError(ret, 'create');

// Create with options
const opts = Dictionary.fromObject({ 'device_idx': '1' });
ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, opts);
FFmpegError.throwIfError(ret, 'create');
```

--------------------------------

### guided

Source: https://seydx.github.io/node-av/api/constants/interfaces/FilterOptionsMap.html

Apply Guided filter. This filter adjusts image based on guidance image.

```APIDOC
## guided

### Description
Apply Guided filter.

### Parameters
#### Optional Parameters
- **eps?** (number) - Optional - set the regularization parameter (with square)
- **guidance?** (string) - Optional - set guidance mode (0: off mode; 1: on mode)
- **mode?** (string) - Optional - set filtering mode (0: basic mode; 1: fast mode)
- **planes?** (number) - Optional - set planes to filter
- **radius?** (number) - Optional - set the box radius
- **sub?** (number) - Optional - subsampling ratio for fast mode

### See
https://ffmpeg.org/ffmpeg-filters.html#guided
```

--------------------------------

### Get Default Stereo Channel Layout

Source: https://seydx.github.io/node-av/api/lib/functions/avChannelLayoutDefault.html

Use avChannelLayoutDefault with 2 to get the default channel layout for stereo audio.

```typescript
const stereo = avChannelLayoutDefault(2); // { order: 1, nbChannels: 2, mask: 3n }
```

--------------------------------

### Initialize and Use SoftwareResampleContext

Source: https://seydx.github.io/node-av/api/lib/classes/SoftwareResampleContext.html

Demonstrates creating, configuring, and using a SoftwareResampleContext for audio frame conversion. Includes error handling and cleanup.

```typescript
import { SoftwareResampleContext, Frame, FFmpegError } from 'node-av';
import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16 } from 'node-av/constants';

// Create resampler
const resampler = new SoftwareResampleContext();

// Configure format conversion
const outLayout = { nbChannels: 2, order: 1, u: { mask: 3n } }; // Stereo
const inLayout = { nbChannels: 1, order: 1, u: { mask: 1n } };  // Mono

const ret = resampler.allocSetOpts2(
  outLayout, AV_SAMPLE_FMT_S16, 48000,  // Output: Stereo, 16-bit, 48kHz
  inLayout, AV_SAMPLE_FMT_FLTP, 44100   // Input: Mono, float, 44.1kHz
);
FFmpegError.throwIfError(ret, 'allocSetOpts2');

const ret2 = resampler.init();
FFmpegError.throwIfError(ret2, 'init');

// Convert audio frame
const outFrame = new Frame();
outFrame.nbSamples = 1024;
outFrame.format = AV_SAMPLE_FMT_S16;
outFrame.channelLayout = outLayout;
outFrame.sampleRate = 48000;
outFrame.allocBuffer();

const ret3 = resampler.convertFrame(outFrame, inFrame);
FFmpegError.throwIfError(ret3, 'convertFrame');

// Get conversion delay
const delay = resampler.getDelay(48000n);
console.log(`Resampler delay: ${delay} samples`);

// Clean up
resampler.free();

```

--------------------------------

### getContext()

Source: https://seydx.github.io/node-av/api/lib/classes/SoftwareScaleContext.html

Sets up the scaler with source and destination formats. This is the primary configuration method.

```APIDOC
## getContext(srcW, srcH, srcFormat, dstW, dstH, dstFormat, flags?)

### Description
Configure scaling context.
Sets up the scaler with source and destination formats. This is the primary configuration method.
Direct mapping to sws_getContext().

### Parameters
#### srcW
`number` - Source width in pixels
#### srcH
`number` - Source height in pixels
#### srcFormat
`AVPixelFormat` - Source pixel format
#### dstW
`number` - Destination width in pixels
#### dstH
`number` - Destination height in pixels
#### dstFormat
`AVPixelFormat` - Destination pixel format
#### flags? (Optional)
`SwsFlags` = `SWS_BILINEAR` - Scaling algorithm flags (SWS_*)

### Returns
`void`
```

--------------------------------

### Create and Configure a Filter Graph

Source: https://seydx.github.io/node-av/api/lib/classes/FilterGraph.html

Demonstrates how to instantiate a FilterGraph, allocate resources, create and link filters (buffer, scale, buffersink), configure the graph, and parse filter strings. This is a foundational example for setting up a filtering pipeline.

```typescript
import { FilterGraph, Filter, FilterInOut, FFmpegError } from 'node-av';

// Create and configure filter graph
const graph = new FilterGraph();
graph.alloc();

// Create filters
const bufferSrc = graph.createFilter(
  Filter.getByName('buffer')!,
  'src',
  'video_size=1920x1080:pix_fmt=yuv420p'
);

const scale = graph.createFilter(
  Filter.getByName('scale')!,
  'scale',
  '640:480'
);

const bufferSink = graph.createFilter(
  Filter.getByName('buffersink')!,
  'sink'
);

// Link filters
bufferSrc.link(0, scale, 0);
scale.link(0, bufferSink, 0);

// Configure graph
const ret = await graph.config();
FFmpegError.throwIfError(ret, 'config');

// Parse filter string
const ret2 = graph.parse2('[in]scale=640:480[out]');
FFmpegError.throwIfError(ret2, 'parse2');
```

--------------------------------

### Get Channel Layout Option

Source: https://seydx.github.io/node-av/api/lib/classes/Option.html

Retrieves the channel layout option from an AV object. Use this when you need to get audio channel configuration.

```typescript
// Get audio channel layout
const layout = Option.getChannelLayout(codecContext, 'channel_layout', AV_OPT_SEARCH_CHILDREN);
console.log('Channel layout:', layout); // stereo, 5.1, etc.
```

--------------------------------

### Set, Get, and List FFmpeg Options

Source: https://seydx.github.io/node-av/api/lib/classes/Option.html

Demonstrates setting various option types (string, integer, rational), retrieving them, and iterating through all available options on an FFmpeg object. Use FFmpegError.throwIfError to check for errors after setting options.

```typescript
import { Option, FFmpegError } from 'node-av';
import { AV_OPT_SEARCH_CHILDREN, AV_PIX_FMT_YUV420P } from 'node-av/constants';

// Set various option types
let ret = Option.set(obj, 'preset', 'fast');
FFmpegError.throwIfError(ret, 'set preset');

ret = Option.setInt(obj, 'bitrate', 2000000);
FFmpegError.throwIfError(ret, 'set bitrate');

ret = Option.setRational(obj, 'framerate', { num: 30, den: 1 });
FFmpegError.throwIfError(ret, 'set framerate');

// Get option values
const preset = Option.get(obj, 'preset');
const bitrate = Option.getInt(obj, 'bitrate');
const framerate = Option.getRational(obj, 'framerate');

// List all options
let opt = null;
while ((opt = Option.next(obj, opt))) {
  console.log(`${opt.name}: ${opt.help}`);
}
```

--------------------------------

### Setup Hardware Acceleration for Decoder

Source: https://seydx.github.io/node-av/api/api/classes/Decoder.html

Configures hardware acceleration using CUDA for the Decoder. Frames decoded with this setup will have their memory references available in `frame.hwFramesCtx`.

```typescript
import { HardwareContext } from 'node-av/api';
import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';

// Setup hardware acceleration
const hw = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
using decoder = await Decoder.create(stream, { hardware: hw });

// Frames will be decoded on GPU
for await (const frame of decoder.frames(packets)) {
  // frame.hwFramesCtx contains GPU memory reference
}
```

--------------------------------

### init()

Source: https://seydx.github.io/node-av/api/lib/classes/HardwareFramesContext.html

Initializes the hardware frames context. This must be called after allocating frames and setting up properties, and it directly maps to the av_hwframe_ctx_init() function.

```APIDOC
## init()

### Description
Initializes the frame pool after configuration. Must be called after alloc() and property setup. Direct mapping to av_hwframe_ctx_init().

### Method
`number`

### Returns
`number`
0 on success, negative AVERROR on error:
  * AVERROR_EINVAL: Invalid parameters
  * AVERROR_ENOMEM: Memory allocation failure
  * AVERROR_ENOSYS: Operation not supported
  * Hardware-specific errors

### Example
```typescript
import { FFmpegError } from 'node-av';

frames.alloc(device);
const ret = frames.init();
FFmpegError.throwIfError(ret, 'init');
```

### See
alloc Must be called first
```

--------------------------------

### Using InputFormat to Find, Probe, and Open Media Files

Source: https://seydx.github.io/node-av/api/lib/classes/InputFormat.html

Demonstrates how to find an input format by name, probe the format of file data, and use the format with a FormatContext to open a media file. Ensure necessary imports are included.

```typescript
import { InputFormat, FormatContext, FFmpegError } from 'node-av';

// Find format by name
const mp4Format = InputFormat.findInputFormat('mp4');
if (mp4Format) {
  console.log(`Format: ${mp4Format.name}`);
  console.log(`Description: ${mp4Format.longName}`);
  console.log(`Extensions: ${mp4Format.extensions}`);
}

// Probe format from file data
const fileData = Buffer.from([...]); // First few KB of file
const detectedFormat = InputFormat.probe(fileData, 'video.mp4');
if (detectedFormat) {
  console.log(`Detected: ${detectedFormat.name}`);
}

// Use with format context
const formatContext = new FormatContext();
formatContext.inputFormat = mp4Format;
const ret = await formatContext.openInput('video.mp4');
FFmpegError.throwIfError(ret, 'openInput');
```

--------------------------------

### Get String Representation of Media Type

Source: https://seydx.github.io/node-av/api/api/classes/MediaTypeUtils.html

Converts a media type enum value to its string representation. Use this to get human-readable names for media types.

```typescript
import { MediaType } from 'node-av';
import { AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO } from 'node-av/constants';

console.log(MediaType.getString(AVMEDIA_TYPE_VIDEO));      // "video"
console.log(MediaType.getString(AVMEDIA_TYPE_AUDIO));      // "audio"
console.log(MediaType.getString(AVMEDIA_TYPE_SUBTITLE));   // "subtitle"
```

```typescript
import { MediaType } from 'node-av';
import {
  AVMEDIA_TYPE_VIDEO,
  AVMEDIA_TYPE_AUDIO,
  AVMEDIA_TYPE_DATA,
  AVMEDIA_TYPE_SUBTITLE,
  AVMEDIA_TYPE_ATTACHMENT
} from 'node-av/constants';

console.log(MediaType.getString(AVMEDIA_TYPE_VIDEO));      // "video"
console.log(MediaType.getString(AVMEDIA_TYPE_AUDIO));      // "audio"
console.log(MediaType.getString(AVMEDIA_TYPE_DATA));       // "data"
console.log(MediaType.getString(AVMEDIA_TYPE_SUBTITLE));   // "subtitle"
console.log(MediaType.getString(AVMEDIA_TYPE_ATTACHMENT)); // "attachment"
```

--------------------------------

### Create and Start RTP Stream

Source: https://seydx.github.io/node-av/api/webrtc/classes/RTPStream.html

Creates an RTP stream from a given input URL and starts the media processing pipeline. Callbacks for video and audio packets can be provided.

```typescript
import { RTPStream } from 'node-av/api';

// Create stream with RTP packet callbacks
const stream = RTPStream.create('rtsp://camera.local/stream', {
  mtu: 1200,
  hardware: 'auto',
  onVideoPacket: (rtp) => {
    // Send RTP packet
    sendRtpPacket(rtp);
  },
  onAudioPacket: (rtp) => {
    sendRtpPacket(rtp);
  }
});

// Start streaming
await stream.start();
```

--------------------------------

### Example Usage of pickSupportedRate

Source: https://seydx.github.io/node-av/api/api/functions/pickSupportedRate.html

Demonstrates how to use pickSupportedRate with different scenarios: keeping the input rate, finding the nearest supported rate, and handling unrestricted codecs.

```typescript
pickSupportedRate(48000, [44100, 48000]); // 48000 (kept)
pickSupportedRate(96000, [44100, 48000]); // 48000 (nearest supported)
pickSupportedRate(48000, null);           // 48000 (codec unrestricted)
```

--------------------------------

### Audio Sample Allocation and Size Calculation Example

Source: https://seydx.github.io/node-av/api/api/classes/AudioSampleUtils.html

Demonstrates allocating audio buffers for stereo float planar format and calculating buffer size for stereo S16 packed format.

```typescript
import { AudioSampleUtils } from 'node-av';
import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16 } from 'node-av/constants';

// Allocate audio buffers for stereo float planar
const audio = AudioSampleUtils.alloc(2, 1024, AV_SAMPLE_FMT_FLTP, 0);
console.log(`Allocated ${audio.size} bytes`);
console.log(`${audio.data.length} buffers (one per channel)`);

// Get buffer size for packed format
const size = AudioSampleUtils.getBufferSize(2, 1024, AV_SAMPLE_FMT_S16, 0);
console.log(`S16 stereo needs ${size.size} bytes`);
```

--------------------------------

### Get Codec Name from ID

Source: https://seydx.github.io/node-av/api/lib/functions/avGetCodecName.html

Use avGetCodecName to get the string name for known codec IDs like H.264 and HEVC. It returns null for unknown IDs.

```typescript
import { AV_CODEC_ID_H264, AV_CODEC_ID_HEVC } from 'node-av/constants';
import { avGetCodecName } from 'node-av/lib';

const h264Name = avGetCodecName(AV_CODEC_ID_H264);  // Returns "h264"
const hevcName = avGetCodecName(AV_CODEC_ID_HEVC);  // Returns "hevc"
const unknownName = avGetCodecName(99999);          // Returns null
```

--------------------------------

### create()

Source: https://seydx.github.io/node-av/api/webrtc/classes/WebRTCStream.html

Creates a WebRTC session from a media source. This method initializes the session and prepares it for negotiation but does not start streaming immediately. It can accept a media source URL or a pre-opened Demuxer object, along with optional configuration settings.

```APIDOC
## create()

### Description
Create a WebRTC session from a media source.
Opens the input media, creates internal streaming components, and prepares for WebRTC peer connection negotiation. Does not start streaming yet. Call setOffer to negotiate SDP and start to begin streaming.

### Method
`static` create(`input`, `options?`): `WebRTCStream`

### Parameters
#### Parameters
- **input** (`string` | `Demuxer`) - Required - Media source URL (RTSP, file path, HTTP, etc.) or a pre-opened Demuxer
- **options?** (`WebRTCStreamOptions`) - Optional - Session configuration options

### Returns
`WebRTCStream` - Configured WebRTC session instance

### Examples
```typescript
const session = WebRTCStream.create('rtsp://camera.local/stream', {
  mtu: 1200,
  hardware: 'auto',
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
```

```typescript
// Session from a pre-opened Demuxer (e.g. screen capture)
const demuxer = await Device.openScreen({ frameRate: 30 });
const session = WebRTCStream.create(demuxer, {
  hardware: 'auto'
});
```
```

--------------------------------

### PixelFormatUtils: Get Format Info and Convert

Source: https://seydx.github.io/node-av/api/api/classes/PixelFormatUtils.html

Demonstrates how to get the name of a pixel format, check if it's hardware accelerated, and convert between format names and enum values.

```typescript
import { PixelFormat } from 'node-av';
import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_CUDA } from 'node-av/constants';

// Get format information
console.log(PixelFormat.getName(AV_PIX_FMT_YUV420P));    // "yuv420p"
console.log(PixelFormat.isHardware(AV_PIX_FMT_CUDA));    // true

// Convert between names and values
const format = PixelFormat.fromName("yuv420p");
console.log(format === AV_PIX_FMT_YUV420P);              // true
```

--------------------------------

### Get Raw Event Listeners in Node.js

Source: https://seydx.github.io/node-av/api/webrtc/classes/MediaStreamTrack.html

Use rawListeners to get a copy of the array of listeners for a given event, including wrappers. This is useful for inspecting listeners without modifying them.

```javascript
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
```

--------------------------------

### Initialize Software Scaling Context

Source: https://seydx.github.io/node-av/api/lib/classes/SoftwareScaleContext.html

Create a new software scaling context. Use SWS_FAST_BILINEAR for faster, lower-quality scaling or SWS_LANCZOS for higher-quality, slower scaling. Ensure initContext is called after configuration.

```typescript
import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24 } from 'node-av/constants';
import { SWS_BILINEAR, SWS_BICUBIC, SWS_LANCZOS, SWS_FAST_BILINEAR } from 'node-av/constants';

// Fast bilinear (lower quality, faster)
scaler.getContext(
  1920, 1080, AV_PIX_FMT_YUV420P,
  1280, 720, AV_PIX_FMT_RGB24,
  SWS_FAST_BILINEAR
);

// High quality Lanczos (higher quality, slower)
scaler.getContext(
  1920, 1080, AV_PIX_FMT_YUV420P,
  3840, 2160, AV_PIX_FMT_YUV420P,  // Upscaling
  SWS_LANCZOS
);
```

--------------------------------

### Allocate and Configure Resampler with allocSetOpts2

Source: https://seydx.github.io/node-av/api/lib/classes/SoftwareResampleContext.html

Illustrates combined allocation and configuration of the resampler using allocSetOpts2, specifying input and output audio formats. Error handling for invalid parameters or memory allocation failures is included.

```typescript
import { FFmpegError } from 'node-av';
import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_S16 } from 'node-av/constants';

// Stereo layout
const stereo = { nbChannels: 2, order: 1, u: { mask: 3n } };
// 5.1 layout
const surround = { nbChannels: 6, order: 1, u: { mask: 63n } };

// Convert 5.1 float to stereo 16-bit
const ret = resampler.allocSetOpts2(
  stereo, AV_SAMPLE_FMT_S16, 48000,
  surround, AV_SAMPLE_FMT_FLTP, 48000
);
FFmpegError.throwIfError(ret, 'allocSetOpts2');

```
Tokens:
Raw