node-av 1.1.0 → 1.2.0

package/dist/api/pipeline.d.ts

@@ -1,14 +1,7 @@
 /**
- * Pipeline - Stream-based media processing pipeline
- *
- * Provides a Node.js-style pipeline function for chaining media processing components.
- * Automatically handles type conversions, buffering, and flushing.
- *
- * Supports two modes:
- * 1. Simple: Single stream with variable parameters
- * 2. Named: Multiple streams with named routing with variable parameters
- *
- * @module api/pipeline
+ * @module pipeline
+ * High-level media processing pipeline for FFmpeg operations.
+ * Provides a fluent API for building transcoding, filtering, and stream processing pipelines.
  */
 import type { Frame, Packet } from '../lib/index.js';
 import type { BitStreamFilterAPI } from './bitstream-filter.js';
@@ -17,101 +10,238 @@ import type { Encoder } from './encoder.js';
 import type { FilterAPI } from './filter.js';
 import type { MediaInput } from './media-input.js';
 import type { MediaOutput } from './media-output.js';
-type StreamName = 'video' | 'audio';
-type NamedInputs<K extends StreamName = StreamName> = Pick<Record<StreamName, MediaInput>, K>;
-type NamedStages<K extends StreamName = StreamName> = Pick<Record<StreamName, (Decoder | FilterAPI | FilterAPI[] | Encoder | BitStreamFilterAPI | BitStreamFilterAPI[])[] | 'passthrough'>, K>;
-type NamedOutputs<K extends StreamName = StreamName> = Pick<Record<StreamName, MediaOutput>, K>;
+export type StreamName = 'video' | 'audio';
+export type NamedInputs<K extends StreamName = StreamName> = Pick<Record<StreamName, MediaInput>, K>;
+export type NamedStages<K extends StreamName = StreamName> = Pick<Record<StreamName, (Decoder | FilterAPI | FilterAPI[] | Encoder | BitStreamFilterAPI | BitStreamFilterAPI[])[] | 'passthrough'>, K>;
+export type NamedOutputs<K extends StreamName = StreamName> = Pick<Record<StreamName, MediaOutput>, K>;
 /**
- * Pipeline control interface for managing pipeline execution
+ * Pipeline control interface for managing pipeline execution.
+ * Allows graceful stopping and completion tracking of running pipelines.
+ *
+ * @example
+ * ```typescript
+ * const control = pipeline(input, decoder, encoder, output);
+ *
+ * // Stop after 10 seconds
+ * setTimeout(() => control.stop(), 10000);
+ *
+ * // Wait for completion
+ * await control.completion;
+ * ```
  */
 export interface PipelineControl {
     /**
-     * Stop the pipeline gracefully
+     * Stop the pipeline gracefully.
+     * The pipeline will stop processing after the current operation completes.
      */
     stop(): void;
     /**
-     * Check if the pipeline has been stopped
+     * Check if the pipeline has been stopped.
+     *
+     * @returns True if stop() has been called
      */
     isStopped(): boolean;
     /**
-     * Promise that resolves when the pipeline completes
+     * Promise that resolves when the pipeline completes.
+     * Resolves when all processing is finished or the pipeline is stopped.
      */
     readonly completion: Promise<void>;
 }
 /**
- * Full transcoding pipeline: input → decoder → encoder → output
+ * Full transcoding pipeline: input → decoder → encoder → output.
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets to frames
+ * @param encoder - Encoder for encoding frames to packets
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
+ *
+ * @example
+ * ```typescript
+ * const control = pipeline(input, decoder, encoder, output);
+ * await control.completion;
+ * ```
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, encoder: Encoder, output: MediaOutput): PipelineControl;
 /**
- * Full transcoding pipeline with filter: input → decoder → filter → encoder → output
+ * Full transcoding pipeline with filter: input → decoder → filter → encoder → output.
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets to frames
+ * @param filter - Filter or filter chain for processing frames
+ * @param encoder - Encoder for encoding frames to packets
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
+ *
+ * @example
+ * ```typescript
+ * const control = pipeline(input, decoder, scaleFilter, encoder, output);
+ * await control.completion;
+ * ```
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[], encoder: Encoder, output: MediaOutput): PipelineControl;
 /**
- * Transcoding with bitstream filter: input → decoder → encoder → bsf → output
+ * Transcoding with bitstream filter: input → decoder → encoder → bsf → output.
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @param encoder - Encoder for encoding frames
+ * @param bsf - Bitstream filter for packet processing
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, encoder: Encoder, bsf: BitStreamFilterAPI | BitStreamFilterAPI[], output: MediaOutput): PipelineControl;
 /**
- * Full pipeline with filter and bsf: input → decoder → filter → encoder → bsf → output
+ * Full pipeline with filter and bsf: input → decoder → filter → encoder → bsf → output.
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @param filter - Filter or filter chain
+ * @param encoder - Encoder for encoding frames
+ * @param bsf - Bitstream filter
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[], encoder: Encoder, bsf: BitStreamFilterAPI | BitStreamFilterAPI[], output: MediaOutput): PipelineControl;
 /**
- * Decode + multiple filters + encode: input → decoder → filter1 → filter2 → encoder → output
+ * Decode + multiple filters + encode: input → decoder → filter1 → filter2 → encoder → output.
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @param filter1 - First filter
+ * @param filter2 - Second filter
+ * @param encoder - Encoder for encoding frames
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, filter1: FilterAPI, filter2: FilterAPI, encoder: Encoder, output: MediaOutput): PipelineControl;
 /**
- * Stream copy pipeline: input → output (copies all streams)
+ * Stream copy pipeline: input → output (copies all streams).
+ *
+ * @param source - Media input source
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
+ *
+ * @example
+ * ```typescript
+ * // Copy all streams without re-encoding
+ * const control = pipeline(input, output);
+ * await control.completion;
+ * ```
  */
 export declare function pipeline(source: MediaInput, output: MediaOutput): PipelineControl;
 /**
- * Stream copy with bitstream filter: input → bsf → output
+ * Stream copy with bitstream filter: input → bsf → output.
+ *
+ * @param source - Media input source
+ * @param bsf - Bitstream filter for packet processing
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline(source: MediaInput, bsf: BitStreamFilterAPI | BitStreamFilterAPI[], output: MediaOutput): PipelineControl;
 /**
- * Filter + encode + output: frames → filter → encoder → output
+ * Filter + encode + output: frames → filter → encoder → output.
+ *
+ * @param source - Frame source (async iterable)
+ * @param filter - Filter or filter chain
+ * @param encoder - Encoder for encoding frames
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline(source: AsyncIterable<Frame>, filter: FilterAPI | FilterAPI[], encoder: Encoder, output: MediaOutput): PipelineControl;
 /**
- * Encode + output: frames → encoder → output
+ * Encode + output: frames → encoder → output.
+ *
+ * @param source - Frame source (async iterable)
+ * @param encoder - Encoder for encoding frames
+ * @param output - Media output destination
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline(source: AsyncIterable<Frame>, encoder: Encoder, output: MediaOutput): PipelineControl;
 /**
- * Partial pipeline: input → decoder (returns frames)
+ * Partial pipeline: input → decoder (returns frames).
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @returns Async generator of frames
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder): AsyncGenerator<Frame>;
 /**
- * Partial pipeline: input → decoder → filter (returns frames)
+ * Partial pipeline: input → decoder → filter (returns frames).
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @param filter - Filter or filter chain
+ * @returns Async generator of frames
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[]): AsyncGenerator<Frame>;
 /**
- * Partial pipeline: input → decoder → filter → encoder (returns packets)
+ * Partial pipeline: input → decoder → filter → encoder (returns packets).
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @param filter - Filter or filter chain
+ * @param encoder - Encoder for encoding frames
+ * @returns Async generator of packets
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[], encoder: Encoder): AsyncGenerator<Packet>;
 /**
- * Partial pipeline: input → decoder → encoder (returns packets)
+ * Partial pipeline: input → decoder → encoder (returns packets).
+ *
+ * @param source - Media input source
+ * @param decoder - Decoder for decoding packets
+ * @param encoder - Encoder for encoding frames
+ * @returns Async generator of packets
  */
 export declare function pipeline(source: MediaInput, decoder: Decoder, encoder: Encoder): AsyncGenerator<Packet>;
 /**
- * Partial pipeline: frames → filter (returns frames)
+ * Partial pipeline: frames → filter (returns frames).
+ *
+ * @param source - Frame source (async iterable)
+ * @param filter - Filter or filter chain
+ * @returns Async generator of filtered frames
  */
 export declare function pipeline(source: AsyncIterable<Frame>, filter: FilterAPI | FilterAPI[]): AsyncGenerator<Frame>;
 /**
- * Partial pipeline: frames → encoder (returns packets)
+ * Partial pipeline: frames → encoder (returns packets).
+ *
+ * @param source - Frame source (async iterable)
+ * @param encoder - Encoder for encoding frames
+ * @returns Async generator of packets
  */
 export declare function pipeline(source: AsyncIterable<Frame>, encoder: Encoder): AsyncGenerator<Packet>;
 /**
- * Partial pipeline: frames → filter → encoder (returns packets)
+ * Partial pipeline: frames → filter → encoder (returns packets).
+ *
+ * @param source - Frame source (async iterable)
+ * @param filter - Filter or filter chain
+ * @param encoder - Encoder for encoding frames
+ * @returns Async generator of packets
  */
 export declare function pipeline(source: AsyncIterable<Frame>, filter: FilterAPI | FilterAPI[], encoder: Encoder): AsyncGenerator<Packet>;
 /**
- * Named pipeline with single output - all streams go to the same output
+ * Named pipeline with single output - all streams go to the same output.
+ *
+ * @param inputs - Named input sources (video/audio)
+ * @param stages - Named processing stages for each stream
+ * @param output - Single output destination for all streams
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline<K extends StreamName>(inputs: NamedInputs<K>, stages: NamedStages<K>, output: MediaOutput): PipelineControl;
 /**
- * Named pipeline with multiple outputs - each stream has its own output
+ * Named pipeline with multiple outputs - each stream has its own output.
+ *
+ * @param inputs - Named input sources (video/audio)
+ * @param stages - Named processing stages for each stream
+ * @param outputs - Named output destinations
+ * @returns Pipeline control for managing execution
  */
 export declare function pipeline<K extends StreamName>(inputs: NamedInputs<K>, stages: NamedStages<K>, outputs: NamedOutputs<K>): PipelineControl;
 /**
- * Partial named pipeline (returns generators for further processing)
+ * Partial named pipeline (returns generators for further processing).
+ *
+ * @param inputs - Named input sources
+ * @param stages - Named processing stages
+ * @returns Record of async generators for each stream
  */
 export declare function pipeline<K extends StreamName, T extends Packet | Frame = Packet | Frame>(inputs: NamedInputs<K>, stages: NamedStages<K>): Record<K, AsyncGenerator<T>>;
-export {};