node-av 3.1.3 → 5.0.0

package/dist/api/encoder.d.ts

@@ -1,7 +1,10 @@
-import { Codec, CodecContext, Packet } from '../lib/index.js';
-import type { AVCodecFlag, AVCodecID } from '../constants/constants.js';
-import type { FFEncoderCodec } from '../constants/encoders.js';
-import type { Frame } from '../lib/index.js';
+import { CodecContext } from '../lib/codec-context.js';
+import { Codec } from '../lib/codec.js';
+import { Frame } from '../lib/frame.js';
+import { Packet } from '../lib/packet.js';
+import { SchedulerControl } from './utilities/scheduler.js';
+import type { AVCodecFlag, AVCodecID, EOFSignal, FFEncoderCodec } from '../constants/index.js';
+import type { Muxer } from './muxer.js';
 import type { EncoderOptions } from './types.js';
 /**
  * High-level encoder for audio and video streams.
@@ -58,17 +61,23 @@ import type { EncoderOptions } from './types.js';
  * ```
  *
  * @see {@link Decoder} For decoding packets to frames
- * @see {@link MediaOutput} For writing encoded packets
+ * @see {@link Muxer} For writing encoded packets
  * @see {@link HardwareContext} For GPU acceleration
  */
 export declare class Encoder implements Disposable {
     private codecContext;
     private packet;
     private codec;
+    private initializePromise;
     private initialized;
     private isClosed;
     private opts?;
     private options;
+    private audioFrameBuffer?;
+    private inputQueue;
+    private outputQueue;
+    private workerPromise;
+    private pipeToPromise;
     /**
      * @param codecContext - Configured codec context
      *
@@ -92,7 +101,7 @@ export declare class Encoder implements Disposable {
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
      *
-     * @param options - Encoder configuration options including required timeBase
+     * @param options - Optional encoder configuration options including required timeBase
      *
      * @returns Configured encoder instance
      *
@@ -133,8 +142,9 @@ export declare class Encoder implements Disposable {
      * ```
      *
      * @see {@link EncoderOptions} For configuration options
+     * @see {@link createSync} For synchronous version
      */
-    static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options: EncoderOptions): Promise<Encoder>;
+    static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options?: EncoderOptions): Promise<Encoder>;
     /**
      * Create an encoder with specified codec and options synchronously.
      * Synchronous version of create.
@@ -147,7 +157,7 @@ export declare class Encoder implements Disposable {
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
      *
-     * @param options - Encoder configuration options including required timeBase
+     * @param options - Optional encoder configuration options including required timeBase
      *
      * @returns Configured encoder instance
      *
@@ -189,9 +199,10 @@ export declare class Encoder implements Disposable {
      * });
      * ```
      *
+     * @see {@link EncoderOptions} For configuration options
      * @see {@link create} For async version
      */
-    static createSync(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options: EncoderOptions): Encoder;
+    static createSync(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options?: EncoderOptions): Encoder;
     /**
      * Check if encoder is open.
      *
@@ -219,6 +230,89 @@ export declare class Encoder implements Disposable {
      * ```
      */
     get isEncoderInitialized(): boolean;
