NodeAV

node-av / lib / Codec

Class: Codec ​

Defined in: src/lib/codec.ts:66

Codec descriptor for audio/video encoding and decoding.

Represents an encoder or decoder implementation that can process media data. Contains codec capabilities, supported formats, and hardware acceleration information. Used to create codec contexts for actual encoding/decoding operations. Supports both software and hardware-accelerated codecs.

Direct mapping to FFmpeg's AVCodec.

Example ​

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

// Find decoder by ID
const decoder = Codec.findDecoder(AV_CODEC_ID_H264);
if (!decoder) {
  throw new Error('H.264 decoder not available');
}

// Find encoder by name
const encoder = Codec.findEncoderByName(FF_ENCODER_LIBX264);
if (!encoder) {
  throw new Error('libx264 encoder not available');
}

// Check capabilities
console.log(`Codec: ${decoder.name}`);
console.log(`Type: ${decoder.type}`);
console.log(`Hardware: ${decoder.hasHardwareAcceleration()}`);

// Get supported pixel formats
const formats = decoder.pixelFormats;
if (formats) {
  console.log(`Supported formats: ${formats.join(', ')}`);
}

See ​

Implements ​

Constructors ​

Constructor ​

new Codec(native): Codec

Defined in: src/lib/codec.ts:74

Internal

Parameters ​

native ​

NativeCodec

The native codec instance

Returns ​

Codec

Accessors ​

capabilities ​

Get Signature ​

get capabilities(): AVCodecCap

Defined in: src/lib/codec.ts:325

Codec capabilities.

Bitfield of AV_CODEC_CAP_* flags indicating codec features.

Direct mapping to AVCodec->capabilities.

Returns ​

AVCodecCap

channelLayouts ​

Get Signature ​

get channelLayouts(): ChannelLayout[] | null

Defined in: src/lib/codec.ts:449

Supported channel layouts.

Array of channel layouts this audio codec supports. Null for video codecs.

Direct mapping to AVCodec->ch_layouts.

Returns ​

ChannelLayout[] | null

id ​

Get Signature ​

get id(): AVCodecID

Defined in: src/lib/codec.ts:314

Codec ID.

Unique identifier for the codec format.

Direct mapping to AVCodec->id.

Returns ​

AVCodecID

longName ​

Get Signature ​

get longName(): string | null

Defined in: src/lib/codec.ts:292

Codec long name.

Human-readable description of the codec.

Direct mapping to AVCodec->long_name.

Returns ​

string | null

maxLowres ​

Get Signature ​

get maxLowres(): number

Defined in: src/lib/codec.ts:365

Maximum lowres value.

Maximum value for lowres decoding (0 = no lowres support).

Direct mapping to AVCodec->max_lowres.

Returns ​

number

name ​

Get Signature ​

get name(): string | null

Defined in: src/lib/codec.ts:281

Codec name.

Short name identifier for the codec (e.g., 'h264', 'aac').

Direct mapping to AVCodec->name.

Returns ​

string | null

pixelFormats ​

Get Signature ​

get pixelFormats(): AVPixelFormat[] | null

Defined in: src/lib/codec.ts:413

Supported pixel formats.

Array of pixel formats this video codec supports. Null for audio codecs.

Direct mapping to AVCodec->pix_fmts.

Returns ​

AVPixelFormat[] | null

profiles ​

Get Signature ​

get profiles(): CodecProfile[] | null

Defined in: src/lib/codec.ts:376

Supported profiles.

Array of profiles this codec can handle (e.g., baseline, main, high).

Direct mapping to AVCodec->profiles.

Returns ​

CodecProfile[] | null

sampleFormats ​

Get Signature ​

get sampleFormats(): AVSampleFormat[] | null

Defined in: src/lib/codec.ts:437

Supported sample formats.

Array of sample formats this audio codec supports. Null for video codecs.

Direct mapping to AVCodec->sample_fmts.

Returns ​

AVSampleFormat[] | null

supportedFramerates ​

Get Signature ​

get supportedFramerates(): Rational[] | null

Defined in: src/lib/codec.ts:399

Supported frame rates.

Array of frame rates this video codec supports. Null for audio codecs or if all rates are supported.

Direct mapping to AVCodec->supported_framerates.

Returns ​

Rational[] | null

supportedSamplerates ​

Get Signature ​

get supportedSamplerates(): number[] | null

Defined in: src/lib/codec.ts:425

Supported sample rates.

Array of sample rates this audio codec supports. Null for video codecs or if all rates are supported.

