node-av 6.0.0-beta.2 → 6.0.0-beta.4

package/dist/api/bitstream-filter.d.ts

@@ -1,19 +1,25 @@
 import { Packet } from '../lib/packet.js';
+import { Stream } from '../lib/stream.js';
+import { Encoder } from './encoder.js';
 import { Muxer } from './muxer.js';
 import { Scheduler, SchedulerControl } from './utilities/scheduler.js';
-import type { Stream } from '../lib/stream.js';
+import type { BsfName, BsfOptionsFor } from '../constants/index.js';
 /**
  * Options for bitstream filter creation.
+ *
+ * @template N - The bitstream filter name; when a literal name is given,
+ * `options` is strongly typed to that filter's known options.
  */
-export interface BitstreamFilterOptions {
+export interface BitstreamFilterOptions<N extends string = string> {
     /**
      * Filter-specific options.
      *
-     * Key-value pairs of FFmpeg bitstream filter options.
-     * These are passed directly to the filter via av_opt_set().
-     * Available options depend on the specific filter being used.
+     * Key-value pairs of FFmpeg bitstream filter options, passed directly to the
+     * filter via av_opt_set(). When created from a known filter name, these are
+     * strongly typed to that filter's options (autocomplete + validation);
+     * otherwise any string/number/boolean values are accepted.
      */
-    options?: Record<string, string | number | boolean | bigint | undefined | null>;
+    options?: BsfOptionsFor<N>;
     /**
      * AbortSignal for cancellation.
      *
@@ -63,7 +69,8 @@ export interface BitstreamFilterOptions {
 export declare class BitStreamFilterAPI implements Disposable {
     private ctx;
     private bsf;
-    private stream;
+    private source;
+    private initialized;
     private packet;
     private isClosed;
     private inputQueue;
@@ -77,63 +84,55 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @param ctx - Filter context
      *
-     * @param stream - Associated stream
+     * @param source - Input source for lazy parameter resolution
      *
      * @internal
      */
     private constructor();
     /**
-     * Create a bitstream filter for a stream.
+     * Create a bitstream filter.
+     *
+     * The input source provides the codec parameters the filter is configured with.
+     * Pass a {@link Stream} to filter its packets directly (stream copy), or an
+     * {@link Encoder} to filter that encoder's output (transcode) - parameters are
+     * derived from the encoder once it is open. Another {@link BitStreamFilterAPI}
+     * may be passed to chain filters.
      *
-     * Initializes filter with stream codec parameters.
-     * Configures time base and prepares for packet processing.
+     * Initialization is lazy: filter options are validated immediately, but the
+     * input parameters are bound and the filter is initialized on the first packet,
+     * so an `Encoder` source (opened lazily on its first frame) is ready in time.
      *
      * Direct mapping to av_bsf_get_by_name() and av_bsf_alloc().
      *
      * @param filterName - Name of the bitstream filter
      *
-     * @param stream - Stream to apply filter to
+     * @param source - Input source: a `Stream` (copy), `Encoder` (transcode), or upstream filter (chain)
      *
      * @param filterOptions - Optional filter-specific options
      *
      * @returns Configured bitstream filter
      *
-     * @throws {Error} If initialization fails
-     *
-     * @throws {FFmpegError} If allocation or initialization fails
+     * @throws {FFmpegError} If the filter is not found, allocation fails, or an option is invalid
      *
      * @example
      * ```typescript
-     * // H.264 MP4 to Annex B conversion
+     * // Stream copy: H.264 MP4 to Annex B conversion
      * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', videoStream);
      * ```
      *
      * @example
      * ```typescript
-     * // AAC ADTS to ASC conversion
-     * const filter = BitStreamFilterAPI.create('aac_adtstoasc', audioStream);
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Remove AUDs from H.264 stream
-     * const filter = BitStreamFilterAPI.create('h264_metadata', stream, {
-     *   options: { aud: 'remove' }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Set H.264 level
-     * const filter = BitStreamFilterAPI.create('h264_metadata', stream, {
-     *   options: { level: 51 }
+     * // Transcode: derive parameters from the encoder's output
+     * const filter = BitStreamFilterAPI.create('h264_metadata', encoder, {
+     *   options: { aud: 'remove', level: '4.1' },
      * });
+     * pipeline(input, decoder, encoder, filter, output);
      * ```
      *
      * @see {@link BitStreamFilter.getByName} For filter discovery
      * @see {@link BitstreamFilterOptions} For available options
      */
-    static create(filterName: string, stream: Stream, filterOptions?: BitstreamFilterOptions): BitStreamFilterAPI;
+    static create<const N extends BsfName | (string & {}) = BsfName | (string & {})>(filterName: N, source: Stream | Encoder | BitStreamFilterAPI, filterOptions?: BitstreamFilterOptions<N>): BitStreamFilterAPI;
     /**
      * Get filter name.
      *
@@ -179,6 +178,38 @@ export declare class BitStreamFilterAPI implements Disposable {
      * ```
      */
     get isBitstreamFilterOpen(): boolean;
+    /**
+     * Check if the filter has been initialized.
+     *
+     * Initialization is lazy and happens on the first processed packet, after
+     * which {@link outputCodecParameters} reflect the filter's output.
+     *
+     * @example
+     * ```typescript
+     * if (filter.isInitialized) {
+     *   const params = filter.outputCodecParameters;
+     * }
+     * ```
+     */
+    get isInitialized(): boolean;
+    /**
+     * Get associated stream.
+     *
+     * Returns the stream this filter was created for. Only available when the
+     * filter was created from a {@link Stream}; filters created from an `Encoder`
+     * derive their parameters from the encoder's output instead.
+     *
+     * @returns Associated stream
+     *
+     * @throws {Error} If the filter was not created from a stream
+     *
+     * @example
+     * ```typescript
+     * const stream = filter.getStream();
+     * console.log(`Filtering stream ${stream.index}`);
+     * ```
+     */
+    getStream(): Stream;
     /**
      * Send a packet to the filter.
      *
@@ -637,6 +668,43 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link receive} For async version
      */
     receiveSync(): Packet | null;
+    /**
+     * Pipe output to another bitstream filter.
+     *
+     * Starts background worker for packet processing.
+     * Packets flow through: input → this filter → target filter.
+     *
+     * @param target - Target bitstream filter
+     *
+     * @returns Scheduler for continued chaining
+     *
+     * @example
+     * ```typescript
+     * const filter1 = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * const filter2 = BitStreamFilterAPI.create('dump_extra', stream);
+     * filter1.pipeTo(filter2).pipeTo(output, 0);
+     * ```
+     */
+    pipeTo(target: BitStreamFilterAPI): Scheduler<Packet>;
+    /**
+     * Pipe output to muxer.
+     *
+     * Terminal stage - writes filtered packets to output file.
+     *
+     * @param output - Muxer to write to
+     *
+     * @param streamIndex - Stream index in output
+     *
+     * @returns Control interface for pipeline
+     *
+     * @example
+     * ```typescript
+     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * const control = filter.pipeTo(output, 0);
+     * await control.send(packet);
+     * ```
+     */
+    pipeTo(output: Muxer, streamIndex: number): SchedulerControl<Packet>;
     /**
      * Flush all buffered packets as async generator.
      *
@@ -686,20 +754,6 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link flushPackets} For async version
      */
     flushPacketsSync(): Generator<Packet>;
-    /**
-     * Get associated stream.
-     *
-     * Returns the stream this filter was created for.
-     *
-     * @returns Associated stream
-     *
-     * @example
-     * ```typescript
-     * const stream = filter.getStream();
-     * console.log(`Filtering stream ${stream.index}`);
-     * ```
-     */
-    getStream(): Stream;
     /**
      * Reset filter state.
      *
@@ -748,6 +802,12 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link close} For manual cleanup
      */
     [Symbol.dispose](): void;
+    /**
+     * Bind input parameters from the source and initialize the filter.
+     *
+     * @internal
+     */
+    private ensureInitialized;
     /**
      * Send packet to input queue or flush the pipeline.
      *
@@ -765,7 +825,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @internal
      */
-    sendToQueue(packet: Packet | null): Promise<void>;
+    private sendToQueue;
     /**
      * Receive packet from output queue.
      *
@@ -773,48 +833,11 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @internal
      */
-    receiveFromQueue(): Promise<Packet | null>;
+    private receiveFromQueue;
     /**
      * Worker loop for push-based processing.
      *
      * @internal
      */
     private runWorker;
-    /**
-     * Pipe output to another bitstream filter.
-     *
-     * Starts background worker for packet processing.
-     * Packets flow through: input → this filter → target filter.
-     *
-     * @param target - Target bitstream filter
-     *
-     * @returns Scheduler for continued chaining
-     *
-     * @example
-     * ```typescript
-     * const filter1 = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
-     * const filter2 = BitStreamFilterAPI.create('dump_extra', stream);
-     * filter1.pipeTo(filter2).pipeTo(output, 0);
-     * ```
-     */
-    pipeTo(target: BitStreamFilterAPI): Scheduler<Packet>;
-    /**
-     * Pipe output to muxer.
-     *
-     * Terminal stage - writes filtered packets to output file.
-     *
-     * @param output - Muxer to write to
-     *
-     * @param streamIndex - Stream index in output
-     *
-     * @returns Control interface for pipeline
-     *
-     * @example
-     * ```typescript
-     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
-     * const control = filter.pipeTo(output, 0);
-     * await control.send(packet);
-     * ```
-     */
-    pipeTo(output: Muxer, streamIndex: number): SchedulerControl<Packet>;
 }