node-av 0.0.1

package/dist/api/encoder.d.ts

@@ -0,0 +1,298 @@
+/**
+ * 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 { CodecContext, Packet } from '../lib/index.js';
+import { Stream } from '../lib/stream.js';
+import type { AVPixelFormat, Frame } from '../lib/index.js';
+import type { EncoderOptions, StreamInfo } from './types.js';
+/**
+ * High-level encoder for media streams.
+ *
+ * Handles codec initialization, frame encoding, and packet output.
+ * Supports various codecs with flexible configuration options.
+ *
+ * Manages codec context lifecycle and provides automatic cleanup.
+ * Supports hardware acceleration with shared frames context for zero-copy.
+ *
+ * @example
+ * ```typescript
+ * // Create H.264 encoder
+ * const encoder = await Encoder.create('libx264', {
+ *   width: 1920,
+ *   height: 1080,
+ *   pixelFormat: 'yuv420p',
+ *   bitrate: '5M',
+ *   gopSize: 60,
+ *   options: {
+ *     preset: 'fast',
+ *     crf: 23
+ *   }
+ * });
+ *
+ * // 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
+ * }
+ * 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
+ * });
+ * // ... use encoder
+ * encoder.close(); // Also disposes hardware
+ * hw?.dispose(); // Safe to call again (no-op)
+ * ```
+ */
+export declare class Encoder implements Disposable {
+    private codecContext;
+    private packet;
+    private codecName;
+    private isOpen;
+    private supportedFormats;
+    private preferredFormat?;
+    private hardware?;
+    private isHardwareEncoder;
+    /**
+     * 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
+     */
+    private constructor();
+    /**
+     * Create an encoder with specified codec and options.
+     *
+     * Factory method that handles codec discovery, context setup,
+     * and initialization.
+     *
+     * 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.
+     *
+     * @param codecName - Name of codec (e.g., 'libx264', 'aac', 'libopus')
+     * @param input - Stream or StreamInfo to copy parameters from
+     * @param options - Encoder configuration options
+     *
+     * @returns Promise resolving to configured Encoder
+     *
+     * @throws {Error} If codec not found or configuration fails
+     *
+     * @example
+     * ```typescript
+     * // Video encoder from stream
+     * const videoStream = media.video();
+     * const videoEncoder = await Encoder.create('libx264', videoStream, {
+     *   bitrate: '5M',
+     *   gopSize: 60
+     * });
+     *
+     * // Audio encoder from stream
+     * const audioStream = media.audio();
+     * const audioEncoder = await Encoder.create('aac', audioStream, {
+     *   bitrate: '192k'
+     * });
+     *
+     * ```
+     */
+    static create(codecName: string, input: Stream | StreamInfo, options?: EncoderOptions): Promise<Encoder>;
+    /**
+     * Check if encoder is open.
+     */
+    get isEncoderOpen(): boolean;
+    /**
+     * 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.
+     *
+     * Uses avcodec_send_frame() and avcodec_receive_packet() internally.
+     * The encoder may buffer frames before producing packets.
+     *
+     * @param frame - Frame to encode (or null to flush)
+     *
+     * @returns Promise resolving to Packet or null
+     *
+     * @throws {Error} If encoder is closed or encode fails
+     *
+     * @example
+     * ```typescript
+     * const packet = await encoder.encode(frame);
+     * if (packet) {
+     *   // Write packet to output
+     *   await output.writePacket(packet);
+     * }
+     * ```
+     */
+    encode(frame: Frame | null): Promise<Packet | null>;
+    /**
+     * 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.
+     *
+     * 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)
+     *
+     * @yields Encoded packets (ownership transferred to caller)
+     *
+     * @example
+     * ```typescript
+     * // Transcode video
+     * for await (const packet of encoder.packets(decoder.frames(media.packets()))) {
+     *   await output.writePacket(packet);
+     *   packet.free(); // Must free output packet
+     * }
+     * ```
+     */
+    packets(frames: AsyncIterable<Frame>): AsyncGenerator<Packet>;
+    /**
+     * Flush encoder and get remaining packets.
+     *
+     * Sends null frame to trigger flush mode.
+     * Call repeatedly until it returns null.
+     *
+     * Uses avcodec_send_frame(NULL) to signal end of stream.
+     * Retrieves buffered packets from the encoder.
+     *
+     * @returns Promise resolving to Packet or null
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @example
+     * ```typescript
+     * // Flush all remaining packets
+     * let packet;
+     * while ((packet = await encoder.flush()) !== null) {
+     *   // Write final packets
+     *   await output.writePacket(packet);
+     * }
+     * ```
+     */
+    flush(): Promise<Packet | null>;
+    /**
+     * 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.
+     *
+     * @returns Async generator of remaining packets
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @example
+     * ```typescript
+     * // Process all remaining packets with generator
+     * for await (const packet of encoder.flushPackets()) {
+     *   await output.writePacket(packet, streamIdx);
+     *   using _ = packet; // Auto cleanup
+     * }
+     * ```
+     */
+    flushPackets(): AsyncGenerator<Packet>;
+    /**
+     * Close encoder and free resources.
+     *
+     * After closing, the encoder cannot be used again.
+     *
+     * Frees the packet buffer and codec context.
+     * Note: Does NOT dispose the HardwareContext - caller is responsible for that.
+     */
+    close(): void;
+    /**
+     * Get the codec name.
+     */
+    getCodecName(): string;
+    /**
+     * 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(): 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
+     *
+     * @example
+     * ```typescript
+     * const format = encoder.getPreferredPixelFormat();
+     * if (format) {
+     *   console.log(`Encoder prefers format: ${format}`);
+     * }
+     * ```
+     */
+    getPreferredPixelFormat(): AVPixelFormat | null;
+    /**
+     * Get all supported pixel formats for this encoder.
+     *
+     * Returns a list of pixel formats that this encoder can accept.
+     *
+     * @returns Array of supported pixel formats
+     *
+     * @example
+     * ```typescript
+     * const formats = encoder.getSupportedPixelFormats();
+     * console.log(`Encoder supports: ${formats.join(', ')}`);
+     * ```
+     */
+    getSupportedPixelFormats(): AVPixelFormat[];
+    /**
+     * Receive a packet from the encoder.
+     *
+     * Internal method to receive encoded packets.
+     *
+     * Uses avcodec_receive_packet() to get encoded packets from the codec.
+     * Clones the packet for the user to prevent internal buffer corruption.
+     *
+     * @returns Packet or null if no packet available
+     */
+    private receivePacket;
+    /**
+     * Symbol.dispose for automatic cleanup.
+     *
+     * Implements the Disposable interface for automatic resource management.
+     * Calls close() to free all resources.
+     */
+    [Symbol.dispose](): void;
+}