+    /**
+     * Codec flags.
+     *
+     * @returns Current codec flags
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @example
+     * ```typescript
+     * const flags = encoder.codecFlags;
+     * console.log('Current flags:', flags);
+     * ```
+     *
+     * @see {@link setCodecFlags} To set flags
+     * @see {@link clearCodecFlags} To clear flags
+     * @see {@link hasCodecFlags} To check flags
+     */
+    get codecFlags(): AVCodecFlag;
+    /**
+     * Set codec flags.
+     *
+     * @param flags - One or more flag values to set
+     *
+     * @throws {Error} If encoder is already initialized or closed
+     *
+     * @example
+     * ```typescript
+     * import { AV_CODEC_FLAG_GLOBAL_HEADER, AV_CODEC_FLAG_QSCALE } from 'node-av/constants';
+     *
+     * // Set multiple flags before initialization
+     * encoder.setCodecFlags(AV_CODEC_FLAG_GLOBAL_HEADER, AV_CODEC_FLAG_QSCALE);
+     * ```
+     *
+     * @see {@link clearCodecFlags} To clear flags
+     * @see {@link hasCodecFlags} To check flags
+     * @see {@link codecFlags} For direct flag access
+     */
+    setCodecFlags(...flags: AVCodecFlag[]): void;
+    /**
+     * Clear codec flags.
+     *
+     * @param flags - One or more flag values to clear
+     *
+     * @throws {Error} If encoder is already initialized or closed
+     *
+     * @example
+     * ```typescript
+     * import { AV_CODEC_FLAG_QSCALE } from 'node-av/constants';
+     *
+     * // Clear specific flag before initialization
+     * encoder.clearCodecFlags(AV_CODEC_FLAG_QSCALE);
+     * ```
+     *
+     * @see {@link setCodecFlags} To set flags
+     * @see {@link hasCodecFlags} To check flags
+     * @see {@link codecFlags} For direct flag access
+     */
+    clearCodecFlags(...flags: AVCodecFlag[]): void;
+    /**
+     * Check if codec has specific flags.
+     *
+     * Tests whether all specified codec flags are set using bitwise AND.
+     *
+     * @param flags - One or more flag values to check
+     *
+     * @returns true if all specified flags are set, false otherwise
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @example
+     * ```typescript
+     * import { AV_CODEC_FLAG_GLOBAL_HEADER } from 'node-av/constants';
+     *
+     * if (encoder.hasCodecFlags(AV_CODEC_FLAG_GLOBAL_HEADER)) {
+     *   console.log('Global header flag is set');
+     * }
+     * ```
+     *
+     * @see {@link setCodecFlags} To set flags
+     * @see {@link clearCodecFlags} To clear flags
+     * @see {@link codecFlags} For direct flag access
+     */
+    hasCodecFlags(...flags: AVCodecFlag[]): boolean;
     /**
      * Check if encoder uses hardware acceleration.
      *
@@ -248,24 +342,119 @@ export declare class Encoder implements Disposable {
      */
     isReady(): boolean;
     /**
-     * Encode a frame to a packet.
+     * Send a frame to the encoder.
+     *
+     * Sends a raw frame to the encoder for encoding.
+     * Does not return encoded packets - use {@link receive} to retrieve packets.
+     * On first frame, automatically initializes encoder with frame properties.
+     * A single frame can produce zero, one, or multiple packets depending on codec buffering.
+     *
+     * **Important**: This method only SENDS the frame to the encoder.
+     * You must call {@link receive} separately (potentially multiple times) to get encoded packets.
+     *
+     * Direct mapping to avcodec_send_frame().
+     *
+     * @param frame - Raw frame to send to encoder
+     *
+     * @throws {FFmpegError} If sending frame fails
+     *
+     * @example
+     * ```typescript
+     * // Send frame and receive packets
+     * await encoder.encode(frame);
+     *
+     * // Receive all available packets
+     * while (true) {
+     *   const packet = await encoder.receive();
+     *   if (!packet) break;
+     *   console.log(`Encoded packet with PTS: ${packet.pts}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * for await (const frame of decoder.frames(input.packets())) {
+     *   // Send frame
+     *   await encoder.encode(frame);
+     *
+     *   // Receive available packets
+     *   let packet;
+     *   while ((packet = await encoder.receive())) {
+     *     await output.writePacket(packet);
+     *     packet.free();
+     *   }
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link receive} For receiving encoded packets
+     * @see {@link encodeAll} For combined send+receive operation
+     * @see {@link packets} For automatic frame iteration
+     * @see {@link flush} For end-of-stream handling
+     * @see {@link encodeSync} For synchronous version
+     */
+    encode(frame: Frame): Promise<void>;
+    /**
+     * Send a frame to the encoder synchronously.
+     * Synchronous version of encode.
+     *
+     * Sends a raw frame to the encoder for encoding.
+     * Does not return encoded packets - use {@link receiveSync} to retrieve packets.
+     * On first frame, automatically initializes encoder with frame properties.
+     * A single frame can produce zero, one, or multiple packets depending on codec buffering.
+     *
+     * **Important**: This method only SENDS the frame to the encoder.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get encoded packets.
+     *
+     * Direct mapping to avcodec_send_frame().
+     *
+     * @param frame - Raw frame to send to encoder
+     *
+     * @throws {FFmpegError} If sending frame fails
+     *
+     * @example
+     * ```typescript
+     * // Send frame and receive packets
+     * encoder.encodeSync(frame);
+     *
+     * // Receive all available packets
+     * let packet;
+     * while ((packet = encoder.receiveSync())) {
+     *   console.log(`Encoded packet with PTS: ${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link receiveSync} For receiving encoded packets
+     * @see {@link encodeAllSync} For combined send+receive operation
+     * @see {@link packetsSync} For automatic frame iteration
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link encode} For async version
+     */
+    encodeSync(frame: Frame): void;
+    /**
+     * Encode a frame to packets.
      *
-     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * Sends a frame to the encoder and receives all available encoded packets.
+     * Returns array of packets - may be empty if encoder needs more data.
      * On first frame, automatically initializes encoder with frame properties.
-     * Handles internal buffering - may return null if more frames needed.
+     * One frame can produce zero, one, or multiple packets depending on codec.
      *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @param frame - Raw frame to encode (or null to flush)
      *
-     * @returns Encoded packet, null if more data needed, or null if encoder is closed
+     * @returns Array of encoded packets (empty if more data needed or encoder is closed)
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * const packet = await encoder.encode(frame);
-     * if (packet) {
+     * const packets = await encoder.encodeAll(frame);
+     * for (const packet of packets) {
      *   console.log(`Encoded packet with PTS: ${packet.pts}`);
      *   await output.writePacket(packet);
      *   packet.free();
@@ -276,8 +465,8 @@ export declare class Encoder implements Disposable {
      * ```typescript
      * // Encode loop
      * for await (const frame of decoder.frames(input.packets())) {
-     *   const packet = await encoder.encode(frame);
-     *   if (packet) {
+     *   const packets = await encoder.encodeAll(frame);
+     *   for (const packet of packets) {
      *     await output.writePacket(packet);
      *     packet.free();
      *   }
@@ -285,30 +474,33 @@ export declare class Encoder implements Disposable {
      * }
      * ```
      *
+     * @see {@link encode} For single packet encoding
      * @see {@link packets} For automatic frame iteration
      * @see {@link flush} For end-of-stream handling
+     * @see {@link encodeAllSync} For synchronous version
      */
