node-av 1.1.0 → 1.2.0

package/dist/api/encoder.js

@@ -1,91 +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 { AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
-import { AVERROR_EAGAIN, Codec, CodecContext, FFmpegError, Packet, Rational } from '../lib/index.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
+ *   await output.writePacket(packet);
+ *   packet.free();
  * }
- *
- * // Flush encoder
- * let packet;
- * while ((packet = await encoder.flush()) !== null) {
- *   // Process final packets
- * }
- * 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 for hardware pixel format
+    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 hardware pixel format
+     * @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();
@@ -93,37 +80,60 @@ 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 encoderCodec - Codec to use for encoding
-     * @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(encoderCodec, input, options = {}) {
         let codec = null;
@@ -149,9 +159,16 @@ export class Encoder {
         // 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}`);
+            }
             codecContext.width = videoInfo.width;
             codecContext.height = videoInfo.height;
-            codecContext.pixelFormat = videoInfo.pixelFormat; // Will be overwritten if it's a hardware encoder
+            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);
@@ -164,6 +181,13 @@ export class Encoder {
         }
         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}`);
+            }
             codecContext.sampleRate = audioInfo.sampleRate;
             codecContext.sampleFormat = audioInfo.sampleFormat;
             codecContext.channelLayout = audioInfo.channelLayout;
@@ -205,6 +229,7 @@ export class Encoder {
         }
         const isHWEncoder = codec.isHardwareAcceleratedEncoder();
         if (isHWEncoder && !options.hardware) {
+            codecContext.freeContext();
             throw new Error(`Hardware encoder '${codecName}' requires a hardware context`);
         }
         // Open codec
@@ -213,80 +238,79 @@ export class Encoder {
             codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open encoder');
         }
-        const encoder = new Encoder(codecContext, codecName, isHWEncoder ? options.hardware : undefined);
-        // 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;
     }
     /**
-     * Get output stream information.
+     * Check if encoder uses hardware acceleration.
      *
-     * Returns the encoder output format configuration.
-     * Useful for setting up subsequent processing stages.
+     * @returns true if hardware-accelerated
      *
-     * For hardware encoders, returns the hardware pixel format even before
-     * the first frame is encoded.
+     * @example
+     * ```typescript
+     * if (encoder.isHardware()) {
+     *   console.log('Using GPU acceleration');
+     * }
+     * ```
      *
-     * @returns StreamInfo with encoder output properties
+     * @see {@link HardwareContext} For hardware setup
      */
-    getOutputStreamInfo() {
-        if (this.codecContext.codecType === AVMEDIA_TYPE_VIDEO) {
-            // For hardware encoders, we need to return the hardware pixel format
-            // even if it hasn't been set yet on the codec context
-            const pixelFormat = this.hardware?.getHardwarePixelFormat() ?? this.codecContext.pixelFormat;
-            return {
-                type: 'video',
-                width: this.codecContext.width,
-                height: this.codecContext.height,
-                pixelFormat,
-                timeBase: this.codecContext.timeBase,
-                frameRate: this.codecContext.framerate,
-                sampleAspectRatio: this.codecContext.sampleAspectRatio,
-            };
-        }
-        else {
-            // For audio
-            return {
-                type: 'audio',
-                sampleRate: this.codecContext.sampleRate,
-                sampleFormat: this.codecContext.sampleFormat,
-                channelLayout: this.codecContext.channelLayout,
-                timeBase: this.codecContext.timeBase,
-            };
-        }
+    isHardware() {
+        return !!this.hardware;
     }
     /**
-     * Encode a frame and return a packet if available.
-     *
-     * Sends frame to encoder and attempts to receive a packet.
-     * May return null if encoder needs more data.
+     * 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) {
@@ -297,7 +321,7 @@ export class Encoder {
         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.getHardwarePixelFormat();
+            this.codecContext.pixelFormat = this.hardware.devicePixelFormat;
         }
         // Send frame to encoder
         const sendRet = await this.codecContext.sendFrame(frame);
@@ -312,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.
+     * Encode frame stream to packet stream.
      *
-     * Encodes all provided frames and yields resulting packets.
-     * Automatically handles encoder flushing at the end.
-     * Input frames are automatically freed after encoding.
+     * 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.
      *
-     * Processes frames in sequence, encoding each and yielding packets.
-     * After all frames are processed, flushes the encoder for remaining packets.
-     *
-     * 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) {
@@ -364,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) {
@@ -393,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) {
@@ -426,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.
+     * Get encoder codec.
      *
-     * Provides access to the underlying AVCodecContext for advanced operations.
+     * Returns the codec used by this encoder.
+     * Useful for checking codec capabilities and properties.
      *
-     * @returns CodecContext or null if closed
-     *
-     * @internal
-     */
-    getCodecContext() {
-        return this.isOpen ? this.codecContext : null;
-    }
-    /**
-     * Get the preferred pixel format for this encoder.
-     *
-     * Returns the first supported format, which is usually the most efficient.
-     *
-     * @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
@@ -524,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();