Skip to content

node-av / lib / SoftwareScaleContext

Class: SoftwareScaleContext

Defined in: src/lib/software-scale-context.ts:54

Video scaling and pixel format conversion context.

Provides high-quality image scaling and pixel format conversion for video frames. Supports various scaling algorithms from fast bilinear to high-quality Lanczos. Essential for resolution changes, aspect ratio adjustments, and format compatibility in video processing pipelines.

Direct mapping to FFmpeg's SwsContext.

Example

typescript
import { SoftwareScaleContext, Frame, FFmpegError } from 'node-av';
import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24, SWS_LANCZOS } from 'node-av/constants';

// Create scaler
const scaler = new SoftwareScaleContext();

// Configure scaling: 1920x1080 YUV420P -> 1280x720 RGB24
scaler.getContext(
  1920, 1080, AV_PIX_FMT_YUV420P,  // Source
  1280, 720, AV_PIX_FMT_RGB24,     // Destination
  SWS_LANCZOS                       // High quality
);

const ret = scaler.initContext();
FFmpegError.throwIfError(ret, 'initContext');

// Scale frames
const dstFrame = new Frame();
dstFrame.width = 1280;
dstFrame.height = 720;
dstFrame.format = AV_PIX_FMT_RGB24;
dstFrame.allocBuffer();

const height = await scaler.scaleFrame(dstFrame, srcFrame);
console.log(`Scaled to ${height} lines`);

// Clean up
scaler.freeContext();

See

Extends

Implements

Constructors

Constructor

new SoftwareScaleContext(): SoftwareScaleContext

Defined in: src/lib/software-scale-context.ts:55

Returns

SoftwareScaleContext

Overrides

OptionMember<NativeSoftwareScaleContext>.constructor

Properties

native

protected native: NativeSoftwareScaleContext

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

Inherited from

OptionMember.native

Methods

[dispose]()

[dispose](): void

Defined in: src/lib/software-scale-context.ts:377

Dispose of the scaling context.

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

Returns

void

Example

typescript
{
  using scaler = new SoftwareScaleContext();
  scaler.getContext(...);
  scaler.initContext();
  // Use scaler...
} // Automatically freed when leaving scope

Implementation of

Disposable.[dispose]


allocContext()

allocContext(): void

Defined in: src/lib/software-scale-context.ts:76

Allocate scale context.

Allocates memory for the scaler. Must be called before configuration if using options.

Direct mapping to sws_alloc_context().

Returns

void

Example

typescript
const scaler = new SoftwareScaleContext();
scaler.allocContext();
// Now configure with setOption() or getContext()

See

getContext For direct configuration


freeContext()

freeContext(): void

Defined in: src/lib/software-scale-context.ts:170

Free scaling context.

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

Direct mapping to sws_freeContext().

Returns

void

Example

typescript
scaler.freeContext();
// Scaler is now invalid

See

Symbol.dispose For automatic cleanup


getContext()

getContext(srcW, srcH, srcFormat, dstW, dstH, dstFormat, flags): void

Defined in: src/lib/software-scale-context.ts:124

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

SWSFlag = SWS_BILINEAR

Scaling algorithm flags (SWS_*)

Returns

void

Example

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

See

initContext Must be called after configuration


getNative()

getNative(): NativeSoftwareScaleContext

Defined in: src/lib/software-scale-context.ts:357

Internal

Get the underlying native SoftwareScaleContext object.

Returns

NativeSoftwareScaleContext

The native SoftwareScaleContext 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

Option name

Param

Option type (defaults to AV_OPT_TYPE_STRING)

Param

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?): null | string

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

Parameters
name

string

type?

AVOptionTypeString

searchFlags?

AVOptionSearchFlags

Returns

null | string

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeColor

searchFlags?

AVOptionSearchFlags

Returns

null | string

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeInt

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeInt64

searchFlags?

AVOptionSearchFlags

Returns

null | bigint

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeUint

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeUint64

searchFlags?

AVOptionSearchFlags

