node-av 3.1.2 → 4.0.0

package/dist/api/filter.d.ts

@@ -1,5 +1,9 @@
-import { Frame } from '../lib/index.js';
-import type { AVFilterCmdFlag } from '../constants/constants.js';
+import { Frame } from '../lib/frame.js';
+import { Scheduler } from './utilities/scheduler.js';
+import type { AVColorRange, AVColorSpace, AVFilterCmdFlag, AVPixelFormat, AVSampleFormat } from '../constants/index.js';
+import type { FilterContext } from '../lib/filter-context.js';
+import type { ChannelLayout, IDimension, IRational } from '../lib/types.js';
+import type { Encoder } from './encoder.js';
 import type { FilterOptions } from './types.js';
 /**
  * High-level filter API for audio and video processing.
@@ -44,8 +48,17 @@ export declare class FilterAPI implements Disposable {
     private options;
     private buffersrcCtx;
     private buffersinkCtx;
+    private frame;
+    private initializePromise;
     private initialized;
     private isClosed;
+    private calculatedTimeBase;
+    private lastFrameProps;
+    private inputQueue;
+    private outputQueue;
+    private workerPromise;
+    private nextComponent;
+    private pipeToPromise;
     /**
      * @param graph - Filter graph instance
      *
@@ -61,44 +74,46 @@ export declare class FilterAPI implements Disposable {
      *
      * Creates and allocates filter graph immediately.
      * Filter configuration is completed on first frame with frame properties.
+     * TimeBase is automatically calculated from first frame based on CFR option.
      * Hardware frames context is automatically detected from input frames.
      *
      * Direct mapping to avfilter_graph_parse_ptr() and avfilter_graph_config().
      *
      * @param description - Filter graph description
      *
-     * @param options - Filter options including required timeBase
+     * @param options - Filter options
      *
      * @returns Configured filter instance
      *
+     * @throws {Error} If cfr=true but framerate is not set
+     *
      * @example
      * ```typescript
-     * // Simple video filter
-     * const filter = FilterAPI.create('scale=640:480', {
-     *   timeBase: video.timeBase
-     * });
+     * // Simple video filter (VFR mode, auto timeBase)
+     * const filter = FilterAPI.create('scale=640:480');
      * ```
      *
      * @example
      * ```typescript
-     * // Complex filter chain
-     * const filter = FilterAPI.create('crop=640:480:0:0,rotate=PI/4', {
-     *   timeBase: video.timeBase
+     * // CFR mode with constant framerate
+     * const filter = FilterAPI.create('scale=1920:1080', {
+     *   cfr: true,
+     *   framerate: { num: 25, den: 1 }
      * });
      * ```
      *
      * @example
      * ```typescript
-     * // Audio filter
-     * const filter = FilterAPI.create('volume=0.5,aecho=0.8:0.9:1000:0.3', {
-     *   timeBase: audio.timeBase
+     * // Audio filter with resampling
+     * const filter = FilterAPI.create('aformat=sample_fmts=s16:sample_rates=44100', {
+     *   audioResampleOpts: 'async=1'
      * });
      * ```
      *
      * @see {@link process} For frame processing
      * @see {@link FilterOptions} For configuration options
      */
-    static create(description: string, options: FilterOptions): FilterAPI;
+    static create(description: string, options?: FilterOptions): FilterAPI;
     /**
      * Check if filter is open.
      *
@@ -126,6 +141,206 @@ export declare class FilterAPI implements Disposable {
      * ```
      */
     get isFilterInitialized(): boolean;
