Interface: DecoderOptions<C> | NodeAV
NodeAV

Appearance

node-av / api / DecoderOptions

Interface: DecoderOptions<C> ​

Defined in: src/api/decoder.ts:46

Options for decoder creation.

Type Parameters ​

C ​

C = unknown

Properties ​

applyCropping? ​

optional applyCropping?: boolean

Defined in: src/api/decoder.ts:99

Apply cropping from frame metadata.

When true, automatically crops frames based on their crop metadata. Uses av_frame_apply_cropping() with AV_FRAME_CROP_UNALIGNED flag. Useful for streams with letterboxing/pillarboxing metadata.

Default ​

ts
false

configure? ​

optional configure?: (context) => void

Defined in: src/api/decoder.ts:229

Configure the underlying codec context just before it is opened.

The imperative escape hatch for cases the DecoderOptions.context bag cannot express: additive flags via setFlags, other methods, or conditional logic. Called with the decoder's CodecContext after context is applied and immediately before avcodec_open2.

Parameters ​

context ​

CodecContext

Returns ​

void

Example ​

typescript
await Decoder.create(stream, {
  configure: (ctx) => {
    ctx.setFlags(AV_CODEC_FLAG_LOW_DELAY);
  },
});

context? ​

optional context?: Partial<{ bitRate: bigint; bitsPerCodedSample: number; bitsPerRawSample: number; channelLayout: ChannelLayout; channels: number; chromaLocation: AVChromaLocation; codecId: AVCodecID; codecTag: number; codecType: AVMediaType; colorPrimaries: AVColorPrimaries; colorRange: AVColorRange; colorSpace: AVColorSpace; colorTrc: AVColorTransferCharacteristic; extraData: Buffer<ArrayBufferLike> | null; extraHWFrames: number; flags: AVCodecFlag; flags2: AVCodecFlag2; framerate: Rational; frameSize: number; globalQuality: number; gopSize: number; height: number; hwDeviceCtx: HardwareDeviceContext | null; hwFramesCtx: HardwareFramesContext | null; level: number; maxBFrames: number; mbDecision: number; pixelFormat: AVPixelFormat; pktTimebase: Rational; profile: AVProfile; qMax: number; qMin: number; rcBufferSize: number; rcMaxRate: bigint; rcMinRate: bigint; sampleAspectRatio: Rational; sampleFormat: AVSampleFormat; sampleRate: number; threadCount: number; threadType: AVThreadType; timeBase: Rational; width: number; }>

Defined in: src/api/decoder.ts:210

Fields to set on the underlying codec context.

A typed, declarative bag for any writable CodecContext field that has no dedicated option — e.g. skipLoopFilter, skipFrame, flags2, exportSideData. Applied after node-av's stream parameters, hardware, and threading settings and immediately before avcodec_open2. The allowed keys are derived from the class, so every writable field is available and correctly typed.

Example ​

typescript
await Decoder.create(stream, {
  context: {
    skipLoopFilter: AVDISCARD_ALL,
  },
});

exitOnError? ​

optional exitOnError?: boolean

Defined in: src/api/decoder.ts:55

Exit immediately on first decode error.

When enabled, the decoder will terminate on the first decode error. When disabled, errors are logged but decoding continues with next packet.

Default ​

ts
true

extraHWFrames? ​

optional extraHWFrames?: number

Defined in: src/api/decoder.ts:71

Number of extra hardware frames to allocate.

Useful for hardware decoders requiring additional frame buffering. Some hardware decoders need extra frames for reference or look-ahead.

forcedFramerate? ​

optional forcedFramerate?: IRational

Defined in: src/api/decoder.ts:80

Force constant framerate mode.

When set, ignores all timestamps and generates frames at a constant rate. Sets frame PTS to AV_NOPTS_VALUE, duration to 1, and time_base to 1/framerate. Matches FFmpeg CLI's DECODER_FLAG_FRAMERATE_FORCED behavior.

hardware? ​

optional hardware?: HardwareContext | null

Defined in: src/api/decoder.ts:63

