node-av 1.0.3 → 1.2.0

package/dist/api/filter.d.ts

@@ -1,51 +1,43 @@
-import { Frame, Stream } from '../lib/index.js';
-import type { AVFilterCmdFlag, AVMediaType, AVPixelFormat, AVSampleFormat, HardwareFramesContext, IRational } from '../lib/index.js';
+import { Frame } from '../lib/index.js';
+import type { AVFilterCmdFlag, AVMediaType } from '../constants/constants.js';
 import type { FilterOptions, StreamInfo } from './types.js';
-interface VideoFilterConfig {
-    type: 'video';
-    width: number;
-    height: number;
-    pixelFormat: AVPixelFormat;
-    timeBase: IRational;
-    frameRate?: IRational;
-    sampleAspectRatio?: IRational;
-    hwFramesCtx?: HardwareFramesContext | null;
-}
-interface AudioFilterConfig {
-    type: 'audio';
-    sampleRate: number;
-    sampleFormat: AVSampleFormat;
-    channelLayout: bigint;
-    timeBase: IRational;
-}
-type FilterConfig = VideoFilterConfig | AudioFilterConfig;
 /**
- * High-level filter API for media processing.
+ * High-level filter API for audio and video processing.
  *
- * Provides a simplified interface for FFmpeg's filter system.
- * Supports both simple filter chains and complex filter graphs.
- * Handles automatic format negotiation and buffer management.
+ * Provides simplified interface for applying FFmpeg filters to frames.
+ * Handles filter graph construction, frame buffering, and command control.
+ * Supports both software and hardware-accelerated filtering operations.
+ * Essential component for effects, transformations, and format conversions.
  *
  * @example
  * ```typescript
- * import { FilterAPI, Frame } from 'node-av/api';
+ * import { FilterAPI } from 'node-av/api';
  *
- * // Create a simple video filter from a stream
- * const videoStream = media.video();
- * const filter = await FilterAPI.create('scale=1280:720,format=yuv420p', videoStream);
+ * // Create video filter
+ * const filter = await FilterAPI.create('scale=1280:720', videoInfo);
  *
- * // Process frames
- * const outputFrame = await filter.process(inputFrame);
+ * // Process frame
+ * const output = await filter.process(inputFrame);
+ * if (output) {
+ *   console.log(`Filtered frame: ${output.width}x${output.height}`);
+ *   output.free();
+ * }
  * ```
  *
  * @example
  * ```typescript
- * // Create filter with hardware acceleration
- * const hw = await HardwareContext.auto();
- * const filter = await FilterAPI.create('scale_vt=640:480', videoStream, {
- *   hardware: hw
- * });
+ * // Hardware-accelerated filtering
+ * const hw = HardwareContext.auto();
+ * const filter = await FilterAPI.create(
+ *   'hwupload,scale_cuda=1920:1080,hwdownload',
+ *   videoInfo,
+ *   { hardware: hw }
+ * );
  * ```
+ *
+ * @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;
@@ -54,404 +46,408 @@ export declare class FilterAPI implements Disposable {
     private config;
     private mediaType;
     private initialized;
-    private needsHardware;
     private hardware?;
-    private pendingInit?;
+    private description;
+    private options;
     /**
-     * Create a new Filter instance.
-     *
-     * The filter is uninitialized until setup with a filter description.
-     * Use the static factory methods for easier creation.
-     *
-     * @param config - Filter configuration
-     * @param hardware - Optional hardware context for late framesContext binding
+     * @param config - Stream configuration
+     * @param description - Filter description string
+     * @param options - Filter options
      * @internal
      */
     private constructor();
     /**
-     * Create a filter from a filter description string.
-     *
-     * Accepts either a Stream (from MediaInput/Decoder) or StreamInfo (for raw data).
-     * Automatically sets up buffer source and sink filters.
+     * Create a filter with specified description and configuration.
      *
-     * Handles complex filter chains with multiple filters. Automatically detects if ANY
-     * filter in the chain requires hardware acceleration (e.g., scale_vt in
-     * "format=nv12,hwupload,scale_vt=640:480").
+     * Constructs filter graph from description string.
+     * Configures input/output buffers and threading.
+     * For video filters, uses lazy initialization to detect hardware frames.
      *
-     * @param description - Filter graph description (e.g., "scale=1280:720" or complex chains)
-     * @param input - Stream or StreamInfo describing the input
-     * @param options - Optional filter options including hardware context
+     * Direct mapping to avfilter_graph_parse_ptr() and avfilter_graph_config().
      *
-     * @returns Promise resolving to configured Filter instance
+     * @param description - Filter graph description
+     * @param input - Input stream configuration
+     * @param options - Filter options
+     * @returns Configured filter instance
      *
-     * @throws {FFmpegError} If filter creation or configuration fails
+     * @throws {Error} If filter creation or configuration fails
+     * @throws {FFmpegError} If graph parsing or config fails
      *
      * @example
      * ```typescript
-     * // Simple filter
-     * const filter = await FilterAPI.create('scale=640:480', videoStream);
+     * // Simple video filter
+     * const filter = await FilterAPI.create('scale=640:480', videoInfo);
+     * ```
      *
-     * // Complex filter chain with hardware
-     * const hw = await HardwareContext.auto();
+     * @example
+     * ```typescript
+     * // Complex filter chain
      * const filter = await FilterAPI.create(
-     *   'format=nv12,hwupload,scale_vt=640:480,hwdownload,format=yuv420p',
-     *   videoStream,
-     *   { hardware: hw }
+     *   'crop=640:480:0:0,rotate=PI/4',
+     *   videoInfo
      * );
+     * ```
      *
-     * // From StreamInfo (for raw data)
-     * const filter = await FilterAPI.create('scale=640:480', {
-     *   type: 'video',
-     *   width: 1920,
-     *   height: 1080,
-     *   pixelFormat: AV_PIX_FMT_YUV420P,
-     *   timeBase: { num: 1, den: 30 }
-     * });
+     * @example
+     * ```typescript
+     * // Audio filter
+     * const filter = await FilterAPI.create(
+     *   'volume=0.5,aecho=0.8:0.9:1000:0.3',
+     *   audioInfo
+     * );
      * ```
+     *
+     * @see {@link process} For frame processing
+     * @see {@link FilterOptions} For configuration options
      */
