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:1030
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
Option name
Param
Option type (defaults to AV_OPT_TYPE_STRING)
Param
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:1259
Parameters
name
string
type?
searchFlags?
Returns
string | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):string|null
Defined in: src/lib/option.ts:1260
Parameters
name
string
type
searchFlags?
Returns
string | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1263
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):bigint|null
Defined in: src/lib/option.ts:1264
Parameters
name
string
type
searchFlags?
Returns
bigint | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1265
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):bigint|null
Defined in: src/lib/option.ts:1266
Parameters
name
string
type
searchFlags?
Returns
bigint | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1267
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):boolean|null
Defined in: src/lib/option.ts:1268
Parameters
name
string
type
searchFlags?
Returns
boolean | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1269
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1270
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1273
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):number|null
Defined in: src/lib/option.ts:1274
Parameters
name
string
type
searchFlags?
Returns
number | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):IRational|null
Defined in: src/lib/option.ts:1277
Parameters
name
string
type
searchFlags?
Returns
IRational | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):IRational|null
Defined in: src/lib/option.ts:1278
Parameters
name
string
type
searchFlags?
Returns
IRational | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):AVPixelFormat|null
Defined in: src/lib/option.ts:1279
Parameters
name
string
type
searchFlags?
Returns
AVPixelFormat | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):AVSampleFormat|null
Defined in: src/lib/option.ts:1280
Parameters
name
string
type
searchFlags?
Returns
AVSampleFormat | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):IDimension|null
Defined in: src/lib/option.ts:1281
Parameters
name
string
type
searchFlags?
Returns
IDimension | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):ChannelLayout|null
Defined in: src/lib/option.ts:1282
Parameters
name
string
type
searchFlags?
Returns
ChannelLayout | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):Dictionary|null
Defined in: src/lib/option.ts:1283
Parameters
name
string
type
searchFlags?
Returns
Dictionary | null
Inherited from
Call Signature
getOption(
name,type,searchFlags?):string|null
Defined in: src/lib/option.ts:1284
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:1400
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
Option name
Param
Option value
Param
Option type (defaults to AV_OPT_TYPE_STRING)
Param
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';
// 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):number
Defined in: src/lib/option.ts:1037
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:1038
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:1039
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:1042
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:1043
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:1044
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:1045
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:1046
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:1047
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:1048
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:1049
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:1052
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:1053
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:1056
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1057
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1058
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1059
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1060
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name,value,type,searchFlags?):number
Defined in: src/lib/option.ts:1061
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:1062
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:1063
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:1064
Parameters
name
string
value
type
searchFlags?
Returns
number
