node-av / lib / SoftwareResampleContext

Class: SoftwareResampleContext

Defined in: src/lib/software-resample-context.ts:62

Audio resampling and format conversion context.

Provides comprehensive audio format conversion including sample rate conversion, channel layout remapping, and sample format conversion. Essential for audio processing pipelines where format compatibility is required between components. Supports high-quality resampling algorithms with configurable parameters.

Direct mapping to FFmpeg's SwrContext.

Example

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();

See

SwrContext - FFmpeg Doxygen
Frame For audio frame operations

Extends

OptionMember<NativeSoftwareResampleContext>

Implements

Disposable
NativeWrapper<NativeSoftwareResampleContext>

Constructors

Constructor

new SoftwareResampleContext(): SoftwareResampleContext

Defined in: src/lib/software-resample-context.ts:63

Returns

SoftwareResampleContext

Overrides

OptionMember<NativeSoftwareResampleContext>.constructor

Properties

native

protected native: NativeSoftwareResampleContext

Defined in: src/lib/option.ts:1059

Inherited from

OptionMember.native

Methods

[dispose]()

[dispose](): void

Defined in: src/lib/software-resample-context.ts:621

Dispose of the resampler context.

Implements the Disposable interface for automatic cleanup. Equivalent to calling free().

Returns

void

Example

typescript

{
  using resampler = new SoftwareResampleContext();
  resampler.allocSetOpts2(...);
  resampler.init();
  // Use resampler...
} // Automatically freed when leaving scope

Implementation of

Disposable.[dispose]

alloc()

alloc(): void

Defined in: src/lib/software-resample-context.ts:84

Allocate resample context.

Allocates memory for the resampler. Must be called before configuration.

Direct mapping to swr_alloc().

Returns

void

Example

typescript

const resampler = new SoftwareResampleContext();
resampler.alloc();
// Now configure with setOption() or allocSetOpts2()

See

allocSetOpts2 For combined allocation and configuration

allocSetOpts2()

allocSetOpts2(outChLayout, outSampleFmt, outSampleRate, inChLayout, inSampleFmt, inSampleRate): number

Defined in: src/lib/software-resample-context.ts:132

Allocate and configure resampler.

Combined allocation and configuration of the resampler with input and output format specifications.

Direct mapping to swr_alloc_set_opts2().

Parameters

outChLayout

ChannelLayout

Output channel layout

outSampleFmt

AVSampleFormat

Output sample format

outSampleRate

number

Output sample rate in Hz

inChLayout

ChannelLayout

Input channel layout

inSampleFmt

AVSampleFormat

Input sample format

inSampleRate

number

Input sample rate in Hz

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EINVAL: Invalid parameters
AVERROR_ENOMEM: Memory allocation failure

Example

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');

See

init Must be called after configuration

close()

close(): void

Defined in: src/lib/software-resample-context.ts:207

Close resampler context.

Closes the resampler but keeps the context allocated. Can be reconfigured and reinitialized after closing.

Direct mapping to swr_close().

Returns

void

Example

typescript

resampler.close();
// Can now reconfigure and reinit

See

free For complete deallocation

configFrame()

configFrame(outFrame, inFrame): number

Defined in: src/lib/software-resample-context.ts:369

Configure resampler from frames.

Configures the resampler using format information from frames. Alternative to allocSetOpts2() for frame-based setup.

Direct mapping to swr_config_frame().

Parameters

outFrame

Frame | null

Frame with output format

inFrame

Frame | null

Frame with input format

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EINVAL: Invalid parameters

Example

typescript

import { FFmpegError } from 'node-av';

// Configure from frames
const ret = resampler.configFrame(outFrame, inFrame);
FFmpegError.throwIfError(ret, 'configFrame');

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

See

allocSetOpts2 For manual configuration

convert()

convert(outBuffer, outCount, inBuffer, inCount): Promise<number>

Defined in: src/lib/software-resample-context.ts:252

