node-av 0.0.1

package/dist/lib/filter-graph.d.ts

@@ -0,0 +1,556 @@
+import { FilterContext } from './filter-context.js';
+import { OptionMember } from './option.js';
+import type { AVFilterCmdFlag, AVFilterConstants } from './constants.js';
+import type { FilterInOut } from './filter-inout.js';
+import type { Filter } from './filter.js';
+import type { NativeFilterGraph, NativeWrapper } from './native-types.js';
+/**
+ * Filter graph for media processing.
+ *
+ * Container for filters and their connections in a processing pipeline.
+ * Manages the entire filtering system from sources to sinks.
+ * Supports complex filter chains with multiple inputs and outputs.
+ *
+ * Direct mapping to FFmpeg's AVFilterGraph.
+ *
+ * @example
+ * ```typescript
+ * import { FilterGraph, Filter, FilterContext, FFmpegError } from 'node-av';
+ *
+ * // Create and configure a simple filter graph
+ * const graph = new FilterGraph();
+ * graph.alloc();
+ *
+ * // Create buffer source
+ * const bufferFilter = Filter.getByName('buffer');
+ * if (!bufferFilter) throw new Error('Buffer filter not found');
+ * const bufferSrc = graph.createFilter(
+ *   bufferFilter,
+ *   'in',
+ *   'video_size=1920x1080:pix_fmt=yuv420p:time_base=1/25'
+ * );
+ * if (!bufferSrc) throw new Error('Failed to create buffer source');
+ *
+ * // Create scale filter
+ * const scaleFilter = Filter.getByName('scale');
+ * if (!scaleFilter) throw new Error('Scale filter not found');
+ * const scale = graph.createFilter(
+ *   scaleFilter,
+ *   'scale',
+ *   '1280:720'
+ * );
+ * if (!scale) throw new Error('Failed to create scale filter');
+ *
+ * // Create buffer sink
+ * const sinkFilter = Filter.getByName('buffersink');
+ * if (!sinkFilter) throw new Error('Buffersink filter not found');
+ * const bufferSink = graph.createFilter(
+ *   sinkFilter,
+ *   'out'
+ * );
+ * if (!bufferSink) throw new Error('Failed to create buffer sink');
+ *
+ * // Link filters
+ * const linkRet1 = bufferSrc.link(0, scale, 0);
+ * FFmpegError.throwIfError(linkRet1, 'link buffer to scale');
+ *
+ * const linkRet2 = scale.link(0, bufferSink, 0);
+ * FFmpegError.throwIfError(linkRet2, 'link scale to sink');
+ *
+ * // Configure the graph
+ * const configRet = graph.config();
+ * FFmpegError.throwIfError(configRet, 'config');
+ *
+ * // Clean up
+ * graph.free();
+ * ```
+ */
+export declare class FilterGraph extends OptionMember<NativeFilterGraph> implements Disposable, NativeWrapper<NativeFilterGraph> {
+    /**
+     * Create a new FilterGraph instance.
+     *
+     * The graph is uninitialized - you must call alloc() before use.
+     * No FFmpeg resources are allocated until alloc() is called.
+     *
+     * Direct wrapper around AVFilterGraph.
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph } from 'node-av';
+     *
+     * const graph = new FilterGraph();
+     * graph.alloc();
+     * // Graph is now ready for use
+     * ```
+     */
+    constructor();
+    /**
+     * Number of filters in the graph.
+     *
+     * Direct mapping to AVFilterGraph->nb_filters
+     *
+     * The total count of filters currently in the graph.
+     */
+    get nbFilters(): number;
+    /**
+     * Array of all filters in the graph.
+     *
+     * Direct mapping to AVFilterGraph->filters
+     *
+     * All filter contexts currently in the graph.
+     */
+    get filters(): FilterContext[] | null;
+    /**
+     * Thread type for graph processing.
+     *
+     * Direct mapping to AVFilterGraph->thread_type
+     *
+     * Controls threading behavior of the graph (0 = disabled, AVFILTER_THREAD_SLICE = slice threading).
+     */
+    get threadType(): AVFilterConstants;
+    set threadType(value: AVFilterConstants);
+    /**
+     * Number of threads for graph processing.
+     *
+     * Direct mapping to AVFilterGraph->nb_threads
+     *
+     * 0 means automatic detection based on CPU cores.
+     */
+    get nbThreads(): number;
+    set nbThreads(value: number);
+    /**
+     * Software scaler options.
+     *
+     * Direct mapping to AVFilterGraph->scale_sws_opts
+     *
+     * Options string passed to the software scaler (e.g., "flags=bicubic").
+     */
+    get scaleSwsOpts(): string | null;
+    set scaleSwsOpts(value: string | null);
+    /**
+     * Allocate the filter graph.
+     *
+     * Allocates the graph structure and initializes it.
+     * Must be called before adding filters to the graph.
+     *
+     * Direct mapping to avfilter_graph_alloc()
+     *
+     * @throws {Error} Memory allocation failure (ENOMEM)
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph } from 'node-av';
+     *
+     * const graph = new FilterGraph();
+     * graph.alloc();
+     * // Graph is now allocated and ready
+     * ```
+     *
+     * @see {@link free} To free the graph
+     */
+    alloc(): void;
+    /**
+     * Free the filter graph.
+     *
+     * Releases all resources associated with the graph.
+     * All filters in the graph are also freed.
+     *
+     * Direct mapping to avfilter_graph_free()
+     *
+     * @example
+     * ```typescript
+     * graph.free();
+     * // graph is now invalid and should not be used
+     * ```
+     */
+    free(): void;
+    /**
+     * Create a filter instance in the graph.
+     *
+     * Direct mapping to avfilter_graph_create_filter()
+     *
+     * @param filter - The filter definition
+     * @param name - Name for this filter instance (must be unique in the graph)
+     * @param args - Optional initialization arguments (filter-specific format)
+     *
+     * @returns The created filter context or null on failure
+     *
+     * @example
+     * ```typescript
+     * // Create a scale filter
+     * const scaleFilter = Filter.getByName('scale');
+     * const scaleCtx = graph.createFilter(
+     *   scaleFilter!,
+     *   'my_scale',
+     *   '1280:720'  // width:height
+     * );
+     *
+     * // Create a buffer source for video
+     * const bufferFilter = Filter.getByName('buffer');
+     * const bufferCtx = graph.createFilter(
+     *   bufferFilter!,
+     *   'video_in',
+     *   'video_size=1920x1080:pix_fmt=yuv420p:time_base=1/25:pixel_aspect=1/1'
+     * );
+     * ```
+     */
+    createFilter(filter: Filter, name: string, args?: string | null): FilterContext | null;
+    /**
+     * Allocate a filter instance in the graph without initializing it.
+     *
+     * Direct mapping to avfilter_graph_alloc_filter()
+     *
+     * This method allocates the filter but does not initialize it.
+     * You must call filter.init() or filter.initStr() afterwards.
+     *
+     * @param filter - The filter definition
+     * @param name - Name for this filter instance (must be unique in the graph)
+     *
+     * @returns The allocated filter context or null on failure
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, Filter, FFmpegError } from 'node-av';
+     *
+     * // Allocate a filter without initializing
+     * const scaleFilter = Filter.getByName('scale');
+     * if (!scaleFilter) throw new Error('Scale filter not found');
+     * const scaleCtx = graph.allocFilter(scaleFilter, 'my_scale');
+     * if (!scaleCtx) throw new Error('Failed to allocate filter');
+     *
+     * // Set options using setOpt
+     * const ret1 = scaleCtx.setOpt('width', '1280');
+     * FFmpegError.throwIfError(ret1, 'setOpt width');
+     * const ret2 = scaleCtx.setOpt('height', '720');
+     * FFmpegError.throwIfError(ret2, 'setOpt height');
+     *
+     * // Initialize the filter
+     * const initRet = scaleCtx.init();
+     * FFmpegError.throwIfError(initRet, 'init');
+     * ```
+     *
+     * @note This provides an alternative workflow to createFilter,
+     * allowing options to be set before initialization.
+     */
+    allocFilter(filter: Filter, name: string): FilterContext | null;
+    /**
+     * Get a filter by name from the graph.
+     *
+     * Direct mapping to avfilter_graph_get_filter()
+     *
+     * @param name - The filter instance name
+     *
+     * @returns The filter context or null if not found
+     *
+     * @example
+     * ```typescript
+     * const scaleCtx = graph.getFilter('my_scale');
+     * if (scaleCtx) {
+     *   console.log('Found scale filter');
+     * }
+     * ```
+     */
+    getFilter(name: string): FilterContext | null;
+    /**
+     * Configure the filter graph.
+     *
+     * Direct mapping to avfilter_graph_config()
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR(EINVAL): Invalid graph configuration
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *   - <0: Other configuration errors
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FFmpegError } from 'node-av';
+     *
+     * // After creating and linking all filters
+     * const ret = graph.config();
+     * FFmpegError.throwIfError(ret, 'config');
+     * // Graph is now ready for processing
+     * ```
+     *
+     * @note Must be called after all filters are added and connected.
+     */
+    config(): Promise<number>;
+    /**
+     * Parse a filtergraph description.
+     *
+     * Direct mapping to avfilter_graph_parse()
+     *
+     * @param filters - Filtergraph description string
+     * @param inputs - Input pad list
+     * @param outputs - Output pad list
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR(EINVAL): Invalid filtergraph syntax
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *   - <0: Other parsing errors
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FilterInOut, FFmpegError } from 'node-av';
+     *
+     * const inputs = new FilterInOut();
+     * inputs.alloc();
+     * inputs.name = 'in';
+     * inputs.filterCtx = bufferSrcCtx;
+     * inputs.padIdx = 0;
+     *
+     * const outputs = new FilterInOut();
+     * outputs.alloc();
+     * outputs.name = 'out';
+     * outputs.filterCtx = bufferSinkCtx;
+     * outputs.padIdx = 0;
+     *
+     * const ret = graph.parse('[in] scale=1280:720 [out]', inputs, outputs);
+     * FFmpegError.throwIfError(ret, 'parse');
+     * ```
+     */
+    parse(filters: string, inputs: FilterInOut | null, outputs: FilterInOut | null): number;
+    /**
+     * Parse a filtergraph description (simplified).
+     *
+     * Direct mapping to avfilter_graph_parse2()
+     *
+     * @param filters - Filtergraph description string
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR(EINVAL): Invalid filtergraph syntax
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *   - <0: Other parsing errors
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FFmpegError } from 'node-av';
+     *
+     * // Parse a simple filter chain
+     * const ret = graph.parse2('scale=1280:720,format=yuv420p');
+     * FFmpegError.throwIfError(ret, 'parse2');
+     * ```
+     *
+     * @note Automatically handles inputs and outputs.
+     */
+    parse2(filters: string): number;
+    /**
+     * Parse a filtergraph description (pointer version).
+     *
+     * Direct mapping to avfilter_graph_parse_ptr()
+     *
+     * @param filters - Filtergraph description string
+     * @param inputs - Optional input pad list (FilterInOut)
+     * @param outputs - Optional output pad list (FilterInOut)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR(EINVAL): Invalid filtergraph syntax
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *   - <0: Other parsing errors
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FFmpegError } from 'node-av';
+     *
+     * // Parse a complex filter graph
+     * const ret = graph.parsePtr(
+     *   '[0:v] scale=1280:720 [scaled]; [scaled] split [out1][out2]'
+     * );
+     * FFmpegError.throwIfError(ret, 'parsePtr');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FilterInOut, FFmpegError } from 'node-av';
+     *
+     * // Parse with explicit inputs/outputs
+     * const inputs = new FilterInOut();
+     * inputs.name = 'in';
+     * inputs.filterCtx = buffersrcCtx;
+     * inputs.padIdx = 0;
+     *
+     * const outputs = new FilterInOut();
+     * outputs.name = 'out';
+     * outputs.filterCtx = buffersinkCtx;
+     * outputs.padIdx = 0;
+     *
+     * const ret = graph.parsePtr(filtersDescr, inputs, outputs);
+     * FFmpegError.throwIfError(ret, 'parsePtr');
+     * ```
+     *
+     * @note Similar to parse2 but with different internal handling.
+     */
+    parsePtr(filters: string, inputs?: FilterInOut | null, outputs?: FilterInOut | null): number;
+    /**
+     * Validate the filter graph.
+     *
+     * Direct mapping to avfilter_graph_validate()
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Valid graph structure
+     *   - AVERROR(EINVAL): Invalid graph structure
+     *   - <0: Other validation errors
+     *
+     * @example
+     * ```typescript
+     * // Validate before configuring
+     * const ret = graph.validate();
+     * if (ret < 0) {
+     *   console.error('Graph validation failed');
+     * }
+     * ```
+     *
+     * @note Checks that the graph structure is valid without configuring it.
+     */
+    validate(): number;
+    /**
+     * Request a frame from the oldest sink.
+     *
+     * Direct mapping to avfilter_graph_request_oldest()
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR_EOF: No more frames available
+     *   - AVERROR(EAGAIN): Need more input data
+     *   - <0: Other processing errors
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FFmpegError } from 'node-av';
+     * import { AVERROR_EOF, AVERROR_EAGAIN } from 'node-av/constants';
+     *
+     * // Pull frames from the graph
+     * while (true) {
+     *   const ret = await graph.requestOldest();
+     *   if (FFmpegError.is(ret, AVERROR_EOF)) {
+     *     break; // No more frames
+     *   }
+     *   if (ret < 0 && !FFmpegError.is(ret, AVERROR_EAGAIN)) {
+     *     FFmpegError.throwIfError(ret, 'requestOldest');
+     *   }
+     *   // Process output from sinks
+     * }
+     * ```
+     *
+     * @note Triggers processing in the graph to produce output.
+     */
+    requestOldest(): Promise<number>;
+    /**
+     * Get the graph structure as a string.
+     *
+     * Returns a string representation of the filter graph in DOT format.
+     * Uses avfilter_graph_dump() internally.
+     *
+     * @returns String representation of the filter graph or null if not allocated
+     *
+     * @example
+     * ```typescript
+     * const graphDescription = graph.dump();
+     * console.log('Filter graph:', graphDescription);
+     * ```
+     */
+    dump(): string | null;
+    /**
+     * Send a command to one or more filters in the graph.
+     *
+     * Direct mapping to avfilter_graph_send_command()
+     *
+     * @param target - Filter name or "all" to send to all filters
+     * @param cmd - Command name (e.g., "volume", "hue", "rate")
+     * @param arg - Command argument (e.g., "0.5", "2.0")
+     * @param flags - Command flags (AVFilterCmdFlag, default: 0)
+     *   - AVFILTER_CMD_FLAG_ONE: Stop once a filter understood the command
+     *   - AVFILTER_CMD_FLAG_FAST: Only execute if fast (hardware acceleration)
+     *
+     * @returns Error code (negative) or response object { response: string | null }
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FFmpegError, AVFILTER_CMD_FLAG_ONE } from 'node-av';
+     *
+     * // Send volume change command to audio filter
+     * const result = graph.sendCommand('volume', 'volume', '0.5');
+     * if (typeof result === 'number') {
+     *   console.error('Command failed:', FFmpegError.strerror(result));
+     * } else {
+     *   console.log('Response:', result.response);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Send command to all filters, stop at first one that handles it
+     * const result = graph.sendCommand('all', 'enable', 'expr=gte(t,10)', AVFILTER_CMD_FLAG_ONE);
+     *
+     * // Send command to specific filter
+     * const result = graph.sendCommand('scale', 'width', '1920');
+     * ```
+     *
+     * @note Not all filters support commands. Check filter documentation.
+     */
+    sendCommand(target: string, cmd: string, arg: string, flags?: AVFilterCmdFlag): number | {
+        response: string | null;
+    };
+    /**
+     * Queue a command to be executed at a specific time.
+     *
+     * Direct mapping to avfilter_graph_queue_command()
+     *
+     * @param target - Filter name or "all" to send to all filters
+     * @param cmd - Command name (e.g., "volume", "hue", "rate")
+     * @param arg - Command argument (e.g., "0.5", "2.0")
+     * @param ts - Timestamp when the command should be executed
+     * @param flags - Command flags (AVFilterCmdFlag, default: 0)
+     *   - AVFILTER_CMD_FLAG_ONE: Stop once a filter understood the command
+     *   - AVFILTER_CMD_FLAG_FAST: Only execute if fast (hardware acceleration)
+     *
+     * @returns 0 on success, negative AVERROR on error
+     *
+     * @example
+     * ```typescript
+     * import { FilterGraph, FFmpegError, AVFILTER_CMD_FLAG_ONE } from 'node-av';
+     *
+     * // Queue volume change at 10 seconds
+     * const ret = graph.queueCommand('volume', 'volume', '0.2', 10.0);
+     * FFmpegError.throwIfError(ret, 'queueCommand');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Queue multiple commands at different times
+     * graph.queueCommand('volume', 'volume', '0.5', 5.0);
+     * graph.queueCommand('volume', 'volume', '1.0', 10.0);
+     * graph.queueCommand('volume', 'volume', '0.2', 15.0);
+     * ```
+     *
+     * @note Commands are executed when processing frames with matching timestamps.
+     * @note Not all filters support queued commands.
+     */
+    queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): number;
+    /**
+     * Get the native FFmpeg AVFilterGraph pointer.
+     *
+     * @internal For use by other wrapper classes
+     * @returns The underlying native filter graph object
+     */
+    getNative(): NativeFilterGraph;
+    /**
+     * Dispose of the filter graph.
+     *
+     * Implements the Disposable interface for automatic cleanup.
+     * Equivalent to calling free().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using graph = new FilterGraph();
+     *   graph.alloc();
+     *   // ... use graph
+     * } // Automatically freed when leaving scope
+     * ```
+     */
+    [Symbol.dispose](): void;
+}