-    static create(description: string, input: Stream | StreamInfo, options?: FilterOptions): Promise<FilterAPI>;
+    static create(description: string, input: StreamInfo, options?: FilterOptions): Promise<FilterAPI>;
     /**
-     * Process a single frame through the filter.
+     * Process a frame through the filter.
      *
-     * Sends a frame through the filter graph and returns the filtered result.
-     * May return null if the filter needs more input frames.
+     * Applies filter operations to input frame.
+     * May buffer frames internally before producing output.
+     * For video, performs lazy initialization on first frame.
      *
-     * @param frame - Input frame to filter
+     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @returns Promise resolving to filtered frame or null
+     * @param frame - Input frame to process
+     * @returns Filtered frame or null if buffered
      *
+     * @throws {Error} If filter not ready
      * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * const outputFrame = await filter.process(inputFrame);
-     * if (outputFrame) {
-     *   // Process the filtered frame
+     * const output = await filter.process(inputFrame);
+     * if (output) {
+     *   console.log(`Got filtered frame: pts=${output.pts}`);
+     *   output.free();
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Process and drain
+     * const output = await filter.process(frame);
+     * if (output) yield output;
+     *
+     * // Drain buffered frames
+     * let buffered;
+     * while ((buffered = await filter.receive()) !== null) {
+     *   yield buffered;
+     * }
+     * ```
+     *
+     * @see {@link receive} For draining buffered frames
+     * @see {@link frames} For stream processing
      */
     process(frame: Frame): Promise<Frame | null>;
     /**
-     * Process multiple frames through the filter.
+     * Process multiple frames at once.
      *
-     * Batch processing for better performance.
-     * Returns all available output frames.
+     * Processes batch of frames and drains all output.
+     * Useful for filters that buffer multiple frames.
      *
      * @param frames - Array of input frames
+     * @returns Array of all output frames
      *
-     * @returns Promise resolving to array of filtered frames
-     *
+     * @throws {Error} If filter not ready
      * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * const outputFrames = await filter.processMultiple(inputFrames);
+     * const outputs = await filter.processMultiple([frame1, frame2, frame3]);
+     * for (const output of outputs) {
+     *   console.log(`Output frame: pts=${output.pts}`);
+     *   output.free();
+     * }
      * ```
+     *
+     * @see {@link process} For single frame processing
      */
     processMultiple(frames: Frame[]): Promise<Frame[]>;
     /**
-     * Receive a filtered frame without sending input.
+     * Receive buffered frame from filter.
+     *
+     * Drains frames buffered by the filter.
+     * Call repeatedly until null to get all buffered frames.
      *
-     * Used to drain buffered frames from the filter.
-     * Returns null when no more frames are available.
+     * Direct mapping to av_buffersink_get_frame().
      *
-     * @returns Promise resolving to filtered frame or null
+     * @returns Buffered frame or null if none available
      *
-     * @throws {FFmpegError} If receiving fails
+     * @throws {Error} If filter not ready
+     * @throws {FFmpegError} If receive fails
      *
      * @example
      * ```typescript
-     * // Drain all buffered frames
-     * while (true) {
-     *   const frame = await filter.receive();
-     *   if (!frame) break;
-     *   // Process frame
+     * // Drain buffered frames
+     * let frame;
+     * while ((frame = await filter.receive()) !== null) {
+     *   console.log(`Buffered frame: pts=${frame.pts}`);
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link process} For input processing
+     * @see {@link flush} For end-of-stream
      */
     receive(): Promise<Frame | null>;
     /**
-     * Flush the filter by sending null frame.
+     * Flush filter and signal end-of-stream.
      *
-     * Signals end of stream to the filter.
-     * Use receive() to get any remaining frames.
+     * Sends null frame to flush buffered data.
+     * Must call receive() to get flushed frames.
      *
-     * @returns Promise resolving when flush is complete
+     * Direct mapping to av_buffersrc_add_frame(NULL).
      *
+     * @throws {Error} If filter not ready
      * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
      * await filter.flush();
      * // Get remaining frames
-     * while (true) {
-     *   const frame = await filter.receive();
-     *   if (!frame) break;
-     *   // Process final frames
+     * let frame;
+     * while ((frame = await filter.receive()) !== null) {
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link flushFrames} For async iteration
+     * @see {@link receive} For draining frames
      */
     flush(): Promise<void>;
     /**
-     * Flush filter and yield all remaining frames as a generator.
+     * Flush filter and yield remaining frames.
      *
-     * More convenient than calling flush() + receive() in a loop.
-     * Automatically sends flush signal and yields all buffered frames.
+     * Convenient async generator for flushing.
+     * Combines flush and receive operations.
      *
-     * @returns Async generator of remaining frames
-     *
-     * @throws {Error} If filter is not initialized
+     * @yields Remaining frames from filter
+     * @throws {Error} If filter not ready
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * // Process all remaining frames with generator
      * for await (const frame of filter.flushFrames()) {
-     *   // Process final frame
-     *   using _ = frame; // Auto cleanup
+     *   console.log(`Flushed frame: pts=${frame.pts}`);
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link flush} For manual flush
+     * @see {@link frames} For complete pipeline
      */
     flushFrames(): AsyncGenerator<Frame>;
     /**
-     * Process frames as an async generator.
-     *
-     * Provides a convenient iterator interface for filtering.
-     * Automatically handles buffering and draining.
-     * Input frames are automatically freed after processing.
-     *
-     * IMPORTANT: The yielded frames MUST be freed by the caller!
-     * Input frames are automatically freed after processing.
+     * Process frame stream through filter.
      *
-     * @param frames - Async generator of input frames (will be freed automatically)
+     * High-level async generator for filtering frame streams.
+     * Automatically handles buffering and flushing.
+     * Frees input frames after processing.
      *
-     * @returns Async generator of filtered frames (ownership transferred to caller)
+     * @param frames - Async generator of input frames
+     * @yields Filtered frames
+     * @throws {Error} If filter not ready
+     * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * for await (const filtered of filter.frames(decoder.frames())) {
-     *   // Process filtered frame
-     *   filtered.free(); // Must free output frame
+     * // Filter decoded frames
+     * for await (const frame of filter.frames(decoder.frames(packets))) {
+     *   await encoder.encode(frame);
+     *   frame.free();
      * }
      * ```
-     */
-    frames(frames: AsyncGenerator<Frame>): AsyncGenerator<Frame>;
-    /**
-     * Get the filter graph description.
-     *
-     * Returns a string representation of the filter graph in DOT format.
-     * Useful for debugging and visualization.
-     *
-     * @returns Graph description or null if not initialized
      *
      * @example
      * ```typescript
-     * const description = filter.getGraphDescription();
-     * console.log(description);
+     * // Chain filters
+     * const filter1 = await FilterAPI.create('scale=640:480', info);
+     * const filter2 = await FilterAPI.create('rotate=PI/4', info);
+     *
+     * for await (const frame of filter2.frames(filter1.frames(input))) {
+     *   // Process filtered frames
+     *   frame.free();
+     * }
      * ```
-     */
-    getGraphDescription(): string | null;
-    /**
-     * Check if the filter is initialized and ready.
      *
-     * @returns true if the filter is ready for processing
+     * @see {@link process} For single frame processing
+     * @see {@link flush} For end-of-stream handling
      */