Convert audio samples.

Converts audio samples from input format to output format. Handles resampling, channel remapping, and format conversion.

Direct mapping to swr_convert().

Parameters

outBuffer

Buffer<ArrayBufferLike>[] | null

Output sample buffers (one per channel for planar)

outCount

number

Maximum output samples per channel

inBuffer

Buffer<ArrayBufferLike>[] | null

Input sample buffers (one per channel for planar)

inCount

number

Input samples per channel

Returns

Promise<number>

Number of output samples per channel, negative AVERROR on error:

AVERROR_EINVAL: Invalid parameters
AVERROR_INPUT_CHANGED: Input format changed

Example

typescript

import { FFmpegError } from 'node-av';

// Convert audio buffers
const outBuffers = [Buffer.alloc(4096), Buffer.alloc(4096)]; // Stereo
const inBuffers = [inputBuffer]; // Mono

const samples = await resampler.convert(
  outBuffers, 1024,
  inBuffers, inputSamples
);

if (samples < 0) {
  FFmpegError.throwIfError(samples, 'convert');
}
console.log(`Converted ${samples} samples`);

See

convertFrame For frame-based conversion

convertFrame()

convertFrame(outFrame, inFrame): number

Defined in: src/lib/software-resample-context.ts:336

Convert audio frame.

Converts an entire audio frame to the output format. Simpler interface than convert() for frame-based processing.

Direct mapping to swr_convert_frame().

Parameters

outFrame

Frame | null

Output frame (null to drain)

inFrame

Frame | null

Input frame (null to flush)

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EINVAL: Invalid parameters
AVERROR_ENOMEM: Memory allocation failure
AVERROR_INPUT_CHANGED: Input format changed

Example

typescript

import { Frame, FFmpegError } from 'node-av';

// Convert frame
const outFrame = new Frame();
const ret = resampler.convertFrame(outFrame, inFrame);
FFmpegError.throwIfError(ret, 'convertFrame');

// Drain remaining samples
const drainFrame = new Frame();
const ret2 = resampler.convertFrame(drainFrame, null);
if (ret2 === 0) {
  // Got drained samples
}

See

convert For buffer-based conversion
configFrame To configure from frame

convertSync()

convertSync(outBuffer, outCount, inBuffer, inCount): number

Defined in: src/lib/software-resample-context.ts:295

Convert audio samples synchronously. Synchronous version of convert.

Converts audio between formats, sample rates, and channel layouts. Can handle format conversion, resampling, and channel mixing.

Direct mapping to swr_convert().

Parameters

outBuffer

Buffer<ArrayBufferLike>[] | null

Output buffer array (one per channel, null to get delay)

outCount

number

Number of output samples space per channel

inBuffer

Buffer<ArrayBufferLike>[] | null

Input buffer array (one per channel, null to flush)

inCount

number

Number of input samples per channel

Returns

number

Number of samples output per channel, or negative AVERROR:

AVERROR_EINVAL: Invalid parameters
AVERROR_ENOMEM: Memory allocation failure

Example

typescript

import { FFmpegError } from 'node-av';

// Convert stereo float to mono s16
const inBuffers = [leftChannel, rightChannel];
const outBuffers = [monoOutput];

const samples = resampler.convertSync(
  outBuffers, 1024,  // Output: 1024 samples max
  inBuffers, 1024    // Input: 1024 samples
);
FFmpegError.throwIfError(samples, 'convertSync');
console.log(`Converted ${samples} samples`);

See

convert For async version

dropOutput()

dropOutput(count): number

Defined in: src/lib/software-resample-context.ts:565

Drop output samples.

Drops the specified number of output samples. Used for synchronization adjustments.

Direct mapping to swr_drop_output().

Parameters

count

number

Number of samples to drop

Returns

number

0 on success, negative AVERROR on error

Example

typescript

