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

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

@@ -1,8 +1,9 @@
 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 { BsfOptionsFor } from '../constants/index.js';
-import type { Stream } from '../lib/stream.js';
+import type { BsfName, BsfOptionsFor } from '../constants/index.js';
 /**
  * Options for bitstream filter creation.
  *
@@ -68,7 +69,8 @@ export interface BitstreamFilterOptions<N extends string = string> {
 export declare class BitStreamFilterAPI implements Disposable {
     private ctx;
     private bsf;
-    private stream;
+    private source;
+    private initialized;
     private packet;
     private isClosed;
     private inputQueue;
@@ -82,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.
      *
-     * Initializes filter with stream codec parameters.
-     * Configures time base and prepares for packet processing.
+     * 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.
+     *
+     * 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<const N extends string = string>(filterName: N, stream: Stream, filterOptions?: BitstreamFilterOptions<N>): BitStreamFilterAPI;
+    static create<const N extends BsfName | (string & {}) = BsfName | (string & {})>(filterName: N, source: Stream | Encoder | BitStreamFilterAPI, filterOptions?: BitstreamFilterOptions<N>): BitStreamFilterAPI;
     /**
      * Get filter name.
      *
@@ -184,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.
      *
@@ -642,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.
      *
@@ -691,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.
      *
@@ -753,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.
      *
@@ -770,7 +825,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @internal
      */
-    sendToQueue(packet: Packet | null): Promise<void>;
+    private sendToQueue;
     /**
      * Receive packet from output queue.
      *
@@ -778,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>;
 }

package/dist/api/bitstream-filter.js

@@ -55,7 +55,9 @@ import { BitStreamFilterContext } from '../lib/bitstream-filter-context.js';
 import { BitStreamFilter } from '../lib/bitstream-filter.js';
 import { FFmpegError } from '../lib/error.js';
 import { Packet } from '../lib/packet.js';
+import { Stream } from '../lib/stream.js';
 import { PACKET_THREAD_QUEUE_SIZE } from './constants.js';
+import { Encoder } from './encoder.js';
 import { Muxer } from './muxer.js';
 import { AsyncQueue } from './utilities/async-queue.js';
 import { Scheduler, SchedulerControl } from './utilities/scheduler.js';
@@ -101,7 +103,8 @@ import { Scheduler, SchedulerControl } from './utilities/scheduler.js';
 export class BitStreamFilterAPI {
     ctx;
     bsf;
-    stream;
+    source;
+    initialized = false;
     packet;
     isClosed = false;
     // Worker pattern for push-based processing
@@ -116,73 +119,66 @@ export class BitStreamFilterAPI {
      *
      * @param ctx - Filter context
      *
-     * @param stream - Associated stream
+     * @param source - Input source for lazy parameter resolution
      *
      * @internal
      */