-    isReady(): boolean;
+    frames(frames: AsyncGenerator<Frame>): AsyncGenerator<Frame>;
     /**
-     * Get the media type of this filter.
+     * Send command to filter.
      *
-     * @returns The media type (video or audio)
-     */
-    getMediaType(): AVMediaType;
-    /**
-     * Get the filter configuration.
+     * Sends runtime command to specific filter in graph.
+     * Allows dynamic parameter adjustment.
      *
-     * @returns The filter configuration used to create this instance
-     */
-    getConfig(): FilterConfig;
-    /**
-     * Free all filter resources.
+     * Direct mapping to avfilter_graph_send_command().
      *
-     * Releases the filter graph and all associated filters.
-     * The filter instance cannot be used after calling this.
+     * @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
+     * @throws {FFmpegError} If command fails
      *
      * @example
      * ```typescript
-     * filter.free();
-     * // filter is now invalid
+     * // Change volume at runtime
+     * const response = filter.sendCommand('volume', 'volume', '0.5');
+     * console.log(`Volume changed: ${response}`);
      * ```
+     *
+     * @see {@link queueCommand} For delayed commands
      */
-    free(): void;
+    sendCommand(target: string, cmd: string, arg: string, flags?: AVFilterCmdFlag): string;
     /**
-     * Initialize the filter graph.
+     * Queue command for later execution.
      *
-     * Sets up buffer source, buffer sink, and parses the filter description.
-     * Configures the graph for processing.
+     * Schedules command to execute at specific timestamp.
+     * Useful for synchronized parameter changes.
      *
-     * @internal
-     */
-    private initialize;
-    /**
-     * Create and configure the buffer source filter.
+     * Direct mapping to avfilter_graph_queue_command().
      *
-     * @internal
-     */
-    private createBufferSource;
-    /**
-     * Create and configure the buffer sink filter.
+     * @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
      *
-     * @internal
-     */
-    private createBufferSink;
-    /**
-     * Parse and connect the filter description.
+     * @example
+     * ```typescript
+     * // Queue volume change at 10 seconds
+     * filter.queueCommand('volume', 'volume', '0.8', 10.0);
+     * ```
      *
-     * @internal
+     * @see {@link sendCommand} For immediate commands
      */
