node-av 6.2.0-beta.2 → 6.2.0-beta.21

package/dist/api/scaler.d.ts

@@ -81,6 +81,10 @@ export interface ScalerOptions {
  * Software frames are scaled with swscale; hardware frames are cropped, scaled,
  * and converted on the GPU with only the small result downloaded.
  *
+ * Safe for concurrent use: calls that share a cached graph or pooled encoder are
+ * serialized on that resource, while distinct output configurations run fully in
+ * parallel, and cache eviction never disposes a resource that is still in flight.
+ *
  * @example
  * ```typescript
  * import { Scaler } from 'node-av/api';
@@ -99,13 +103,14 @@ export interface ScalerOptions {
  */
 export declare class Scaler implements Disposable {
     private native;
+    private syncNative?;
+    private nativeLock;
     private hardware?;
     private flags;
     private maxCacheSize;
     private graphs;
     private jpegPool?;
     private pngPool?;
-    private downloadFrame?;
     private disposed;
     /**
      * Create a new scaler.
@@ -259,12 +264,13 @@ export declare class Scaler implements Disposable {
     /**
      * Download a hardware frame to system memory (no hardware context available).
      *
-     * Reuses a single target frame across calls. The frame's own hwframe context
-     * selects a supported software format.
+     * Allocates a fresh target per call - concurrent downloads must not share a
+     * staging frame. The frame's own hwframe context selects a supported software
+     * format. The caller frees the returned frame.
      *
      * @param frame - Hardware source frame
      *
-     * @returns Software frame
+     * @returns Software frame (caller frees)
      *
      * @throws {FFmpegError} If the transfer fails
      *
@@ -276,7 +282,7 @@ export declare class Scaler implements Disposable {
      *
      * @param frame - Hardware source frame
      *
-     * @returns Software frame
+     * @returns Software frame (caller frees)
      *
      * @throws {FFmpegError} If the transfer fails
      *
@@ -284,13 +290,34 @@ export declare class Scaler implements Disposable {
      */
     private downloadToSoftwareSync;
     /**
-     * Lazily allocate and reset the reused download target frame.
+     * Run the pooled native software scaler, serialized per instance.
+     *
+     * The native scaler reuses staging frames and sws contexts per configuration;
+     * overlapping async calls would race on them in the worker threads.
+     *
+     * @param frame - Software source frame
+     *
+     * @param options - Crop, resize, and format options
+     *
+     * @returns Tightly packed pixel data
+     *
+     * @throws {FFmpegError} If scaling fails
+     *
+     * @internal
+     */
+    private processNative;
+    /**
+     * The native scaler used by the sync path (lazily created).
+     *
+     * Sync calls block the event loop but can land while an async call's worker is
+     * scaling in the background; a separate native instance keeps them off the async
+     * scaler's pooled contexts, which are not safe to share across threads.
      *
-     * @returns The cleared download frame
+     * @returns The sync-path native scaler
      *
      * @internal
      */
-    private prepareDownloadTarget;
+    private getSyncNative;
     /**
      * Scale/crop/convert a frame through a cached filter graph and return the
      * resulting frame (caller must free it).
@@ -318,6 +345,10 @@ export declare class Scaler implements Disposable {
     /**
      * Synchronous version of toFrame.
      *
+     * Sync scales cannot interleave with each other (they block the event loop),
+     * but they can land between the awaits of an in-flight async scale; a busy
+     * cached graph is bypassed with a throwaway graph in that case.
+     *
      * @param frame - Source frame (software, or hardware with a hardware context)
      *
      * @param crop - Crop region, or undefined for the full frame
@@ -332,9 +363,23 @@ export declare class Scaler implements Disposable {
      */
     private toFrameSync;
     /**
-     * Resolve (and, on demand, build) the cached filter graph for a frame, applying
-     * the crop reconfiguration. Shared by the sync and async scaling paths; all of
-     * this work (parse, config, sendCommand) is synchronous.
+     * Scale through a throwaway graph with the crop baked in, bypassing the cache.
+     *
+     * @param frame - Source frame
+     *
+     * @param acq - Resolved operation configuration
+     *
+     * @returns The scaled output frame (caller frees)
+     *
+     * @throws {Error} If the graph produces no frame
+     *
+     * @internal
+     */
+    private scaleOneShotSync;
+    /**
+     * Resolve (and, on demand, build) the cached filter graph for a frame. Shared
+     * by the sync and async scaling paths; all of this work is synchronous, so a
+     * resolved entry cannot be evicted before the caller marks it in use.
      *
      * @param frame - Source frame (software, or hardware with a hardware context)
      *
@@ -344,7 +389,7 @@ export declare class Scaler implements Disposable {
      *
      * @param format - Output pixel format
      *
-     * @returns The cached graph entry (ready to process the frame) and its cache key
+     * @returns The cached graph entry and the resolved operation configuration
      *
      * @throws {Error} If the crop is out of bounds
      *
@@ -352,16 +397,57 @@ export declare class Scaler implements Disposable {
      */
     private resolveGraph;
     /**
-     * Dispose a cached graph and remove it from the cache.
+     * Bring a cached graph in line with the current call. Must run under the entry
+     * lock (async path) or with no async call in flight (sync path).
+     *
+     * Rebuilds the graph when the source parameters changed: FilterAPI would
+     * otherwise reinitialize itself from the original graph description, silently
+     * resurrecting the crop baked in at build time instead of the current one. A
+     * graph that has not seen a frame yet is likewise rebuilt when the crop
+     * differs, because commands cannot be sent before initialization. Otherwise a
+     * changed crop is re-aimed with runtime commands - identical crops reuse the
+     * graph untouched (no config_input/config_output re-run).
      *
-     * Used after a graph has been flushed (and is therefore at EOF and can no
-     * longer accept frames) so the next operation rebuilds it.
+     * @param acq - Resolved graph and operation configuration
      *
-     * @param key - Cache key of the graph to evict
+     * @param frame - Frame about to be processed
+     *
+     * @internal
+     */
+    private prepareGraph;
+    /**
+     * Remove a graph from the cache and retire it.
+     *
+     * Identity-checked so a newer graph cached under the same key is left alone.
+     * Used after a flush (the graph is at EOF and can no longer accept frames) and
+     * after mid-stream failures, so the next operation rebuilds it.
+     *
+     * @param key - Cache key of the graph
+     *
+     * @param entry - The exact entry to evict
      *
      * @internal
      */
     private evictGraph;
+    /**
+     * Take a graph out of service, disposing it now or on last release.
+     *
+     * An entry with in-flight scales is only marked; the final {@link releaseGraph}
+     * disposes the filter once nothing uses it anymore.
+     *
+     * @param entry - Entry removed from the cache
+     *
+     * @internal
+     */
+    private retireEntry;
+    /**
+     * Drop an in-flight reference, disposing the graph if it was retired meanwhile.
+     *
+     * @param entry - Entry acquired by {@link toFrame}
+     *
+     * @internal
+     */
+    private releaseGraph;
     /**
      * Tag a frame for MJPEG encoding: full color range and a per-frame quality.
      *
@@ -397,7 +483,9 @@ export declare class Scaler implements Disposable {
      * For software frames this is `crop,scale,format`. For hardware frames the crop
      * filter sets crop metadata that the hardware scaler (scale_vt/scale_cuda/
      * scale_vaapi) applies on the GPU; the result is kept in NV12, downloaded, and
-     * converted on the CPU. When `commandable` the crop is a labeled instance
+     * converted on the CPU. Scalers with a same-size/same-format passthrough mode
+     * (scale_vaapi/scale_cuda/vpp_qsv) get `passthrough=0`, since skipping the scaler
+     * would drop the crop metadata unapplied. When `commandable` the crop is a labeled instance
      * (`crop@sc`) whose initial region is `crop` but which is re-aimed per frame via
      * `sendCommand`. Otherwise (OpenCL) the crop is fixed in the graph.
      *