-    constructor(bsf, ctx, stream) {
+    constructor(bsf, ctx, source) {
         this.bsf = bsf;
         this.ctx = ctx;
-        this.stream = stream;
+        this.source = source;
         this.packet = new Packet();
         this.packet.alloc();
         this.inputQueue = new AsyncQueue(PACKET_THREAD_QUEUE_SIZE);
         this.outputQueue = new AsyncQueue(PACKET_THREAD_QUEUE_SIZE);
     }
     /**
-     * Create a bitstream filter for a stream.
+     * Create a bitstream filter.
      *
-     * Initializes filter with stream codec parameters.
-     * Configures time base and prepares for packet processing.
+     * 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.
+     *
+     * 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, stream, filterOptions) {
-        if (!stream) {
-            throw new Error('Stream is required');
+    // eslint-disable-next-line space-before-function-paren
+    static create(filterName, source, filterOptions) {
+        if (!source) {
+            throw new Error('A source (Stream, Encoder, or BitStreamFilterAPI) is required');
         }
         // Find the bitstream filter
         const filter = BitStreamFilter.getByName(filterName);
@@ -194,24 +190,15 @@ export class BitStreamFilterAPI {
         const allocRet = ctx.alloc(filter);
         FFmpegError.throwIfError(allocRet, 'Failed to allocate bitstream filter context');
         try {
-            // Copy codec parameters from stream
-            if (!ctx.inputCodecParameters) {
-                throw new Error('Failed to get input codec parameters from filter context');
-            }
-            stream.codecpar.copy(ctx.inputCodecParameters);
-            // Set time base
-            ctx.inputTimeBase = stream.timeBase;
-            // Apply filter-specific options before init
+            // Apply (and validate) filter-specific options now; input parameters and
+            // init() are deferred to ensureInitialized() on the first packet.
             if (filterOptions?.options) {
                 for (const [key, value] of Object.entries(filterOptions.options)) {
                     const ret = ctx.setOption(key, value);
                     FFmpegError.throwIfError(ret, `Failed to set bitstream filter option '${key}'`);
                 }
             }
-            // Initialize the filter
-            const initRet = ctx.init();
-            FFmpegError.throwIfError(initRet, 'Failed to initialize bitstream filter');
-            const bsfApi = new BitStreamFilterAPI(filter, ctx, stream);
+            const bsfApi = new BitStreamFilterAPI(filter, ctx, source);
             if (filterOptions?.signal) {
                 filterOptions.signal.throwIfAborted();
                 bsfApi.signal = filterOptions.signal;
@@ -277,6 +264,45 @@ export class BitStreamFilterAPI {
     get isBitstreamFilterOpen() {
         return !this.isClosed;
     }
+    /**
+     * 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() {
+        return this.initialized;
+    }
+    /**
+     * 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() {
+        if (!(this.source instanceof Stream)) {
+            throw new Error('No associated stream: this bitstream filter derives its parameters from an upstream component');
+        }
+        return this.source;
+    }
     /**
      * Send a packet to the filter.
      *
@@ -334,6 +360,7 @@ export class BitStreamFilterAPI {
         if (this.isClosed) {
             return;
         }
+        this.ensureInitialized();
         // Send packet to filter (null signals EOF/flush)
         const sendRet = await this.ctx.sendPacket(packet);
         if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
@@ -397,6 +424,7 @@ export class BitStreamFilterAPI {
         if (this.isClosed) {
             return;
         }
+        this.ensureInitialized();
         // Send packet to filter (null signals EOF/flush)
         const sendRet = this.ctx.sendPacketSync(packet);
         if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
@@ -748,7 +776,7 @@ export class BitStreamFilterAPI {
      */
     async flush() {
         this.signal?.throwIfAborted();
-        if (this.isClosed) {
+        if (this.isClosed || !this.initialized) {
             return;
         }
         // Send EOF
@@ -791,7 +819,7 @@ export class BitStreamFilterAPI {
      * @see {@link flush} For async version
      */
     flushSync() {
-        if (this.isClosed) {
+        if (this.isClosed || !this.initialized) {
             return;
         }
         // Send EOF
@@ -844,7 +872,7 @@ export class BitStreamFilterAPI {
      * @see {@link receiveSync} For synchronous version
      */
     async receive() {
-        if (this.isClosed) {
+        if (this.isClosed || !this.initialized) {
             return null;
         }
         // Clear previous packet data
@@ -911,7 +939,7 @@ export class BitStreamFilterAPI {
      * @see {@link receive} For async version
      */
     receiveSync() {
-        if (this.isClosed) {
+        if (this.isClosed || !this.initialized) {
             return null;
         }
         // Clear previous packet data
@@ -935,6 +963,42 @@ export class BitStreamFilterAPI {
             return null;
         }
     }
+    pipeTo(target, streamIndex) {
+        if (target instanceof Muxer) {
+            // Start worker if not already running
+            this.workerPromise ??= this.runWorker();
+            // Start pipe task: filter.outputQueue -> output
+            this.pipeToPromise = (async () => {
+                while (true) {
+                    const packet = await this.receiveFromQueue();
+                    if (!packet)
+                        break;
+                    await target.writePacket(packet, streamIndex);
+                }
+            })();
+            // Return control without pipeTo (terminal stage)
+            return new SchedulerControl(this);
+        }
+        else {
+            // BitStreamFilterAPI
+            const t = target;
+            // Store reference to next component for flush propagation
+            this.nextComponent = t;
+            // Start worker if not already running
+            this.workerPromise ??= this.runWorker();
+            // Start pipe task: filter.outputQueue -> target.inputQueue (via target.send)
+            this.pipeToPromise = (async () => {
+                while (true) {
+                    const packet = await this.receiveFromQueue();
+                    if (!packet)
+                        break;
+                    await t.sendToQueue(packet);
+                }
+            })();
+            // Return scheduler for chaining (target is now the last component)
+            return new Scheduler(this, t);
+        }
+    }
     /**
      * Flush all buffered packets as async generator.
      *
@@ -998,22 +1062,6 @@ export class BitStreamFilterAPI {
             yield 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() {
-        return this.stream;
-    }
     /**
      * Reset filter state.
      *
@@ -1079,6 +1127,50 @@ export class BitStreamFilterAPI {
     [Symbol.dispose]() {
         this.close();
     }
+    /**
+     * Bind input parameters from the source and initialize the filter.
+     *
+     * @internal
+     */
+    ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        const params = this.ctx.inputCodecParameters;
+        if (!params) {
+            throw new Error('Failed to get input codec parameters from filter context');
+        }
+        const source = this.source;
+        if (source instanceof Stream) {
+            source.codecpar.copy(params);
+            this.ctx.inputTimeBase = source.timeBase;
+        }
+        else if (source instanceof Encoder) {
+            const codecContext = source.getCodecContext();
+            if (!codecContext) {
+                throw new Error('Encoder is not initialized yet; cannot derive bitstream filter parameters.');
+            }
+            const ret = params.fromContext(codecContext);
+            FFmpegError.throwIfError(ret, 'Failed to derive bitstream filter parameters from encoder');
+            this.ctx.inputTimeBase = codecContext.timeBase;
+        }
+        else {
+            // Upstream is another bitstream filter: chain from its output.
+            source.ensureInitialized();
+            const upstream = source.outputCodecParameters;
+            if (!upstream) {
+                throw new Error('Upstream bitstream filter has no output parameters.');
+            }
+            upstream.copy(params);
+            const tb = source.outputTimeBase;
+            if (tb) {
+                this.ctx.inputTimeBase = tb;
+            }
+        }
+        const initRet = this.ctx.init();
+        FFmpegError.throwIfError(initRet, 'Failed to initialize bitstream filter');
+        this.initialized = true;
+    }
     /**
      * Send packet to input queue or flush the pipeline.
      *
@@ -1146,6 +1238,7 @@ export class BitStreamFilterAPI {
                     if (this.isClosed) {
                         break;
                     }
+                    this.ensureInitialized();
                     // Send packet to filter
                     const sendRet = await this.ctx.sendPacket(packet);
                     // Handle EAGAIN
@@ -1202,41 +1295,5 @@ export class BitStreamFilterAPI {
             this.outputQueue?.close();
         }
     }
-    pipeTo(target, streamIndex) {
-        if (target instanceof Muxer) {
-            // Start worker if not already running
-            this.workerPromise ??= this.runWorker();
-            // Start pipe task: filter.outputQueue -> output
-            this.pipeToPromise = (async () => {
-                while (true) {
-                    const packet = await this.receiveFromQueue();
-                    if (!packet)
-                        break;
-                    await target.writePacket(packet, streamIndex);
-                }
-            })();
-            // Return control without pipeTo (terminal stage)
-            return new SchedulerControl(this);
-        }
-        else {
-            // BitStreamFilterAPI
-            const t = target;
-            // Store reference to next component for flush propagation
-            this.nextComponent = t;
-            // Start worker if not already running
-            this.workerPromise ??= this.runWorker();
-            // Start pipe task: filter.outputQueue -> target.inputQueue (via target.send)
-            this.pipeToPromise = (async () => {
-                while (true) {
-                    const packet = await this.receiveFromQueue();
-                    if (!packet)
-                        break;
-                    await t.sendToQueue(packet);
-                }
-            })();
-            // Return scheduler for chaining (target is now the last component)
-            return new Scheduler(this, t);
-        }
-    }
 }
 //# sourceMappingURL=bitstream-filter.js.map