Interface: EncoderOptions<C> | NodeAV
NodeAV

Appearance

node-av / api / EncoderOptions

Interface: EncoderOptions<C> ​

Defined in: src/api/encoder.ts:91

Options for encoder creation.

Type Parameters ​

C ​

C = unknown

Properties ​

autoFormat? ​

optional autoFormat?: boolean

Defined in: src/api/encoder.ts:278

Automatically convert incoming video to a pixel format the codec supports.

Video encoders only accept specific pixel formats (e.g. libx264 wants planar YUV like yuv420p and rejects rgb24). When true, the encoder transparently converts each frame to the least-loss supported pixel format via swscale (like ffmpeg's automatic format filter), keeping the same resolution. When false (default), an unsupported input raises a descriptive error instead — keeping behaviour explicit and 1:1 with the codec.

Resolution is never changed (the encoder already adopts the frame's dimensions), and hardware frames are left untouched (their format is negotiated via the hardware frames context). Has no effect on audio.

Default ​

ts
false

autoResample? ​

optional autoResample?: boolean

Defined in: src/api/encoder.ts:260

Automatically resample incoming audio to a format the codec supports.

Audio encoders only accept specific sample rates, sample formats, and channel layouts (e.g. libmp3lame rejects 96 kHz; AAC needs planar fltp). When true, the encoder transparently converts each frame to the nearest supported sample rate / sample format / channel layout (like ffmpeg's automatic aresample). When false (default), an unsupported input raises a descriptive error instead — keeping behaviour explicit and 1:1 with the codec.

Has no effect on video.

Default ​

ts
false

bitrate? ​

optional bitrate?: string | number | bigint

Defined in: src/api/encoder.ts:102

Target bitrate.

Can be specified as number, bigint, or string with suffix (e.g., '5M', '128k'). Used for rate control in video and audio encoding.

Default ​

ts
128k for audio, 1M for video

Deprecated ​

Use the EncoderOptions.context option instead, e.g. context: { bitRate: '5M' }.

bufSize? ​

optional bufSize?: string | number | bigint

Defined in: src/api/encoder.ts:132

Rate control buffer size.

Can be specified as number, bigint, or string with suffix (e.g., '5M', '128k'). Determines the decoder buffer model size for rate control.

Deprecated ​

Use the EncoderOptions.context option instead, e.g. context: { rcBufferSize: '2M' }.

configure? ​

optional configure?: (context) => void

Defined in: src/api/encoder.ts:202

Configure the underlying codec context just before it is opened.

The imperative escape hatch for cases the EncoderOptions.context bag cannot express: additive flags via setFlags, other methods, conditional logic, or setter-only input forms (e.g. a 'hvc1' FourCC string). Called with the encoder's CodecContext after context is applied and immediately before avcodec_open2.

Parameters ​

context ​

CodecContext

Returns ​

void

Example ​

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

context? ​

optional context?: EncoderContextOptions

Defined in: src/api/encoder.ts:181

Fields to set on the underlying codec context.

The home for all raw CodecContext settings: rate control (bitRate, rcMinRate, rcMaxRate, rcBufferSize — each accepting a unit-suffixed string like '5M'), gopSize, maxBFrames, threading, color /HDR metadata, profile, level, aspect ratio, etc. The allowed keys are derived from the class, so every writable field is available and correctly typed. Applied after node-av's derived settings (resolution, pixel/sample format, color, timebase) and immediately before avcodec_open2, so values here override the derived defaults.

For the codec tag use a numeric FourCC here, or the string form (e.g. 'hvc1') via EncoderOptions.configure.

Example ​

typescript
await Encoder.create(FF_ENCODER_LIBX265, {
  decoder,
  context: {
    bitRate: '5M',
    gopSize: 60,
    colorPrimaries: AVCOL_PRI_BT2020,
  },
});

decoder? ​

optional decoder?: Decoder

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

Optional decoder reference for metadata extraction.

Used to extract bits_per_raw_sample and other decoder-specific properties. Helps maintain quality during transcoding.

filter? ​

optional filter?: FilterAPI | FilterComplexAPI

Defined in: src/api/encoder.ts:218

Optional filter reference for metadata extraction.

Used to extract filter output parameters. Ensures encoder matches filter output characteristics.

gopSize? ​

optional gopSize?: number

Defined in: src/api/encoder.ts:142

Group of Pictures (GOP) size.

Number of frames between keyframes. Larger GOP improves compression but reduces seekability.

Deprecated ​

Use the EncoderOptions.context option instead, e.g. context: { gopSize: 60 }.

maxBFrames? ​

optional maxBFrames?: number

Defined in: src/api/encoder.ts:152

Maximum number of consecutive B-frames.

B-frames improve compression but increase encoding complexity. Maximum B-frames allowed between I or P frames.

Deprecated ​

Use the EncoderOptions.context option instead, e.g. context: { maxBFrames: 0 }.

maxRate? ​

optional maxRate?: string | number | bigint

Defined in: src/api/encoder.ts:122

Maximum bitrate for rate control.

Can be specified as number, bigint, or string with suffix (e.g., '5M', '128k'). Used with variable bitrate encoding to enforce bitrate ceiling.

Deprecated ​

Use the EncoderOptions.context option instead, e.g. context: { rcMaxRate: '8M' }.

minRate? ​

optional minRate?: string | number | bigint

Defined in: src/api/encoder.ts:112

Minimum bitrate for rate control.

Can be specified as number, bigint, or string with suffix (e.g., '5M', '128k'). Used with variable bitrate encoding to enforce quality floor.

Deprecated ​

Use the EncoderOptions.context option instead, e.g. context: { rcMinRate: '1M' }.

options? ​

optional options?: EncoderOptionsFor<C>

Defined in: src/api/encoder.ts:288

Additional codec-specific options.

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

signal? ​

optional signal?: AbortSignal

Defined in: src/api/encoder.ts:295

AbortSignal for cancellation.

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

threadCount? ​

optional threadCount?: number

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

Number of threads to use for encoding.

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

Default ​

ts
1

Deprecated ​

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

threadType? ​

optional threadType?: AVThreadType

Defined in: src/api/encoder.ts:244

Type of threading to use for encoding.

  • FF_THREAD_FRAME (1): Encode multiple frames in parallel. Higher throughput but adds latency (1 frame delay per thread).

  • FF_THREAD_SLICE (2): Encode parts of a single frame in parallel. Lower latency, suitable for real-time encoding.

Default ​

ts
FFmpeg default (both methods, codec chooses best)

Deprecated ​

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