node-av 1.3.0 → 2.1.0

package/dist/api/filter.d.ts

@@ -1,6 +1,6 @@
 import { Frame } from '../lib/index.js';
-import type { AVFilterCmdFlag, AVMediaType } from '../constants/constants.js';
-import type { FilterOptions, StreamInfo } from './types.js';
+import type { AVFilterCmdFlag } from '../constants/constants.js';
+import type { FilterOptions } from './types.js';
 /**
  * High-level filter API for audio and video processing.
  *
@@ -13,10 +13,12 @@ import type { FilterOptions, StreamInfo } from './types.js';
  * ```typescript
  * import { FilterAPI } from 'node-av/api';
  *
- * // Create video filter
- * const filter = await FilterAPI.create('scale=1280:720', videoInfo);
+ * // Create video filter - initializes on first frame
+ * const filter = await FilterAPI.create('scale=1280:720', {
+ *   timeBase: video.timeBase,
+ * });
  *
- * // Process frame
+ * // Process frame - first frame configures filter graph
  * const output = await filter.process(inputFrame);
  * if (output) {
  *   console.log(`Filtered frame: ${output.width}x${output.height}`);
@@ -26,48 +28,47 @@ import type { FilterOptions, StreamInfo } from './types.js';
  *
  * @example
  * ```typescript
- * // Hardware-accelerated filtering
- * const hw = HardwareContext.auto();
- * const filter = await FilterAPI.create(
- *   'hwupload,scale_cuda=1920:1080,hwdownload',
- *   videoInfo,
- *   { hardware: hw }
- * );
+ * // Hardware-accelerated filtering - hw context detected from frame
+ * const filter = await FilterAPI.create('hwupload,scale_cuda=1920:1080,hwdownload', {
+ *   timeBase: video.timeBase,
+ * });
+ * // Hardware frames context will be automatically detected from first frame
  * ```
  *
  * @see {@link FilterGraph} For low-level filter graph API
- * @see {@link HardwareContext} For hardware acceleration
  * @see {@link Frame} For frame operations
  */
 export declare class FilterAPI implements Disposable {
     private graph;
+    private description;
+    private options;
     private buffersrcCtx;
     private buffersinkCtx;
-    private config;
-    private mediaType;
     private initialized;
-    private hardware?;
-    private description;
-    private options;
+    private isClosed;
     /**
-     * @param config - Stream configuration
+     * @param graph - Filter graph instance
+     *
      * @param description - Filter description string
+     *
      * @param options - Filter options
+     *
      * @internal
      */
     private constructor();
     /**
      * Create a filter with specified description and configuration.
      *
-     * Constructs filter graph from description string.
-     * Configures input/output buffers and threading.
-     * For video filters, uses lazy initialization to detect hardware frames.
+     * Creates and allocates filter graph immediately.
+     * Filter configuration is completed on first frame with frame properties.
+     * 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 input - Input stream configuration
-     * @param options - Filter options
+     *
+     * @param options - Filter options including required timeBase
+     *
      * @returns Configured filter instance
      *
      * @throws {Error} If filter creation or configuration fails
@@ -77,44 +78,104 @@ export declare class FilterAPI implements Disposable {
      * @example
      * ```typescript
      * // Simple video filter
-     * const filter = await FilterAPI.create('scale=640:480', videoInfo);
+     * const filter = await FilterAPI.create('scale=640:480', {
+     *   timeBase: video.timeBase
+     * });
      * ```
      *
      * @example
      * ```typescript
      * // Complex filter chain
-     * const filter = await FilterAPI.create(
-     *   'crop=640:480:0:0,rotate=PI/4',
-     *   videoInfo
-     * );
+     * const filter = await FilterAPI.create('crop=640:480:0:0,rotate=PI/4', {
+     *   timeBase: video.timeBase
+     * });
      * ```
      *
      * @example
      * ```typescript
      * // Audio filter
-     * const filter = await FilterAPI.create(
-     *   'volume=0.5,aecho=0.8:0.9:1000:0.3',
-     *   audioInfo
-     * );
+     * const filter = await FilterAPI.create('volume=0.5,aecho=0.8:0.9:1000:0.3', {
+     *   timeBase: audio.timeBase
+     * });
      * ```
      *
      * @see {@link process} For frame processing
      * @see {@link FilterOptions} For configuration options
      */
-    static create(description: string, input: StreamInfo, options?: FilterOptions): Promise<FilterAPI>;
+    static create(description: string, options: FilterOptions): Promise<FilterAPI>;
+    /**
+     * Check if filter is open.
+     *
+     * @example
+     * ```typescript
+     * if (filter.isFilterOpen) {
+     *   const output = await filter.process(frame);
+     * }
+     * ```
+     */
+    get isFilterOpen(): boolean;
+    /**
+     * Check if filter has been initialized.
+     *
+     * Returns true after first frame has been processed and filter graph configured.
+     * Useful for checking if filter has received frame properties.
+     *
+     * @returns true if filter graph has been built from first frame
+     *
+     * @example
+     * ```typescript
+     * if (!filter.isFilterInitialized) {
+     *   console.log('Filter will initialize on first frame');
+     * }
+     * ```
+     */
+    get isFilterInitialized(): boolean;
+    /**
+     * Check if filter is ready for processing.
+     *
+     * @returns true if initialized and ready
+     *
+     * @example
+     * ```typescript
+     * if (filter.isReady()) {
+     *   const output = await filter.process(frame);
+     * }
+     * ```
+     */
+    isReady(): boolean;
+    /**
+     * Get filter graph description.
+     *
+     * Returns human-readable graph structure.
+     * Useful for debugging filter chains.
+     *
+     * Direct mapping to avfilter_graph_dump().
+     *
+     * @returns Graph description or null if closed
+     *
+     * @example
+     * ```typescript
+     * const description = filter.getGraphDescription();
+     * console.log('Filter graph:', description);
+     * ```
+     */
+    getGraphDescription(): string | null;
     /**
      * Process a frame through the filter.
      *
      * Applies filter operations to input frame.
+     * On first frame, automatically builds filter graph with frame properties.
      * May buffer frames internally before producing output.
-     * For video, performs lazy initialization on first frame.
+     * Hardware frames context is automatically detected from frame.
+     * Returns null if filter is closed and frame is null.
      *
      * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @param frame - Input frame to process
+     * @param frame - Input frame to process (or null to flush)
+     *
      * @returns Filtered frame or null if buffered
      *
-     * @throws {Error} If filter not ready
+     * @throws {Error} If filter is closed with non-null frame
      *
      * @throws {FFmpegError} If processing fails
      *
@@ -129,21 +190,62 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Process and drain
+     * // Process frame - may buffer internally
      * const output = await filter.process(frame);
-     * if (output) yield output;
+     * if (output) {
+     *   // Got output immediately
+     *   yield output;
+     * }
+     * // For buffered frames, use the frames() async generator
+     * ```
+     *
+     * @see {@link frames} For processing frame streams
+     * @see {@link flush} For end-of-stream handling
+     */
+    process(frame: Frame | null): Promise<Frame | null>;
+    /**
+     * Process a frame through the filter synchronously.
+     * Synchronous version of process.
+     *
+     * Applies filter operations to input frame.
+     * On first frame, automatically builds filter graph with frame properties.
+     * May buffer frames internally before producing output.
+     * Hardware frames context is automatically detected from frame.
+     * Returns null if filter is closed and frame is null.
+     *
+     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
+     *
+     * @param frame - Input frame to process (or null to flush)
+     *
+     * @returns Filtered frame or null if buffered
+     *
+     * @throws {Error} If filter is closed with non-null frame
+     *
+     * @throws {FFmpegError} If processing fails
      *
-     * // Drain buffered frames
-     * let buffered;
-     * while ((buffered = await filter.receive()) !== null) {
-     *   yield buffered;
+     * @example
+     * ```typescript
+     * const output = filter.processSync(inputFrame);
+     * if (output) {
+     *   console.log(`Got filtered frame: pts=${output.pts}`);
+     *   output.free();
      * }
      * ```
      *
-     * @see {@link receive} For draining buffered frames
-     * @see {@link frames} For stream processing
+     * @example
+     * ```typescript
+     * // Process frame - may buffer internally
+     * const output = filter.processSync(frame);
+     * if (output) {
+     *   // Got output immediately
+     *   yield output;
+     * }
+     * // For buffered frames, use the framesSync() generator
+     * ```
+     *
+     * @see {@link process} For async version
      */
-    process(frame: Frame): Promise<Frame | null>;
+    processSync(frame: Frame | null): Frame | null;
     /**
      * Process multiple frames at once.
      *
@@ -151,6 +253,7 @@ export declare class FilterAPI implements Disposable {
      * Useful for filters that buffer multiple frames.
      *
      * @param frames - Array of input frames
+     *
      * @returns Array of all output frames
      *
      * @throws {Error} If filter not ready
@@ -170,43 +273,129 @@ export declare class FilterAPI implements Disposable {
      */
     processMultiple(frames: Frame[]): Promise<Frame[]>;
     /**
-     * Receive buffered frame from filter.
+     * Process multiple frames at once synchronously.
+     * Synchronous version of processMultiple.
      *
-     * Drains frames buffered by the filter.
-     * Call repeatedly until null to get all buffered frames.
+     * Processes batch of frames and drains all output.
+     * Useful for filters that buffer multiple frames.
      *
-     * Direct mapping to av_buffersink_get_frame().
+     * @param frames - Array of input frames
      *
-     * @returns Buffered frame or null if none available
+     * @returns Array of all output frames
      *
      * @throws {Error} If filter not ready
      *
-     * @throws {FFmpegError} If receive fails
+     * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * // Drain buffered frames
-     * let frame;
-     * while ((frame = await filter.receive()) !== null) {
-     *   console.log(`Buffered frame: pts=${frame.pts}`);
+     * const outputs = filter.processMultipleSync([frame1, frame2, frame3]);
+     * for (const output of outputs) {
+     *   console.log(`Output frame: pts=${output.pts}`);
+     *   output.free();
+     * }
+     * ```
+     *
+     * @see {@link processMultiple} For async version
+     */
+    processMultipleSync(frames: Frame[]): Frame[];
+    /**
+     * Process frame stream through filter.
+     *
+     * High-level async generator for filtering frame streams.
+     * Automatically handles buffering and flushing.
+     * Frees input frames after processing.
+     *
+     * @param frames - Async generator of input frames
+     *
+     * @yields {Frame} Filtered frames
+     *
+     * @throws {Error} If filter not ready
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * // Filter decoded frames
+     * for await (const frame of filter.frames(decoder.frames(packets))) {
+     *   await encoder.encode(frame);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link process} For input processing
-     * @see {@link flush} For end-of-stream
+     * @example
+     * ```typescript
+     * // Chain filters
+     * const filter1 = await FilterAPI.create('scale=640:480', {
+     *   timeBase: video.timeBase
+     * });
+     * const filter2 = await FilterAPI.create('rotate=PI/4', {
+     *   timeBase: video.timeBase
+     * });
+     *
+     * for await (const frame of filter2.frames(filter1.frames(input))) {
+     *   // Process filtered frames
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link process} For single frame processing
+     * @see {@link flush} For end-of-stream handling
      */
-    receive(): Promise<Frame | null>;
+    frames(frames: AsyncGenerator<Frame>): AsyncGenerator<Frame>;
+    /**
+     * Process frame stream through filter synchronously.
+     * Synchronous version of frames.
+     *
+     * High-level sync generator for filtering frame streams.
+     * Automatically handles buffering and flushing.
+     * Frees input frames after processing.
+     *
+     * @param frames - Generator of input frames
+     *
+     * @yields {Frame} Filtered frames
+     *
+     * @throws {Error} If filter not ready
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * // Filter decoded frames
+     * for (const frame of filter.framesSync(decoder.framesSync(packets))) {
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chain filters
+     * const filter1 = await FilterAPI.create('scale=640:480', {
+     *   timeBase: video.timeBase
+     * });
+     * const filter2 = await FilterAPI.create('rotate=PI/4', {
+     *   timeBase: video.timeBase
+     * });
+     *
+     * for (const frame of filter2.framesSync(filter1.framesSync(input))) {
+     *   // Process filtered frames
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link frames} For async version
+     */
+    framesSync(frames: Generator<Frame>): Generator<Frame>;
     /**
      * Flush filter and signal end-of-stream.
      *
      * Sends null frame to flush buffered data.
      * Must call receive() to get flushed frames.
+     * Does nothing if filter is closed or was never initialized.
      *
      * Direct mapping to av_buffersrc_add_frame(NULL).
      *
-     * @throws {Error} If filter not ready
-     *
      * @throws {FFmpegError} If flush fails
      *
      * @example
@@ -220,17 +409,42 @@ export declare class FilterAPI implements Disposable {
      * ```
      *
      * @see {@link flushFrames} For async iteration
-     * @see {@link receive} For draining frames
+     * @see {@link frames} For complete pipeline
      */
     flush(): Promise<void>;
+    /**
+     * Flush filter and signal end-of-stream synchronously.
+     * Synchronous version of flush.
+     *
+     * Sends null frame to flush buffered data.
+     * Must call receiveSync() to get flushed frames.
+     * Does nothing if filter is closed or was never initialized.
+     *
+     * Direct mapping to av_buffersrc_add_frame(NULL).
+     *
+     * @throws {FFmpegError} If flush fails
+     *
+     * @example
+     * ```typescript
+     * filter.flushSync();
+     * // Get remaining frames
+     * let frame;
+     * while ((frame = filter.receiveSync()) !== null) {
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link flush} For async version
+     */
+    flushSync(): void;
     /**
      * Flush filter and yield remaining frames.
      *
      * Convenient async generator for flushing.
      * Combines flush and receive operations.
+     * Returns immediately if filter is closed or was never initialized.
      *
-     * @yields Remaining frames from filter
-     * @throws {Error} If filter not ready
+     * @yields {Frame} Remaining frames from filter
      *
      * @throws {FFmpegError} If flush fails
      *
@@ -247,43 +461,77 @@ export declare class FilterAPI implements Disposable {
      */
     flushFrames(): AsyncGenerator<Frame>;
     /**
-     * Process frame stream through filter.
+     * Flush filter and yield remaining frames synchronously.
+     * Synchronous version of flushFrames.
      *
-     * High-level async generator for filtering frame streams.
-     * Automatically handles buffering and flushing.
-     * Frees input frames after processing.
+     * Convenient sync generator for flushing.
+     * Combines flush and receive operations.
+     * Returns immediately if filter is closed or was never initialized.
      *
-     * @param frames - Async generator of input frames
-     * @yields Filtered frames
-     * @throws {Error} If filter not ready
+     * @yields {Frame} Remaining frames from filter
      *
-     * @throws {FFmpegError} If processing fails
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * // Filter decoded frames
-     * for await (const frame of filter.frames(decoder.frames(packets))) {
-     *   await encoder.encode(frame);
+     * for (const frame of filter.flushFramesSync()) {
+     *   console.log(`Flushed frame: pts=${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
+     * @see {@link flushFrames} For async version
+     */
+    flushFramesSync(): Generator<Frame>;
+    /**
+     * Receive buffered frame from filter.
+     *
+     * Drains frames buffered by the filter.
+     * Call repeatedly until null to get all buffered frames.
+     * Returns null if filter is closed, not initialized, or no frames available.
+     *
+     * Direct mapping to av_buffersink_get_frame().
+     *
+     * @returns Buffered frame or null if none available
+     *
+     * @throws {FFmpegError} If receiving fails
+     *
      * @example
      * ```typescript
-     * // Chain filters
-     * const filter1 = await FilterAPI.create('scale=640:480', info);
-     * const filter2 = await FilterAPI.create('rotate=PI/4', info);
+     * let frame;
+     * while ((frame = await filter.receive()) !== null) {
+     *   console.log(`Received frame: pts=${frame.pts}`);
+     *   frame.free();
+     * }
+     * ```
+     */
+    receive(): Promise<Frame | null>;
+    /**
+     * Receive buffered frame from filter synchronously.
+     * Synchronous version of receive.
      *
-     * for await (const frame of filter2.frames(filter1.frames(input))) {
-     *   // Process filtered frames
+     * Drains frames buffered by the filter.
+     * Call repeatedly until null to get all buffered frames.
+     * Returns null if filter is closed, not initialized, or no frames available.
+     *
+     * Direct mapping to av_buffersink_get_frame().
+     *
+     * @returns Buffered frame or null if none available
+     *
+     * @throws {FFmpegError} If receiving fails
+     *
+     * @example
+     * ```typescript
+     * let frame;
+     * while ((frame = filter.receiveSync()) !== null) {
+     *   console.log(`Received frame: pts=${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link process} For single frame processing
-     * @see {@link flush} For end-of-stream handling
+     * @see {@link receive} For async version
      */
-    frames(frames: AsyncGenerator<Frame>): AsyncGenerator<Frame>;
+    receiveSync(): Frame | null;
     /**
      * Send command to filter.
      *
@@ -293,9 +541,13 @@ export declare class FilterAPI implements Disposable {
      * Direct mapping to avfilter_graph_send_command().
      *
      * @param target - Target filter name
+     *
      * @param cmd - Command name
+     *
      * @param arg - Command argument
+     *
      * @param flags - Command flags
+     *
      * @returns Response string from filter
      *
      * @throws {Error} If filter not ready
@@ -321,10 +573,15 @@ export declare class FilterAPI implements Disposable {
      * Direct mapping to avfilter_graph_queue_command().
      *
      * @param target - Target filter name
+     *
      * @param cmd - Command name
+     *
      * @param arg - Command argument
+     *
      * @param ts - Timestamp for execution
+     *
      * @param flags - Command flags
+     *
      * @throws {Error} If filter not ready
      *
      * @throws {FFmpegError} If queue fails
@@ -338,49 +595,6 @@ export declare class FilterAPI implements Disposable {
      * @see {@link sendCommand} For immediate commands
      */
     queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): void;