-    encode(frame: Frame | null): Promise<Packet | null>;
+    encodeAll(frame: Frame | null): Promise<Packet[]>;
     /**
-     * Encode a frame to a packet synchronously.
-     * Synchronous version of encode.
+     * Encode a frame to packets synchronously.
+     * Synchronous version of encodeAll.
      *
-     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * Sends a frame to the encoder and receives all available encoded packets.
+     * Returns array of packets - may be empty if encoder needs more data.
      * On first frame, automatically initializes encoder with frame properties.
-     * Handles internal buffering - may return null if more frames needed.
+     * One frame can produce zero, one, or multiple packets depending on codec.
      *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @param frame - Raw frame to encode (or null to flush)
      *
-     * @returns Encoded packet, null if more data needed, or null if encoder is closed
+     * @returns Array of encoded packets (empty if more data needed or encoder is closed)
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * const packet = encoder.encodeSync(frame);
-     * if (packet) {
+     * const packets = encoder.encodeAllSync(frame);
+     * for (const packet of packets) {
      *   console.log(`Encoded packet with PTS: ${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
@@ -319,8 +511,8 @@ export declare class Encoder implements Disposable {
      * ```typescript
      * // Encode loop
      * for (const frame of decoder.framesSync(packets)) {
-     *   const packet = encoder.encodeSync(frame);
-     *   if (packet) {
+     *   const packets = encoder.encodeAllSync(frame);
+     *   for (const packet of packets) {
      *     output.writePacketSync(packet);
      *     packet.free();
      *   }
@@ -328,27 +520,38 @@ export declare class Encoder implements Disposable {
      * }
      * ```
      *
-     * @see {@link encode} For async version
+     * @see {@link encodeSync} For single packet encoding
+     * @see {@link packetsSync} For automatic frame iteration
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link encodeAll} For async version
      */