Returns

null | bigint

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeFlags

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeBool

searchFlags?

AVOptionSearchFlags

Returns

null | boolean

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeDuration

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeConst

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeDouble

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeFloat

searchFlags?

AVOptionSearchFlags

Returns

null | number

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeRational

searchFlags?

AVOptionSearchFlags

Returns

null | IRational

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeVideoRate

searchFlags?

AVOptionSearchFlags

Returns

null | IRational

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypePixelFmt

searchFlags?

AVOptionSearchFlags

Returns

null | AVPixelFormat

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeSampleFmt

searchFlags?

AVOptionSearchFlags

Returns

null | AVSampleFormat

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): null | { height: number; width: number; }

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

Parameters
name

string

type

AVOptionTypeImageSize

searchFlags?

AVOptionSearchFlags

Returns

null | { height: number; width: number; }

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeChLayout

searchFlags?

AVOptionSearchFlags

Returns

null | ChannelLayout

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeDict

searchFlags?

AVOptionSearchFlags

Returns

null | Dictionary

Inherited from

OptionMember.getOption

Call Signature

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

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

Parameters
name

string

type

AVOptionTypeBinary

searchFlags?

AVOptionSearchFlags

Returns

null | string

Inherited from

OptionMember.getOption


initContext()

initContext(): number

Defined in: src/lib/software-scale-context.ts:150

Initialize scaling context.

Initializes the scaler after configuration. Must be called before any scaling operations.

Direct mapping to sws_init_context().

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

const ret = scaler.initContext();
FFmpegError.throwIfError(ret, 'initContext');

See

getContext For configuration


listOptions()

listOptions(): OptionInfo[]

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

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


scale()

scale(srcSlice, srcStride, srcSliceY, srcSliceH, dst, dstStride): Promise<number>

Defined in: src/lib/software-scale-context.ts:214

Scale image data.

Scales raw image data from source to destination buffers. Low-level interface for custom buffer management.

Direct mapping to sws_scale().

Parameters

srcSlice

Buffer<ArrayBufferLike>[]

Source data planes (one buffer per plane)

srcStride

number[]

Bytes per line for each plane

srcSliceY

number

Starting Y position in source

srcSliceH

number

Height of source slice to process

dst

Buffer<ArrayBufferLike>[]

Destination data planes

dstStride

number[]

Destination bytes per line

Returns

Promise<number>

Output height in pixels, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid parameters

Example

typescript
// Scale YUV420P data
const srcPlanes = [yPlane, uPlane, vPlane];
const srcStrides = [1920, 960, 960]; // Full HD
const dstPlanes = [dstY, dstU, dstV];
const dstStrides = [1280, 640, 640]; // 720p

const height = await scaler.scale(
  srcPlanes, srcStrides, 0, 1080,
  dstPlanes, dstStrides
);
console.log(`Scaled ${height} lines`);

See

scaleFrame For frame-based scaling


scaleFrame()

scaleFrame(dst, src): Promise<number>

Defined in: src/lib/software-scale-context.ts:305

Scale video frame.

Scales an entire video frame to the destination format. Simpler interface than scale() for frame-based processing.

Direct mapping to sws_scale_frame().

Parameters

dst

Frame

Destination frame (must be allocated)

src

Frame

Source frame

Returns

Promise<number>

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid parameters
  • AVERROR_ENOMEM: Memory allocation failure

Example

typescript
import { Frame, FFmpegError } from 'node-av';
import { AV_PIX_FMT_RGB24 } from 'node-av/constants';

// Create destination frame
const dstFrame = new Frame();
dstFrame.width = 1280;
dstFrame.height = 720;
dstFrame.format = AV_PIX_FMT_RGB24;
const ret = dstFrame.allocBuffer();
FFmpegError.throwIfError(ret, 'allocBuffer');

// Scale frame
const ret2 = await scaler.scaleFrame(dstFrame, srcFrame);
FFmpegError.throwIfError(ret2, 'scaleFrame');