Direct mapping to AVCodec->supported_samplerates.

Returns ​

number[] | null

type ​

Get Signature ​

get type(): AVMediaType

Defined in: src/lib/codec.ts:303

Media type.

Type of media this codec processes (video, audio, subtitle, etc.).

Direct mapping to AVCodec->type.

Returns ​

AVMediaType

wrapper ​

Get Signature ​

get wrapper(): string | null

Defined in: src/lib/codec.ts:387

Wrapper name.

Name of the codec wrapper, if this is a wrapper codec.

Direct mapping to AVCodec->wrapper_name.

Returns ​

string | null

Methods ​

getHardwareMethod() ​

getHardwareMethod(deviceType): number | null

Defined in: src/lib/codec.ts:707

Get hardware method flags for device type.

Returns the hardware configuration methods for a specific device.

Parameters ​

deviceType ​

FFHWDeviceType | AVHWDeviceType

Device type to query

Returns ​

number | null

Method flags, or null if not supported

Example ​

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

const methods = codec.getHardwareMethod(AV_HWDEVICE_TYPE_CUDA);
if (methods) {
  if (methods & AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX) {
    console.log('Supports device context');
  }
}

getHwConfig() ​

getHwConfig(index): { deviceType: AVHWDeviceType; methods: number; pixFmt: AVPixelFormat; } | null

Defined in: src/lib/codec.ts:749

Get hardware configuration at index.

Retrieves hardware acceleration configuration details.

Direct mapping to avcodec_get_hw_config().

Parameters ​

index ​

number

Configuration index

Returns ​

{ deviceType: AVHWDeviceType; methods: number; pixFmt: AVPixelFormat; } | null

Hardware configuration, or null if index out of range

Example ​

typescript
// Enumerate all hardware configs
for (let i = 0; ; i++) {
  const config = codec.getHwConfig(i);
  if (!config) break;

  console.log(`Config ${i}:`);
  console.log(`  Pixel format: ${config.pixFmt}`);
  console.log(`  Device type: ${config.deviceType}`);
  console.log(`  Methods: 0x${config.methods.toString(16)}`);
}

getNative() ​

getNative(): NativeCodec

Defined in: src/lib/codec.ts:792

Internal

Get the underlying native Codec object.

Returns ​

NativeCodec

The native Codec binding object

Implementation of ​

NativeWrapper.getNative

getOptions() ​

getOptions(): NativeCodecOption[]

Defined in: src/lib/codec.ts:781

Enumerate the codec's private options.

Returns the codec-specific tunables exposed by the codec's private AVClass (e.g. libx264's preset, crf, tune). These are the options accepted via the options dictionary when creating an encoder/decoder, and are distinct from the generic AVCodecContext fields (bitrate, gop_size, ...).

Options of type AV_OPT_TYPE_CONST are the named values belonging to a parent option's unit (i.e. enum members). Returns an empty array when the codec has no private options.

Direct mapping to iterating codec->priv_class via av_opt_next().

Returns ​

NativeCodecOption[]

Array of private option descriptors

Example ​

typescript
const codec = Codec.findEncoderByName(FF_ENCODER_LIBX264);
for (const opt of codec?.getOptions() ?? []) {
  console.log(opt.name, opt.type, opt.unit);
}

getSupportedDeviceTypes() ​

getSupportedDeviceTypes(): AVHWDeviceType[]

Defined in: src/lib/codec.ts:670

Get supported hardware device types.

Returns all hardware acceleration types this codec supports.

Returns ​

AVHWDeviceType[]

Array of supported device types

Example ​

typescript
const devices = codec.getSupportedDeviceTypes();
console.log('Supported devices:', devices.map(d => {
  switch(d) {
    case AV_HWDEVICE_TYPE_CUDA: return 'CUDA';
    case AV_HWDEVICE_TYPE_VAAPI: return 'VAAPI';
    default: return 'Unknown';
  }
}));

See ​

supportsDevice To check specific device

hasCapabilities() ​

hasCapabilities(...caps): boolean

Defined in: src/lib/codec.ts:349

Check if codec has specific capabilities.

Tests whether all specified capabilities are present using bitwise AND.

Parameters ​

caps ​

...AVCodecCap[]

One or more capability values to check

Returns ​

boolean

true if all specified capabilities are present, false otherwise

Example ​

typescript
import { AV_CODEC_CAP_HARDWARE } from 'node-av/constants';

if (codec.hasCapabilities(AV_CODEC_CAP_HARDWARE)) {
  console.log('This codec supports hardware acceleration');
}

