node-av 2.0.0 → 2.1.0

package/dist/api/filter.d.ts

@@ -48,8 +48,11 @@ export declare class FilterAPI implements Disposable {
     private isClosed;
     /**
      * @param graph - Filter graph instance
+     *
      * @param description - Filter description string
+     *
      * @param options - Filter options
+     *
      * @internal
      */
     private constructor();
@@ -63,7 +66,9 @@ export declare class FilterAPI implements Disposable {
      * Direct mapping to avfilter_graph_parse_ptr() and avfilter_graph_config().
      *
      * @param description - Filter graph description
+     *
      * @param options - Filter options including required timeBase
+     *
      * @returns Configured filter instance
      *
      * @throws {Error} If filter creation or configuration fails
@@ -167,6 +172,7 @@ export declare class FilterAPI implements Disposable {
      * 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
@@ -197,6 +203,49 @@ export declare class FilterAPI implements Disposable {
      * @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
+     *
+     * @example
+     * ```typescript
+     * const output = filter.processSync(inputFrame);
+     * if (output) {
+     *   console.log(`Got filtered frame: pts=${output.pts}`);
+     *   output.free();
+     * }
+     * ```
+     *
+     * @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
+     */
+    processSync(frame: Frame | null): Frame | null;
     /**
      * Process multiple frames at once.
      *
@@ -204,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
@@ -222,6 +272,33 @@ export declare class FilterAPI implements Disposable {
      * @see {@link process} For single frame processing
      */
     processMultiple(frames: Frame[]): Promise<Frame[]>;
+    /**
+     * Process multiple frames at once synchronously.
+     * Synchronous version of processMultiple.
+     *
+     * 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
+     *
+     * @throws {Error} If filter not ready
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * 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.
      *
@@ -230,7 +307,9 @@ export declare class FilterAPI implements Disposable {
      * 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
@@ -264,6 +343,50 @@ export declare class FilterAPI implements Disposable {
      * @see {@link flush} For end-of-stream handling
      */
     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.
      *
@@ -289,6 +412,31 @@ export declare class FilterAPI implements Disposable {
      * @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.
      *
@@ -312,6 +460,29 @@ export declare class FilterAPI implements Disposable {
      * @see {@link frames} For complete pipeline
      */
     flushFrames(): AsyncGenerator<Frame>;
+    /**
+     * Flush filter and yield remaining frames synchronously.
+     * Synchronous version of flushFrames.
+     *
+     * Convenient sync generator for flushing.
+     * Combines flush and receive operations.
+     * Returns immediately if filter is closed or was never initialized.
+     *
+     * @yields {Frame} Remaining frames from filter
+     *
+     * @throws {FFmpegError} If flush fails
+     *
+     * @example
+     * ```typescript
+     * 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.
      *
@@ -335,6 +506,32 @@ export declare class FilterAPI implements Disposable {
      * ```
      */
     receive(): Promise<Frame | null>;
+    /**
+     * Receive buffered frame from filter synchronously.
+     * Synchronous version of receive.
+     *
+     * 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 receive} For async version
+     */
+    receiveSync(): Frame | null;
     /**
      * Send command to filter.
      *
@@ -344,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
@@ -372,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
@@ -419,6 +625,25 @@ export declare class FilterAPI implements Disposable {
      * @internal
      */
     private initialize;
+    /**
+     * Initialize filter graph from first frame synchronously.
+     * Synchronous version of initialize.
+     *
+     * Creates and configures filter graph components.
+     * Sets buffer source parameters from frame properties.
+     * Automatically configures hardware frames context if present.
+     *
+     * @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 initializeSync;
     /**
      * Create buffer source with frame parameters.
      *