node-av 1.0.3 → 1.2.0

package/dist/api/encoder.js

@@ -1,92 +1,78 @@
-/**
- * Encoder - High-level wrapper for media encoding
- *
- * Simplifies FFmpeg's encoding API with automatic codec selection,
- * parameter configuration, and packet management.
- *
- * Handles codec initialization, frame encoding, and packet output.
- * Supports hardware acceleration and zero-copy transcoding.
- *
- * @module api/encoder
- */
-import { AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, Codec, CodecContext, FFmpegError, Packet, Rational, } from '../lib/index.js';
-import { Stream } from '../lib/stream.js';
+import { AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
+import { AVERROR_EAGAIN, avGetPixFmtName, avGetSampleFmtName, Codec, CodecContext, FFmpegError, Packet, Rational } from '../lib/index.js';
 import { parseBitrate } from './utils.js';
 /**
- * High-level encoder for media streams.
- *
- * Handles codec initialization, frame encoding, and packet output.
- * Supports various codecs with flexible configuration options.
+ * High-level encoder for audio and video streams.
  *
- * Manages codec context lifecycle and provides automatic cleanup.
- * Supports hardware acceleration with shared frames context for zero-copy.
+ * Provides a simplified interface for encoding media frames to packets.
+ * Handles codec initialization, hardware acceleration setup, and packet management.
+ * Supports both synchronous frame-by-frame encoding and async iteration over packets.
+ * Essential component in media processing pipelines for converting raw frames to compressed data.
  *
  * @example
  * ```typescript
+ * import { Encoder } from 'node-av/api';
+ * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+ *
  * // Create H.264 encoder
  * const encoder = await Encoder.create('libx264', {
+ *   type: 'video',
  *   width: 1920,
  *   height: 1080,
- *   pixelFormat: 'yuv420p',
+ *   pixelFormat: AV_PIX_FMT_YUV420P,
+ *   timeBase: { num: 1, den: 30 },
+ *   frameRate: { num: 30, den: 1 }
+ * }, {
  *   bitrate: '5M',
- *   gopSize: 60,
- *   options: {
- *     preset: 'fast',
- *     crf: 23
- *   }
+ *   gopSize: 60
  * });
  *
  * // Encode frames
  * const packet = await encoder.encode(frame);
  * if (packet) {
- *   // Write packet to output
- * }
- *
- * // Flush encoder
- * let packet;
- * while ((packet = await encoder.flush()) !== null) {
- *   // Process final packets
+ *   await output.writePacket(packet);
+ *   packet.free();
  * }
- * encoder.close();
  * ```
  *
  * @example
  * ```typescript
- * // With hardware acceleration
- * const hw = await HardwareContext.auto();
- * const encoder = await Encoder.create('h264_videotoolbox', {
- *   width: 1920,
- *   height: 1080,
- *   pixelFormat: 'nv12',
- *   bitrate: '5M',
- *   hardware: hw
+ * // Hardware-accelerated encoding
+ * import { HardwareContext } from 'node-av/api';
+ * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
+ *
+ * const hw = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
+ * const encoder = await Encoder.create('h264_nvenc', streamInfo, {
+ *   hardware: hw,
+ *   bitrate: '10M'
  * });
- * // ... use encoder
- * encoder.close(); // Also disposes hardware
- * hw?.dispose(); // Safe to call again (no-op)
+ *
+ * // Frames with hw_frames_ctx will be encoded on GPU
+ * for await (const packet of encoder.packets(frames)) {
+ *   await output.writePacket(packet);
+ *   packet.free();
+ * }
  * ```
+ *
+ * @see {@link Decoder} For decoding packets to frames
+ * @see {@link MediaOutput} For writing encoded packets
+ * @see {@link HardwareContext} For GPU acceleration
  */
 export class Encoder {
     codecContext;
     packet;
-    codecName;
+    codec;
     isOpen = true;
-    supportedFormats = [];
-    preferredFormat;
-    hardware; // Store reference to check for late framesContext
-    isHardwareEncoder = false; // Track if this is a hardware encoder
+    hardware;
     /**
-     * Private constructor - use Encoder.create() instead.
-     *
-     * Initializes the encoder with a codec context and allocates a packet buffer.
-     *
-     * @param codecContext - Initialized codec context
-     * @param codecName - Name of the codec
-     * @param hardware - Optional hardware context for late framesContext binding
+     * @param codecContext - Configured codec context
+     * @param codec - Encoder codec
+     * @param hardware - Optional hardware context
+     * @internal
      */
-    constructor(codecContext, codecName, hardware) {
+    constructor(codecContext, codec, hardware) {
         this.codecContext = codecContext;
-        this.codecName = codecName;
+        this.codec = codec;
         this.hardware = hardware;
         this.packet = new Packet();
         this.packet.alloc();
@@ -94,122 +80,128 @@ export class Encoder {
     /**
      * Create an encoder with specified codec and options.
      *
-     * Factory method that handles codec discovery, context setup,
-     * and initialization.
+     * Initializes an encoder with the appropriate codec and configuration.
+     * Automatically configures parameters based on input stream info.
+     * Handles hardware acceleration setup if provided.
      *
-     * Uses avcodec_find_encoder_by_name() to locate the codec,
-     * configures the context with provided options, and opens it.
-     * Handles hardware setup including shared frames context for zero-copy.
+     * Direct mapping to avcodec_find_encoder_by_name() or avcodec_find_encoder().
      *
-     * @param codecName - Name of codec (e.g., 'libx264', 'aac', 'libopus')
-     * @param input - Stream or StreamInfo to copy parameters from
+     * @param encoderCodec - Codec name, ID, or instance to use for encoding
+     * @param input - Stream information to configure encoder
      * @param options - Encoder configuration options
+     * @returns Configured encoder instance
      *
-     * @returns Promise resolving to configured Encoder
-     *
-     * @throws {Error} If codec not found or configuration fails
+     * @throws {Error} If encoder not found or unsupported format
+     * @throws {FFmpegError} If codec initialization fails
      *
      * @example
      * ```typescript
-     * // Video encoder from stream
-     * const videoStream = media.video();
-     * const videoEncoder = await Encoder.create('libx264', videoStream, {
+     * // From decoder stream info
+     * const streamInfo = decoder.getOutputStreamInfo();
+     * const encoder = await Encoder.create('libx264', streamInfo, {
      *   bitrate: '5M',
-     *   gopSize: 60
+     *   gopSize: 60,
+     *   options: {
+     *     preset: 'fast',
+     *     crf: '23'
+     *   }
      * });
+     * ```
      *
-     * // Audio encoder from stream
-     * const audioStream = media.audio();
-     * const audioEncoder = await Encoder.create('aac', audioStream, {
+     * @example
+     * ```typescript
+     * // With custom stream info
+     * const encoder = await Encoder.create('aac', {
+     *   type: 'audio',
+     *   sampleRate: 48000,
+     *   sampleFormat: AV_SAMPLE_FMT_FLTP,
+     *   channelLayout: AV_CH_LAYOUT_STEREO,
+     *   timeBase: { num: 1, den: 48000 }
+     * }, {
      *   bitrate: '192k'
      * });
+     * ```
      *
+     * @example
+     * ```typescript
+     * // Hardware encoder
+     * const hw = HardwareContext.auto();
+     * const encoder = await Encoder.create('hevc_videotoolbox', streamInfo, {
+     *   hardware: hw,
+     *   bitrate: '8M'
+     * });
      * ```
+     *
+     * @see {@link Decoder.getOutputStreamInfo} For stream info source
+     * @see {@link EncoderOptions} For configuration options
      */
-    static async create(codecName, input, options = {}) {
-        const actualCodecName = codecName;
-        // Find encoder by name
-        const codec = Codec.findEncoderByName(actualCodecName);
+    static async create(encoderCodec, input, options = {}) {
+        let codec = null;
+        let codecName = '';
+        if (encoderCodec instanceof Codec) {
+            codec = encoderCodec;
+            codecName = codec.name ?? 'Unknown';
+        }
+        else if (typeof encoderCodec === 'string') {
+            codec = Codec.findEncoderByName(encoderCodec);
+            codecName = codec?.name ?? encoderCodec;
+        }
+        else {
+            codec = Codec.findEncoder(encoderCodec);
+            codecName = codec?.name ?? encoderCodec.toString();
+        }
         if (!codec) {
-            throw new Error(`Encoder ${actualCodecName} not found`);
+            throw new Error(`Encoder ${codecName} not found`);
         }
         // Allocate codec context
         const codecContext = new CodecContext();
         codecContext.allocContext3(codec);
-        // Apply parameters based on input type
-        if (input instanceof Stream) {
-            // It's a Stream - copy ONLY the essential parameters
-            // DO NOT use parametersToContext as it copies everything including decoder-specific settings
-            if (codec.type === AVMEDIA_TYPE_VIDEO) {
-                // Set required video parameters from input stream
-                codecContext.width = input.codecpar.width;
-                codecContext.height = input.codecpar.height;
-                codecContext.pixelFormat = input.codecpar.format;
-                // Set timing information
-                codecContext.pktTimebase = input.timeBase;
-                codecContext.timeBase = input.timeBase;
-                // Set framerate if available
-                if (input.avgFrameRate && input.avgFrameRate.num > 0 && input.avgFrameRate.den > 0) {
-                    codecContext.framerate = new Rational(input.avgFrameRate.num, input.avgFrameRate.den);
-                }
-                else if (input.rFrameRate && input.rFrameRate.num > 0 && input.rFrameRate.den > 0) {
-                    codecContext.framerate = new Rational(input.rFrameRate.num, input.rFrameRate.den);
-                }
-                // Copy sample aspect ratio if present
-                if (input.sampleAspectRatio && input.sampleAspectRatio.num > 0) {
-                    codecContext.sampleAspectRatio = new Rational(input.sampleAspectRatio.num, input.sampleAspectRatio.den);
-                }
+        // It's StreamInfo - apply manually
+        if (input.type === 'video' && codec.type === AVMEDIA_TYPE_VIDEO) {
+            const videoInfo = input;
+            const codecPixelformats = codec.pixelFormats;
+            if (codecPixelformats && !codecPixelformats.includes(videoInfo.pixelFormat)) {
+                codecContext.freeContext();
+                const pixelFormatName = avGetPixFmtName(videoInfo.pixelFormat) ?? 'unknown';
+                const codecPixFmtNames = codecPixelformats.map(avGetPixFmtName).filter(Boolean).join(', ');
+                throw new Error(`Unsupported pixel format for '${codecName}' encoder: ${pixelFormatName}! Supported formats: ${codecPixFmtNames}`);
             }
-            else if (codec.type === AVMEDIA_TYPE_AUDIO) {
-                // Set required audio parameters from input stream
-                codecContext.sampleRate = input.codecpar.sampleRate;
-                codecContext.sampleFormat = input.codecpar.format;
-                // Copy channel layout from input
-                // NOTE: This means the encoder will use the same channel configuration as the input
-                // If you need different channels, use an audio filter or pass StreamInfo instead
-                codecContext.channelLayout = input.codecpar.channelLayout;
-                // Set timing information
-                codecContext.pktTimebase = input.timeBase;
-                codecContext.timeBase = input.timeBase;
+            codecContext.width = videoInfo.width;
+            codecContext.height = videoInfo.height;
+            codecContext.pixelFormat = videoInfo.pixelFormat;
+            // Set pkt_timebase and timeBase to input timebase
+            codecContext.pktTimebase = new Rational(videoInfo.timeBase.num, videoInfo.timeBase.den);
+            codecContext.timeBase = new Rational(videoInfo.timeBase.num, videoInfo.timeBase.den);
+            if (videoInfo.frameRate) {
+                codecContext.framerate = new Rational(videoInfo.frameRate.num, videoInfo.frameRate.den);
             }
-            else {
-                codecContext.freeContext();
-                throw new Error('Unsupported codec type for encoder');
+            if (videoInfo.sampleAspectRatio) {
+                codecContext.sampleAspectRatio = new Rational(videoInfo.sampleAspectRatio.num, videoInfo.sampleAspectRatio.den);
             }
         }
-        else {
-            // It's StreamInfo - apply manually
-            if (input.type === 'video' && codec.type === AVMEDIA_TYPE_VIDEO) {
-                const videoInfo = input;
-                codecContext.width = videoInfo.width;
-                codecContext.height = videoInfo.height;
-                codecContext.pixelFormat = videoInfo.pixelFormat;
-                // Set pkt_timebase and timeBase to input timebase
-                codecContext.pktTimebase = new Rational(videoInfo.timeBase.num, videoInfo.timeBase.den);
-                codecContext.timeBase = new Rational(videoInfo.timeBase.num, videoInfo.timeBase.den);
-                if (videoInfo.frameRate) {
-                    codecContext.framerate = new Rational(videoInfo.frameRate.num, videoInfo.frameRate.den);
-                }
-                if (videoInfo.sampleAspectRatio) {
-                    codecContext.sampleAspectRatio = new Rational(videoInfo.sampleAspectRatio.num, videoInfo.sampleAspectRatio.den);
-                }
-            }
-            else if (input.type === 'audio' && codec.type === AVMEDIA_TYPE_AUDIO) {
-                const audioInfo = input;
-                codecContext.sampleRate = audioInfo.sampleRate;
-                codecContext.sampleFormat = audioInfo.sampleFormat;
-                codecContext.channelLayout = audioInfo.channelLayout;
-                // Set both pkt_timebase and timeBase for audio
-                codecContext.pktTimebase = new Rational(audioInfo.timeBase.num, audioInfo.timeBase.den);
-                codecContext.timeBase = new Rational(audioInfo.timeBase.num, audioInfo.timeBase.den);
-                if (audioInfo.frameSize) {
-                    codecContext.frameSize = audioInfo.frameSize;
-                }
+        else if (input.type === 'audio' && codec.type === AVMEDIA_TYPE_AUDIO) {
+            const audioInfo = input;
+            const codecSampleFormats = codec.sampleFormats;
+            if (codecSampleFormats && !codecSampleFormats.includes(audioInfo.sampleFormat)) {
+                codecContext.freeContext();
+                const sampleFormatName = avGetSampleFmtName(audioInfo.sampleFormat) ?? 'unknown';
+                const supportedFormats = codecSampleFormats.map(avGetSampleFmtName).filter(Boolean).join(', ');
+                throw new Error(`Unsupported sample format for '${codecName}' encoder: ${sampleFormatName}! Supported formats: ${supportedFormats}`);
             }
-            else {
-                throw new Error(`Codec type mismatch: ${input.type} info but ${codec.type === AVMEDIA_TYPE_VIDEO ? 'video' : 'audio'} codec`);
+            codecContext.sampleRate = audioInfo.sampleRate;
+            codecContext.sampleFormat = audioInfo.sampleFormat;
+            codecContext.channelLayout = audioInfo.channelLayout;
+            // Set both pkt_timebase and timeBase for audio
+            codecContext.pktTimebase = new Rational(audioInfo.timeBase.num, audioInfo.timeBase.den);
+            codecContext.timeBase = new Rational(audioInfo.timeBase.num, audioInfo.timeBase.den);
+            if (audioInfo.frameSize) {
+                codecContext.frameSize = audioInfo.frameSize;
             }
         }
+        else {
+            codecContext.freeContext();
+            throw new Error(`Unsupported codec type for encoder! Input type: ${input.type}, Codec type: ${codec.type}`);
+        }
         // Apply encoder-specific options
         if (options.gopSize !== undefined) {
             codecContext.gopSize = options.gopSize;
@@ -235,106 +227,102 @@ export class Encoder {
                 codecContext.setOption(key, value.toString());
             }
         }
-        // Check if this encoder supports hardware acceleration
-        let supportsHardware = false;
-        let isHardwareEncoder = false;
-        // Check encoder's hardware configurations
-        for (let i = 0;; i++) {
-            const config = codec.getHwConfig(i);
-            if (!config)
-                break;
-            // Check if encoder supports HW_FRAMES_CTX method
-            if ((config.methods & AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX) !== 0) {
-                supportsHardware = true;
-                // If hardware context provided, check if it matches this encoder
-                if (options.hardware && config.deviceType === options.hardware.deviceType) {
-                    isHardwareEncoder = true;
-                    break;
-                }
-            }
-        }
-        // Validation: Hardware encoder MUST have HardwareContext
-        if (supportsHardware && !options.hardware) {
-            throw new Error(`Hardware encoder '${actualCodecName}' requires a hardware context. ` + 'Please provide one via options.hardware');
-        }
-        // Apply hardware acceleration if provided and encoder supports it
-        if (options.hardware && isHardwareEncoder) {
-            // Check if frames context already available (shared from decoder)
-            if (options.hardware.framesContext) {
-                codecContext.hwFramesCtx = options.hardware.framesContext;
-                codecContext.pixelFormat = options.hardware.getHardwarePixelFormat();
-            }
-            // Else: Will set hwFramesCtx later in encode() when first frame arrives
-            // DO NOT create frames context here - wait for first frame!
+        const isHWEncoder = codec.isHardwareAcceleratedEncoder();
+        if (isHWEncoder && !options.hardware) {
+            codecContext.freeContext();
+            throw new Error(`Hardware encoder '${codecName}' requires a hardware context`);
         }
-        // Note: Software encoder silently ignores hardware context
         // Open codec
         const openRet = await codecContext.open2(codec, null);
         if (openRet < 0) {
             codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open encoder');
         }
-        const encoder = new Encoder(codecContext, codecName, isHardwareEncoder ? options.hardware : undefined);
-        encoder.isHardwareEncoder = isHardwareEncoder;
-        // Get supported formats from codec (for validation and helpers)
-        if (codec.pixelFormats) {
-            encoder.supportedFormats = codec.pixelFormats;
-            encoder.preferredFormat = encoder.supportedFormats[0];
-        }
+        const encoder = new Encoder(codecContext, codec, isHWEncoder ? options.hardware : undefined);
         return encoder;
     }
     /**
      * Check if encoder is open.
+     *
+     * @example
+     * ```typescript
+     * if (encoder.isEncoderOpen) {
+     *   const packet = await encoder.encode(frame);
+     * }
+     * ```
      */
     get isEncoderOpen() {
         return this.isOpen;
     }
     /**
-     * Encode a frame and return a packet if available.
+     * Check if encoder uses hardware acceleration.
+     *
+     * @returns true if hardware-accelerated
+     *
+     * @example
+     * ```typescript
+     * if (encoder.isHardware()) {
+     *   console.log('Using GPU acceleration');
+     * }
+     * ```
      *
-     * Sends frame to encoder and attempts to receive a packet.
-     * May return null if encoder needs more data.
+     * @see {@link HardwareContext} For hardware setup
+     */
+    isHardware() {
+        return !!this.hardware;
+    }
+    /**
+     * Encode a frame to a packet.
      *
-     * Uses avcodec_send_frame() and avcodec_receive_packet() internally.
-     * The encoder may buffer frames before producing packets.
+     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * Handles internal buffering - may return null if more frames needed.
+     * Automatically manages encoder state and hardware context binding.
      *
-     * @param frame - Frame to encode (or null to flush)
+     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
-     * @returns Promise resolving to Packet or null
+     * @param frame - Raw frame to encode (or null to flush)
+     * @returns Encoded packet or null if more data needed
      *
-     * @throws {Error} If encoder is closed or encode fails
+     * @throws {Error} If encoder is closed
+     * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
      * const packet = await encoder.encode(frame);
      * if (packet) {
-     *   // Write packet to output
+     *   console.log(`Encoded packet with PTS: ${packet.pts}`);
      *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Encode loop
+     * for await (const frame of decoder.frames(input.packets())) {
+     *   const packet = await encoder.encode(frame);
+     *   if (packet) {
+     *     await output.writePacket(packet);
+     *     packet.free();
+     *   }
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link packets} For automatic frame iteration
+     * @see {@link flush} For end-of-stream handling
      */
     async encode(frame) {
         if (!this.isOpen) {
             throw new Error('Encoder is closed');
         }
-        // Late binding of hw_frames_ctx ONLY for hardware encoders
-        if (this.hardware && this.isHardwareEncoder && !this.codecContext.hwFramesCtx) {
-            if (this.hardware.framesContext) {
-                // Use shared frames context from decoder
-                this.codecContext.hwFramesCtx = this.hardware.framesContext;
-            }
-            else if (frame?.width && frame.height) {
-                // First frame - create frames context for upload
-                this.hardware.ensureFramesContext(frame.width, frame.height);
-                this.codecContext.hwFramesCtx = this.hardware.framesContext ?? null;
-            }
-            if (this.codecContext.hwFramesCtx) {
-                this.codecContext.pixelFormat = this.hardware.getHardwarePixelFormat();
-            }
+        // Late binding of hw_frames_ctx for hardware encoders
+        // Hardware encoders get hw_frames_ctx from the frames they receive
+        if (this.hardware && frame?.hwFramesCtx && !this.codecContext.hwFramesCtx) {
+            // Use the hw_frames_ctx from the frame
+            this.codecContext.hwFramesCtx = frame.hwFramesCtx;
+            this.codecContext.pixelFormat = this.hardware.devicePixelFormat;
         }
-        // Software encoder completely ignores hardware context
-        // NO MANUAL RESCALING! FFmpeg's avcodec_send_frame() does this internally
-        // The encoder needs pkt_timebase to be set for proper rescaling
         // Send frame to encoder
         const sendRet = await this.codecContext.sendFrame(frame);
         if (sendRet < 0 && sendRet !== AVERROR_EOF) {
@@ -348,33 +336,65 @@ export class Encoder {
             }
         }
         // Try to receive packet
-        return this.receivePacket();
+        return await this.receivePacket();
     }
     /**
-     * Async iterator that encodes frames and yields packets.
-     *
-     * Encodes all provided frames and yields resulting packets.
-     * Automatically handles encoder flushing at the end.
-     * Input frames are automatically freed after encoding.
+     * Encode frame stream to packet stream.
      *
-     * Processes frames in sequence, encoding each and yielding packets.
-     * After all frames are processed, flushes the encoder for remaining packets.
+     * High-level async generator for complete encoding pipeline.
+     * Automatically manages frame memory, encoder state,
+     * and flushes buffered packets at end.
+     * Primary interface for stream-based encoding.
      *
-     * IMPORTANT: The yielded packets MUST be freed by the caller!
-     * Input frames are automatically freed after processing.
-     *
-     * @param frames - Async iterable of frames to encode (will be freed automatically)
+     * @param frames - Async iterable of frames (freed automatically)
+     * @yields Encoded packets (caller must free)
+     * @throws {Error} If encoder is closed
+     * @throws {FFmpegError} If encoding fails
      *
-     * @yields Encoded packets (ownership transferred to caller)
+     * @example
+     * ```typescript
+     * // Basic encoding pipeline
+     * for await (const packet of encoder.packets(decoder.frames(input.packets()))) {
+     *   await output.writePacket(packet);
+     *   packet.free(); // Must free output packets
+     * }
+     * ```
      *
      * @example
      * ```typescript
-     * // Transcode video
-     * for await (const packet of encoder.packets(decoder.frames(media.packets()))) {
+     * // With frame filtering
+     * async function* filteredFrames() {
+     *   for await (const frame of decoder.frames(input.packets())) {
+     *     await filter.filterFrame(frame);
+     *     const filtered = await filter.getFrame();
+     *     if (filtered) {
+     *       yield filtered;
+     *     }
+     *   }
+     * }
+     *
+     * for await (const packet of encoder.packets(filteredFrames())) {
      *   await output.writePacket(packet);
-     *   packet.free(); // Must free output packet
+     *   packet.free();
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Pipeline integration
+     * import { pipeline } from 'node-av/api';
+     *
+     * const control = pipeline(
+     *   input,
+     *   decoder,
+     *   encoder,
+     *   output
+     * );
+     * await control.completion;
+     * ```
+     *
+     * @see {@link encode} For single frame encoding
+     * @see {@link Decoder.frames} For frame source
      */
     async *packets(frames) {
         if (!this.isOpen) {
@@ -400,27 +420,31 @@ export class Encoder {
         }
     }
     /**
-     * Flush encoder and get remaining packets.
+     * Flush encoder and get buffered packet.
      *
-     * Sends null frame to trigger flush mode.
-     * Call repeatedly until it returns null.
+     * Signals end-of-stream and retrieves remaining packets.
+     * Call repeatedly until null to get all buffered packets.
+     * Essential for ensuring all frames are encoded.
      *
-     * Uses avcodec_send_frame(NULL) to signal end of stream.
-     * Retrieves buffered packets from the encoder.
+     * Direct mapping to avcodec_send_frame(NULL).
      *
-     * @returns Promise resolving to Packet or null
+     * @returns Buffered packet or null if none remaining
      *
      * @throws {Error} If encoder is closed
      *
      * @example
      * ```typescript
-     * // Flush all remaining packets
+     * // Flush remaining packets
      * let packet;
      * while ((packet = await encoder.flush()) !== null) {
-     *   // Write final packets
+     *   console.log('Got buffered packet');
      *   await output.writePacket(packet);
+     *   packet.free();
      * }
      * ```
+     *
+     * @see {@link flushPackets} For async iteration
+     * @see {@link packets} For complete encoding pipeline
      */
     async flush() {
         if (!this.isOpen) {
@@ -429,26 +453,30 @@ export class Encoder {
         // Send flush frame (null)
         await this.codecContext.sendFrame(null);
         // Receive packet
-        return this.receivePacket();
+        return await this.receivePacket();
     }
     /**
-     * Flush encoder and yield all remaining packets as a generator.
-     *
-     * More convenient than calling flush() in a loop.
-     * Automatically sends flush signal and yields all buffered packets.
+     * Flush all buffered packets as async generator.
      *
-     * @returns Async generator of remaining packets
+     * Convenient async iteration over remaining packets.
+     * Automatically handles repeated flush calls.
+     * Useful for end-of-stream processing.
      *
+     * @yields Buffered packets
      * @throws {Error} If encoder is closed
      *
      * @example
      * ```typescript
-     * // Process all remaining packets with generator
+     * // Flush at end of encoding
      * for await (const packet of encoder.flushPackets()) {
-     *   await output.writePacket(packet, streamIdx);
-     *   using _ = packet; // Auto cleanup
+     *   console.log('Processing buffered packet');
+     *   await output.writePacket(packet);
+     *   packet.free();
      * }
      * ```
+     *
+     * @see {@link flush} For single packet flush
+     * @see {@link packets} For complete pipeline
      */
     async *flushPackets() {
         if (!this.isOpen) {
@@ -462,84 +490,74 @@ export class Encoder {
     /**
      * Close encoder and free resources.
      *
-     * After closing, the encoder cannot be used again.
+     * Releases codec context and internal packet buffer.
+     * Safe to call multiple times.
+     * Does NOT dispose hardware context - caller is responsible.
+     * Automatically called by Symbol.dispose.
      *
-     * Frees the packet buffer and codec context.
-     * Note: Does NOT dispose the HardwareContext - caller is responsible for that.
+     * @example
+     * ```typescript
+     * const encoder = await Encoder.create('libx264', streamInfo);
+     * try {
+     *   // Use encoder
+     * } finally {
+     *   encoder.close();
+     * }
+     * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
      */
     close() {
         if (!this.isOpen)
             return;
         this.packet.free();
         this.codecContext.freeContext();
-        // NOTE: We do NOT dispose the hardware context here anymore
-        // The caller who created the HardwareContext is responsible for disposing it
-        // This allows reusing the same HardwareContext for multiple encoders
         this.isOpen = false;
     }
     /**
-     * Get the codec name.
-     */
-    getCodecName() {
-        return this.codecName;
-    }
-    /**
-     * Get codec context for advanced configuration.
-     *
-     * Use with caution - direct manipulation may cause issues.
-     *
-     * Provides access to the underlying AVCodecContext for advanced operations.
-     *
-     * @returns CodecContext or null if closed
-     *
-     * @internal
-     */
-    getCodecContext() {
-        return this.isOpen ? this.codecContext : null;
-    }
-    /**
-     * Get the preferred pixel format for this encoder.
+     * Get encoder codec.
      *
-     * Returns the first supported format, which is usually the most efficient.
+     * Returns the codec used by this encoder.
+     * Useful for checking codec capabilities and properties.
      *
-     * @returns Preferred pixel format or null if not available
+     * @returns Codec instance
      *
      * @example
      * ```typescript
-     * const format = encoder.getPreferredPixelFormat();
-     * if (format) {
-     *   console.log(`Encoder prefers format: ${format}`);
-     * }
+     * const codec = encoder.getCodec();
+     * console.log(`Using codec: ${codec.name}`);
+     * console.log(`Capabilities: ${codec.capabilities}`);
      * ```
+     *
+     * @see {@link Codec} For codec properties
      */
-    getPreferredPixelFormat() {
-        return this.preferredFormat ?? null;
+    getCodec() {
+        return this.codec;
     }
     /**
-     * Get all supported pixel formats for this encoder.
+     * Get underlying codec context.
      *
-     * Returns a list of pixel formats that this encoder can accept.
+     * Returns the internal codec context for advanced operations.
+     * Returns null if encoder is closed.
      *
-     * @returns Array of supported pixel formats
+     * @returns Codec context or null
      *
-     * @example
-     * ```typescript
-     * const formats = encoder.getSupportedPixelFormats();
-     * console.log(`Encoder supports: ${formats.join(', ')}`);
-     * ```
+     * @internal
      */
-    getSupportedPixelFormats() {
-        return this.supportedFormats;
+    getCodecContext() {
+        return this.isOpen ? this.codecContext : null;
     }
     /**
-     * Receive a packet from the encoder.
+     * Receive packet from encoder.
      *
-     * Internal method to receive encoded packets.
+     * Internal method to get encoded packets from codec.
+     * Handles packet cloning and error checking.
      *
-     * Uses avcodec_receive_packet() to get encoded packets from the codec.
-     * Clones the packet for the user to prevent internal buffer corruption.
+     * Direct mapping to avcodec_receive_packet().
      *
-     * @returns Packet or null if no packet available
+     * @returns Cloned packet or null
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      */
     async receivePacket() {
         // Clear previous packet data
@@ -560,10 +578,20 @@ export class Encoder {
         }
     }
     /**
-     * Symbol.dispose for automatic cleanup.
+     * Dispose of encoder.
+     *
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling close().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using encoder = await Encoder.create('libx264', streamInfo);
+     *   // Encode frames...
+     * } // Automatically closed
+     * ```
      *
-     * Implements the Disposable interface for automatic resource management.
-     * Calls close() to free all resources.
+     * @see {@link close} For manual cleanup
      */
     [Symbol.dispose]() {
         this.close();