-    private parseFilterDescription;
+    queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): void;
     /**
-     * Send a command to a filter in the graph.
-     *
-     * Allows runtime modification of filter parameters without recreating the graph.
-     * Not all filters support commands - check filter documentation.
+     * Get filter graph description.
      *
-     * @param target - Filter name or "all" to send to all filters
-     * @param cmd - Command name (e.g., "volume", "hue", "brightness")
-     * @param arg - Command argument value
-     * @param flags - Optional command flags
+     * Returns human-readable graph structure.
+     * Useful for debugging filter chains.
      *
-     * @returns Command response
+     * Direct mapping to avfilter_graph_dump().
      *
-     * @example
-     * ```typescript
-     * // Change volume dynamically
-     * const response = filter.sendCommand('volume', 'volume', '0.5');
-     * if (response) {
-     *   console.log('Volume changed successfully');
-     * }
-     * ```
+     * @returns Graph description or null if not initialized
      *
      * @example
      * ```typescript
-     * // Enable/disable all filters at runtime
-     * filter.sendCommand('all', 'enable', 'expr=gte(t,10)');
+     * const description = filter.getGraphDescription();
+     * console.log('Filter graph:', description);
      * ```
      */
-    sendCommand(target: string, cmd: string, arg: string, flags?: AVFilterCmdFlag): string;
+    getGraphDescription(): string | null;
     /**
-     * Queue a command to be executed at a specific time.
+     * Check if filter is ready for processing.
      *
-     * Commands are executed when processing frames with matching timestamps.
-     * Useful for scripted filter changes synchronized with media playback.
-     *
-     * @param target - Filter name or "all" to send to all filters
-     * @param cmd - Command name (e.g., "volume", "hue", "brightness")
-     * @param arg - Command argument value
-     * @param ts - Timestamp when command should execute (in seconds)
-     * @param flags - Optional command flags
+     * @returns true if initialized and ready
      *
      * @example
      * ```typescript
-     * // Schedule volume changes at specific times
-     * filter.queueCommand('volume', 'volume', '0.5', 5.0);  // At 5 seconds
-     * filter.queueCommand('volume', 'volume', '0.8', 10.0); // At 10 seconds
-     * filter.queueCommand('volume', 'volume', '0.2', 15.0); // At 15 seconds
+     * 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
-     * // Fade effect at specific timestamp
-     * filter.queueCommand('fade', 'alpha', '0.5', 30.0);
+     * if (filter.getMediaType() === AVMEDIA_TYPE_VIDEO) {
+     *   console.log('Video filter');
+     * }
      * ```
      */