+    /**
+     * Get buffersink filter context.
+     *
+     * Provides access to the buffersink filter context for advanced operations.
+     * Returns null if filter is not initialized.
+     *
+     * @returns Buffersink context or null
+     *
+     * @example
+     * ```typescript
+     * const sink = filter.buffersink;
+     * if (sink) {
+     *   const fr = sink.buffersinkGetFrameRate();
+     *   console.log(`Output frame rate: ${fr.num}/${fr.den}`);
+     * }
+     * ```
+     */
+    get buffersink(): FilterContext | null;
+    /**
+     * Output frame rate from filter graph.
+     *
+     * Returns the frame rate determined by the filter graph output.
+     * Matches FFmpeg CLI's av_buffersink_get_frame_rate() behavior.
+     * Returns null if filter is not initialized or frame rate is not set.
+     *
+     * Direct mapping to av_buffersink_get_frame_rate().
+     *
+     * @returns Frame rate or null if not available
+     *
+     * @example
+     * ```typescript
+     * const frameRate = filter.frameRate;
+     * if (frameRate) {
+     *   console.log(`Filter output: ${frameRate.num}/${frameRate.den} fps`);
+     * }
+     * ```
+     *
+     * @see {@link timeBase} For output timebase
+     */
+    get frameRate(): IRational | null;
+    /**
+     * Output time base from filter graph.
+     *
+     * Returns the time base of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_time_base() behavior.
+     *
+     * Direct mapping to av_buffersink_get_time_base().
+     *
+     * @returns Time base or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const timeBase = filter.timeBase;
+     * if (timeBase) {
+     *   console.log(`Filter timebase: ${timeBase.num}/${timeBase.den}`);
+     * }
+     * ```
+     *
+     * @see {@link frameRate} For output frame rate
+     */
+    get timeBase(): IRational | null;
+    /**
+     * Output format from filter graph.
+     *
+     * Returns the pixel format (video) or sample format (audio) of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_format() behavior.
+     *
+     * Direct mapping to av_buffersink_get_format().
+     *
+     * @returns Pixel format or sample format, or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const format = filter.format;
+     * if (format !== null) {
+     *   console.log(`Filter output format: ${format}`);
+     * }
+     * ```
+     */
+    get format(): AVPixelFormat | AVSampleFormat | null;
+    /**
+     * Output dimensions from filter graph (video only).
+     *
+     * Returns the width and height of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_w() and av_buffersink_get_h() behavior.
+     * Only meaningful for video filters.
+     *
+     * Direct mapping to av_buffersink_get_w() and av_buffersink_get_h().
+     *
+     * @returns Dimensions object or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const dims = filter.dimensions;
+     * if (dims) {
+     *   console.log(`Filter output: ${dims.width}x${dims.height}`);
+     * }
+     * ```
+     */
+    get dimensions(): IDimension | null;
+    /**
+     * Output sample rate from filter graph (audio only).
+     *
+     * Returns the sample rate of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_sample_rate() behavior.
+     * Only meaningful for audio filters.
+     *
+     * Direct mapping to av_buffersink_get_sample_rate().
+     *
+     * @returns Sample rate or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const sampleRate = filter.sampleRate;
+     * if (sampleRate) {
+     *   console.log(`Filter output sample rate: ${sampleRate} Hz`);
+     * }
+     * ```
+     */
+    get sampleRate(): number | null;
+    /**
+     * Output channel layout from filter graph (audio only).
+     *
+     * Returns the channel layout of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_ch_layout() behavior.
+     * Only meaningful for audio filters.
+     *
+     * Direct mapping to av_buffersink_get_ch_layout().
+     *
+     * @returns Channel layout or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const layout = filter.channelLayout;
+     * if (layout) {
+     *   console.log(`Filter output channels: ${layout.nbChannels}`);
+     * }
+     * ```
+     */
+    get channelLayout(): ChannelLayout | null;
+    /**
+     * Output color space from filter graph (video only).
+     *
+     * Returns the color space of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_colorspace() behavior.
+     * Only meaningful for video filters.
+     *
+     * Direct mapping to av_buffersink_get_colorspace().
+     *
+     * @returns Color space or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const colorSpace = filter.colorSpace;
+     * if (colorSpace !== null) {
+     *   console.log(`Filter output color space: ${colorSpace}`);
+     * }
+     * ```
+     */
+    get colorSpace(): AVColorSpace | null;
+    /**
+     * Output color range from filter graph (video only).
+     *
+     * Returns the color range of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_color_range() behavior.
+     * Only meaningful for video filters.
+     *
+     * Direct mapping to av_buffersink_get_color_range().
+     *
+     * @returns Color range or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const colorRange = filter.colorRange;
+     * if (colorRange !== null) {
+     *   console.log(`Filter output color range: ${colorRange}`);
+     * }
+     * ```
+     */
+    get colorRange(): AVColorRange | null;
+    /**
+     * Output sample aspect ratio from filter graph (video only).
+     *
+     * Returns the sample aspect ratio of the buffersink output.
+     * Matches FFmpeg CLI's av_buffersink_get_sample_aspect_ratio() behavior.
+     * Only meaningful for video filters.
+     *
+     * Direct mapping to av_buffersink_get_sample_aspect_ratio().
+     *
+     * @returns Sample aspect ratio or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const sar = filter.sampleAspectRatio;
+     * if (sar) {
+     *   console.log(`Filter output SAR: ${sar.num}:${sar.den}`);
+     * }
+     * ```
+     */
+    get sampleAspectRatio(): IRational | null;
     /**
      * Check if filter is ready for processing.
      *
@@ -165,6 +380,10 @@ export declare class FilterAPI implements Disposable {
      * Hardware frames context is automatically detected from frame.
      * Returns null if filter is closed and frame is null.
      *
+     * **Note**: This method receives only ONE frame per call.
+     * A single input frame can produce multiple output frames (e.g., fps filter, deinterlace).
+     * To receive all frames from an input, use {@link processAll} or {@link frames} instead.
+     *
      * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
      * @param frame - Input frame to process (or null to flush)
@@ -195,8 +414,10 @@ export declare class FilterAPI implements Disposable {
      * // For buffered frames, use the frames() async generator
      * ```
      *
+     * @see {@link processAll} For processing multiple output frames
      * @see {@link frames} For processing frame streams
      * @see {@link flush} For end-of-stream handling
+     * @see {@link processSync} For synchronous version
      */
     process(frame: Frame | null): Promise<Frame | null>;
     /**
@@ -209,6 +430,10 @@ export declare class FilterAPI implements Disposable {
      * Hardware frames context is automatically detected from frame.
      * Returns null if filter is closed and frame is null.
      *
+     * **Note**: This method receives only ONE frame per call.
+     * A single input frame can produce multiple output frames (e.g., fps filter, deinterlace).
+     * To receive all frames from an input, use {@link processAllSync} or {@link framesSync} instead.
+     *
      * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
      * @param frame - Input frame to process (or null to flush)
@@ -239,62 +464,99 @@ export declare class FilterAPI implements Disposable {
      * // For buffered frames, use the framesSync() generator
      * ```
      *
+     * @see {@link processAllSync} For processing multiple output frames
+     * @see {@link framesSync} For processing frame streams
+     * @see {@link flushSync} For end-of-stream handling
      * @see {@link process} For async version
      */
     processSync(frame: Frame | null): Frame | null;
     /**
-     * Process multiple frames at once.
+     * Process a frame through the filter.
      *
-     * Processes batch of frames and drains all output.
-     * Useful for filters that buffer multiple frames.
+     * Applies filter operations to input frame and receives all available output frames.
+     * Returns array of frames - may be empty if filter needs more input.
+     * On first frame, automatically builds filter graph with frame properties.
+     * One input frame can produce zero, one, or multiple output frames depending on filter.
+     * Hardware frames context is automatically detected from frame.
      *
-     * @param frames - Array of input frames
+     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @returns Array of all output frames (empty if filter closed)
+     * @param frame - Input frame to process (or null to flush)
      *
-     * @throws {Error} If filter not ready
+     * @returns Array of filtered frames (empty if buffered or filter closed)
+     *
+     * @throws {Error} If filter could not be initialized
      *
      * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * const outputs = await filter.processMultiple([frame1, frame2, frame3]);
-     * for (const output of outputs) {
-     *   console.log(`Output frame: pts=${output.pts}`);
+     * const frames = await filter.processAll(inputFrame);
+     * for (const output of frames) {
+     *   console.log(`Got filtered frame: pts=${output.pts}`);
      *   output.free();
      * }
      * ```
      *
+     * @example
+     * ```typescript
+     * // Process frame - may return multiple frames (e.g. fps filter)
+     * const frames = await filter.processAll(frame);
+     * for (const output of frames) {
+     *   yield output;
+     * }
+     * ```
+     *
      * @see {@link process} For single frame processing
+     * @see {@link frames} For processing frame streams
+     * @see {@link flush} For end-of-stream handling
+     * @see {@link processAllSync} For synchronous version
      */