-    encodeSync(frame: Frame | null): Packet | null;
+    encodeAllSync(frame: Frame | null): Packet[];
     /**
      * Encode frame stream to packet stream.
      *
      * High-level async generator for complete encoding pipeline.
-     * Automatically manages frame memory, encoder state,
-     * and flushes buffered packets at end.
+     * Encoder is only flushed when EOF (null) signal is explicitly received.
      * Primary interface for stream-based encoding.
      *
-     * @param frames - Async iterable of frames (freed automatically)
+     * **EOF Handling:**
+     * - Send null to flush encoder and get remaining buffered packets
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - encoder stays open until EOF or close()
+     *
+     * @param frames - Async iterable of frames, single frame, or null to flush
      *
-     * @yields {Packet} Encoded packets (caller must free)
+     * @yields {Packet | null} Encoded packets, followed by null when explicitly flushed
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * // Basic encoding pipeline
+     * // Stream of frames with automatic EOF propagation
      * for await (const packet of encoder.packets(decoder.frames(input.packets()))) {
+     *   if (packet === null) {
+     *     console.log('Encoder flushed');
+     *     break;
+     *   }
      *   await output.writePacket(packet);
      *   packet.free(); // Must free output packets
      * }
@@ -356,60 +559,60 @@ export declare class Encoder implements Disposable {
      *
      * @example
      * ```typescript
-     * // With frame filtering
-     * async function* filteredFrames() {
-     *   for await (const frame of decoder.frames(input.packets())) {
-     *     const filtered = await filter.process(frame);
-     *     if (filtered) {
-     *       yield filtered;
-     *     }
-     *     frame.free();
-     *   }
-     * }
-     *
-     * for await (const packet of encoder.packets(filteredFrames())) {
+     * // Single frame - no automatic flush
+     * for await (const packet of encoder.packets(singleFrame)) {
      *   await output.writePacket(packet);
      *   packet.free();
      * }
+     * // Encoder remains open, buffered packets not flushed
      * ```
      *
      * @example
      * ```typescript
-     * // Pipeline integration
-     * import { pipeline } from 'node-av/api';
-     *
-     * const control = pipeline(
-     *   input,
-     *   decoder,
-     *   encoder,
-     *   output
-     * );
-     * await control.completion;
+     * // Explicit flush with EOF
+     * for await (const packet of encoder.packets(null)) {
+     *   if (packet === null) {
+     *     console.log('All buffered packets flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered packet:', packet.pts);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
      * ```
      *
      * @see {@link encode} For single frame encoding
      * @see {@link Decoder.frames} For frame source
+     * @see {@link packetsSync} For sync version
      */
