node-av 1.3.0 → 2.1.0

package/dist/api/decoder.js

@@ -1,5 +1,5 @@
-import { AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
-import { Codec, CodecContext, FFmpegError, Frame } from '../lib/index.js';
+import { AVERROR_EAGAIN, AVERROR_EOF } from '../constants/constants.js';
+import { Codec, CodecContext, Dictionary, FFmpegError, Frame } from '../lib/index.js';
 /**
  * High-level decoder for audio and video streams.
  *
@@ -44,23 +44,28 @@ import { Codec, CodecContext, FFmpegError, Frame } from '../lib/index.js';
  */
 export class Decoder {
     codecContext;
+    codec;
     frame;
-    streamIndex;
     stream;
-    isOpen = true;
+    initialized = true;
+    isClosed = false;
     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
      *
      * @internal
      */
-    constructor(codecContext, stream, hardware) {
+    constructor(codecContext, codec, stream, hardware) {
         this.codecContext = codecContext;
+        this.codec = codec;
         this.stream = stream;
-        this.streamIndex = stream.index;
         this.hardware = hardware;
         this.frame = new Frame();
         this.frame.alloc();
@@ -73,7 +78,9 @@ export class Decoder {
      * 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
@@ -142,20 +149,14 @@ export class Decoder {
         if (isHWDecoder && options.hardware) {
             codecContext.hwDeviceCtx = options.hardware.deviceContext;
         }
-        // Apply codec-specific options via AVOptions
-        if (options.options) {
-            for (const [key, value] of Object.entries(options.options)) {
-                codecContext.setOption(key, value.toString());
-            }
-        }
+        const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
         // Open codec
-        const openRet = await codecContext.open2(codec, null);
+        const openRet = await codecContext.open2(codec, opts);
         if (openRet < 0) {
             codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open codec');
         }
-        const decoder = new Decoder(codecContext, stream, isHWDecoder ? options.hardware : undefined);
-        return decoder;
+        return new Decoder(codecContext, codec, stream, isHWDecoder ? options.hardware : undefined);
     }
     /**
      * Check if decoder is open.
@@ -170,59 +171,25 @@ export class Decoder {
      * ```
      */
     get isDecoderOpen() {
-        return this.isOpen;
+        return !this.isClosed;
     }
     /**
-     * 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() {
-        if (this.stream.codecpar.codecType === AVMEDIA_TYPE_VIDEO) {
-            return {
-                type: 'video',
-                width: this.codecContext.width,
-                height: this.codecContext.height,
-                pixelFormat: this.hardware?.devicePixelFormat ?? this.codecContext.pixelFormat,
-                timeBase: this.stream.timeBase,
-                frameRate: this.stream.rFrameRate,
-                sampleAspectRatio: this.codecContext.sampleAspectRatio,
-            };
-        }
-        else {
-            return {
-                type: 'audio',
-                sampleRate: this.codecContext.sampleRate,
-                sampleFormat: this.codecContext.sampleFormat,
-                channelLayout: this.codecContext.channelLayout,
-                timeBase: this.stream.timeBase,
-            };
-        }
+    get isDecoderInitialized() {
+        return this.initialized;
     }
     /**
      * Check if decoder uses hardware acceleration.
@@ -239,7 +206,22 @@ export class Decoder {
      * @see {@link HardwareContext} For hardware setup
      */
     isHardware() {
-        return !!this.hardware;
+        return !!this.hardware && this.codec.isHardwareAcceleratedDecoder();
+    }
+    /**
+     * 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() {
+        return this.initialized && !this.isClosed;
     }
     /**
      * Decode a packet to a frame.
@@ -251,6 +233,7 @@ export class Decoder {
      * 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
@@ -269,7 +252,7 @@ export class Decoder {
      * @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);
@@ -284,14 +267,14 @@ export class Decoder {
      * @see {@link flush} For end-of-stream handling
      */
     async decode(packet) {
-        if (!this.isOpen) {
+        if (this.isClosed) {
             throw new Error('Decoder is closed');
         }
         // Send packet to decoder
         const sendRet = await this.codecContext.sendPacket(packet);
         if (sendRet < 0 && sendRet !== AVERROR_EOF) {
             // Decoder might be full, try to receive first
-            const frame = await this.receiveFrameInternal();
+            const frame = await this.receive();
             if (frame) {
                 return frame;
             }
@@ -301,77 +284,55 @@ export class Decoder {
             }
         }
         // Try to receive frame
-        const frame = await this.receiveFrameInternal();
+        const frame = await this.receive();
         return frame;
     }
     /**
-     * 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
-     */
-    async flush() {
-        if (!this.isOpen) {
-            throw new Error('Decoder is closed');
-        }
-        // Send flush packet (null)
-        await this.codecContext.sendPacket(null);
-        // Receive frame
-        const frame = await this.receiveFrameInternal();
-        return frame;
-    }
-    /**
-     * 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
      */
-    async *flushFrames() {
-        if (!this.isOpen) {
+    decodeSync(packet) {
+        if (this.isClosed) {
             throw new Error('Decoder is closed');
         }
-        let frame;
-        while ((frame = await this.flush()) !== null) {
-            yield frame;
+        // Send packet to decoder
+        const sendRet = this.codecContext.sendPacketSync(packet);
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            // Decoder might be full, try to receive first
+            const frame = this.receiveSync();
+            if (frame) {
+                return frame;
+            }
+            // If still failing, it's an error
+            if (sendRet !== AVERROR_EAGAIN) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send packet');
+            }
         }
+        // Try to receive frame
+        const frame = this.receiveSync();
+        return frame;
     }
     /**
      * Decode packet stream to frame stream.
@@ -382,7 +343,9 @@ export class Decoder {
      * 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
@@ -402,7 +365,7 @@ export class Decoder {
      * ```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();
@@ -426,14 +389,11 @@ export class Decoder {
      * @see {@link MediaInput.packets} For packet source
      */
     async *frames(packets) {
-        if (!this.isOpen) {
-            throw new Error('Decoder is closed');
-        }
         // Process packets
         for await (const packet of packets) {
             try {
                 // Only process packets for our stream
-                if (packet.streamIndex === this.streamIndex) {
+                if (packet.streamIndex === this.stream.index) {
                     const frame = await this.decode(packet);
                     if (frame) {
                         yield frame;
@@ -446,115 +406,240 @@ export class Decoder {
             }
         }
         // Flush decoder after all packets
-        let frame;
-        while ((frame = await this.flush()) !== null) {
-            yield frame;
+        await this.flush();
+        while (true) {
+            const remaining = await this.receive();
+            if (!remaining)
+                break;
+            yield remaining;
         }
     }
     /**
-     * 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() {
-        if (!this.isOpen) {
+    *framesSync(packets) {
+        // Process packets
+        for (const packet of packets) {
+            try {
+                // Only process packets for our stream
+                if (packet.streamIndex === this.stream.index) {
+                    const frame = this.decodeSync(packet);
+                    if (frame) {
+                        yield frame;
+                    }
+                }
+            }
+            finally {
+                // Free the input packet after processing
+                packet.free();
+            }
+        }
+        // Flush decoder after all packets
+        this.flushSync();
+        while (true) {
+            const remaining = this.receiveSync();
+            if (!remaining)
+                break;
+            yield remaining;
+        }
+    }
+    /**
+     * Flush decoder and signal end-of-stream.
+     *
+     * 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.
+     *
+     * Direct mapping to avcodec_send_packet(NULL).
+     *
+     * @throws {FFmpegError} If flush fails
+     *
+     * @example
+     * ```typescript
+     * // 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 flushFrames} For convenient async iteration
+     * @see {@link receive} For getting buffered frames
+     */
+    async flush() {
+        if (this.isClosed) {
             return;
         }
-        this.frame.free();
-        this.codecContext.freeContext();
-        this.isOpen = false;
+        // Send flush packet (null)
+        const ret = await this.codecContext.sendPacket(null);
+        if (ret < 0 && ret !== AVERROR_EOF) {
+            if (ret !== AVERROR_EAGAIN) {
+                FFmpegError.throwIfError(ret, 'Failed to flush decoder');
+            }
+        }
     }
     /**
-     * Get stream index.
+     * Flush decoder and signal end-of-stream synchronously.
+     * Synchronous version of flush.
      *
-     * Returns the index of the stream being decoded.
-     * Used for packet filtering in multi-stream files.
+     * Send null packet to signal end of input stream.
+     * Decoder may still have buffered frames.
+     * Call receiveSync() repeatedly to get remaining frames.
      *
-     * @returns Stream index
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * if (packet.streamIndex === decoder.getStreamIndex()) {
-     *   const frame = await decoder.decode(packet);
+     * decoder.flushSync();
+     * // Get remaining frames
+     * let frame;
+     * while ((frame = decoder.receiveSync()) !== null) {
+     *   console.log('Buffered frame');
      * }
      * ```
      *
-     * @see {@link getStream} For full stream object
+     * @see {@link flush} For async version
      */
-    getStreamIndex() {
-        return this.streamIndex;
+    flushSync() {
+        if (this.isClosed) {
+            return;
+        }
+        // Send flush packet (null)
+        const ret = this.codecContext.sendPacketSync(null);
+        if (ret < 0 && ret !== AVERROR_EOF) {
+            if (ret !== AVERROR_EAGAIN) {
+                FFmpegError.throwIfError(ret, 'Failed to flush decoder');
+            }
+        }
     }
     /**
-     * Get stream object.
+     * Flush all buffered frames as async generator.
      *
-     * Returns the underlying stream being decoded.
-     * Provides access to stream metadata and parameters.
+     * Convenient async iteration over remaining frames.
+     * Automatically sends flush signal and retrieves buffered frames.
+     * Useful for end-of-stream processing.
      *
-     * @returns Stream object
+     * @yields {Frame} Buffered frames
      *
      * @example
      * ```typescript
-     * const stream = decoder.getStream();
-     * console.log(`Duration: ${stream.duration}`);
-     * console.log(`Time base: ${stream.timeBase.num}/${stream.timeBase.den}`);
+     * // 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 Stream} For stream properties
-     * @see {@link getStreamIndex} For index only
+     * @see {@link flush} For signaling end-of-stream
+     * @see {@link frames} For complete pipeline
      */
-    getStream() {
-        return this.stream;
+    async *flushFrames() {
+        // Send flush signal
+        await this.flush();
+        let frame;
+        while ((frame = await this.receive()) !== null) {
+            yield frame;
+        }
     }
     /**
-     * Get underlying codec context.
+     * Flush all buffered frames as generator synchronously.
+     * Synchronous version of flushFrames.
      *
-     * Returns the internal codec context for advanced operations.
-     * Returns null if decoder is closed.
+     * Convenient sync 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 (const frame of decoder.flushFramesSync()) {
+     *   console.log('Processing buffered frame');
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link flushFrames} For async version
      */
-    getCodecContext() {
-        return this.isOpen ? this.codecContext : null;
+    *flushFramesSync() {
+        // Send flush signal
+        this.flushSync();
+        let frame;
+        while ((frame = this.receiveSync()) !== null) {
+            yield 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
      *
-     * @internal
+     * @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
      */
-    async receiveFrameInternal() {
+    async receive() {
         // Clear previous frame data
         this.frame.unref();
         const ret = await this.codecContext.receiveFrame(this.frame);
         if (ret === 0) {
-            // Note: hw_frames_ctx is now available in the frame
-            // Other components should get it directly from frames, not from HardwareContext
             // Got a frame, clone it for the user
             return this.frame.clone();
         }
@@ -568,6 +653,134 @@ export class Decoder {
             return 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() {
+        // Clear previous frame data
+        this.frame.unref();
+        const ret = this.codecContext.receiveFrameSync(this.frame);
+        if (ret === 0) {
+            // Got a frame, clone it for the user
+            return this.frame.clone();
+        }
+        else if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
+            // Need more data or end of stream
+            return null;
+        }
+        else {
+            // Error
+            FFmpegError.throwIfError(ret, 'Failed to receive frame');
+            return 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() {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        this.frame.free();
+        this.codecContext.freeContext();
+        this.initialized = false;
+    }
+    /**
+     * 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
+     */
+    getStream() {
+        return this.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() {
+        return this.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() {
+        return !this.isClosed && this.initialized ? this.codecContext : null;
+    }
     /**
      * Dispose of decoder.
      *