node-av 3.1.2 → 4.0.0

package/dist/api/decoder.js

@@ -1,5 +1,66 @@
-import { AVERROR_EAGAIN, AVERROR_EOF } from '../constants/constants.js';
-import { Codec, CodecContext, Dictionary, FFmpegError, Frame } from '../lib/index.js';
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { AV_CODEC_FLAG_COPY_OPAQUE, AV_FRAME_FLAG_CORRUPT, AV_NOPTS_VALUE, AV_ROUND_UP, AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, INT_MAX, } from '../constants/constants.js';
+import { CodecContext } from '../lib/codec-context.js';
+import { Codec } from '../lib/codec.js';
+import { Dictionary } from '../lib/dictionary.js';
+import { FFmpegError } from '../lib/error.js';
+import { Frame } from '../lib/frame.js';
+import { Rational } from '../lib/rational.js';
+import { avGcd, avInvQ, avMulQ, avRescaleDelta, avRescaleQ, avRescaleQRnd } from '../lib/utilities.js';
+import { FRAME_THREAD_QUEUE_SIZE, PACKET_THREAD_QUEUE_SIZE } from './constants.js';
+import { AsyncQueue } from './utilities/async-queue.js';
+import { Scheduler } from './utilities/scheduler.js';
 /**
  * High-level decoder for audio and video streams.
  *
@@ -10,10 +71,10 @@ import { Codec, CodecContext, Dictionary, FFmpegError, Frame } from '../lib/inde
  *
  * @example
  * ```typescript
- * import { MediaInput, Decoder } from 'node-av/api';
+ * import { Demuxer, Decoder } from 'node-av/api';
  *
  * // Open media and create decoder
- * await using input = await MediaInput.open('video.mp4');
+ * await using input = await Demuxer.open('video.mp4');
  * using decoder = await Decoder.create(input.video());
  *
  * // Decode frames
@@ -39,7 +100,7 @@ import { Codec, CodecContext, Dictionary, FFmpegError, Frame } from '../lib/inde
  * ```
  *
  * @see {@link Encoder} For encoding frames to packets
- * @see {@link MediaInput} For reading media files
+ * @see {@link Demuxer} For reading media files
  * @see {@link HardwareContext} For GPU acceleration
  */
 export class Decoder {
@@ -50,6 +111,19 @@ export class Decoder {
     initialized = true;
     isClosed = false;
     options;
+    // Frame tracking for PTS/duration estimation
+    lastFramePts = AV_NOPTS_VALUE;
+    lastFrameDurationEst = 0n;
+    lastFrameTb;
+    // Audio-specific frame tracking
+    lastFrameSampleRate = 0;
+    lastFilterInRescaleDelta = AV_NOPTS_VALUE;
+    // Worker pattern for push-based processing
+    inputQueue;
+    outputQueue;
+    workerPromise = null;
+    nextComponent = null;
+    pipeToPromise = null;
     /**
      * @param codecContext - Configured codec context
      *
@@ -70,71 +144,67 @@ export class Decoder {
         this.options = options;
         this.frame = new Frame();
         this.frame.alloc();
+        this.lastFrameTb = new Rational(0, 1);
+        this.inputQueue = new AsyncQueue(PACKET_THREAD_QUEUE_SIZE);
+        this.outputQueue = new AsyncQueue(FRAME_THREAD_QUEUE_SIZE);
     }
-    /**
-     * Create a decoder for a media stream.
-     *
-     * Initializes a decoder with the appropriate codec and configuration.
-     * Automatically detects and configures hardware acceleration if provided.
-     * 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
-     *
-     * @throws {FFmpegError} If codec initialization fails
-     *
-     * @example
-     * ```typescript
-     * import { MediaInput, Decoder } from 'node-av/api';
-     *
-     * await using input = await MediaInput.open('video.mp4');
-     * using decoder = await Decoder.create(input.video());
-     * ```
-     *
-     * @example
-     * ```typescript
-     * using decoder = await Decoder.create(stream, {
-     *   threads: 4,
-     *   options: {
-     *     'refcounted_frames': '1',
-     *     'skip_frame': 'nonkey'  // Only decode keyframes
-     *   }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * const hw = HardwareContext.auto();
-     * using decoder = await Decoder.create(stream, {
-     *   hardware: hw,
-     *   threads: 0  // Auto-detect thread count
-     *   exitOnError: false     // Continue on decode errors (default: true)
-     * });
-     * ```
-     *
-     * @see {@link HardwareContext} For GPU acceleration setup
-     * @see {@link DecoderOptions} For configuration options
-     */
-    static async create(stream, options = {}) {
+    static async create(stream, optionsOrCodec, maybeOptions) {
+        // Parse arguments
+        let options = {};
+        let explicitCodec;
+        if (optionsOrCodec !== undefined) {
+            // Check if first argument is a codec or options
+            if (typeof optionsOrCodec === 'string' || // FFDecoderCodec
+                typeof optionsOrCodec === 'number' || // AVCodecID
+                optionsOrCodec instanceof Codec // Codec instance
+            ) {
+                // First argument is a codec
+                explicitCodec = optionsOrCodec;
+                options = maybeOptions ?? {};
+            }
+            else {
+                // First argument is options
+                options = optionsOrCodec;
+            }
+        }
         let codec = null;
-        // If hardware acceleration requested, try to find hardware decoder first
-        if (options.hardware) {
-            codec = options.hardware.getDecoderCodec(stream.codecpar.codecId);
-            if (!codec) {
-                // No hardware decoder available, fall back to software
-                options.hardware = undefined;
+        // If explicit codec provided, use it
+        if (explicitCodec !== undefined) {
+            if (typeof explicitCodec === 'object' && 'id' in explicitCodec) {
+                // Already a Codec instance
+                codec = explicitCodec;
+            }
+            else if (typeof explicitCodec === 'string') {
+                // FFDecoderCodec string
+                codec = Codec.findDecoderByName(explicitCodec);
+                if (!codec) {
+                    throw new Error(`Decoder '${explicitCodec}' not found`);
+                }
+            }
+            else {
+                // AVCodecID number
+                codec = Codec.findDecoder(explicitCodec);
+                if (!codec) {
+                    throw new Error(`Decoder not found for codec ID ${explicitCodec}`);
+                }
             }
         }
-        // If no hardware decoder or no hardware requested, use software decoder
-        if (!codec) {
-            codec = Codec.findDecoder(stream.codecpar.codecId);
+        else {
+            // No explicit codec - use auto-detection logic
+            // If hardware acceleration requested, try to find hardware decoder first
+            if (options.hardware) {
+                codec = options.hardware.getDecoderCodec(stream.codecpar.codecId);
+                if (!codec) {
+                    // No hardware decoder available, fall back to software
+                    options.hardware = undefined;
+                }
+            }
+            // If no hardware decoder or no hardware requested, use software decoder
             if (!codec) {
-                throw new Error(`Decoder not found for codec ${stream.codecpar.codecId}`);
+                codec = Codec.findDecoder(stream.codecpar.codecId);
+                if (!codec) {
+                    throw new Error(`Decoder not found for codec ${stream.codecpar.codecId}`);
+                }
             }
         }
         // Allocate and configure codec context
@@ -148,16 +218,14 @@ export class Decoder {
         }
         // Set packet time base
         codecContext.pktTimebase = stream.timeBase;
-        // Apply options
-        if (options.threads !== undefined) {
-            codecContext.threadCount = options.threads;
-        }
         // Check if this decoder supports hardware acceleration
         // Only apply hardware acceleration if the decoder supports it
         // Silently ignore hardware for software decoders
         const isHWDecoder = codec.isHardwareAcceleratedDecoder();
         if (isHWDecoder && options.hardware) {
             codecContext.hwDeviceCtx = options.hardware.deviceContext;
+            // Set hardware pixel format
+            codecContext.setHardwarePixelFormat(options.hardware.devicePixelFormat);
             // Set extra_hw_frames if specified
             if (options.extraHWFrames !== undefined && options.extraHWFrames > 0) {
                 codecContext.extraHWFrames = options.extraHWFrames;
@@ -167,6 +235,8 @@ export class Decoder {
             options.hardware = undefined;
         }
         options.exitOnError = options.exitOnError ?? true;
+        // Enable COPY_OPAQUE flag to copy packet.opaque to frame.opaque
+        codecContext.setFlags(AV_CODEC_FLAG_COPY_OPAQUE);
         const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
         // Open codec
         const openRet = await codecContext.open2(codec, opts);
@@ -174,71 +244,76 @@ export class Decoder {
             codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open codec');
         }
+        // Adjust extra_hw_frames for queuing
+        // This is done AFTER open2 because the decoder validates extra_hw_frames during open
+        if (isHWDecoder && options.hardware) {
+            const currentExtraFrames = codecContext.extraHWFrames;
+            if (currentExtraFrames >= 0) {
+                codecContext.extraHWFrames = currentExtraFrames + FRAME_THREAD_QUEUE_SIZE;
+            }
+            else {
+                codecContext.extraHWFrames = 1;
+            }
+        }
         return new Decoder(codecContext, codec, stream, options);
     }
-    /**
-     * Create a decoder for a media stream synchronously.
-     * Synchronous version of create.
-     *
-     * Initializes a decoder with the appropriate codec and configuration.
-     * Automatically detects and configures hardware acceleration if provided.
-     * 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
-     *
-     * @throws {FFmpegError} If codec initialization fails
-     *
-     * @example
-     * ```typescript
-     * import { MediaInput, Decoder } from 'node-av/api';
-     *
-     * await using input = await MediaInput.open('video.mp4');
-     * using decoder = await Decoder.create(input.video());
-     * ```
-     *
-     * @example
-     * ```typescript
-     * using decoder = await Decoder.create(stream, {
-     *   threads: 4,
-     *   options: {
-     *     'refcounted_frames': '1',
-     *     'skip_frame': 'nonkey'  // Only decode keyframes
-     *   }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * const hw = HardwareContext.auto();
-     * using decoder = await Decoder.create(stream, {
-     *   hardware: hw,
-     *   threads: 0  // Auto-detect thread count
-     * });
-     * ```
-     *
-     * @see {@link create} For async version
-     */
-    static createSync(stream, options = {}) {
+    static createSync(stream, optionsOrCodec, maybeOptions) {
+        // Parse arguments
+        let options = {};
+        let explicitCodec;
+        if (optionsOrCodec !== undefined) {
+            // Check if first argument is a codec or options
+            if (typeof optionsOrCodec === 'string' || // FFDecoderCodec
+                typeof optionsOrCodec === 'number' || // AVCodecID
+                optionsOrCodec instanceof Codec // Codec instance
+            ) {
+                // First argument is a codec
+                explicitCodec = optionsOrCodec;
+                options = maybeOptions ?? {};
+            }
+            else {
+                // First argument is options
+                options = optionsOrCodec;
+            }
+        }
         let codec = null;
-        // If hardware acceleration requested, try to find hardware decoder first
-        if (options.hardware) {
-            codec = options.hardware.getDecoderCodec(stream.codecpar.codecId);
-            if (!codec) {
-                // No hardware decoder available, fall back to software
-                options.hardware = undefined;
+        // If explicit codec provided, use it
+        if (explicitCodec !== undefined) {
+            if (typeof explicitCodec === 'object' && 'id' in explicitCodec) {
+                // Already a Codec instance
+                codec = explicitCodec;
+            }
+            else if (typeof explicitCodec === 'string') {
+                // FFDecoderCodec string
+                codec = Codec.findDecoderByName(explicitCodec);
+                if (!codec) {
+                    throw new Error(`Decoder '${explicitCodec}' not found`);
+                }
+            }
+            else {
+                // AVCodecID number
+                codec = Codec.findDecoder(explicitCodec);
+                if (!codec) {
+                    throw new Error(`Decoder not found for codec ID ${explicitCodec}`);
+                }
             }
         }
-        // If no hardware decoder or no hardware requested, use software decoder
-        if (!codec) {
-            codec = Codec.findDecoder(stream.codecpar.codecId);
+        else {
+            // No explicit codec - use auto-detection logic
+            // If hardware acceleration requested, try to find hardware decoder first
+            if (options.hardware) {
+                codec = options.hardware.getDecoderCodec(stream.codecpar.codecId);
+                if (!codec) {
+                    // No hardware decoder available, fall back to software
+                    options.hardware = undefined;
+                }
+            }
+            // If no hardware decoder or no hardware requested, use software decoder
             if (!codec) {
-                throw new Error(`Decoder not found for codec ${stream.codecpar.codecId}`);
+                codec = Codec.findDecoder(stream.codecpar.codecId);
+                if (!codec) {
+                    throw new Error(`Decoder not found for codec ${stream.codecpar.codecId}`);
+                }
             }
         }
         // Allocate and configure codec context
@@ -252,16 +327,14 @@ export class Decoder {
         }
         // Set packet time base
         codecContext.pktTimebase = stream.timeBase;
-        // Apply options
-        if (options.threads !== undefined) {
-            codecContext.threadCount = options.threads;
-        }
         // Check if this decoder supports hardware acceleration
         // Only apply hardware acceleration if the decoder supports it
         // Silently ignore hardware for software decoders
         const isHWDecoder = codec.isHardwareAcceleratedDecoder();
         if (isHWDecoder && options.hardware) {
             codecContext.hwDeviceCtx = options.hardware.deviceContext;
+            // Set hardware pixel format and get_format callback
+            codecContext.setHardwarePixelFormat(options.hardware.devicePixelFormat);
             // Set extra_hw_frames if specified
             if (options.extraHWFrames !== undefined && options.extraHWFrames > 0) {
                 codecContext.extraHWFrames = options.extraHWFrames;
@@ -270,6 +343,9 @@ export class Decoder {
         else {
             options.hardware = undefined;
         }
+        options.exitOnError = options.exitOnError ?? true;
+        // Enable COPY_OPAQUE flag to copy packet.opaque to frame.opaque
+        // codecContext.setFlags(AV_CODEC_FLAG_COPY_OPAQUE);
         const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
         // Open codec synchronously
         const openRet = codecContext.open2Sync(codec, opts);
@@ -277,6 +353,17 @@ export class Decoder {
             codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open codec');
         }
+        // Adjust extra_hw_frames for queuing
+        // This is done AFTER open2 because the decoder validates extra_hw_frames during open
+        if (isHWDecoder && options.hardware) {
+            const currentExtraFrames = codecContext.extraHWFrames;
+            if (currentExtraFrames >= 0) {
+                codecContext.extraHWFrames = currentExtraFrames + FRAME_THREAD_QUEUE_SIZE;
+            }
+            else {
+                codecContext.extraHWFrames = 1;
+            }
+        }
         return new Decoder(codecContext, codec, stream, options);
     }
     /**
@@ -351,6 +438,10 @@ export class Decoder {
      * Handles internal buffering - may return null if more packets needed.
      * 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.
+     *
      * Direct mapping to avcodec_send_packet() and avcodec_receive_frame().
      *
      * @param packet - Compressed packet to decode
@@ -382,29 +473,42 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link decodeAll} For multiple frame decoding
      * @see {@link frames} For automatic packet iteration
      * @see {@link flush} For end-of-stream handling
+     * @see {@link decodeSync} For synchronous version
      */
     async decode(packet) {
         if (this.isClosed) {
             return null;
         }
+        // Skip 0-sized packets
+        if (packet.size === 0) {
+            return null;
+        }
         // 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
+        // Handle EAGAIN: decoder buffer is full, need to read frames first
+        // Unlike FFmpeg CLI which reads ALL frames in a loop, our decode() returns
+        // only one frame at a time. This means the decoder can still have frames
+        // from previous packets when we try to send a new packet.
+        if (sendRet === AVERROR_EAGAIN) {
+            // Decoder buffer full, receive a frame first
             const frame = await this.receive();
             if (frame) {
                 return frame;
             }
-            // If still failing, it's an error
-            if (sendRet !== AVERROR_EAGAIN && this.options.exitOnError) {
-                FFmpegError.throwIfError(sendRet, 'Failed to send packet');
+            // If receive() returned null, this is unexpected - treat as decoder bug
+            throw new Error('Decoder returned EAGAIN on send but no frame available - decoder bug');
+        }
+        // Handle other send errors (matches FFmpeg's error handling)
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            if (this.options.exitOnError) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send packet to decoder');
             }
         }
         // Try to receive frame
-        const frame = await this.receive();
-        return frame;
+        return await this.receive();
     }
     /**
      * Decode a packet to frame synchronously.
@@ -414,6 +518,10 @@ export class Decoder {
      * Handles decoder buffering and error conditions.
      * May return null if decoder needs more data.
      *
+     * **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.
+     *
      * @param packet - Compressed packet to decode
      *
      * @returns Decoded frame or null if more data needed or decoder is closed
@@ -428,28 +536,179 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link decodeAllSync} For multiple frame decoding
+     * @see {@link framesSync} For automatic packet iteration
+     * @see {@link flushSync} For end-of-stream handling
      * @see {@link decode} For async version
      */
     decodeSync(packet) {
         if (this.isClosed) {
             return null;
         }
+        // Skip 0-sized packets
+        if (packet.size === 0) {
+            return null;
+        }
         // Send packet to decoder
         const sendRet = this.codecContext.sendPacketSync(packet);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            // Decoder might be full, try to receive first
+        // Handle EAGAIN: decoder buffer is full, need to read frames first
+        // Unlike FFmpeg CLI which reads ALL frames in a loop, our decode() returns
+        // only one frame at a time. This means the decoder can still have frames
+        // from previous packets when we try to send a new packet.
+        if (sendRet === AVERROR_EAGAIN) {
+            // Decoder buffer full, receive a frame 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');
+            // If receive() returned null, this is unexpected - treat as decoder bug
+            throw new Error('Decoder returned EAGAIN on send but no frame available - decoder bug');
+        }
+        // Handle other send errors
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            if (this.options.exitOnError) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send packet to decoder');
             }
+            // exitOnError=false: Continue to receive
         }
         // Try to receive frame
-        const frame = this.receiveSync();
-        return frame;
+        return this.receiveSync();
+    }
+    /**
+     * Decode a packet to frames.
+     *
+     * Sends a packet to the decoder and receives all available decoded frames.
+     * Returns array of frames - may be empty if decoder needs more data.
+     * One packet can produce zero, one, or multiple frames depending on codec.
+     * Automatically manages decoder state and error recovery.
+     *
+     * Direct mapping to avcodec_send_packet() and avcodec_receive_frame().
+     *
+     * @param packet - Compressed packet to decode
+     *
+     * @returns Array of decoded frames (empty if more data needed or decoder is closed)
+     *
+     * @throws {FFmpegError} If decoding fails
+     *
+     * @example
+     * ```typescript
+     * const frames = await decoder.decodeAll(packet);
+     * for (const frame of frames) {
+     *   console.log(`Decoded frame with PTS: ${frame.pts}`);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @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();
+     *     }
+     *   }
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link decode} For single packet decoding
+     * @see {@link frames} For automatic packet iteration
+     * @see {@link flush} For end-of-stream handling
+     * @see {@link decodeAllSync} For synchronous version
+     */
+    async decodeAll(packet) {
+        if (this.isClosed) {
+            return [];
+        }
+        // Skip 0-sized packets
+        if (packet.size === 0) {
+            return [];
+        }
+        // Send packet to decoder
+        const sendRet = await this.codecContext.sendPacket(packet);
+        // EAGAIN during send_packet is a decoder bug (FFmpeg treats this as AVERROR_BUG)
+        // We read all decoded frames with receive() until done, so decoder should never be full
+        if (sendRet === AVERROR_EAGAIN) {
+            throw new Error('Decoder returned EAGAIN on send - this is a decoder bug');
+        }
+        // Handle send errors
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            if (this.options.exitOnError) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send packet to decoder');
+            }
+            // exitOnError=false: Continue to receive loop to drain any buffered frames
+        }
+        // Receive all available frames
+        const frames = [];
+        while (true) {
+            const remaining = await this.receive();
+            if (!remaining)
+                break;
+            frames.push(remaining);
+        }
+        return frames;
+    }
+    /**
+     * Decode a packet to frames synchronously.
+     * Synchronous version of decodeAll.
+     *
+     * Sends packet to decoder and receives all available decoded frames.
+     * Returns array of frames - may be empty if decoder needs more data.
+     * One packet can produce zero, one, or multiple frames depending on codec.
+     *
+     * @param packet - Compressed packet to decode
+     *
+     * @returns Array of decoded frames (empty if more data needed or decoder is closed)
+     *
+     * @throws {FFmpegError} If decoding fails
+     *
+     * @example
+     * ```typescript
+     * const frames = decoder.decodeAllSync(packet);
+     * for (const frame of frames) {
+     *   console.log(`Decoded: ${frame.width}x${frame.height}`);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link decodeSync} For single packet decoding
+     * @see {@link framesSync} For automatic packet iteration
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link decodeAll} For async version
+     */
+    decodeAllSync(packet) {
+        if (this.isClosed) {
+            return [];
+        }
+        // Skip 0-sized packets
+        if (packet.size === 0) {
+            return [];
+        }
+        // Send packet to decoder
+        const sendRet = this.codecContext.sendPacketSync(packet);
+        // EAGAIN during send_packet is a decoder bug (FFmpeg treats this as AVERROR_BUG)
+        // We read all decoded frames with receive() until done, so decoder should never be full
+        if (sendRet === AVERROR_EAGAIN) {
+            throw new Error('Decoder returned EAGAIN on send - this is a decoder bug');
+        }
+        // Handle send errors
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            if (this.options.exitOnError) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send packet to decoder');
+            }
+            // exitOnError=false: Continue to receive loop to drain any buffered frames
+        }
+        // Receive all available frames
+        const frames = [];
+        while (true) {
+            const remaining = this.receiveSync();
+            if (!remaining)
+                break;
+            frames.push(remaining);
+        }
+        return frames;
     }
     /**
      * Decode packet stream to frame stream.
@@ -469,7 +728,7 @@ export class Decoder {
      *
      * @example
      * ```typescript
-     * await using input = await MediaInput.open('video.mp4');
+     * await using input = await Demuxer.open('video.mp4');
      * using decoder = await Decoder.create(input.video());
      *
      * for await (const frame of decoder.frames(input.packets())) {
@@ -503,33 +762,77 @@ export class Decoder {
      * ```
      *
      * @see {@link decode} For single packet decoding
-     * @see {@link MediaInput.packets} For packet source
+     * @see {@link Demuxer.packets} For packet source
+     * @see {@link framesSync} For sync version
      */
     async *frames(packets) {
-        // Process packets
-        for await (const packet of packets) {
+        for await (const packet_1 of packets) {
+            const env_1 = { stack: [], error: void 0, hasError: false };
             try {
+                const packet = __addDisposableResource(env_1, packet_1, false);
+                // Handle EOF signal
+                if (packet === null) {
+                    // Flush decoder
+                    await this.flush();
+                    while (true) {
+                        const remaining = await this.receive();
+                        if (!remaining)
+                            break;
+                        yield remaining;
+                    }
+                    // Signal EOF and stop processing
+                    yield null;
+                    return;
+                }
                 // Only process packets for our stream
                 if (packet.streamIndex === this.stream.index) {
-                    const frame = await this.decode(packet);
-                    if (frame) {
+                    if (this.isClosed) {
+                        break;
+                    }
+                    // Skip 0-sized packets
+                    if (packet.size === 0) {
+                        continue;
+                    }
+                    // Send packet to decoder
+                    const sendRet = await this.codecContext.sendPacket(packet);
+                    // EAGAIN during send_packet is a decoder bug
+                    // We read all decoded frames with receive() until done, so decoder should never be full
+                    if (sendRet === AVERROR_EAGAIN) {
+                        throw new Error('Decoder returned EAGAIN but no frame available');
+                    }
+                    if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+                        if (this.options.exitOnError) {
+                            FFmpegError.throwIfError(sendRet, 'Failed to send packet');
+                        }
+                    }
+                    // Receive ALL available frames immediately
+                    // This ensures frames are yielded ASAP without latency
+                    while (true) {
+                        const frame = await this.receive();
+                        if (!frame)
+                            break; // EAGAIN or EOF
                         yield frame;
                     }
                 }
             }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
             finally {
-                // Free the input packet after processing
-                packet.free();
+                __disposeResources(env_1);
             }
         }
-        // Flush decoder after all packets
+        // Flush decoder after all packets (fallback if no null was sent)
         await this.flush();
-        while (!this.isClosed) {
+        while (true) {
             const remaining = await this.receive();
             if (!remaining)
                 break;
             yield remaining;
         }
+        // Signal EOF
+        yield null;
     }
     /**
      * Decode packet stream to frame stream synchronously.
@@ -555,33 +858,78 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link decodeSync} For single packet decoding
+     * @see {@link Demuxer.packetsSync} For packet source
      * @see {@link frames} For async version
      */
     *framesSync(packets) {
-        // Process packets
-        for (const packet of packets) {
+        for (const packet_2 of packets) {
+            const env_2 = { stack: [], error: void 0, hasError: false };
             try {
+                const packet = __addDisposableResource(env_2, packet_2, false);
+                // Handle EOF signal
+                if (packet === null) {
+                    // Flush decoder
+                    this.flushSync();
+                    while (true) {
+                        const remaining = this.receiveSync();
+                        if (!remaining)
+                            break;
+                        yield remaining;
+                    }
+                    // Signal EOF and stop processing
+                    yield null;
+                    return;
+                }
                 // Only process packets for our stream
                 if (packet.streamIndex === this.stream.index) {
-                    const frame = this.decodeSync(packet);
-                    if (frame) {
+                    if (this.isClosed) {
+                        break;
+                    }
+                    // Skip 0-sized packets
+                    if (packet.size === 0) {
+                        continue;
+                    }
+                    // Send packet to decoder
+                    const sendRet = this.codecContext.sendPacketSync(packet);
+                    // EAGAIN during send_packet is a decoder bug
+                    // We read all decoded frames with receive() until done, so decoder should never be full
+                    if (sendRet === AVERROR_EAGAIN) {
+                        throw new Error('Decoder returned EAGAIN but no frame available');
+                    }
+                    if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+                        if (this.options.exitOnError) {
+                            FFmpegError.throwIfError(sendRet, 'Failed to send packet');
+                        }
+                    }
+                    // Receive ALL available frames immediately
+                    // This ensures frames are yielded ASAP without latency
+                    while (true) {
+                        const frame = this.receiveSync();
+                        if (!frame)
+                            break; // EAGAIN or EOF
                         yield frame;
                     }
                 }
             }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
             finally {
-                // Free the input packet after processing
-                packet.free();
+                __disposeResources(env_2);
             }
         }
-        // Flush decoder after all packets
+        // Flush decoder after all packets (fallback if no null was sent)
         this.flushSync();
-        while (!this.isClosed) {
+        while (true) {
             const remaining = this.receiveSync();
             if (!remaining)
                 break;
             yield remaining;
         }
+        // Signal EOF
+        yield null;
     }
     /**
      * Flush decoder and signal end-of-stream.
@@ -609,6 +957,7 @@ export class Decoder {
      *
      * @see {@link flushFrames} For convenient async iteration
      * @see {@link receive} For getting buffered frames
+     * @see {@link flushSync} For synchronous version
      */
     async flush() {
         if (this.isClosed) {
@@ -642,6 +991,8 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link flushFramesSync} For convenient sync iteration
+     * @see {@link receiveSync} For getting buffered frames
      * @see {@link flush} For async version
      */
     flushSync() {
@@ -675,15 +1026,18 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link decode} For sending packets and receiving frames
      * @see {@link flush} For signaling end-of-stream
-     * @see {@link frames} For complete pipeline
+     * @see {@link flushFramesSync} For synchronous version
      */
     async *flushFrames() {
         // Send flush signal
         await this.flush();
-        let frame;
-        while ((frame = await this.receive()) !== null) {
-            yield frame;
+        while (true) {
+            const remaining = await this.receive();
+            if (!remaining)
+                break;
+            yield remaining;
         }
     }
     /**
@@ -706,14 +1060,18 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link decodeSync} For sending packets and receiving frames
+     * @see {@link flushSync} For signaling end-of-stream
      * @see {@link flushFrames} For async version
      */
     *flushFramesSync() {
         // Send flush signal
         this.flushSync();
-        let frame;
-        while ((frame = this.receiveSync()) !== null) {
-            yield frame;
+        while (true) {
+            const remaining = this.receiveSync();
+            if (!remaining)
+                break;
+            yield remaining;
         }
     }
     /**
@@ -751,29 +1109,50 @@ export class Decoder {
      *
      * @see {@link decode} For sending packets and receiving frames
      * @see {@link flush} For signaling end-of-stream
+     * @see {@link receiveSync} For synchronous version
      */
     async receive() {
-        // Clear previous frame data
-        this.frame.unref();
-        if (this.isClosed) {
-            return null;
-        }
-        const ret = await this.codecContext.receiveFrame(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
-            if (this.options.exitOnError) {
-                FFmpegError.throwIfError(ret, 'Failed to receive frame');
+        // When exitOnError=false, continue on errors until we get a frame or EAGAIN/EOF
+        while (!this.isClosed) {
+            // Clear previous frame data
+            this.frame.unref();
+            const ret = await this.codecContext.receiveFrame(this.frame);
+            if (ret === 0) {
+                // Set frame time_base to decoder's packet timebase
+                this.frame.timeBase = this.codecContext.pktTimebase;
+                // Check for corrupt frame
+                if (this.frame.decodeErrorFlags || this.frame.hasFlags(AV_FRAME_FLAG_CORRUPT)) {
+                    if (this.options.exitOnError) {
+                        throw new Error('Corrupt decoded frame detected');
+                    }
+                    // exitOnError=false: skip corrupt frame, continue to next
+                    continue;
+                }
+                // Handles PTS assignment, duration estimation, and frame tracking
+                if (this.codecContext.codecType === AVMEDIA_TYPE_VIDEO) {
+                    this.processVideoFrame(this.frame);
+                }
+                // Handles timestamp extrapolation, sample rate changes, and duration calculation
+                if (this.codecContext.codecType === AVMEDIA_TYPE_AUDIO) {
+                    this.processAudioFrame(this.frame);
+                }
+                // 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 during receive
+                if (this.options.exitOnError) {
+                    FFmpegError.throwIfError(ret, 'Failed to receive frame');
+                }
+                // exitOnError=false: continue to next frame
+                continue;
             }
-            return null;
         }
+        return null;
     }
     /**
      * Receive frame from decoder synchronously.
@@ -809,30 +1188,72 @@ export class Decoder {
      * }
      * ```
      *
+     * @see {@link decodeSync} For sending packets and receiving frames
+     * @see {@link flushSync} For signaling end-of-stream
      * @see {@link receive} For async version
      */
     receiveSync() {
-        // Clear previous frame data
-        this.frame.unref();
-        if (this.isClosed) {
-            return null;
-        }
-        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
-            if (this.options.exitOnError) {
-                FFmpegError.throwIfError(ret, 'Failed to receive frame');
+        // When exitOnError=false, continue on errors until we get a frame or EAGAIN/EOF
+        while (!this.isClosed) {
+            // Clear previous frame data
+            this.frame.unref();
+            const ret = this.codecContext.receiveFrameSync(this.frame);
+            if (ret === 0) {
+                // Set frame time_base to decoder's packet timebase
+                this.frame.timeBase = this.codecContext.pktTimebase;
+                // Check for corrupt frame
+                if (this.frame.decodeErrorFlags || this.frame.hasFlags(AV_FRAME_FLAG_CORRUPT)) {
+                    if (this.options.exitOnError) {
+                        throw new Error('Corrupt decoded frame detected');
+                    }
+                    // exitOnError=false: skip corrupt frame, continue to next
+                    continue;
+                }
+                // Process video frame
+                // Handles PTS assignment, duration estimation, and frame tracking
+                if (this.codecContext.codecType === AVMEDIA_TYPE_VIDEO) {
+                    this.processVideoFrame(this.frame);
+                }
+                // Process audio frame
+                // Handles timestamp extrapolation, sample rate changes, and duration calculation
+                if (this.codecContext.codecType === AVMEDIA_TYPE_AUDIO) {
+                    this.processAudioFrame(this.frame);
+                }
+                // 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 during receive
+                if (this.options.exitOnError) {
+                    FFmpegError.throwIfError(ret, 'Failed to receive frame');
+                }
+                // exitOnError=false: continue to next frame
+                continue;
             }
-            return null;
         }
+        return null;
+    }
+    pipeTo(target) {
+        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: decoder.outputQueue -> target.inputQueue (via target.send)
+        this.pipeToPromise = (async () => {
+            while (true) {
+                const frame = await this.receiveFromQueue();
+                if (!frame)
+                    break;
+                await t.sendToQueue(frame);
+            }
+        })();
+        // Return scheduler for chaining (target is now the last component)
+        return new Scheduler(this, t);
     }
     /**
      * Close decoder and free resources.
@@ -858,6 +1279,8 @@ export class Decoder {
             return;
         }
         this.isClosed = true;
+        this.inputQueue?.close();
+        this.outputQueue?.close();
         this.frame.free();
         this.codecContext.freeContext();
         this.initialized = false;
@@ -908,6 +1331,372 @@ export class Decoder {
     getCodecContext() {
         return !this.isClosed && this.initialized ? this.codecContext : null;
     }
+    /**
+     * Worker loop for push-based processing.
+     *
+     * @internal
+     */
+    async runWorker() {
+        try {
+            // Outer loop - receive packets
+            while (!this.inputQueue.isClosed) {
+                const env_3 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const packet = __addDisposableResource(env_3, await this.inputQueue.receive(), false);
+                    if (!packet)
+                        break;
+                    // Skip packets for other streams
+                    if (packet.streamIndex !== this.stream.index) {
+                        continue;
+                    }
+                    if (packet.size === 0) {
+                        continue;
+                    }
+                    // Send packet to decoder
+                    const sendRet = await this.codecContext.sendPacket(packet);
+                    // EAGAIN during send_packet is a decoder bug
+                    // We read all decoded frames with receive() until done, so decoder should never be full
+                    if (sendRet === AVERROR_EAGAIN) {
+                        throw new Error('Decoder returned EAGAIN but no frame available');
+                    }
+                    if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+                        if (this.options.exitOnError) {
+                            FFmpegError.throwIfError(sendRet, 'Failed to send packet');
+                        }
+                    }
+                    // Receive ALL available frames immediately
+                    // This ensures frames are yielded ASAP without latency
+                    while (!this.outputQueue.isClosed) {
+                        const frame = await this.receive();
+                        if (!frame)
+                            break; // EAGAIN or EOF
+                        await this.outputQueue.send(frame);
+                    }
+                }
+                catch (e_3) {
+                    env_3.error = e_3;
+                    env_3.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_3);
+                }
+            }
+            // Flush decoder at end
+            await this.flush();
+            while (!this.outputQueue.isClosed) {
+                const frame = await this.receive();
+                if (!frame)
+                    break;
+                await this.outputQueue.send(frame);
+            }
+        }
+        catch {
+            // Ignore ?
+        }
+        finally {
+            // Close output queue when done
+            this.outputQueue?.close();
+        }
+    }
+    /**
+     * Send packet to input queue.
+     *
+     * @param packet - Packet to send
+     *
+     * @internal
+     */
+    async sendToQueue(packet) {
+        await this.inputQueue.send(packet);
+    }
+    /**
+     * Receive frame from output queue.
+     *
+     * @returns Frame from output queue or null if closed
+     *
+     * @internal
+     */
+    async receiveFromQueue() {
+        return await this.outputQueue.receive();
+    }
+    /**
+     * Flush the entire filter pipeline.
+     *
+     * Propagates flush through worker, output queue, and next component.
+     *
+     * @internal
+     */
+    async flushPipeline() {
+        // Close input queue to signal end of stream to worker
+        this.inputQueue.close();
+        // Wait for worker to finish processing all packets (if exists)
+        if (this.workerPromise) {
+            await this.workerPromise;
+        }
+        // Flush decoder at end
+        await this.flush();
+        // Send all flushed frames to output queue
+        while (true) {
+            const frame = await this.receive();
+            if (!frame)
+                break;
+            await this.outputQueue.send(frame);
+        }
+        // Close output queue to signal end of stream to pipeTo() task
+        this.outputQueue.close();
+        // Wait for pipeTo() task to finish processing all frames (if exists)
+        if (this.pipeToPromise) {
+            await this.pipeToPromise;
+        }
+        // Then propagate flush to next component
+        if (this.nextComponent) {
+            await this.nextComponent.flushPipeline();
+        }
+    }
+    /**
+     * Estimate video frame duration.
+     *
+     * Implements FFmpeg CLI's video_duration_estimate() logic.
+     * Uses multiple heuristics to determine frame duration when not explicitly available:
+     * 1. Frame duration from container (if reliable)
+     * 2. Duration from codec framerate
+     * 3. PTS difference between frames
+     * 4. Stream framerate
+     * 5. Last frame's estimated duration
+     *
+     * @param frame - Frame to estimate duration for
+     *
+     * @returns Estimated duration in frame's timebase units
+     *
+     * @internal
+     */
+    estimateVideoDuration(frame) {
+        // Difference between this and last frame's timestamps
+        const tsDiff = frame.pts !== AV_NOPTS_VALUE && this.lastFramePts !== AV_NOPTS_VALUE ? frame.pts - this.lastFramePts : -1n;
+        // Frame duration is unreliable (typically guessed by lavf) when it is equal
+        // to 1 and the actual duration of the last frame is more than 2x larger
+        const durationUnreliable = frame.duration === 1n && tsDiff > 2n * frame.duration;
+        // Prefer frame duration for containers with timestamps
+        if (frame.duration > 0n && !durationUnreliable) {
+            return frame.duration;
+        }
+        // Calculate codec duration from framerate
+        let codecDuration = 0n;
+        const framerate = this.codecContext.framerate;
+        if (framerate && framerate.den > 0 && framerate.num > 0) {
+            const fields = (frame.repeatPict ?? 0) + 2;
+            const fieldRate = avMulQ(framerate, { num: 2, den: 1 });
+            codecDuration = avRescaleQ(fields, avInvQ(fieldRate), frame.timeBase);
+        }
+        // When timestamps are available, repeat last frame's actual duration
+        if (tsDiff > 0n) {
+            return tsDiff;
+        }
+        // Try frame/codec duration
+        if (frame.duration > 0n) {
+            return frame.duration;
+        }
+        if (codecDuration > 0n) {
+            return codecDuration;
+        }
+        // Try stream framerate
+        const streamFramerate = this.stream.avgFrameRate ?? this.stream.rFrameRate;
+        if (streamFramerate && streamFramerate.num > 0 && streamFramerate.den > 0) {
+            const d = avRescaleQ(1, avInvQ(streamFramerate), frame.timeBase);
+            if (d > 0n) {
+                return d;
+            }
+        }
+        // Last resort is last frame's estimated duration, and 1
+        return this.lastFrameDurationEst > 0n ? this.lastFrameDurationEst : 1n;
+    }
+    /**
+     * Process video frame after decoding.
+     *
+     * Implements FFmpeg CLI's video_frame_process() logic.
+     * Handles:
+     * - Hardware frame transfer to software format
+     * - PTS assignment from best_effort_timestamp
+     * - PTS extrapolation when missing
+     * - Duration estimation
+     * - Frame tracking for next frame
+     *
+     * @param frame - Decoded frame to process
+     *
+     * @internal
+     */
+    processVideoFrame(frame) {
+        // Hardware acceleration retrieve
+        // If hwaccel_output_format is set and frame is in hardware format, transfer to software format
+        if (this.options.hwaccelOutputFormat !== undefined && frame.isHwFrame()) {
+            const swFrame = new Frame();
+            swFrame.alloc();
+            swFrame.format = this.options.hwaccelOutputFormat;
+            // Transfer data from hardware to software frame
+            const ret = frame.hwframeTransferDataSync(swFrame, 0);
+            if (ret < 0) {
+                swFrame.free();
+                if (this.options.exitOnError) {
+                    FFmpegError.throwIfError(ret, 'Failed to transfer hardware frame data');
+                }
+                return;
+            }
+            // Copy properties from hw frame to sw frame
+            swFrame.copyProps(frame);
+            // Replace frame with software version (unref old, move ref)
+            frame.unref();
+            const refRet = frame.ref(swFrame);
+            swFrame.free();
+            if (refRet < 0) {
+                if (this.options.exitOnError) {
+                    FFmpegError.throwIfError(refRet, 'Failed to reference software frame');
+                }
+                return;
+            }
+        }
+        // Set PTS from best_effort_timestamp
+        frame.pts = frame.bestEffortTimestamp;
+        // DECODER_FLAG_FRAMERATE_FORCED: Ignores all timestamps and generates constant framerate
+        if (this.options.forcedFramerate) {
+            frame.pts = AV_NOPTS_VALUE;
+            frame.duration = 1n;
+            const invFramerate = avInvQ(this.options.forcedFramerate);
+            frame.timeBase = new Rational(invFramerate.num, invFramerate.den);
+        }
+        // No timestamp available - extrapolate from previous frame duration
+        if (frame.pts === AV_NOPTS_VALUE) {
+            frame.pts = this.lastFramePts === AV_NOPTS_VALUE ? 0n : this.lastFramePts + this.lastFrameDurationEst;
+        }
+        // Update timestamp history
+        this.lastFrameDurationEst = this.estimateVideoDuration(frame);
+        this.lastFramePts = frame.pts;
+        this.lastFrameTb = new Rational(frame.timeBase.num, frame.timeBase.den);
+        // SAR override
+        if (this.options.sarOverride) {
+            frame.sampleAspectRatio = new Rational(this.options.sarOverride.num, this.options.sarOverride.den);
+        }
+        // Apply cropping
+        if (this.options.applyCropping) {
+            const ret = frame.applyCropping(1); // AV_FRAME_CROP_UNALIGNED = 1
+            if (ret < 0) {
+                if (this.options.exitOnError) {
+                    FFmpegError.throwIfError(ret, 'Error applying decoder cropping');
+                }
+            }
+        }
+    }
+    /**
+     * Audio samplerate update - handles sample rate changes.
+     *
+     * Based on FFmpeg's audio_samplerate_update().
+     *
+     * On sample rate change, chooses a new internal timebase that can represent
+     * timestamps from all sample rates seen so far. Uses GCD to find minimal
+     * common timebase, with fallback to LCM of common sample rates (28224000).
+     *
+     * Handles:
+     * - Sample rate change detection
+     * - Timebase calculation via GCD
+     * - Overflow detection and fallback
+     * - Frame timebase optimization
+     * - Rescaling existing timestamps
+     *
+     * @param frame - Audio frame to process
+     *
+     * @returns Timebase to use for this frame
+     *
+     * @internal
+     */
+    audioSamplerateUpdate(frame) {
+        const prev = this.lastFrameTb.den;
+        const sr = frame.sampleRate;
+        // No change - return existing timebase
+        if (frame.sampleRate === this.lastFrameSampleRate) {
+            return this.lastFrameTb;
+        }
+        // Calculate GCD to find minimal common timebase
+        const gcd = avGcd(prev, sr);
+        let tbNew;
+        // Check for overflow
+        if (Number(prev) / Number(gcd) >= INT_MAX / sr) {
+            // LCM of 192000, 44100 - represents all common sample rates
+            tbNew = { num: 1, den: 28224000 };
+        }
+        else {
+            // Normal case
+            tbNew = { num: 1, den: (Number(prev) / Number(gcd)) * sr };
+        }
+        // Keep frame's timebase if strictly better
+        // "Strictly better" means: num=1, den > tbNew.den, and tbNew.den divides den evenly
+        if (frame.timeBase.num === 1 && frame.timeBase.den > tbNew.den && frame.timeBase.den % tbNew.den === 0) {
+            tbNew = { num: frame.timeBase.num, den: frame.timeBase.den };
+        }
+        // Rescale existing timestamps to new timebase
+        if (this.lastFramePts !== AV_NOPTS_VALUE) {
+            this.lastFramePts = avRescaleQ(this.lastFramePts, this.lastFrameTb, tbNew);
+        }
+        this.lastFrameDurationEst = avRescaleQ(this.lastFrameDurationEst, this.lastFrameTb, tbNew);
+        this.lastFrameTb = new Rational(tbNew.num, tbNew.den);
+        this.lastFrameSampleRate = frame.sampleRate;
+        return this.lastFrameTb;
+    }
+    /**
+     * Audio timestamp processing - handles audio frame timestamps.
+     *
+     * Based on FFmpeg's audio_ts_process().
+     *
+     * Processes audio frame timestamps with:
+     * - Sample rate change handling via audioSamplerateUpdate()
+     * - PTS extrapolation when missing (pts_pred)
+     * - Gap detection (resets av_rescale_delta state)
+     * - Smooth timestamp conversion via av_rescale_delta
+     * - Duration calculation from nb_samples
+     * - Conversion to filtering timebase {1, sample_rate}
+     *
+     * Handles:
+     * - Dynamic sample rate changes
+     * - Missing timestamps (AV_NOPTS_VALUE)
+     * - Timestamp gaps/discontinuities
+     * - Sample-accurate timestamp generation
+     * - Frame duration calculation
+     *
+     * @param frame - Decoded audio frame to process
+     *
+     * @internal
+     */
+    processAudioFrame(frame) {
+        // Filtering timebase is always {1, sample_rate} for audio
+        const tbFilter = { num: 1, den: frame.sampleRate };
+        // Handle sample rate change - updates internal timebase
+        const tb = this.audioSamplerateUpdate(frame);
+        // Predict next PTS based on last frame + duration
+        const ptsPred = this.lastFramePts === AV_NOPTS_VALUE ? 0n : this.lastFramePts + this.lastFrameDurationEst;
+        // No timestamp - use predicted value
+        if (frame.pts === AV_NOPTS_VALUE) {
+            frame.pts = ptsPred;
+            frame.timeBase = new Rational(tb.num, tb.den);
+        }
+        else if (this.lastFramePts !== AV_NOPTS_VALUE) {
+            // Detect timestamp gap - compare with predicted timestamp
+            const ptsPredInFrameTb = avRescaleQRnd(ptsPred, tb, frame.timeBase, AV_ROUND_UP);
+            if (frame.pts > ptsPredInFrameTb) {
+                // Gap detected - reset rescale_delta state for smooth conversion
+                this.lastFilterInRescaleDelta = AV_NOPTS_VALUE;
+            }
+        }
+        // Smooth timestamp conversion with av_rescale_delta
+        // This maintains fractional sample accuracy across timebase conversions
+        // avRescaleDelta modifies lastRef in place (simulates C's &last_filter_in_rescale_delta)
+        const lastRef = { value: this.lastFilterInRescaleDelta };
+        frame.pts = avRescaleDelta(frame.timeBase, frame.pts, tb, frame.nbSamples, lastRef, tb);
+        this.lastFilterInRescaleDelta = lastRef.value;
+        // Update frame tracking
+        this.lastFramePts = frame.pts;
+        this.lastFrameDurationEst = avRescaleQ(BigInt(frame.nbSamples), tbFilter, tb);
+        // Convert to filtering timebase
+        frame.pts = avRescaleQ(frame.pts, tb, tbFilter);
+        frame.duration = BigInt(frame.nbSamples);
+        frame.timeBase = new Rational(tbFilter.num, tbFilter.den);
+    }
     /**
      * Dispose of decoder.
      *