See ​

capabilities For direct capabilities access

hasHardwareAcceleration() ​

hasHardwareAcceleration(): boolean

Defined in: src/lib/codec.ts:529

Check if codec supports hardware acceleration.

Checks if the codec has any hardware configuration.

Returns ​

boolean

True if hardware acceleration is available

Example ​

typescript
import { FF_DECODER_H264_CUVID } from 'node-av/constants';

const codec = Codec.findDecoderByName(FF_DECODER_H264_CUVID);
if (codec?.hasHardwareAcceleration()) {
  console.log('Hardware acceleration available');
}

See ​

getSupportedDeviceTypes For specific device types

isDecoder() ​

isDecoder(): boolean

Defined in: src/lib/codec.ts:487

Check if codec is a decoder.

Returns ​

boolean

True if this codec can decode

Example ​

typescript
const codec = Codec.findDecoder(AV_CODEC_ID_H264);
if (codec?.isDecoder()) {
  console.log('This is a decoder');
}

See ​

isEncoder To check for encoders

isEncoder() ​

isEncoder(): boolean

Defined in: src/lib/codec.ts:468

Check if codec is an encoder.

Returns ​

boolean

True if this codec can encode

Example ​

typescript
const codec = Codec.findEncoderByName(FF_ENCODER_LIBX264);
if (codec?.isEncoder()) {
  console.log('This is an encoder');
}

See ​

isDecoder To check for decoders

isExperimental() ​

isExperimental(): boolean

Defined in: src/lib/codec.ts:506

Check if codec is experimental.

Experimental codecs require explicit opt-in to use.

Returns ​

boolean

True if codec is marked experimental

Example ​

typescript
if (codec.isExperimental()) {
  console.warn('This codec is experimental');
  // Need to set strict_std_compliance = -2
}

isHardwareAcceleratedDecoder() ​

isHardwareAcceleratedDecoder(deviceType?): boolean

Defined in: src/lib/codec.ts:607

Check if decoder supports hardware acceleration.

Parameters ​

deviceType? ​

FFHWDeviceType | AVHWDeviceType

Optional specific device type

Returns ​

boolean

True if hardware decoding is supported

Example ​

typescript
import { AV_HWDEVICE_TYPE_VIDEOTOOLBOX } from 'node-av/constants';

// Check any hardware support
if (codec.isHardwareAcceleratedDecoder()) {
  console.log('Hardware decoding available');
}

// Check specific device
if (codec.isHardwareAcceleratedDecoder(AV_HWDEVICE_TYPE_VIDEOTOOLBOX)) {
  console.log('VideoToolbox decoding available');
}

isHardwareAcceleratedEncoder() ​

isHardwareAcceleratedEncoder(deviceType?): boolean

Defined in: src/lib/codec.ts:639

Check if encoder supports hardware acceleration.

Parameters ​

deviceType? ​

FFHWDeviceType | AVHWDeviceType

Optional specific device type

Returns ​

boolean

True if hardware encoding is supported

Example ​

typescript
import { AV_HWDEVICE_TYPE_VAAPI } from 'node-av/constants';

// Check any hardware support
if (codec.isHardwareAcceleratedEncoder()) {
  console.log('Hardware encoding available');
}

// Check specific device
if (codec.isHardwareAcceleratedEncoder(AV_HWDEVICE_TYPE_VAAPI)) {
  console.log('VAAPI encoding available');
}

supportsDevice() ​

supportsDevice(deviceType): boolean

Defined in: src/lib/codec.ts:564

Check if codec supports specific device type.

Parameters ​

deviceType ​

FFHWDeviceType | AVHWDeviceType

Hardware device type to check

Returns ​

boolean

True if device type is supported

Example ​

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

if (codec.supportsDevice(AV_HWDEVICE_TYPE_CUDA)) {
  console.log('Supports NVIDIA CUDA');
}

See ​

getSupportedDeviceTypes For all supported types

findDecoder() ​

static findDecoder(id): Codec | null

Defined in: src/lib/codec.ts:106

Find a decoder by codec ID.

Searches for a decoder that can decode the specified codec format.

Direct mapping to avcodec_find_decoder().

Parameters ​

id ​

AVCodecID

Codec ID to search for

Returns ​

Codec | null

Decoder if found, null otherwise

Example ​

typescript
import { AV_CODEC_ID_H264, AV_CODEC_ID_AAC } from 'node-av/constants';

