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
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
- SwsContext - FFmpeg Doxygen
- Frame For video frame operations
Extends
Implements
DisposableNativeWrapper<NativeSoftwareScaleContext>
Constructors
Constructor
new SoftwareScaleContext():
SoftwareScaleContext
Defined in: src/lib/software-scale-context.ts:55
Returns
SoftwareScaleContext
Overrides
OptionMember<NativeSoftwareScaleContext>.constructor
Properties
native
protectednative:NativeSoftwareScaleContext
Defined in: src/lib/option.ts:1059
Inherited from
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
{
using scaler = new SoftwareScaleContext();
scaler.getContext(...);
scaler.initContext();
// Use scaler...
} // Automatically freed when leaving scopeImplementation 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
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
scaler.freeContext();
// Scaler is now invalidSee
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
Source pixel format
dstW
number
Destination width in pixels
dstH
number
Destination height in pixels
dstFormat
Destination pixel format
flags?
SwsFlags = SWS_BILINEAR
Scaling algorithm flags (SWS_*)
Returns
void
Example
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
The native SoftwareScaleContext binding object
Implementation of
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
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 bigintCall Signature
getOption(
name,type?,searchFlags?):string|null
Defined in: src/lib/option.ts:1288
Parameters
name
string
type?
searchFlags?
Returns
string | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):string|null
Defined in: src/lib/option.ts:1289
Parameters
name
string
type
searchFlags?
Returns
string | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1292
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):bigint|null
Defined in: src/lib/option.ts:1293
Parameters
name
string
type
searchFlags?
Returns
bigint | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1294
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):bigint|null
Defined in: src/lib/option.ts:1295
Parameters
name
string
type
searchFlags?
Returns
bigint | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1296
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):boolean|null
Defined in: src/lib/option.ts:1297
Parameters
name
string
type
searchFlags?
Returns
boolean | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1298
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1299
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1302
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1303
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):IRational|null
Defined in: src/lib/option.ts:1306
Parameters
name
string
type
searchFlags?
Returns
IRational | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):IRational|null
Defined in: src/lib/option.ts:1307
Parameters
name
string
type
searchFlags?
Returns
IRational | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):AVPixelFormat|null
Defined in: src/lib/option.ts:1308
Parameters
name
string
type
searchFlags?
Returns
AVPixelFormat | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):AVSampleFormat|null
Defined in: src/lib/option.ts:1309
Parameters
name
string
type
searchFlags?
Returns
AVSampleFormat | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):IDimension|null
Defined in: src/lib/option.ts:1310
Parameters
name
string
type
searchFlags?
Returns
IDimension | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):ChannelLayout|null
Defined in: src/lib/option.ts:1311
Parameters
name
string
type
searchFlags?
Returns
ChannelLayout | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):Dictionary|null
Defined in: src/lib/option.ts:1312
Parameters
name
string
type
searchFlags?
Returns
Dictionary | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):string|null
Defined in: src/lib/option.ts:1313
Parameters
name
string
type
searchFlags?
Returns
string | null
Inherited from
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
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: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
Array of option information objects
Example
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
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
// 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
Destination frame (must be allocated)
src
Source frame
Returns
Promise<number>
0 on success, negative AVERROR on error:
- AVERROR_EINVAL: Invalid parameters
- AVERROR_ENOMEM: Memory allocation failure
Example
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 imageSee
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
Destination frame (must be allocated)
src
Source frame
Returns
number
0 on success, negative AVERROR on error:
- AVERROR_EINVAL: Invalid parameters
Example
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 imageSee
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
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
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
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');Call Signature
setOption(
name,value):number
Defined in: src/lib/option.ts:1066
Parameters
name
string
value
string | number | bigint | boolean | null | undefined
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1067
Parameters
name
string
value
string
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1068
Parameters
name
string
value
string
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1071
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1072
Parameters
name
string
value
bigint
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1073
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1074
Parameters
name
string
value
bigint
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1075
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1076
Parameters
name
string
value
boolean
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1077
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1078
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1081
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1082
Parameters
name
string
value
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1085
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1086
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1087
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1088
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1089
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1090
Parameters
name
string
value
number | bigint
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1091
Parameters
name
string
value
Buffer
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1092
Parameters
name
string
value
number[]
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1093
Parameters
name
string
value
type
searchFlags?
Returns
number