-    packets(frames: AsyncIterable<Frame>): AsyncGenerator<Packet>;
+    packets(frames: AsyncIterable<Frame | null> | Frame | null): AsyncGenerator<Packet | null>;
     /**
      * Encode frame stream to packet stream synchronously.
      * Synchronous version of packets.
      *
      * High-level sync generator for complete encoding pipeline.
-     * Automatically manages frame memory, encoder state,
-     * and flushes buffered packets at end.
+     * Encoder is only flushed when EOF (null) signal is explicitly received.
      * Primary interface for stream-based encoding.
      *
-     * @param frames - Iterable of frames (freed automatically)
+     * **EOF Handling:**
+     * - Send null to flush encoder and get remaining buffered packets
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - encoder stays open until EOF or close()
+     *
+     * @param frames - Iterable of frames, single frame, or null to flush
      *
-     * @yields {Packet} Encoded packets (caller must free)
+     * @yields {Packet | null} Encoded packets, followed by null when explicitly flushed
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * // Basic encoding pipeline
+     * // Stream of frames with automatic EOF propagation
      * for (const packet of encoder.packetsSync(decoder.framesSync(packets))) {
+     *   if (packet === null) {
+     *     console.log('Encoder flushed');
+     *     break;
+     *   }
      *   output.writePacketSync(packet);
      *   packet.free(); // Must free output packets
      * }
@@ -417,26 +620,33 @@ export declare class Encoder implements Disposable {
      *
      * @example
      * ```typescript
-     * // With frame filtering
-     * function* filteredFrames() {
-     *   for (const frame of decoder.framesSync(packets)) {
-     *     const filtered = filter.processSync(frame);
-     *     if (filtered) {
-     *       yield filtered;
-     *     }
-     *     frame.free();
-     *   }
+     * // Single frame - no automatic flush
+     * for (const packet of encoder.packetsSync(singleFrame)) {
+     *   output.writePacketSync(packet);
+     *   packet.free();
      * }
+     * // Encoder remains open, buffered packets not flushed
+     * ```
      *
-     * for (const packet of encoder.packetsSync(filteredFrames())) {
+     * @example
+     * ```typescript
+     * // Explicit flush with EOF
+     * for (const packet of encoder.packetsSync(null)) {
+     *   if (packet === null) {
+     *     console.log('All buffered packets flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered packet:', packet.pts);
      *   output.writePacketSync(packet);
      *   packet.free();
      * }
      * ```
      *
+     * @see {@link encodeSync} For single frame encoding
+     * @see {@link Decoder.framesSync} For frame source
      * @see {@link packets} For async version
      */
-    packetsSync(frames: Iterable<Frame>): Generator<Packet>;
+    packetsSync(frames: Iterable<Frame | null> | Frame | null): Generator<Packet | null>;
     /**
      * Flush encoder and signal end-of-stream.
      *
@@ -462,6 +672,7 @@ export declare class Encoder implements Disposable {
      *
      * @see {@link flushPackets} For async iteration
      * @see {@link receive} For getting buffered packets
+     * @see {@link flushSync} For synchronous version
      */
     flush(): Promise<void>;
     /**
@@ -488,6 +699,8 @@ export declare class Encoder implements Disposable {
      * }
      * ```
      *
+     * @see {@link flushPacketsSync} For sync iteration
+     * @see {@link receiveSync} For getting buffered packets
      * @see {@link flush} For async version
      */
     flushSync(): void;
@@ -510,8 +723,9 @@ export declare class Encoder implements Disposable {
      * }
      * ```
      *
+     * @see {@link encode} For sending frames and receiving packets
      * @see {@link flush} For signaling end-of-stream
-     * @see {@link packets} For complete pipeline
+     * @see {@link flushPacketsSync} For synchronous version
      */
     flushPackets(): AsyncGenerator<Packet>;
     /**
@@ -534,6 +748,8 @@ export declare class Encoder implements Disposable {
      * }
      * ```
      *
+     * @see {@link encodeSync} For sending frames and receiving packets
+     * @see {@link flushSync} For signaling end-of-stream
      * @see {@link flushPackets} For async version
      */
     flushPacketsSync(): Generator<Packet>;