-    /**
-     * Get filter graph description.
-     *
-     * Returns human-readable graph structure.
-     * Useful for debugging filter chains.
-     *
-     * Direct mapping to avfilter_graph_dump().
-     *
-     * @returns Graph description or null if not initialized
-     *
-     * @example
-     * ```typescript
-     * const description = filter.getGraphDescription();
-     * console.log('Filter graph:', description);
-     * ```
-     */
-    getGraphDescription(): string | null;
-    /**
-     * Check if filter is ready for processing.
-     *
-     * @returns true if initialized and ready
-     *
-     * @example
-     * ```typescript
-     * if (filter.isReady()) {
-     *   const output = await filter.process(frame);
-     * }
-     * ```
-     */
-    isReady(): boolean;
-    /**
-     * Get media type of filter.
-     *
-     * @returns AVMEDIA_TYPE_VIDEO or AVMEDIA_TYPE_AUDIO
-     *
-     * @example
-     * ```typescript
-     * if (filter.getMediaType() === AVMEDIA_TYPE_VIDEO) {
-     *   console.log('Video filter');
-     * }
-     * ```
-     */
-    getMediaType(): AVMediaType;
     /**
      * Free filter resources.
      *
@@ -389,19 +603,20 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * filter.free();
+     * filter.close();
      * ```
      *
      * @see {@link Symbol.dispose} For automatic cleanup
      */