// Drop 100 output samples
const ret = resampler.dropOutput(100);
if (ret >= 0) {
  console.log(`Dropped ${ret} samples`);
}

free()

free(): void

Defined in: src/lib/software-resample-context.ts:187

Free resampler context.

Releases all resources associated with the resampler. The context becomes invalid after calling this.

Direct mapping to swr_free().

Returns

void

Example

typescript

resampler.free();
// Resampler is now invalid

See

close For closing without freeing
Symbol.dispose For automatic cleanup

getDelay()

getDelay(base): bigint

Defined in: src/lib/software-resample-context.ts:418

Get resampler delay.

Returns the number of samples currently buffered in the resampler. These samples will be output when flushing or with new input.

Direct mapping to swr_get_delay().

Parameters

base

bigint

Time base for the returned delay

Returns

bigint

Delay in samples at the given base rate

Example

typescript

// Get delay in output sample rate
const delay = resampler.getDelay(48000n);
console.log(`${delay} samples buffered`);

// Get delay in microseconds
const delayUs = resampler.getDelay(1000000n);
console.log(`${delayUs} microseconds delay`);

getNative()

getNative(): NativeSoftwareResampleContext

Defined in: src/lib/software-resample-context.ts:601

Internal

Get the underlying native SoftwareResampleContext object.

Returns

NativeSoftwareResampleContext

The native SoftwareResampleContext binding object

Implementation of

NativeWrapper.getNative

getOption()

Get an option value from this object.

Uses the AVOption API to retrieve options.

Direct mapping to av_opt_get* functions.

Param

name

Option name

Param

type

Option type (defaults to AV_OPT_TYPE_STRING)

Param

searchFlags

Search flags (default: AV_OPT_SEARCH_CHILDREN)

Example

typescript

import { AV_OPT_TYPE_STRING, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_PIXEL_FMT, AV_OPT_TYPE_INT64 } from 'node-av/constants';

// String options (default)
const preset = obj.getOption('preset');
const codec = obj.getOption('codec', AV_OPT_TYPE_STRING);

// Typed options
const framerate = obj.getOption('framerate', AV_OPT_TYPE_RATIONAL); // Returns {num, den}
const pixFmt = obj.getOption('pix_fmt', AV_OPT_TYPE_PIXEL_FMT); // Returns AVPixelFormat
const bitrate = obj.getOption('bitrate', AV_OPT_TYPE_INT64); // Returns bigint

Call Signature

getOption(name, type?, searchFlags?): string | null

Defined in: src/lib/option.ts:1288

Parameters

name

string

type?

AVOptionTypeString

searchFlags?

AVOptionSearchFlags

Returns

string | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): string | null

Defined in: src/lib/option.ts:1289

Parameters

name

string

type

AVOptionTypeColor

searchFlags?

AVOptionSearchFlags

Returns

string | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1292

Parameters

name

string

type

AVOptionTypeInt

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): bigint | null

Defined in: src/lib/option.ts:1293

Parameters

name

string

type

AVOptionTypeInt64

searchFlags?

AVOptionSearchFlags

Returns

bigint | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1294

Parameters

name

string

type

AVOptionTypeUint

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): bigint | null

Defined in: src/lib/option.ts:1295

Parameters

name

string

type

AVOptionTypeUint64

searchFlags?

AVOptionSearchFlags

Returns

bigint | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1296

Parameters

name

string

type

AVOptionTypeFlags

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): boolean | null

Defined in: src/lib/option.ts:1297

Parameters

name

string

type

AVOptionTypeBool

searchFlags?

AVOptionSearchFlags

Returns

boolean | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1298

Parameters

name

string

type

AVOptionTypeDuration

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1299

Parameters

name

string

type

AVOptionTypeConst

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1302

Parameters

name

string

type

AVOptionTypeDouble

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1303

Parameters

name

string

type

AVOptionTypeFloat

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): IRational | null

Defined in: src/lib/option.ts:1306

Parameters

name

string

Call Signature

