node-av 1.3.0 → 2.1.0

package/dist/api/decoder.d.ts

@@ -1,6 +1,6 @@
-import { CodecContext, Frame } from '../lib/index.js';
+import { Codec, CodecContext, Frame } from '../lib/index.js';
 import type { Packet, Stream } from '../lib/index.js';
-import type { DecoderOptions, StreamInfo } from './types.js';
+import type { DecoderOptions } from './types.js';
 /**
  * High-level decoder for audio and video streams.
  *
@@ -45,14 +45,19 @@ import type { DecoderOptions, StreamInfo } from './types.js';
  */
 export declare class Decoder implements Disposable {
     private codecContext;
+    private codec;
     private frame;
-    private streamIndex;
     private stream;
-    private isOpen;
+    private initialized;
+    private isClosed;
     private hardware?;
     /**
      * @param codecContext - Configured codec context
+     *
+     * @param codec - Codec being used
+     *
      * @param stream - Media stream being decoded
+     *
      * @param hardware - Optional hardware context
      * Use {@link create} factory method
      *
@@ -67,7 +72,9 @@ export declare class Decoder implements Disposable {
      * Applies custom codec options and threading configuration.
      *
      * @param stream - Media stream to decode
+     *
      * @param options - Decoder configuration options
+     *
      * @returns Configured decoder instance
      *
      * @throws {Error} If decoder not found for codec
@@ -120,36 +127,21 @@ export declare class Decoder implements Disposable {
      */
     get isDecoderOpen(): boolean;
     /**
-     * Get output stream information.
+     * Check if decoder has been initialized.
      *
-     * Returns format information about decoded frames.
-     * For hardware decoding, returns the hardware pixel format.
-     * Essential for configuring downstream components like encoders or filters.
+     * Returns true if decoder is initialized (true by default for decoders).
+     * Decoders are pre-initialized from stream parameters.
      *
-     * @returns Stream format information
+     * @returns true if decoder has been initialized
      *
      * @example
      * ```typescript
-     * const info = decoder.getOutputStreamInfo();
-     * if (info.type === 'video') {
-     *   console.log(`Video: ${info.width}x${info.height} @ ${info.pixelFormat}`);
-     *   console.log(`Frame rate: ${info.frameRate.num}/${info.frameRate.den}`);
+     * if (decoder.isDecoderInitialized) {
+     *   console.log('Decoder is ready to process frames');
      * }
      * ```
-     *
-     * @example
-     * ```typescript
-     * const info = decoder.getOutputStreamInfo();
-     * if (info.type === 'audio') {
-     *   console.log(`Audio: ${info.sampleRate}Hz ${info.sampleFormat}`);
-     *   console.log(`Channels: ${info.channelLayout}`);
-     * }
-     * ```
-     *
-     * @see {@link StreamInfo} For format details
-     * @see {@link Encoder.create} For matching encoder configuration
      */
-    getOutputStreamInfo(): StreamInfo;
+    get isDecoderInitialized(): boolean;
     /**
      * Check if decoder uses hardware acceleration.
      *
@@ -165,6 +157,19 @@ export declare class Decoder implements Disposable {
      * @see {@link HardwareContext} For hardware setup
      */
     isHardware(): boolean;
+    /**
+     * Check if decoder is ready for processing.
+     *
+     * @returns true if initialized and ready
+     *
+     * @example
+     * ```typescript
+     * if (decoder.isReady()) {
+     *   const frame = await decoder.decode(packet);
+     * }
+     * ```
+     */
+    isReady(): boolean;
     /**
      * Decode a packet to a frame.
      *
@@ -175,6 +180,7 @@ export declare class Decoder implements Disposable {
      * Direct mapping to avcodec_send_packet() and avcodec_receive_frame().
      *
      * @param packet - Compressed packet to decode
+     *
      * @returns Decoded frame or null if more data needed
      *
      * @throws {Error} If decoder is closed
@@ -193,7 +199,7 @@ export declare class Decoder implements Disposable {
      * @example
      * ```typescript
      * for await (const packet of input.packets()) {
-     *   if (packet.streamIndex === decoder.getStreamIndex()) {
+     *   if (packet.streamIndex === decoder.getStream().index) {
      *     const frame = await decoder.decode(packet);
      *     if (frame) {
      *       await processFrame(frame);
@@ -209,57 +215,32 @@ export declare class Decoder implements Disposable {
      */
     decode(packet: Packet): Promise<Frame | null>;
     /**
-     * Flush decoder and get buffered frame.
+     * Decode a packet to frame synchronously.
+     * Synchronous version of decode.
      *
-     * Signals end-of-stream and retrieves remaining frames.
-     * Call repeatedly until null to get all buffered frames.
-     * Essential for ensuring all frames are decoded.
+     * Send packet to decoder and attempt to receive frame.
+     * Handles decoder buffering and error conditions.
+     * May return null if decoder needs more data.
      *
-     * Direct mapping to avcodec_send_packet(NULL).
+     * @param packet - Compressed packet to decode
      *
-     * @returns Buffered frame or null if none remaining
+     * @returns Decoded frame or null
      *
      * @throws {Error} If decoder is closed
      *
-     * @example
-     * ```typescript
-     * // After all packets processed
-     * let frame;
-     * while ((frame = await decoder.flush()) !== null) {
-     *   console.log('Got buffered frame');
-     *   await processFrame(frame);
-     *   frame.free();
-     * }
-     * ```
-     *
-     * @see {@link flushFrames} For async iteration
-     * @see {@link frames} For complete decoding pipeline
-     */
-    flush(): Promise<Frame | null>;
-    /**
-     * Flush all buffered frames as async generator.
-     *
-     * Convenient async iteration over remaining frames.
-     * Automatically handles repeated flush calls.
-     * Useful for end-of-stream processing.
-     *
-     * @yields Buffered frames
-     * @throws {Error} If decoder is closed
+     * @throws {FFmpegError} If decoding fails
      *
      * @example
      * ```typescript
-     * // Flush at end of decoding
-     * for await (const frame of decoder.flushFrames()) {
-     *   console.log('Processing buffered frame');
-     *   await encoder.encode(frame);
-     *   frame.free();
+     * const frame = decoder.decodeSync(packet);
+     * if (frame) {
+     *   console.log(`Decoded: ${frame.width}x${frame.height}`);
      * }
      * ```
      *
-     * @see {@link flush} For single frame flush
-     * @see {@link frames} For complete pipeline
+     * @see {@link decode} For async version
      */
-    flushFrames(): AsyncGenerator<Frame>;
+    decodeSync(packet: Packet): Frame | null;
     /**
      * Decode packet stream to frame stream.
      *
@@ -269,7 +250,9 @@ export declare class Decoder implements Disposable {
      * Primary interface for stream-based decoding.
      *
      * @param packets - Async iterable of packets
-     * @yields Decoded frames
+     *
+     * @yields {Frame} Decoded frames
+     *
      * @throws {Error} If decoder is closed
      *
      * @throws {FFmpegError} If decoding fails
@@ -289,7 +272,7 @@ export declare class Decoder implements Disposable {
      * ```typescript
      * for await (const frame of decoder.frames(input.packets())) {
      *   // Process frame
-     *   await filter.filterFrame(frame);
+     *   await filter.process(frame);
      *
      *   // Frame automatically freed
      *   frame.free();
@@ -314,90 +297,263 @@ export declare class Decoder implements Disposable {
      */
     frames(packets: AsyncIterable<Packet>): AsyncGenerator<Frame>;
     /**
-     * Close decoder and free resources.
+     * Decode packet stream to frame stream synchronously.
+     * Synchronous version of frames.
      *
-     * Releases codec context and internal frame buffer.
-     * Safe to call multiple times.
-     * Automatically called by Symbol.dispose.
+     * High-level sync generator for complete decoding pipeline.
+     * Automatically filters packets for this stream, manages memory,
+     * and flushes buffered frames at end.
+     *
+     * @param packets - Iterable of packets
+     *
+     * @yields {Frame} Decoded frames
+     *
+     * @throws {Error} If decoder is closed
+     *
+     * @throws {FFmpegError} If decoding fails
      *
      * @example
      * ```typescript
-     * const decoder = await Decoder.create(stream);
-     * try {
-     *   // Use decoder
-     * } finally {
-     *   decoder.close();
+     * for (const frame of decoder.framesSync(packets)) {
+     *   console.log(`Frame: ${frame.width}x${frame.height}`);
+     *   // Process frame...
      * }
      * ```
      *
-     * @see {@link Symbol.dispose} For automatic cleanup
+     * @see {@link frames} For async version
      */
-    close(): void;
+    framesSync(packets: Iterable<Packet>): Generator<Frame>;
     /**
-     * Get stream index.
+     * Flush decoder and signal end-of-stream.
      *
-     * Returns the index of the stream being decoded.
-     * Used for packet filtering in multi-stream files.
+     * Sends null packet to decoder to signal end-of-stream.
+     * Does nothing if decoder is closed.
+     * Must use receive() or flushFrames() to get remaining buffered frames.
      *
-     * @returns Stream index
+     * Direct mapping to avcodec_send_packet(NULL).
+     *
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * if (packet.streamIndex === decoder.getStreamIndex()) {
-     *   const frame = await decoder.decode(packet);
+     * // Signal end of stream
+     * await decoder.flush();
+     *
+     * // Then get remaining frames
+     * let frame;
+     * while ((frame = await decoder.receive()) !== null) {
+     *   console.log('Got buffered frame');
+     *   frame.free();
      * }
      * ```
      *
-     * @see {@link getStream} For full stream object
+     * @see {@link flushFrames} For convenient async iteration
+     * @see {@link receive} For getting buffered frames
      */
-    getStreamIndex(): number;
+    flush(): Promise<void>;
     /**
-     * Get stream object.
+     * Flush decoder and signal end-of-stream synchronously.
+     * Synchronous version of flush.
      *
-     * Returns the underlying stream being decoded.
-     * Provides access to stream metadata and parameters.
+     * Send null packet to signal end of input stream.
+     * Decoder may still have buffered frames.
+     * Call receiveSync() repeatedly to get remaining frames.
      *
-     * @returns Stream object
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * const stream = decoder.getStream();
-     * console.log(`Duration: ${stream.duration}`);
-     * console.log(`Time base: ${stream.timeBase.num}/${stream.timeBase.den}`);
+     * decoder.flushSync();
+     * // Get remaining frames
+     * let frame;
+     * while ((frame = decoder.receiveSync()) !== null) {
+     *   console.log('Buffered frame');
+     * }
      * ```
      *
-     * @see {@link Stream} For stream properties
-     * @see {@link getStreamIndex} For index only
+     * @see {@link flush} For async version
      */
-    getStream(): Stream;
+    flushSync(): void;
     /**
-     * Get underlying codec context.
+     * Flush all buffered frames as async generator.
      *
-     * Returns the internal codec context for advanced operations.
-     * Returns null if decoder is closed.
+     * Convenient async iteration over remaining frames.
+     * Automatically sends flush signal and retrieves buffered frames.
+     * Useful for end-of-stream processing.
      *
-     * @returns Codec context or null
+     * @yields {Frame} Buffered frames
      *
-     * @internal
+     * @example
+     * ```typescript
+     * // Flush at end of decoding
+     * for await (const frame of decoder.flushFrames()) {
+     *   console.log('Processing buffered frame');
+     *   await encoder.encode(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link flush} For signaling end-of-stream
+     * @see {@link frames} For complete pipeline
      */
-    getCodecContext(): CodecContext | null;
+    flushFrames(): AsyncGenerator<Frame>;
+    /**
+     * Flush all buffered frames as generator synchronously.
+     * Synchronous version of flushFrames.
+     *
+     * Convenient sync iteration over remaining frames.
+     * Automatically sends flush signal and retrieves buffered frames.
+     * Useful for end-of-stream processing.
+     *
+     * @yields {Frame} Buffered frames
+     *
+     * @example
+     * ```typescript
+     * // Flush at end of decoding
+     * for (const frame of decoder.flushFramesSync()) {
+     *   console.log('Processing buffered frame');
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link flushFrames} For async version
+     */
+    flushFramesSync(): Generator<Frame>;
     /**
      * Receive frame from decoder.
      *
-     * Internal method to get decoded frames from codec.
+     * 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.
      *
      * Direct mapping to avcodec_receive_frame().
      *
-     * @returns Cloned frame or null
+     * @returns Cloned frame or null if no frames available
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
+     * @example
+     * ```typescript
+     * const frame = await decoder.receive();
+     * if (frame) {
+     *   console.log('Got decoded frame');
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered frames
+     * let frame;
+     * while ((frame = await decoder.receive()) !== null) {
+     *   console.log(`Frame PTS: ${frame.pts}`);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link decode} For sending packets and receiving frames
+     * @see {@link flush} For signaling end-of-stream
+     */
+    receive(): Promise<Frame | null>;
+    /**
+     * Receive frame from decoder synchronously.
+     * Synchronous version of receive.
+     *
+     * 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.
+     *
+     * Direct mapping to avcodec_receive_frame().
+     *
+     * @returns Cloned frame or null if no frames available
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
+     *
+     * @example
+     * ```typescript
+     * const frame = decoder.receiveSync();
+     * if (frame) {
+     *   console.log('Got decoded frame');
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered frames
+     * let frame;
+     * while ((frame = decoder.receiveSync()) !== null) {
+     *   console.log(`Frame PTS: ${frame.pts}`);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link receive} For async version
+     */
+    receiveSync(): Frame | null;
+    /**
+     * Close decoder and free resources.
+     *
+     * Releases codec context and internal frame buffer.
+     * Safe to call multiple times.
+     * Automatically called by Symbol.dispose.
+     *
+     * @example
+     * ```typescript
+     * const decoder = await Decoder.create(stream);
+     * try {
+     *   // Use decoder
+     * } finally {
+     *   decoder.close();
+     * }
+     * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
+     */
+    close(): void;
+    /**
+     * Get stream object.
+     *
+     * Returns the underlying stream being decoded.
+     * Provides access to stream metadata and parameters.
+     *
+     * @returns Stream object
+     *
      * @internal
      *
+     * @see {@link Stream} For stream details
      */
-    private receiveFrameInternal;
+    getStream(): Stream;
+    /**
+     * Get decoder codec.
+     *
+     * Returns the codec used by this decoder.
+     * Useful for checking codec capabilities and properties.
+     *
+     * @returns Codec instance
+     *
+     * @internal
+     *
+     * @see {@link Codec} For codec details
+     */
+    getCodec(): Codec;
+    /**
+     * Get underlying codec context.
+     *
+     * Returns the codec context for advanced operations.
+     * Useful for accessing low-level codec properties and settings.
+     * Returns null if decoder is closed.
+     *
+     * @returns Codec context or null if closed
+     *
+     * @internal
+     *
+     * @see {@link CodecContext} For context details
+     */
+    getCodecContext(): CodecContext | null;
     /**
      * Dispose of decoder.
      *