@@ -542,19 +758,25 @@ export declare class Encoder implements Disposable {
      *
      * Gets encoded packets from the codec's internal buffer.
      * Handles packet cloning and error checking.
-     * Returns null if encoder is closed, not initialized, or no packets available.
-     * Call repeatedly until null to drain all buffered packets.
+     * Implements FFmpeg's send/receive pattern.
+     *
+     * **Return Values:**
+     * - `Packet` - Successfully encoded packet (AVERROR >= 0)
+     * - `null` - Need more input frames (AVERROR_EAGAIN), or encoder not initialized
+     * - `undefined` - End of stream reached (AVERROR_EOF), or encoder is closed
      *
      * Direct mapping to avcodec_receive_packet().
      *
-     * @returns Cloned packet or null if no packets available
+     * @returns Cloned packet, null if need more data, or undefined if stream ended
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
-     * const packet = await encoder.receive();
-     * if (packet) {
+     * // Process all buffered packets
+     * while (true) {
+     *   const packet = await encoder.receive();
+     *   if (!packet) break; // Stop on EAGAIN or EOF
      *   console.log(`Got packet with PTS: ${packet.pts}`);
      *   await output.writePacket(packet);
      *   packet.free();
@@ -563,10 +785,14 @@ export declare class Encoder implements Disposable {
      *
      * @example
      * ```typescript
-     * // Drain all buffered packets
-     * let packet;
-     * while ((packet = await encoder.receive()) !== null) {
-     *   console.log(`Packet size: ${packet.size}`);
+     * // Handle each return value explicitly
+     * const packet = await encoder.receive();
+     * if (packet === EOF) {
+     *   console.log('Encoder stream ended');
+     * } else if (packet === null) {
+     *   console.log('Need more input frames');
+     * } else {
+     *   console.log(`Got packet: pts=${packet.pts}`);
      *   await output.writePacket(packet);
      *   packet.free();
      * }
@@ -574,27 +800,35 @@ export declare class Encoder implements Disposable {
      *
      * @see {@link encode} For sending frames and receiving packets
      * @see {@link flush} For signaling end-of-stream
+     * @see {@link receiveSync} For synchronous version
+     * @see {@link EOF} For end-of-stream signal
      */
-    receive(): Promise<Packet | null>;
+    receive(): Promise<Packet | EOFSignal | null>;
     /**
      * Receive packet from encoder synchronously.
      * Synchronous version of receive.
      *
      * Gets encoded packets from the codec's internal buffer.
      * Handles packet cloning and error checking.
-     * Returns null if encoder is closed, not initialized, or no packets available.
-     * Call repeatedly until null to drain all buffered packets.
+     * Implements FFmpeg's send/receive pattern.
+     *
+     * **Return Values:**
+     * - `Packet` - Successfully encoded packet (AVERROR >= 0)
+     * - `null` - Need more input frames (AVERROR_EAGAIN), or encoder not initialized
+     * - `undefined` - End of stream reached (AVERROR_EOF), or encoder is closed
      *
      * Direct mapping to avcodec_receive_packet().
      *
-     * @returns Cloned packet or null if no packets available
+     * @returns Cloned packet, null if need more data, or undefined if stream ended
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
-     * const packet = encoder.receiveSync();
-     * if (packet) {
+     * // Process all buffered packets
+     * while (true) {
+     *   const packet = encoder.receiveSync();
+     *   if (!packet) break; // Stop on EAGAIN or EOF
      *   console.log(`Got packet with PTS: ${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
@@ -603,18 +837,40 @@ export declare class Encoder implements Disposable {
      *
      * @example
      * ```typescript
-     * // Drain all buffered packets
-     * let packet;
-     * while ((packet = encoder.receiveSync()) !== null) {
-     *   console.log(`Packet size: ${packet.size}`);
+     * // Handle each return value explicitly
+     * const packet = encoder.receiveSync();
+     * if (packet === EOF) {
+     *   console.log('Encoder stream ended');
+     * } else if (packet === null) {
+     *   console.log('Need more input frames');
+     * } else {
+     *   console.log(`Got packet: pts=${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
      * }
      * ```
      *
+     * @see {@link encodeSync} For sending frames and receiving packets
+     * @see {@link flushSync} For signaling end-of-stream
      * @see {@link receive} For async version
+     * @see {@link EOF} For end-of-stream signal
+     */
+    receiveSync(): Packet | EOFSignal | null;
+    /**
+     * Pipe encoded packets to muxer.
+     *
+     * @param target - Media output component to write packets to
+     *
+     * @param streamIndex - Stream index to write packets to
+     *
+     * @returns Scheduler for continued chaining
+     *
+     * @example
+     * ```typescript
+     * decoder.pipeTo(filter).pipeTo(encoder)
+     * ```
      */
-    receiveSync(): Packet | null;
+    pipeTo(target: Muxer, streamIndex: number): SchedulerControl<Frame>;
     /**
      * Close encoder and free resources.
      *
@@ -635,6 +891,65 @@ export declare class Encoder implements Disposable {
      * @see {@link Symbol.dispose} For automatic cleanup
      */
     close(): void;
+    /**
+     * Get encoder codec.
+     *
+     * Returns the codec used by this encoder.
+     * 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 encoder is closed or not initialized.
+     *
+     * @returns Codec context or null if closed/not initialized
+     *
+     * @internal
+     *
+     * @see {@link CodecContext} For context details
+     */
+    getCodecContext(): CodecContext | null;
+    /**
+     * Worker loop for push-based processing.
+     *
+     * @internal
+     */
+    private runWorker;
+    /**
+     * Send frame to input queue or flush the pipeline.
+     *
+     * When frame is provided, queues it for encoding.
+     * When null is provided, triggers flush sequence:
+     * - Closes input queue
+     * - Waits for worker completion
+     * - Flushes encoder and sends remaining packets to output queue
+     * - Closes output queue
+     * - Waits for pipeTo task completion (writes to muxer)
+     *
+     * Used by scheduler system for pipeline control.
+     *
+     * @param frame - Frame to send, or null to flush
+     *
+     * @internal
+     */
+    private sendToQueue;
+    /**
+     * Receive packet from output queue.
+     *
+     * @returns Packet from output queue
+     *
+     * @internal
+     */
+    private receiveFromQueue;
     /**
      * Initialize encoder from first frame.
      *
@@ -667,57 +982,33 @@ export declare class Encoder implements Disposable {
      */
     private initializeSync;
     /**
-     * Get encoder codec.
+     * Setup hardware acceleration for encoder.
      *
-     * Returns the codec used by this encoder.
-     * Useful for checking codec capabilities and properties.
+     * Implements FFmpeg's hw_device_setup_for_encode logic.
+     * Validates hardware frames context format and codec support.
+     * Falls back to device context if frames context is incompatible.
      *
-     * @returns Codec instance
+     * @param frame - Frame to get hardware context from
      *
      * @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 encoder is closed or not initialized.
-     *
-     * @returns Codec context or null if closed/not initialized
-     *
-     * @internal
-     *
-     * @see {@link CodecContext} For context details
      */
-    getCodecContext(): CodecContext | null;
+    private setupHardwareAcceleration;
     /**
-     * Get codec flags even before encoder initialization.
+     * Prepare frame for encoding.
      *
-     * Unlike getCodecContext(), this works before initialization.
+     * Implements FFmpeg's frame_encode() pre-encoding logic:
+     * 1. Video: Sets frame.quality from encoder's globalQuality (like -qscale)
+     * 2. Audio: Validates channel count consistency for encoders without PARAM_CHANGE capability
      *
-     * @returns Current codec flags
+     * This matches FFmpeg CLI behavior where these properties are automatically managed.
      *
-     * @throws {Error} If encoder is closed
+     * @param frame - Frame to prepare for encoding
      *
-     * @internal
-     */
-    getCodecFlags(): AVCodecFlag;
-    /**
-     * Set codec flags before encoder initialization.
-     *
-     * This allows setting flags on the codec context before the encoder is opened,
-     * which is necessary for flags that affect initialization behavior (like GLOBAL_HEADER).
-     *
-     * @param flags - The flags to set
-     *
-     * @throws {Error} If encoder is already initialized or closed
+     * @throws {Error} If audio channel count changed and encoder doesn't support parameter changes
      *
      * @internal
      */
-    setCodecFlags(flags: AVCodecFlag): void;
+    private prepareFrameForEncoding;
     /**
      * Dispose of encoder.
      *