getOption(name, type, searchFlags?): IRational | null

Defined in: src/lib/option.ts:1307

Parameters

name

string

type

AVOptionTypeVideoRate

searchFlags?

AVOptionSearchFlags

Returns

IRational | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): AVPixelFormat | null

Defined in: src/lib/option.ts:1308

Parameters

name

string

type

AVOptionTypePixelFmt

searchFlags?

AVOptionSearchFlags

Returns

AVPixelFormat | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): AVSampleFormat | null

Defined in: src/lib/option.ts:1309

Parameters

name

string

type

AVOptionTypeSampleFmt

searchFlags?

AVOptionSearchFlags

Returns

AVSampleFormat | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): IDimension | null

Defined in: src/lib/option.ts:1310

Parameters

name

string

type

AVOptionTypeImageSize

searchFlags?

AVOptionSearchFlags

Returns

IDimension | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): ChannelLayout | null

Defined in: src/lib/option.ts:1311

Parameters

name

string

type

AVOptionTypeChLayout

searchFlags?

AVOptionSearchFlags

Returns

ChannelLayout | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): Dictionary | null

Defined in: src/lib/option.ts:1312

Parameters

name

string

type

AVOptionTypeDict

searchFlags?

AVOptionSearchFlags

Returns

Dictionary | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): string | null

Defined in: src/lib/option.ts:1313

Parameters

name

string

type

AVOptionTypeBinary

searchFlags?

AVOptionSearchFlags

Returns

string | null

Inherited from

OptionMember.getOption

getOutSamples()

getOutSamples(inSamples): number

Defined in: src/lib/software-resample-context.ts:440

Calculate output sample count.

Calculates how many output samples will be produced for a given number of input samples.

Direct mapping to swr_get_out_samples().

Parameters

inSamples

number

Number of input samples

Returns

number

Number of output samples

Example

typescript

const outSamples = resampler.getOutSamples(1024);
console.log(`1024 input samples -> ${outSamples} output samples`);

init()

init(): number

Defined in: src/lib/software-resample-context.ts:166

Initialize resampler.

Initializes the resampler after configuration. Must be called before any conversion operations.

Direct mapping to swr_init().

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EINVAL: Invalid configuration
AVERROR_ENOMEM: Memory allocation failure

Example

typescript

import { FFmpegError } from 'node-av';

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

See

allocSetOpts2 For configuration
isInitialized To check initialization status

injectSilence()

injectSilence(count): number

Defined in: src/lib/software-resample-context.ts:590

Inject silence.

Injects silent samples into the output. Used for padding or synchronization.

Direct mapping to swr_inject_silence().

Parameters

count

number

Number of silent samples to inject

Returns

number

0 on success, negative AVERROR on error

Example

typescript

// Inject 100 silent samples
const ret = resampler.injectSilence(100);
if (ret >= 0) {
  console.log(`Injected ${ret} silent samples`);
}

isInitialized()

isInitialized(): boolean

Defined in: src/lib/software-resample-context.ts:391

Check if initialized.

Returns whether the resampler has been initialized.

Direct mapping to swr_is_initialized().

Returns

boolean

True if initialized, false otherwise

Example

typescript

if (!resampler.isInitialized()) {
  resampler.init();
}

See

init To initialize

listOptions()

listOptions(): OptionInfo[]

Defined in: src/lib/option.ts:1428

List all available options for this object.

Uses the AVOption API to enumerate all options. Useful for discovering available settings and their types.

Direct mapping to av_opt_next() iteration.

Returns

OptionInfo[]

Array of option information objects

Example

typescript

const options = obj.listOptions();
for (const opt of options) {
  console.log(`${opt.name}: ${opt.help}`);
  console.log(`  Type: ${opt.type}, Default: ${opt.defaultValue}`);
  console.log(`  Range: ${opt.min} - ${opt.max}`);
}

See

OptionInfo For option metadata structure

Inherited from

