node-av 0.0.1

package/dist/api/filter.d.ts

@@ -0,0 +1,457 @@
+import { Frame, Stream } from '../lib/index.js';
+import type { AVFilterCmdFlag, AVMediaType, AVPixelFormat, AVSampleFormat, HardwareFramesContext, IRational } from '../lib/index.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.
+ *
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { FilterAPI, Frame } 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);
+ *
+ * // Process frames
+ * const outputFrame = await filter.process(inputFrame);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create filter with hardware acceleration
+ * const hw = await HardwareContext.auto();
+ * const filter = await FilterAPI.create('scale_vt=640:480', videoStream, {
+ *   hardware: hw
+ * });
+ * ```
+ */
+export declare class FilterAPI implements Disposable {
+    private graph;
+    private buffersrcCtx;
+    private buffersinkCtx;
+    private config;
+    private mediaType;
+    private initialized;
+    private needsHardware;
+    private hardware?;
+    private pendingInit?;
+    /**
+     * 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
+     * @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.
+     *
+     * 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").
+     *
+     * @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
+     *
+     * @returns Promise resolving to configured Filter instance
+     *
+     * @throws {FFmpegError} If filter creation or configuration fails
+     *
+     * @example
+     * ```typescript
+     * // Simple filter
+     * const filter = await FilterAPI.create('scale=640:480', videoStream);
+     *
+     * // Complex filter chain with hardware
+     * const hw = await HardwareContext.auto();
+     * const filter = await FilterAPI.create(
+     *   'format=nv12,hwupload,scale_vt=640:480,hwdownload,format=yuv420p',
+     *   videoStream,
+     *   { hardware: hw }
+     * );
+     *
+     * // 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 }
+     * });
+     * ```
+     */
+    static create(description: string, input: Stream | StreamInfo, options?: FilterOptions): Promise<FilterAPI>;
+    /**
+     * Process a single 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.
+     *
+     * @param frame - Input frame to filter
+     *
+     * @returns Promise resolving to filtered frame or null
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * const outputFrame = await filter.process(inputFrame);
+     * if (outputFrame) {
+     *   // Process the filtered frame
+     * }
+     * ```
+     */
+    process(frame: Frame): Promise<Frame | null>;
+    /**
+     * Process multiple frames through the filter.
+     *
+     * Batch processing for better performance.
+     * Returns all available output frames.
+     *
+     * @param frames - Array of input frames
+     *
+     * @returns Promise resolving to array of filtered frames
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * const outputFrames = await filter.processMultiple(inputFrames);
+     * ```
+     */
+    processMultiple(frames: Frame[]): Promise<Frame[]>;
+    /**
+     * Receive a filtered frame without sending input.
+     *
+     * Used to drain buffered frames from the filter.
+     * Returns null when no more frames are available.
+     *
+     * @returns Promise resolving to filtered frame or null
+     *
+     * @throws {FFmpegError} If receiving fails
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered frames
+     * while (true) {
+     *   const frame = await filter.receive();
+     *   if (!frame) break;
+     *   // Process frame
+     * }
+     * ```
+     */
+    receive(): Promise<Frame | null>;
+    /**
+     * Flush the filter by sending null frame.
+     *
+     * Signals end of stream to the filter.
+     * Use receive() to get any remaining frames.
+     *
+     * @returns Promise resolving when flush is complete
+     *
+     * @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
+     * }
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush filter and yield all remaining frames as a generator.
+     *
+     * More convenient than calling flush() + receive() in a loop.
+     * Automatically sends flush signal and yields all buffered frames.
+     *
+     * @returns Async generator of remaining frames
+     *
+     * @throws {Error} If filter is not initialized
+     *
+     * @example
+     * ```typescript
+     * // Process all remaining frames with generator
+     * for await (const frame of filter.flushFrames()) {
+     *   // Process final frame
+     *   using _ = frame; // Auto cleanup
+     * }
+     * ```
+     */
+    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.
+     *
+     * @param frames - Async generator of input frames (will be freed automatically)
+     *
+     * @returns Async generator of filtered frames (ownership transferred to caller)
+     *
+     * @example
+     * ```typescript
+     * for await (const filtered of filter.frames(decoder.frames())) {
+     *   // Process filtered frame
+     *   filtered.free(); // Must free output frame
+     * }
+     * ```
+     */
+    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);
+     * ```
+     */
+    getGraphDescription(): string | null;
+    /**
+     * Check if the filter is initialized and ready.
+     *
+     * @returns true if the filter is ready for processing
+     */
+    isReady(): boolean;
+    /**
+     * Get the media type of this filter.
+     *
+     * @returns The media type (video or audio)
+     */
+    getMediaType(): AVMediaType;
+    /**
+     * Get the filter configuration.
+     *
+     * @returns The filter configuration used to create this instance
+     */
+    getConfig(): FilterConfig;
+    /**
+     * Free all filter resources.
+     *
+     * Releases the filter graph and all associated filters.
+     * The filter instance cannot be used after calling this.
+     *
+     * @example
+     * ```typescript
+     * filter.free();
+     * // filter is now invalid
+     * ```
+     */
+    free(): void;
+    /**
+     * Initialize the filter graph.
+     *
+     * Sets up buffer source, buffer sink, and parses the filter description.
+     * Configures the graph for processing.
+     *
+     * @internal
+     */
+    private initialize;
+    /**
+     * Create and configure the buffer source filter.
+     *
+     * @internal
+     */
+    private createBufferSource;
+    /**
+     * Create and configure the buffer sink filter.
+     *
+     * @internal
+     */
+    private createBufferSink;
+    /**
+     * Parse and connect the filter description.
+     *
+     * @internal
+     */
+    private parseFilterDescription;
+    /**
+     * 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.
+     *
+     * @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 Command response
+     *
+     * @example
+     * ```typescript
+     * // Change volume dynamically
+     * const response = filter.sendCommand('volume', 'volume', '0.5');
+     * if (response) {
+     *   console.log('Volume changed successfully');
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Enable/disable all filters at runtime
+     * filter.sendCommand('all', 'enable', 'expr=gte(t,10)');
+     * ```
+     */
+    sendCommand(target: string, cmd: string, arg: string, flags?: AVFilterCmdFlag): string;
+    /**
+     * Queue a command to be executed at a specific time.
+     *
+     * 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
+     *
+     * @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
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Fade effect at specific timestamp
+     * filter.queueCommand('fade', 'alpha', '0.5', 30.0);
+     * ```
+     */
+    queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): void;
+    /**
+     * Dispose of the filter.
+     *
+     * Implements the Disposable interface for automatic cleanup.
+     * Equivalent to calling free().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using filter = await Filter.create('scale=1280:720', config);
+     *   // ... use filter
+     * } // Automatically freed when leaving scope
+     * ```
+     */
+    [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;
+    /**
+     * Apply fade effect.
+     */
+    static fade(type: 'in' | 'out', start: number, duration: number): string;
+    /**
+     * Overlay one video on another.
+     */
+    static overlay(x?: number, y?: number): string;
+    /**
+     * Adjust audio volume.
+     */
+    static volume(factor: number): string;
+    /**
+     * Convert audio sample format.
+     * Can accept either format name string or AVSampleFormat enum.
+     */
+    static aformat(sampleFormat: string | AVSampleFormat, sampleRate?: number, channelLayout?: string): string;
+    /**
+     * Change audio tempo without changing pitch.
+     */
+    static atempo(factor: number): string;
+    /**
+     * Apply audio fade.
+     */
+    static afade(type: 'in' | 'out', start: number, duration: number): string;
+    /**
+     * Mix multiple audio streams.
+     */
+    static amix(inputs?: number, duration?: 'first' | 'longest' | 'shortest'): string;
+}
+export {};