-    processMultiple(frames: Frame[]): Promise<Frame[]>;
+    processAll(frame: Frame | null): Promise<Frame[]>;
     /**
-     * Process multiple frames at once synchronously.
-     * Synchronous version of processMultiple.
+     * Process a frame through the filter synchronously.
+     * Synchronous version of processAll.
+     *
+     * Applies filter operations to input frame and receives all available output frames.
+     * Returns array of frames - may be empty if filter needs more input.
+     * On first frame, automatically builds filter graph with frame properties.
+     * One input frame can produce zero, one, or multiple output frames depending on filter.
+     * Hardware frames context is automatically detected from frame.
      *
-     * Processes batch of frames and drains all output.
-     * Useful for filters that buffer multiple frames.
+     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @param frames - Array of input frames
+     * @param frame - Input frame to process (or null to flush)
      *
-     * @returns Array of all output frames (empty if filter closed)
+     * @returns Array of filtered frames (empty if buffered or filter closed)
      *
-     * @throws {Error} If filter not ready
+     * @throws {Error} If filter could not be initialized
      *
      * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * const outputs = filter.processMultipleSync([frame1, frame2, frame3]);
+     * const outputs = filter.processAllSync(inputFrame);
      * for (const output of outputs) {
-     *   console.log(`Output frame: pts=${output.pts}`);
+     *   console.log(`Got filtered frame: pts=${output.pts}`);
      *   output.free();
      * }
      * ```
      *
-     * @see {@link processMultiple} For async version
+     * @example
+     * ```typescript
+     * // Process frame - may return multiple frames (e.g. fps filter)
+     * const outputs = filter.processAllSync(frame);
+     * for (const output of outputs) {
+     *   yield output;
+     * }
+     * ```
+     *
+     * @see {@link processSync} For single frame processing
+     * @see {@link framesSync} For processing frame streams
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link process} For async version
      */