OptionMember.listOptions

nextPts()

nextPts(pts): bigint

Defined in: src/lib/software-resample-context.ts:462

Calculate next PTS.

Calculates the presentation timestamp for the next output sample.

Direct mapping to swr_next_pts().

Parameters

pts

bigint

Current presentation timestamp

Returns

bigint

Next presentation timestamp

Example

typescript

let pts = 0n;
pts = resampler.nextPts(pts);
console.log(`Next PTS: ${pts}`);

setChannelMapping()

setChannelMapping(channelMap): number

Defined in: src/lib/software-resample-context.ts:512

Set channel mapping.

Sets custom channel mapping for remixing.

Direct mapping to swr_set_channel_mapping().

Parameters

channelMap

number[]

Array mapping input to output channels

Returns

number

0 on success, negative AVERROR on error

Example

typescript

// Map stereo to reverse stereo (swap L/R)
const ret = resampler.setChannelMapping([1, 0]);
FFmpegError.throwIfError(ret, 'setChannelMapping');

setCompensation()

setCompensation(sampleDelta, compensationDistance): number

Defined in: src/lib/software-resample-context.ts:490

Set compensation.

Adjusts the resampling rate to compensate for clock drift. Used for audio/video synchronization.

Direct mapping to swr_set_compensation().

Parameters

sampleDelta

number

Sample difference to compensate

compensationDistance

number

Distance over which to compensate

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EINVAL: Invalid parameters

Example

typescript

import { FFmpegError } from 'node-av';

// Compensate 10 samples over 1000 samples
const ret = resampler.setCompensation(10, 1000);
FFmpegError.throwIfError(ret, 'setCompensation');

setMatrix()

setMatrix(matrix, stride): number

Defined in: src/lib/software-resample-context.ts:540

Set mixing matrix.

Sets a custom mixing matrix for channel remapping.

Direct mapping to swr_set_matrix().

Parameters

matrix

number[]

Mixing matrix coefficients

stride

number

Matrix row stride

Returns

number

0 on success, negative AVERROR on error

Example

typescript

// Custom downmix matrix
const matrix = [
  1.0, 0.0,  // Left channel
  0.0, 1.0,  // Right channel
];
const ret = resampler.setMatrix(matrix, 2);
FFmpegError.throwIfError(ret, 'setMatrix');

setOption()

Set an option on this object.

Uses the AVOption API to set options. Available options depend on the specific object type.

Direct mapping to av_opt_set* functions.

Param

name

Option name

Param

value

Option value

Param

type

Option type; when omitted, the option's declared type is looked up via av_opt_find and the value converted accordingly

Param

searchFlags

Search flags (default: AV_OPT_SEARCH_CHILDREN)

Example

typescript

import { FFmpegError } from 'node-av';
import { AV_OPT_TYPE_STRING, AV_OPT_TYPE_INT64, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_PIXEL_FMT } from 'node-av/constants';

// Untyped - the option's declared type is inferred
let ret = obj.setOption('preset', 'fast');
FFmpegError.throwIfError(ret, 'set preset');

ret = obj.setOption('codec', 'h264', AV_OPT_TYPE_STRING);
FFmpegError.throwIfError(ret, 'set codec');

// Integer options
ret = obj.setOption('bitrate', 2000000, AV_OPT_TYPE_INT64);
FFmpegError.throwIfError(ret, 'set bitrate');

ret = obj.setOption('threads', 4, AV_OPT_TYPE_INT);
FFmpegError.throwIfError(ret, 'set threads');

// Complex types with proper types
ret = obj.setOption('framerate', {num: 30, den: 1}, AV_OPT_TYPE_RATIONAL);
FFmpegError.throwIfError(ret, 'set framerate');

ret = obj.setOption('pix_fmt', AV_PIX_FMT_YUV420P, AV_OPT_TYPE_PIXEL_FMT);
FFmpegError.throwIfError(ret, 'set pixel format');