// Find H.264 video decoder
const h264 = Codec.findDecoder(AV_CODEC_ID_H264);
if (h264) {
  console.log(`Found: ${h264.name}`);
}

// Find AAC audio decoder
const aac = Codec.findDecoder(AV_CODEC_ID_AAC);

See ​

findDecoderByName() ​

static findDecoderByName(name): Codec | null

Defined in: src/lib/codec.ts:139

Find a decoder by name.

Searches for a specific decoder implementation by name. Useful when multiple decoders exist for the same codec.

Direct mapping to avcodec_find_decoder_by_name().

Parameters ​

name ​

FFDecoderCodec

Decoder name

Returns ​

Codec | null

Decoder if found, null otherwise

Example ​

typescript
import { FF_DECODER_H264, FF_DECODER_H264_CUVID } from 'node-av/constants';

// Find specific H.264 decoder
const decoder = Codec.findDecoderByName(FF_DECODER_H264_CUVID);
if (decoder) {
  console.log('Found NVIDIA hardware decoder');
}

// Find software decoder
const sw = Codec.findDecoderByName(FF_DECODER_H264);

See ​

findDecoder To find by codec ID

findEncoder() ​

static findEncoder(id): Codec | null

Defined in: src/lib/codec.ts:172

Find an encoder by codec ID.

Searches for an encoder that can encode to the specified codec format.

Direct mapping to avcodec_find_encoder().

Parameters ​

id ​

AVCodecID

Codec ID to search for

Returns ​

Codec | null

Encoder if found, null otherwise

Example ​

typescript
import { AV_CODEC_ID_H264, AV_CODEC_ID_AAC } from 'node-av/constants';

// Find H.264 video encoder
const h264 = Codec.findEncoder(AV_CODEC_ID_H264);
if (h264) {
  console.log(`Found: ${h264.name}`);
}

// Find AAC audio encoder
const aac = Codec.findEncoder(AV_CODEC_ID_AAC);

See ​

findEncoderByName() ​

static findEncoderByName(name): Codec | null

Defined in: src/lib/codec.ts:205

Find an encoder by name.

Searches for a specific encoder implementation by name. Useful when multiple encoders exist for the same codec.

Direct mapping to avcodec_find_encoder_by_name().

Parameters ​

name ​

FFEncoderCodec

Encoder name

Returns ​

Codec | null

Encoder if found, null otherwise

Example ​

typescript
import { FF_ENCODER_H264_NVENC, FF_ENCODER_LIBX264 } from 'node-av/constants';

// Find specific H.264 encoder
const x264 = Codec.findEncoderByName(FF_ENCODER_LIBX264);
if (x264) {
  console.log('Found x264 encoder');
}

// Find hardware encoder
const nvenc = Codec.findEncoderByName(FF_ENCODER_H264_NVENC);

See ​

findEncoder To find by codec ID

fromNative() ​

static fromNative(native): Codec | null

Defined in: src/lib/codec.ts:805

Internal

Create codec from native instance.

Parameters ​

native ​

NativeCodec | null

Native codec instance

Returns ​

Codec | null

Codec wrapper or null

getCodecList() ​

static getCodecList(): Codec[]

Defined in: src/lib/codec.ts:234

Get list of all available codecs.

Returns all registered codecs (both encoders and decoders).

Returns ​

Codec[]

Array of all available codecs

Example ​

typescript
// List all codecs
const codecs = Codec.getCodecList();
console.log(`Total codecs: ${codecs.length}`);

// Filter encoders
const encoders = codecs.filter(c => c.isEncoder());
console.log(`Encoders: ${encoders.length}`);

// Filter hardware codecs
const hw = codecs.filter(c => c.hasHardwareAcceleration());
console.log(`Hardware codecs: ${hw.length}`);

See ​

iterateCodecs For memory-efficient iteration

iterateCodecs() ​

static iterateCodecs(opaque?): { codec: Codec; opaque: bigint; } | null

Defined in: src/lib/codec.ts:264

Iterate through available codecs.

Memory-efficient way to iterate through all codecs. Uses an opaque pointer to track iteration state.

Direct mapping to av_codec_iterate().

Parameters ​

opaque? ​

bigint | null = null

Iteration state (null to start)

Returns ​

{ codec: Codec; opaque: bigint; } | null

Next codec and state, or null when done

Example ​

typescript
// Iterate all codecs
let iter = null;
let result;
while ((result = Codec.iterateCodecs(iter))) {
  console.log(`Codec: ${result.codec.name}`);
  iter = result.opaque;
}

See ​

getCodecList For simple array access