node-av 1.1.0 → 1.2.0

package/dist/lib/software-scale-context.js

@@ -2,304 +2,260 @@ import { SWS_BILINEAR } from '../constants/constants.js';
 import { bindings } from './binding.js';
 import { OptionMember } from './option.js';
 /**
- * Software video scaling context.
+ * Video scaling and pixel format conversion context.
  *
- * Provides high-quality video scaling, format conversion, and color space conversion.
+ * Provides high-quality image scaling and pixel format conversion for video frames.
  * Supports various scaling algorithms from fast bilinear to high-quality Lanczos.
- * Uses the libswscale library for efficient video processing.
+ * 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_BILINEAR } from 'node-av/constants';
+ * import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24, SWS_LANCZOS } from 'node-av/constants';
  *
- * // Create and configure scale context
- * const sws = new SoftwareScaleContext();
- * sws.getContext(
- *   1920, 1080, AV_PIX_FMT_YUV420P,
- *   1280, 720, AV_PIX_FMT_RGB24,
- *   SWS_BILINEAR
- * );
+ * // Create scaler
+ * const scaler = new SoftwareScaleContext();
  *
- * // Scale frame data
- * const ret = await sws.scale(
- *   srcSlice, srcStride, 0, srcHeight,
- *   dst, dstStride
+ * // 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
  * );
  *
- * // Or scale Frame objects directly
- * const scaleRet = await sws.scaleFrame(dstFrame, srcFrame);
- * FFmpegError.throwIfError(scaleRet, 'scaleFrame');
+ * 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`);
  *
- * // Cleanup
- * sws.freeContext();
+ * // Clean up
+ * scaler.freeContext();
  * ```
+ *
+ * @see [SwsContext](https://ffmpeg.org/doxygen/trunk/structSwsContext.html) - FFmpeg Doxygen
+ * @see {@link Frame} For video frame operations
  */
 export class SoftwareScaleContext extends OptionMember {
-    /**
-     * Create a new software scale context.
-     *
-     * The context is uninitialized - you must call allocContext() or getContext() before use.
-     * No FFmpeg resources are allocated until initialization.
-     *
-     * Direct wrapper around SwsContext.
-     *
-     * @example
-     * ```typescript
-     * import { SoftwareScaleContext } from 'node-av';
-     * import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24, SWS_BILINEAR } from 'node-av/constants';
-     *
-     * const sws = new SoftwareScaleContext();
-     * sws.getContext(
-     *   1920, 1080, AV_PIX_FMT_YUV420P,
-     *   1280, 720, AV_PIX_FMT_RGB24,
-     *   SWS_BILINEAR
-     * );
-     * ```
-     */
     constructor() {
         super(new bindings.SoftwareScaleContext());
     }
     /**
-     * Allocate an empty SwsContext.
+     * Allocate scale context.
      *
-     * Allocates an uninitialized scale context.
-     * Options must be set through the AVOptions API before calling initContext().
+     * Allocates memory for the scaler.
+     * Must be called before configuration if using options.
      *
-     * Direct mapping to sws_alloc_context()
-     *
-     * @throws {Error} Memory allocation failure (ENOMEM)
+     * Direct mapping to sws_alloc_context().
      *
      * @example
      * ```typescript
-     * import { SoftwareScaleContext, FFmpegError } from 'node-av';
-     *
-     * const sws = new SoftwareScaleContext();
-     * sws.allocContext();
-     * // Set options via AVOptions API
-     * const ret = sws.initContext();
-     * FFmpegError.throwIfError(ret, 'initContext');
+     * const scaler = new SoftwareScaleContext();
+     * scaler.allocContext();
+     * // Now configure with setOption() or getContext()
      * ```
      *
-     * @see {@link getContext} For one-step allocation and configuration
-     * @see {@link initContext} To initialize after configuration
+     * @see {@link getContext} For direct configuration
      */
     allocContext() {
         this.native.allocContext();
     }
     /**
-     * Allocate and return an SwsContext.
-     *
-     * One-step allocation and configuration of the scale context.
-     * Sets up everything needed for scaling operations.
-     *
-     * Direct mapping to sws_getContext()
-     *
-     * @param srcW - The width of the source image
-     * @param srcH - The height of the source image
-     * @param srcFormat - The source image format
-     * @param dstW - The width of the destination image
-     * @param dstH - The height of the destination image
-     * @param dstFormat - The destination image format
-     * @param flags - Specify which algorithm and options to use for rescaling:
-     *   - SWS_FAST_BILINEAR: Fast bilinear
-     *   - SWS_BILINEAR: Bilinear
-     *   - SWS_BICUBIC: Bicubic
-     *   - SWS_X: Experimental
-     *   - SWS_POINT: Nearest neighbor
-     *   - SWS_AREA: Area averaging
-     *   - SWS_BICUBLIN: Luma bicubic, chroma bilinear
-     *   - SWS_GAUSS: Gaussian
-     *   - SWS_SINC: Sinc
-     *   - SWS_LANCZOS: Lanczos
-     *   - SWS_SPLINE: Natural bicubic spline
-     *
-     * @throws {Error} Memory allocation failure (ENOMEM)
+     * Configure scaling context.
+     *
+     * Sets up the scaler with source and destination formats.
+     * This is the primary configuration method.
+     *
+     * Direct mapping to sws_getContext().
+     *
+     * @param srcW - Source width in pixels
+     * @param srcH - Source height in pixels
+     * @param srcFormat - Source pixel format
+     * @param dstW - Destination width in pixels
+     * @param dstH - Destination height in pixels
+     * @param dstFormat - Destination pixel format
+     * @param flags - Scaling algorithm flags (SWS_*)
      *
      * @example
      * ```typescript
-     * import { SoftwareScaleContext } from 'node-av';
-     * import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24, SWS_BILINEAR } from 'node-av/constants';
+     * 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';
      *
-     * // Scale from 1080p YUV to 720p RGB
-     * sws.getContext(
+     * // Fast bilinear (lower quality, faster)
+     * scaler.getContext(
      *   1920, 1080, AV_PIX_FMT_YUV420P,
      *   1280, 720, AV_PIX_FMT_RGB24,
-     *   SWS_BILINEAR
+     *   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 {@link scale} To scale image data
-     * @see {@link scaleFrame} To scale Frame objects
+     * @see {@link initContext} Must be called after configuration
      */
     getContext(srcW, srcH, srcFormat, dstW, dstH, dstFormat, flags = SWS_BILINEAR) {
         this.native.getContext(srcW, srcH, srcFormat, dstW, dstH, dstFormat, flags);
     }
     /**
-     * Initialize the swscaler context sws_context.
+     * Initialize scaling context.
      *
-     * Completes initialization of the scale context.
-     * Must be called after allocContext() and configuration.
+     * Initializes the scaler after configuration.
+     * Must be called before any scaling operations.
      *
-     * Direct mapping to sws_init_context()
+     * Direct mapping to sws_init_context().
      *
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success
-     *   - AVERROR(EINVAL): Invalid parameters
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other errors
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
      *
      * @example
      * ```typescript
      * import { FFmpegError } from 'node-av';
      *
-     * const ret = sws.initContext();
+     * const ret = scaler.initContext();
      * FFmpegError.throwIfError(ret, 'initContext');
      * ```
      *
-     * @see {@link allocContext} For allocation
-     * @see {@link getContext} For one-step setup
+     * @see {@link getContext} For configuration
      */
     initContext() {
         return this.native.initContext();
     }
     /**
-     * Free the swscaler context swsContext.
+     * Free scaling context.
      *
-     * Releases all resources associated with the scale context.
-     * Safe to call on NULL context.
+     * Releases all resources associated with the scaler.
+     * The context becomes invalid after calling this.
      *
-     * Direct mapping to sws_freeContext()
+     * Direct mapping to sws_freeContext().
      *
      * @example
      * ```typescript
-     * sws.freeContext();
-     * // sws is now invalid and should not be used
+     * scaler.freeContext();
+     * // Scaler is now invalid
      * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
      */
     freeContext() {
         this.native.freeContext();
     }
     /**
-     * Scale the image slice in srcSlice and put the resulting scaled slice in the image in dst.
-     *
-     * Scales image data from source to destination.
-     * Processes image in slices for efficient memory usage.
+     * Scale image data.
      *
-     * Direct mapping to sws_scale()
+     * Scales raw image data from source to destination buffers.
+     * Low-level interface for custom buffer management.
      *
-     * @param srcSlice - The array containing the pointers to the planes of the source slice
-     * @param srcStride - The array containing the strides for each plane of the source image
-     * @param srcSliceY - The position in the source image of the slice to process (first row number)
-     * @param srcSliceH - The height of the source slice (number of rows)
-     * @param dst - The array containing the pointers to the planes of the destination image
-     * @param dstStride - The array containing the strides for each plane of the destination image
+     * Direct mapping to sws_scale().
      *
-     * @returns Promise resolving to the height of the output slice
+     * @param srcSlice - Source data planes (one buffer per plane)
+     * @param srcStride - Bytes per line for each plane
+     * @param srcSliceY - Starting Y position in source
+     * @param srcSliceH - Height of source slice to process
+     * @param dst - Destination data planes
+     * @param dstStride - Destination bytes per line
+     * @returns Output height in pixels, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
      *
      * @example
      * ```typescript
-     * const outputHeight = await sws.scale(
-     *   srcData,
-     *   srcLinesize,
-     *   0,
-     *   srcHeight,
-     *   dstData,
-     *   dstLinesize
+     * // 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 ${outputHeight} rows`);
+     * console.log(`Scaled ${height} lines`);
      * ```
      *
-     * @see {@link scaleFrame} For Frame-based scaling
-     *
-     * @note Slices must be provided in sequential order (top-bottom or bottom-top).
-     * Non-sequential order results in undefined behavior.
+     * @see {@link scaleFrame} For frame-based scaling
      */
     async scale(srcSlice, srcStride, srcSliceY, srcSliceH, dst, dstStride) {
-        return this.native.scale(srcSlice, srcStride, srcSliceY, srcSliceH, dst, dstStride);
+        return await this.native.scale(srcSlice, srcStride, srcSliceY, srcSliceH, dst, dstStride);
     }
     /**
-     * Scale source data from src and write the output to dst.
-     *
-     * Frame-based scaling with automatic configuration.
-     * Dynamically adapts to frame properties without reallocation.
+     * Scale video frame.
      *
-     * Direct mapping to sws_scale_frame()
+     * Scales an entire video frame to the destination format.
+     * Simpler interface than scale() for frame-based processing.
      *
-     * @param dst - The destination frame (buffers can be pre-allocated or allocated by scaler)
-     * @param src - The source frame
+     * Direct mapping to sws_scale_frame().
      *
-     * @returns The height of the output slice on success, negative AVERROR on error:
-     *   - >0: Output height (success)
-     *   - AVERROR(EINVAL): Invalid parameters
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other errors
+     * @param dst - Destination frame (must be allocated)
+     * @param src - Source frame
+     * @returns 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';
      *
-     * const srcFrame = new Frame();
-     * srcFrame.alloc();
-     * // ... fill srcFrame with data ...
-     *
+     * // Create destination frame
      * const dstFrame = new Frame();
-     * dstFrame.alloc();
      * dstFrame.width = 1280;
      * dstFrame.height = 720;
      * dstFrame.format = AV_PIX_FMT_RGB24;
-     * const bufRet = dstFrame.getBuffer();
-     * FFmpegError.throwIfError(bufRet, 'getBuffer');
+     * const ret = dstFrame.allocBuffer();
+     * FFmpegError.throwIfError(ret, 'allocBuffer');
+     *
+     * // Scale frame
+     * const ret2 = await scaler.scaleFrame(dstFrame, srcFrame);
+     * FFmpegError.throwIfError(ret2, 'scaleFrame');
      *
-     * const ret = await sws.scaleFrame(dstFrame, srcFrame);
-     * FFmpegError.throwIfError(ret, 'scaleFrame');
-     * console.log(`Scaled to height: ${ret}`);
+     * // dstFrame now contains scaled image
      * ```
      *
      * @see {@link scale} For buffer-based scaling
-     *
-     * @note This function can be used directly on an allocated context without
-     * calling sws_init_context(). Such usage is fully dynamic and does not
-     * require reallocation if frame properties change.
      */
     async scaleFrame(dst, src) {
-        return this.native.scaleFrame(dst.getNative(), src.getNative());
+        return await this.native.scaleFrame(dst.getNative(), src.getNative());
     }
     /**
-     * Get the native FFmpeg SwsContext pointer.
+     * Get the underlying native SoftwareScaleContext object.
+     *
+     * @returns The native SoftwareScaleContext binding object
      *
-     * @internal For use by other wrapper classes
-     * @returns The underlying native scale context object
+     * @internal
      */
     getNative() {
         return this.native;
     }
     /**
-     * Dispose of the scale context.
+     * Dispose of the scaling context.
      *
      * Implements the Disposable interface for automatic cleanup.
      * Equivalent to calling freeContext().
      *
      * @example
      * ```typescript
-     * import { SoftwareScaleContext } from 'node-av';
-     * import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24, SWS_BILINEAR } from 'node-av/constants';
-     *
      * {
-     *   using sws = new SoftwareScaleContext();
-     *   sws.getContext(
-     *     1920, 1080, AV_PIX_FMT_YUV420P,
-     *     1280, 720, AV_PIX_FMT_RGB24,
-     *     SWS_BILINEAR
-     *   );
-     *   // ... use context
+     *   using scaler = new SoftwareScaleContext();
+     *   scaler.getContext(...);
+     *   scaler.initContext();
+     *   // Use scaler...
      * } // Automatically freed when leaving scope
      * ```
-     *
-     * @see {@link freeContext} For manual cleanup
      */
     [Symbol.dispose]() {
         this.native[Symbol.dispose]();

package/dist/lib/software-scale-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"software-scale-context.js","sourceRoot":"","sources":["../../src/lib/software-scale-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAwC;IAChF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;QACE,KAAK,CAAC,IAAI,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,YAAY;QACV,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,UAAU,CAAC,IAAY,EAAE,IAAY,EAAE,SAAwB,EAAE,IAAY,EAAE,IAAY,EAAE,SAAwB,EAAE,QAAiB,YAAY;QAClJ,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,WAAW;QACT,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,KAAK,CAAC,KAAK,CAAC,QAAkB,EAAE,SAAmB,EAAE,SAAiB,EAAE,SAAiB,EAAE,GAAa,EAAE,SAAmB;QAC3H,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IACtF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,KAAK,CAAC,UAAU,CAAC,GAAU,EAAE,GAAU;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAClE,CAAC;IAED;;;;;OAKG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,CAAC;CACF"}
+{"version":3,"file":"software-scale-context.js","sourceRoot":"","sources":["../../src/lib/software-scale-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAwC;IAChF;QACE,KAAK,CAAC,IAAI,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY;QACV,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,UAAU,CAAC,IAAY,EAAE,IAAY,EAAE,SAAwB,EAAE,IAAY,EAAE,IAAY,EAAE,SAAwB,EAAE,QAAiB,YAAY;QAClJ,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,WAAW;QACT,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,KAAK,CAAC,KAAK,CAAC,QAAkB,EAAE,SAAmB,EAAE,SAAiB,EAAE,SAAiB,EAAE,GAAa,EAAE,SAAmB;QAC3H,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5F,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,KAAK,CAAC,UAAU,CAAC,GAAU,EAAE,GAAU;QACrC,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,CAAC;CACF"}