-    queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): void;
+    getMediaType(): AVMediaType;
     /**
-     * Dispose of the filter.
+     * Free filter resources.
      *
-     * Implements the Disposable interface for automatic cleanup.
-     * Equivalent to calling free().
+     * Releases filter graph and contexts.
+     * Safe to call multiple times.
      *
      * @example
      * ```typescript
-     * {
-     *   using filter = await Filter.create('scale=1280:720', config);
-     *   // ... use filter
-     * } // Automatically freed when leaving scope
+     * filter.free();
      * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
      */
-    [Symbol.dispose](): void;
-}
-/**
- * Common filter presets for convenience.
- *
- * Provides pre-defined filter strings for common operations.
- * Can be used with Filter.create() for quick setup.
- *
- * @example
- * ```typescript
- * const filter = await Filter.create(
- *   FilterPresets.scale(1280, 720),
- *   config
- * );
- * ```
- */
-export declare class FilterPresets {
-    /**
-     * Scale video to specified dimensions.
-     */
-    static scale(width: number, height: number, flags?: string): string;
-    /**
-     * Crop video to specified dimensions.
-     */
-    static crop(width: number, height: number, x?: number, y?: number): string;
-    /**
-     * Change frame rate.
-     */
-    static fps(fps: number): string;
-    /**
-     * Convert pixel format.
-     * Can accept either format name string or AVPixelFormat enum.
-     */
-    static format(pixelFormat: string | AVPixelFormat): string;
-    /**
-     * Rotate video by angle.
-     */
-    static rotate(angle: number): string;
-    /**
-     * Flip video horizontally.
-     */
-    static hflip(): string;
-    /**
-     * Flip video vertically.
-     */
-    static vflip(): string;
+    free(): void;
     /**
-     * Apply fade effect.
+     * Initialize filter graph.
+     *
+     * Creates and configures filter graph components.
+     * For video, may use hardware frames context from first frame.
+     *
+     * @param firstFrame - First frame for hardware detection (video only)
+     * @throws {Error} If initialization fails
+     * @throws {FFmpegError} If configuration fails
      */
-    static fade(type: 'in' | 'out', start: number, duration: number): string;
+    private initialize;
     /**
-     * Overlay one video on another.
+     * Create buffer source with hardware frames context.
+     *
+     * @param frame - Frame with hw_frames_ctx
+     * @throws {Error} If creation fails
+     * @throws {FFmpegError} If configuration fails
      */
-    static overlay(x?: number, y?: number): string;
+    private createBufferSourceWithHwFrames;
     /**
-     * Adjust audio volume.
+     * Create standard buffer source.
+     *
+     * @throws {Error} If creation fails
      */
-    static volume(factor: number): string;
+    private createBufferSource;
     /**
-     * Convert audio sample format.
-     * Can accept either format name string or AVSampleFormat enum.
+     * Create buffer sink.
+     *
+     * @throws {Error} If creation fails
      */
-    static aformat(sampleFormat: string | AVSampleFormat, sampleRate?: number, channelLayout?: string): string;
+    private createBufferSink;
     /**
-     * Change audio tempo without changing pitch.
+     * Parse filter description and build graph.
+     *
+     * @param description - Filter description string
+     * @throws {Error} If parsing fails
+     * @throws {FFmpegError} If graph construction fails
      */
-    static atempo(factor: number): string;
+    private parseFilterDescription;
     /**
-     * Apply audio fade.
+     * Check hardware requirements for filters.
+     *
+     * @param description - Filter description
+     * @param options - Filter options
+     * @throws {Error} If hardware requirements not met
      */
-    static afade(type: 'in' | 'out', start: number, duration: number): string;
+    private checkHardwareRequirements;
     /**
-     * Mix multiple audio streams.
+     * Dispose of filter.
+     *
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling free().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using filter = await FilterAPI.create('scale=640:480', info);
+     *   // Use filter...
+     * } // Automatically freed
+     * ```
+     *
+     * @see {@link free} For manual cleanup
      */
-    static amix(inputs?: number, duration?: 'first' | 'longest' | 'shortest'): string;
+    [Symbol.dispose](): void;
 }
-export {};