node-av 4.0.0 → 5.0.1

package/dist/api/decoder.d.ts

@@ -1,9 +1,9 @@
 import { CodecContext } from '../lib/codec-context.js';
 import { Codec } from '../lib/codec.js';
 import { Frame } from '../lib/frame.js';
+import { Packet } from '../lib/packet.js';
 import { Scheduler } from './utilities/scheduler.js';
-import type { AVCodecID, FFDecoderCodec } from '../constants/index.js';
-import type { Packet } from '../lib/packet.js';
+import type { AVCodecID, EOFSignal, FFDecoderCodec } from '../constants/index.js';
 import type { Stream } from '../lib/stream.js';
 import type { Encoder } from './encoder.js';
 import type { FilterAPI } from './filter.js';
@@ -259,28 +259,31 @@ export declare class Decoder implements Disposable {
      */
     isReady(): boolean;
     /**
-     * Decode a packet to a frame.
+     * Send a packet to the decoder.
      *
-     * Sends a packet to the decoder and attempts to receive a decoded frame.
-     * Handles internal buffering - may return null if more packets needed.
+     * Sends a compressed packet to the decoder for decoding.
+     * Does not return decoded frames - use {@link receive} to retrieve frames.
+     * A single packet can produce zero, one, or multiple frames depending on codec buffering.
      * Automatically manages decoder state and error recovery.
      *
-     * **Note**: This method receives only ONE frame per call.
-     * A single packet can produce multiple frames (e.g., packed B-frames, codec buffering).
-     * To receive all frames from a packet, use {@link decodeAll} or {@link frames} instead.
+     * **Important**: This method only SENDS the packet to the decoder.
+     * You must call {@link receive} separately (potentially multiple times) to get decoded frames.
      *
-     * Direct mapping to avcodec_send_packet() and avcodec_receive_frame().
-     *
-     * @param packet - Compressed packet to decode
+     * Direct mapping to avcodec_send_packet().
      *
-     * @returns Decoded frame or null if more data needed or decoder is closed
+     * @param packet - Compressed packet to send to decoder
      *
-     * @throws {FFmpegError} If decoding fails
+     * @throws {FFmpegError} If sending packet fails
      *
      * @example
      * ```typescript
-     * const frame = await decoder.decode(packet);
-     * if (frame) {
+     * // Send packet and receive frames
+     * await decoder.decode(packet);
+     *
+     * // Receive all available frames
+     * while (true) {
+     *   const frame = await decoder.receive();
+     *   if (!frame) break;
      *   console.log(`Decoded frame with PTS: ${frame.pts}`);
      *   frame.free();
      * }
@@ -290,8 +293,12 @@ export declare class Decoder implements Disposable {
      * ```typescript
      * for await (const packet of input.packets()) {
      *   if (packet.streamIndex === decoder.getStream().index) {
-     *     const frame = await decoder.decode(packet);
-     *     if (frame) {
+     *     // Send packet
+     *     await decoder.decode(packet);
+     *
+     *     // Receive available frames
+     *     let frame;
+     *     while ((frame = await decoder.receive())) {
      *       await processFrame(frame);
      *       frame.free();
      *     }
@@ -300,44 +307,70 @@ export declare class Decoder implements Disposable {
      * }
      * ```
      *
-     * @see {@link decodeAll} For multiple frame decoding
+     * @see {@link receive} For receiving decoded frames
+     * @see {@link decodeAll} For combined send+receive operation
      * @see {@link frames} For automatic packet iteration
      * @see {@link flush} For end-of-stream handling
      * @see {@link decodeSync} For synchronous version
      */
-    decode(packet: Packet): Promise<Frame | null>;
+    decode(packet: Packet): Promise<void>;
     /**
-     * Decode a packet to frame synchronously.
+     * Send a packet to the decoder synchronously.
      * Synchronous version of decode.
      *
-     * Send packet to decoder and attempt to receive frame.
-     * Handles decoder buffering and error conditions.
-     * May return null if decoder needs more data.
+     * Sends a compressed packet to the decoder for decoding.
+     * Does not return decoded frames - use {@link receiveSync} to retrieve frames.
+     * A single packet can produce zero, one, or multiple frames depending on codec buffering.
+     * Automatically manages decoder state and error recovery.
      *
-     * **Note**: This method receives only ONE frame per call.
-     * A single packet can produce multiple frames (e.g., packed B-frames, codec buffering).
-     * To receive all frames from a packet, use {@link decodeAllSync} or {@link framesSync} instead.
+     * **Important**: This method only SENDS the packet to the decoder.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get decoded frames.
      *
-     * @param packet - Compressed packet to decode
+     * Direct mapping to avcodec_send_packet().
      *
-     * @returns Decoded frame or null if more data needed or decoder is closed
+     * @param packet - Compressed packet to send to decoder
      *
-     * @throws {FFmpegError} If decoding fails
+     * @throws {FFmpegError} If sending packet fails
      *
      * @example
      * ```typescript
-     * const frame = decoder.decodeSync(packet);
-     * if (frame) {
-     *   console.log(`Decoded: ${frame.width}x${frame.height}`);
+     * // Send packet and receive frames
+     * await decoder.decode(packet);
+     *
+     * // Receive all available frames
+     * while (true) {
+     *   const frame = await decoder.receive();
+     *   if (!frame) break;
+     *   console.log(`Decoded frame with PTS: ${frame.pts}`);
+     *   frame.free();
      * }
      * ```
      *
-     * @see {@link decodeAllSync} For multiple frame decoding
+     * @example
+     * ```typescript
+     * for await (const packet of input.packets()) {
+     *   if (packet.streamIndex === decoder.getStream().index) {
+     *     // Send packet
+     *     await decoder.decode(packet);
+     *
+     *     // Receive available frames
+     *     let frame;
+     *     while ((frame = await decoder.receive())) {
+     *       await processFrame(frame);
+     *       frame.free();
+     *     }
+     *   }
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link receiveSync} For receiving decoded frames
+     * @see {@link decodeAllSync} For combined send+receive operation
      * @see {@link framesSync} For automatic packet iteration
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link decode} For async version
      */
-    decodeSync(packet: Packet): Frame | null;
+    decodeSync(packet: Packet): void;
     /**
      * Decode a packet to frames.
      *
@@ -366,12 +399,10 @@ export declare class Decoder implements Disposable {
      * @example
      * ```typescript
      * for await (const packet of input.packets()) {
-     *   if (packet.streamIndex === decoder.getStream().index) {
-     *     const frames = await decoder.decodeAll(packet);
-     *     for (const frame of frames) {
-     *       await processFrame(frame);
-     *       frame.free();
-     *     }
+     *   const frames = await decoder.decodeAll(packet);
+     *   for (const frame of frames) {
+     *     await processFrame(frame);
+     *     frame.free();
      *   }
      *   packet.free();
      * }
@@ -382,7 +413,7 @@ export declare class Decoder implements Disposable {
      * @see {@link flush} For end-of-stream handling
      * @see {@link decodeAllSync} For synchronous version
      */
-    decodeAll(packet: Packet): Promise<Frame[]>;
+    decodeAll(packet: Packet | null): Promise<Frame[]>;
     /**
      * Decode a packet to frames synchronously.
      * Synchronous version of decodeAll.
@@ -404,6 +435,17 @@ export declare class Decoder implements Disposable {
      *   console.log(`Decoded: ${frame.width}x${frame.height}`);
      *   frame.free();
      * }
+     *
+     * @example
+     * ```typescript
+     * for (const packet of input.packetsSync()) {
+     *   const frames = await decoder.decodeAllSync(packet);
+     *   for (const frame of frames) {
+     *     processFrame(frame);
+     *     frame.free();
+     *   }
+     *   packet.free();
+     * }
      * ```
      *
      * @see {@link decodeSync} For single packet decoding
@@ -411,18 +453,22 @@ export declare class Decoder implements Disposable {
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link decodeAll} For async version
      */
-    decodeAllSync(packet: Packet): Frame[];
+    decodeAllSync(packet: Packet | null): Frame[];
     /**
      * Decode packet stream to frame stream.
      *
      * High-level async generator for complete decoding pipeline.
-     * Automatically filters packets for this stream, manages memory,
-     * and flushes buffered frames at end.
+     * Decoder is only flushed when EOF (null) signal is explicitly received.
      * Primary interface for stream-based decoding.
      *
-     * @param packets - Async iterable of packets
+     * **EOF Handling:**
+     * - Send null to flush decoder and get remaining buffered frames
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - decoder stays open until EOF or close()
      *
-     * @yields {Frame} Decoded frames
+     * @param packets - Async iterable of packets, single packet, or null to flush
+     *
+     * @yields {Frame | null} Decoded frames, followed by null when explicitly flushed
      *
      * @throws {Error} If decoder is closed
      *
@@ -430,10 +476,15 @@ export declare class Decoder implements Disposable {
      *
      * @example
      * ```typescript
+     * // Stream of packets with automatic EOF propagation
      * await using input = await Demuxer.open('video.mp4');
      * using decoder = await Decoder.create(input.video());
      *
      * for await (const frame of decoder.frames(input.packets())) {
+     *   if (frame === null) {
+     *     console.log('Decoding complete');
+     *     break;
+     *   }
      *   console.log(`Frame: ${frame.width}x${frame.height}`);
      *   frame.free();
      * }
@@ -441,44 +492,53 @@ export declare class Decoder implements Disposable {
      *
      * @example
      * ```typescript
-     * for await (const frame of decoder.frames(input.packets())) {
-     *   // Process frame
-     *   await filter.process(frame);
-     *
-     *   // Frame automatically freed
+     * // Single packet (no automatic flush)
+     * for await (const frame of decoder.frames(singlePacket)) {
+     *   await encoder.encode(frame);
+     *   frame.free();
+     * }
+     * // Decoder still has buffered frames - send null to flush
+     * for await (const frame of decoder.frames(null)) {
+     *   if (frame === null) break;
+     *   await encoder.encode(frame);
      *   frame.free();
      * }
      * ```
      *
      * @example
      * ```typescript
-     * import { pipeline } from 'node-av/api';
-     *
-     * const control = pipeline(
-     *   input,
-     *   decoder,
-     *   encoder,
-     *   output
-     * );
-     * await control.completion;
+     * // Explicit flush with EOF
+     * for await (const frame of decoder.frames(null)) {
+     *   if (frame === null) {
+     *     console.log('All buffered frames flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered frame:', frame.pts);
+     *   frame.free();
+     * }
      * ```
      *
      * @see {@link decode} For single packet decoding
      * @see {@link Demuxer.packets} For packet source
      * @see {@link framesSync} For sync version
      */
-    frames(packets: AsyncIterable<Packet | null>): AsyncGenerator<Frame | null>;
+    frames(packets: AsyncIterable<Packet | null> | Packet | null): AsyncGenerator<Frame | null>;
     /**
      * Decode packet stream to frame stream synchronously.
      * Synchronous version of frames.
      *
-     * High-level sync generator for complete decoding pipeline.
-     * Automatically filters packets for this stream, manages memory,
-     * and flushes buffered frames at end.
+     * High-level async generator for complete decoding pipeline.
+     * Decoder is only flushed when EOF (null) signal is explicitly received.
+     * Primary interface for stream-based decoding.
+     *
+     * **EOF Handling:**
+     * - Send null to flush decoder and get remaining buffered frames
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - decoder stays open until EOF or close()
      *
-     * @param packets - Iterable of packets
+     * @param packets - Iterable of packets, single packet, or null to flush
      *
-     * @yields {Frame} Decoded frames
+     * @yields {Frame | null} Decoded frames, followed by null when explicitly flushed
      *
      * @throws {Error} If decoder is closed
      *
@@ -486,17 +546,49 @@ export declare class Decoder implements Disposable {
      *
      * @example
      * ```typescript
-     * for (const frame of decoder.framesSync(packets)) {
+     * // Stream of packets with automatic EOF propagation
+     * await using input = await Demuxer.open('video.mp4');
+     * using decoder = await Decoder.create(input.video());
+     *
+     * for (const frame of decoder.framesSync(input.packetsSync())) {
+     *   if (frame === null) {
+     *     console.log('Decoding complete');
+     *     break;
+     *   }
      *   console.log(`Frame: ${frame.width}x${frame.height}`);
-     *   // Process frame...
+     *   frame.free();
      * }
      * ```
      *
-     * @see {@link decodeSync} For single packet decoding
-     * @see {@link Demuxer.packetsSync} For packet source
-     * @see {@link frames} For async version
+     * @example
+     * ```typescript
+     * // Single packet (no automatic flush)
+     * for (const frame of decoder.framesSync(singlePacket)) {
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * // Decoder still has buffered frames - send null to flush
+     * for (const frame of decoder.framesSync(null)) {
+     *   if (frame === null) break;
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Explicit flush with EOF
+     * for (const frame of decoder.framesSync(null)) {
+     *   if (frame === null) {
+     *     console.log('All buffered frames flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered frame:', frame.pts);
+     *   frame.free();
+     * }
+     * ```
      */
-    framesSync(packets: Iterable<Packet | null>): Generator<Frame | null>;
+    framesSync(packets: Iterable<Packet | null> | Packet | null): Generator<Frame | null>;
     /**
      * Flush decoder and signal end-of-stream.
      *
@@ -606,38 +698,48 @@ export declare class Decoder implements Disposable {
      * Gets decoded frames from the codec's internal buffer.
      * Handles frame cloning and error checking.
      * Hardware frames include hw_frames_ctx reference.
-     * Call repeatedly until null to drain all buffered frames.
+     * Call repeatedly to drain all buffered frames.
+     *
+     * **Return Values:**
+     * - `Frame` - Successfully decoded frame
+     * - `null` - No frame available (AVERROR_EAGAIN), send more packets
+     * - `undefined` - End of stream reached (AVERROR_EOF), decoder flushed
      *
      * Direct mapping to avcodec_receive_frame().
      *
-     * @returns Cloned frame or null if no frames available
+     * @returns Decoded frame, null (need more data), or undefined (end of stream)
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
      * const frame = await decoder.receive();
-     * if (frame) {
+     * if (frame === EOF) {
+     *   console.log('Decoder flushed, no more frames');
+     * } else if (frame) {
      *   console.log('Got decoded frame');
      *   frame.free();
+     * } else {
+     *   console.log('Need more packets');
      * }
      * ```
      *
      * @example
      * ```typescript
-     * // Drain all buffered frames
+     * // Drain all buffered frames (stop on null or EOF)
      * let frame;
-     * while ((frame = await decoder.receive()) !== null) {
+     * while ((frame = await decoder.receive()) && frame !== EOF) {
      *   console.log(`Frame PTS: ${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link decode} For sending packets and receiving frames
+     * @see {@link decode} For sending packets
      * @see {@link flush} For signaling end-of-stream
      * @see {@link receiveSync} For synchronous version
+     * @see {@link EOF} For end-of-stream signal
      */
-    receive(): Promise<Frame | null>;
+    receive(): Promise<Frame | EOFSignal | null>;
     /**
      * Receive frame from decoder synchronously.
      * Synchronous version of receive.
@@ -645,38 +747,48 @@ export declare class Decoder implements Disposable {
      * Gets decoded frames from the codec's internal buffer.
      * Handles frame cloning and error checking.
      * Hardware frames include hw_frames_ctx reference.
-     * Call repeatedly until null to drain all buffered frames.
+     * Call repeatedly to drain all buffered frames.
+     *
+     * **Return Values:**
+     * - `Frame` - Successfully decoded frame
+     * - `null` - No frame available (AVERROR_EAGAIN), send more packets
+     * - `undefined` - End of stream reached (AVERROR_EOF), decoder flushed
      *
      * Direct mapping to avcodec_receive_frame().
      *
-     * @returns Cloned frame or null if no frames available
+     * @returns Decoded frame, null (need more data), or undefined (end of stream)
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
      * const frame = decoder.receiveSync();
-     * if (frame) {
+     * if (frame === EOF) {
+     *   console.log('Decoder flushed, no more frames');
+     * } else if (frame) {
      *   console.log('Got decoded frame');
      *   frame.free();
+     * } else {
+     *   console.log('Need more packets');
      * }
      * ```
      *
      * @example
      * ```typescript
-     * // Drain all buffered frames
+     * // Drain all buffered frames (stop on null or EOF)
      * let frame;
-     * while ((frame = decoder.receiveSync()) !== null) {
+     * while ((frame = decoder.receiveSync()) && frame !== EOF) {
      *   console.log(`Frame PTS: ${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link decodeSync} For sending packets and receiving frames
+     * @see {@link decodeSync} For sending packets
      * @see {@link flushSync} For signaling end-of-stream
      * @see {@link receive} For async version
+     * @see {@link EOF} For end-of-stream signal
      */
-    receiveSync(): Frame | null;
+    receiveSync(): Frame | EOFSignal | null;
     /**
      * Pipe decoded frames to a filter component or encoder.
      *
@@ -758,9 +870,20 @@ export declare class Decoder implements Disposable {
      */
     private runWorker;
     /**
-     * Send packet to input queue.
+     * Send packet to input queue or flush the pipeline.
+     *
+     * When packet is provided, queues it for processing.
+     * When null is provided, triggers flush sequence:
+     * - Closes input queue
+     * - Waits for worker completion
+     * - Flushes decoder and sends remaining frames to output queue
+     * - Closes output queue
+     * - Waits for pipeTo task completion
+     * - Propagates flush to next component (if any)
+     *
+     * Used by scheduler system for pipeline control.
      *
-     * @param packet - Packet to send
+     * @param packet - Packet to send, or null to flush
      *
      * @internal
      */
@@ -773,14 +896,6 @@ export declare class Decoder implements Disposable {
      * @internal
      */
     private receiveFromQueue;
-    /**
-     * Flush the entire filter pipeline.
-     *
-     * Propagates flush through worker, output queue, and next component.
-     *
-     * @internal
-     */
-    private flushPipeline;
     /**
      * Estimate video frame duration.
      *