-    free(): void;
+    close(): void;
     /**
-     * Initialize filter graph.
+     * Initialize filter graph from first frame.
      *
      * Creates and configures filter graph components.
-     * For video, may use hardware frames context from first frame.
+     * Sets buffer source parameters from frame properties.
+     * Automatically configures hardware frames context if present.
      *
-     * @param firstFrame - First frame for hardware detection (video only)
+     * @param frame - First frame to process, provides format and hw context
      *
      * @throws {Error} If initialization fails
      *
@@ -411,28 +626,44 @@ export declare class FilterAPI implements Disposable {
      */
     private initialize;
     /**
-     * Create buffer source with hardware frames context.
+     * Initialize filter graph from first frame synchronously.
+     * Synchronous version of initialize.
      *
-     * @param frame - Frame with hw_frames_ctx
+     * Creates and configures filter graph components.
+     * Sets buffer source parameters from frame properties.
+     * Automatically configures hardware frames context if present.
      *
-     * @throws {Error} If creation fails
+     * @param frame - First frame to process, provides format and hw context
+     *
+     * @throws {Error} If initialization fails
      *
      * @throws {FFmpegError} If configuration fails
      *
      * @internal
+     *
+     * @see {@link initialize} For async version
      */
-    private createBufferSourceWithHwFrames;
+    private initializeSync;
     /**
-     * Create standard buffer source.
+     * Create buffer source with frame parameters.
+     *
+     * Configures buffer source with frame properties including hardware context.
+     * Automatically detects video/audio and sets appropriate parameters.
+     *
+     * @param frame - Frame providing format, dimensions, and hw_frames_ctx
      *
      * @throws {Error} If creation fails
      *
+     * @throws {FFmpegError} If configuration fails
+     *
      * @internal
      */
     private createBufferSource;
     /**
      * Create buffer sink.
      *
+     * @param frame - Frame
+     *
      * @throws {Error} If creation fails
      *
      * @internal
@@ -450,32 +681,21 @@ export declare class FilterAPI implements Disposable {
      * @internal
      */
     private parseFilterDescription;
-    /**
-     * Check hardware requirements for filters.
-     *
-     * @param description - Filter description
-     * @param options - Filter options
-     *
-     * @throws {Error} If hardware requirements not met
-     *
-     * @internal
-     */
-    private checkHardwareRequirements;
     /**
      * Dispose of filter.
      *
      * Implements Disposable interface for automatic cleanup.
-     * Equivalent to calling free().
+     * Equivalent to calling close().
      *
      * @example
      * ```typescript
      * {
-     *   using filter = await FilterAPI.create('scale=640:480', info);
+     *   using filter = await FilterAPI.create('scale=640:480', { ... });
      *   // Use filter...
      * } // Automatically freed
      * ```
      *
-     * @see {@link free} For manual cleanup
+     * @see {@link close} For manual cleanup
      */
     [Symbol.dispose](): void;
 }