Hardware acceleration context.

Pass a HardwareContext instance to enable hardware-accelerated decoding. Set to null to disable hardware acceleration.

options? ​

optional options?: DecoderOptionsFor<C>

Defined in: src/api/decoder.ts:189

Additional codec-specific options.

Key-value pairs of FFmpeg private codec options, passed directly to the decoder. When the codec is created from a branded constant (e.g. FF_DECODER_H264_CUVID), these are strongly typed to that codec's known options (autocomplete + validation); otherwise any string/number/boolean values are accepted.

resample? ​

optional resample?: object

Defined in: src/api/decoder.ts:118

Resample decoded audio to a target format (audio only).

When set, decoded audio frames are transparently converted to the requested sample rate, sample format, and/or channel layout before they are returned — the audio mirror of rescale. Any omitted field keeps the decoded value, and conversion is skipped entirely when the source already matches the target. Useful when a capture device delivers a rate you cannot control (e.g. avfoundation ignoring a microphone sample-rate request) and you want every downstream stage to receive the rate you asked for.

channelLayout? ​

optional channelLayout?: ChannelLayout

sampleFormat? ​

optional sampleFormat?: AVSampleFormat

sampleRate? ​

optional sampleRate?: number

Example ​

typescript
// Guarantee 48 kHz frames regardless of the device's actual rate
const decoder = await Decoder.create(stream, { resample: { sampleRate: 48000 } });

rescale? ​

optional rescale?: object

Defined in: src/api/decoder.ts:148

Rescale decoded video to a target pixel format and/or size (video only).

When set, decoded video frames are transparently converted to the requested pixel format and/or dimensions before they are returned — the video mirror of resample. Any omitted field keeps the decoded value, and conversion is skipped entirely when the source already matches the target.

Hardware frames are automatically transferred to a supported software format first and then converted to the requested one; software frames are converted directly. Hardware frames are left untouched (kept on the GPU, zero-copy) when rescale is not set. This replaces the former hwaccelOutputFormat option: use rescale: { pixelFormat } to get decoded frames in a fixed software format.

Useful to normalize a heterogeneous set of sources (e.g. RTSP cameras that each deliver a different pixel format) so every downstream stage receives a uniform format/size, regardless of whether a stream was hardware- or software-decoded.

height? ​

optional height?: number

pixelFormat? ​

optional pixelFormat?: AVPixelFormat

width? ​

optional width?: number

Example ​

typescript
// Normalize any source to yuv420p, whether it was hardware- or software-decoded
const decoder = await Decoder.create(stream, { hardware: hw, rescale: { pixelFormat: AV_PIX_FMT_YUV420P } });

sarOverride? ​

optional sarOverride?: IRational

Defined in: src/api/decoder.ts:88

Override sample aspect ratio.

When set, overrides the frame's sample_aspect_ratio with this value. Useful for fixing incorrect SAR in source material.

signal? ​

optional signal?: AbortSignal

Defined in: src/api/decoder.ts:236

AbortSignal for cancellation.

When aborted, async generators stop yielding and async methods throw AbortError.

threadCount? ​

optional threadCount?: number

Defined in: src/api/decoder.ts:163

Number of threads to use for decoding.

Set to 0 to auto-detect based on CPU cores.

Default ​

ts
1

Deprecated ​

Use the DecoderOptions.context option instead, e.g. context: { threadCount: 0 }.

threadType? ​

optional threadType?: AVThreadType

Defined in: src/api/decoder.ts:179

Type of threading to use for decoding.

  • FF_THREAD_FRAME (1): Decode multiple frames in parallel. Higher throughput but adds latency (1 frame delay per thread). Not recommended for live streaming where future frames are unavailable.

  • FF_THREAD_SLICE (2): Decode parts of a single frame in parallel. No additional latency, suitable for real-time/live streaming.

Default ​

ts
FFmpeg default (both methods, codec chooses best)

Deprecated ​

Use the DecoderOptions.context option instead, e.g. context: { threadType: FF_THREAD_SLICE }.