-    processMultipleSync(frames: Frame[]): Frame[];
+    processAllSync(frame: Frame | null): Frame[];
     /**
      * Process frame stream through filter.
      *
@@ -336,9 +598,10 @@ export declare class FilterAPI implements Disposable {
      * ```
      *
      * @see {@link process} For single frame processing
-     * @see {@link flush} For end-of-stream handling
+     * @see {@link Decoder.frames} For frames source
+     * @see {@link framesSync} For sync version
      */
-    frames(frames: AsyncGenerator<Frame>): AsyncGenerator<Frame>;
+    frames(frames: AsyncIterable<Frame | null>): AsyncGenerator<Frame | null>;
     /**
      * Process frame stream through filter synchronously.
      * Synchronous version of frames.
@@ -380,9 +643,11 @@ export declare class FilterAPI implements Disposable {
      * }
      * ```
      *
+     * @see {@link processSync} For single frame processing
+     * @see {@link Decoder.framesSync} For frames source
      * @see {@link frames} For async version
      */
-    framesSync(frames: Generator<Frame>): Generator<Frame>;
+    framesSync(frames: Generator<Frame | null>): Generator<Frame | null>;
     /**
      * Flush filter and signal end-of-stream.
      *
@@ -405,7 +670,8 @@ export declare class FilterAPI implements Disposable {
      * ```
      *
      * @see {@link flushFrames} For async iteration
-     * @see {@link frames} For complete pipeline
+     * @see {@link receive} For getting flushed frames
+     * @see {@link flushSync} For synchronous version
      */
     flush(): Promise<void>;
     /**
@@ -430,6 +696,8 @@ export declare class FilterAPI implements Disposable {
      * }
      * ```
      *
+     * @see {@link flushFramesSync} For sync iteration
+     * @see {@link receiveSync} For getting flushed frames
      * @see {@link flush} For async version
      */
     flushSync(): void;
@@ -452,8 +720,9 @@ export declare class FilterAPI implements Disposable {
      * }
      * ```
      *
+     * @see {@link process} For frame processing
      * @see {@link flush} For manual flush
-     * @see {@link frames} For complete pipeline
+     * @see {@link flushFramesSync} For sync version
      */
     flushFrames(): AsyncGenerator<Frame>;
     /**
@@ -476,6 +745,8 @@ export declare class FilterAPI implements Disposable {
      * }
      * ```
      *
