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
Disposable
NativeWrapper
<NativeSoftwareScaleContext
>
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
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 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
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 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
Source pixel format
dstW
number
Destination width in pixels
dstH
number
Destination height in pixels
dstFormat
Destination pixel format
flags
SWSFlag
= 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 bigint
Call Signature
getOption(
name
,type?
,searchFlags?
):null
|string
Defined in: src/lib/option.ts:1217
Parameters
name
string
type?
searchFlags?
Returns
null
| string
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|string
Defined in: src/lib/option.ts:1218
Parameters
name
string
type
searchFlags?
Returns
null
| string
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1221
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|bigint
Defined in: src/lib/option.ts:1222
Parameters
name
string
type
searchFlags?
Returns
null
| bigint
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1223
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|bigint
Defined in: src/lib/option.ts:1224
Parameters
name
string
type
searchFlags?
Returns
null
| bigint
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1225
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|boolean
Defined in: src/lib/option.ts:1226
Parameters
name
string
type
searchFlags?
Returns
null
| boolean
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1227
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1228
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1231
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|number
Defined in: src/lib/option.ts:1232
Parameters
name
string
type
searchFlags?
Returns
null
| number
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|IRational
Defined in: src/lib/option.ts:1235
Parameters
name
string
type
searchFlags?
Returns
null
| IRational
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|IRational
Defined in: src/lib/option.ts:1236
Parameters
name
string
type
searchFlags?
Returns
null
| IRational
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|AVPixelFormat
Defined in: src/lib/option.ts:1237
Parameters
name
string
type
searchFlags?
Returns
null
| AVPixelFormat
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|AVSampleFormat
Defined in: src/lib/option.ts:1238
Parameters
name
string
type
searchFlags?
Returns
null
| AVSampleFormat
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
| {height
:number
;width
:number
; }
Defined in: src/lib/option.ts:1239
Parameters
name
string
type
searchFlags?
Returns
null
| { height
: number
; width
: number
; }
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|ChannelLayout
Defined in: src/lib/option.ts:1240
Parameters
name
string
type
searchFlags?
Returns
null
| ChannelLayout
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|Dictionary
Defined in: src/lib/option.ts:1241
Parameters
name
string
type
searchFlags?
Returns
null
| Dictionary
Inherited from
Call Signature
getOption(
name
,type
,searchFlags?
):null
|string
Defined in: src/lib/option.ts:1242
Parameters
name
string
type
searchFlags?
Returns
null
| string
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: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
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 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
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 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
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
,type?
,searchFlags?
):number
Defined in: src/lib/option.ts:1006
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:1007
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:1010
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:1011
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:1012
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:1013
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:1014
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:1015
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:1016
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:1017
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:1020
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:1021
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:1024
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name
,value
,type
,searchFlags?
):number
Defined in: src/lib/option.ts:1025
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name
,value
,type
,searchFlags?
):number
Defined in: src/lib/option.ts:1026
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name
,value
,type
,searchFlags?
):number
Defined in: src/lib/option.ts:1027
Parameters
name
string
value
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name
,value
,type
,searchFlags?
):number
Defined in: src/lib/option.ts:1028
Parameters
name
string
value
height
number
width
number
type
searchFlags?
Returns
number
Inherited from
Call Signature
setOption(
name
,value
,type
,searchFlags?
):number
Defined in: src/lib/option.ts:1029
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:1030
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:1031
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:1032
Parameters
name
string
value
type
searchFlags?
Returns
number