// dstFrame now contains scaled image

See

scale For buffer-based scaling


scaleFrameSync()

scaleFrameSync(dst, src): number

Defined in: src/lib/software-scale-context.ts:346

Scale video frame synchronously. Synchronous version of scaleFrame.

Scales an entire video frame to the destination format. Simpler interface than scaleSync() for frame-based processing.

Direct mapping to sws_scale_frame().

Parameters

dst

Frame

Destination frame (must be allocated)

src

Frame

Source frame

Returns

number

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid parameters

Example

typescript
import { FFmpegError } from 'node-av';
import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24 } from 'node-av/constants';

// Convert YUV to RGB
const srcFrame = new Frame();
srcFrame.allocBuffer(AV_PIX_FMT_YUV420P, 1920, 1080);
// ... fill with YUV data ...

const dstFrame = new Frame();
dstFrame.allocBuffer(AV_PIX_FMT_RGB24, 1920, 1080);

const ret = scaler.scaleFrameSync(dstFrame, srcFrame);
FFmpegError.throwIfError(ret, 'scaleFrameSync');

// dstFrame now contains scaled image

See

scaleFrame For async version


scaleSync()

scaleSync(srcSlice, srcStride, srcSliceY, srcSliceH, dst, dstStride): number

Defined in: src/lib/software-scale-context.ts:263

Scale video synchronously. Synchronous version of scale.

Scales raw video data from source to destination format. Can scale a slice or entire image.

Direct mapping to sws_scale().

Parameters

srcSlice

Buffer<ArrayBufferLike>[]

Array of source buffers (one per plane)

srcStride

number[]

Array of source strides (bytes per row)

srcSliceY

number

Y position of slice (0 for full image)

srcSliceH

number

Height of slice (full height for entire image)

dst

Buffer<ArrayBufferLike>[]

Array of destination buffers (one per plane)

dstStride

number[]

Array of destination strides

Returns

number

Height of output image, or negative AVERROR:

  • AVERROR_EINVAL: Invalid parameters

Example

typescript
import { FFmpegError } from 'node-av';

// Scale YUV420P image
const srcBufs = [yPlane, uPlane, vPlane];
const srcStrides = [srcWidth, srcWidth/2, srcWidth/2];
const dstBufs = [dstY, dstU, dstV];
const dstStrides = [dstWidth, dstWidth/2, dstWidth/2];

const height = scaler.scaleSync(
  srcBufs, srcStrides,
  0, srcHeight,  // Full image
  dstBufs, dstStrides
);
FFmpegError.throwIfError(height, 'scaleSync');
console.log(`Scaled ${height} lines`);

See

scale For async version


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

Option name

Param

Option value

Param

Option type (defaults to AV_OPT_TYPE_STRING)

Param

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

// String options (default)
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');

Call Signature

setOption(name, value, type?, searchFlags?): number

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

Parameters
name

string

value

string

type?

AVOptionTypeString

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

string

type

AVOptionTypeColor

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeInt

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

bigint

type

AVOptionTypeInt64

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeUint

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

bigint

type

AVOptionTypeUint64

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeFlags

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

boolean

type

AVOptionTypeBool

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeDuration

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeConst

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeDouble

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number

type

AVOptionTypeFloat

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

IRational

type

AVOptionTypeRational

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

IRational

type

AVOptionTypeVideoRate

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

AVPixelFormat

type

AVOptionTypePixelFmt

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

AVSampleFormat

type

AVOptionTypeSampleFmt

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value
height

number

width

number

type

AVOptionTypeImageSize

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number | bigint

type

AVOptionTypeChLayout

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

Buffer

type

AVOptionTypeBinary

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

number[]

type

AVOptionTypeBinaryIntArray

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption

Call Signature

setOption(name, value, type, searchFlags?): number

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

Parameters
name

string

value

Dictionary

type

AVOptionTypeDict

searchFlags?

AVOptionSearchFlags

Returns

number

Inherited from

OptionMember.setOption