+     * @see {@link processSync} For frame processing
+     * @see {@link flushSync} For manual flush
      * @see {@link flushFrames} For async version
      */
     flushFramesSync(): Generator<Frame>;
@@ -500,6 +771,10 @@ export declare class FilterAPI implements Disposable {
      *   frame.free();
      * }
      * ```
+     *
+     * @see {@link process} For frame processing
+     * @see {@link flush} For flushing filter
+     * @see {@link receiveSync} For synchronous version
      */
     receive(): Promise<Frame | null>;
     /**
@@ -525,6 +800,8 @@ export declare class FilterAPI implements Disposable {
      * }
      * ```
      *
+     * @see {@link processSync} For frame processing
+     * @see {@link flushSync} For flushing filter
      * @see {@link receive} For async version
      */
     receiveSync(): Frame | null;
@@ -591,6 +868,20 @@ export declare class FilterAPI implements Disposable {
      * @see {@link sendCommand} For immediate commands
      */
     queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): void;
+    /**
+     * Pipe decoded frames to a filter component or encoder.
+     *
+     * @param target - Filter to receive frames or encoder to encode frames
+     *
+     * @returns Scheduler for continued chaining
+     *
+     * @example
+     * ```typescript
+     * decoder.pipeTo(filter).pipeTo(encoder)
+     * ```
+     */
+    pipeTo(target: FilterAPI): Scheduler<Frame>;
+    pipeTo(target: Encoder): Scheduler<Frame>;
     /**
      * Free filter resources.
      *
@@ -605,6 +896,36 @@ export declare class FilterAPI implements Disposable {
      * @see {@link Symbol.dispose} For automatic cleanup
      */
     close(): void;
+    /**
+     * Worker loop for push-based processing.
+     *
+     * @internal
+     */
+    private runWorker;
+    /**
+     * Send frame to input queue.
+     *
+     * @param frame - Frame to send
+     *
+     * @internal
+     */
+    private sendToQueue;
+    /**
+     * Receive frame from output queue.
+     *
+     * @returns Frame from output queue or null if closed
+     *
+     * @internal
+     */
+    private receiveFrame;
+    /**
+     * Flush the entire filter pipeline.
+     *
+     * Propagates flush through worker, output queue, and next component.
+     *
+     * @internal
+     */
+    private flushPipeline;
     /**
      * Initialize filter graph from first frame.
      *
@@ -640,6 +961,51 @@ export declare class FilterAPI implements Disposable {
      * @see {@link initialize} For async version
      */
     private initializeSync;
+    /**
+     * Check if frame properties changed and handle according to dropOnChange/allowReinit options.
+     *
+     * Implements FFmpeg's IFILTER_FLAG_DROPCHANGED and IFILTER_FLAG_REINIT logic
+     *
+     * @param frame - Frame to check
+     *
+     * @returns true if frame should be processed, false if frame should be dropped
+     *
+     * @throws {Error} If format changed and allowReinit is false
+     *
+     * @internal
+     */
+    private checkFramePropertiesChanged;
+    /**
+     * Calculate timeBase from frame based on media type and CFR option.
+     *
+     * Implements FFmpeg's ifilter_parameters_from_frame logic:
+     * - Audio: Always { 1, sample_rate }
+     * - Video CFR: 1/framerate (inverse of framerate)
+     * - Video VFR: Use frame.timeBase
+     *
+     * @param frame - Input frame
+     *
+     * @returns Calculated timeBase
+     *
+     * @internal
+     */
+    private calculateTimeBase;
+    /**
+     * Post-process output frame from buffersink.
+     *
+     * Applies FFmpeg's fg_output_step() behavior:
+     * 1. Sets frame.timeBase from buffersink (filters can change timeBase, e.g., aresample)
+     * 2. Calculates video frame duration from frame rate if not set
+     *
+     * This must be called AFTER buffersinkGetFrame() for every output frame.
+     *
+     * @param frame - Output frame from buffersink
+     *
+     * @throws {Error} If buffersink context not available
+     *
+     * @internal
+     */
+    private postProcessOutputFrame;
     /**
      * Create buffer source with frame parameters.
      *