node-av 1.2.0 → 2.0.0

package/dist/api/encoder.d.ts

@@ -2,7 +2,7 @@ import { Codec, CodecContext, Packet } from '../lib/index.js';
 import type { AVCodecID } from '../constants/constants.js';
 import type { FFEncoderCodec } from '../constants/encoders.js';
 import type { Frame } from '../lib/index.js';
-import type { EncoderOptions, StreamInfo } from './types.js';
+import type { EncoderOptions } from './types.js';
 /**
  * High-level encoder for audio and video streams.
  *
@@ -14,10 +14,10 @@ import type { EncoderOptions, StreamInfo } from './types.js';
  * @example
  * ```typescript
  * import { Encoder } from 'node-av/api';
- * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+ * import { AV_CODEC_ID_H264, FF_ENCODER_LIBX264 } from 'node-av/constants';
  *
  * // Create H.264 encoder
- * const encoder = await Encoder.create('libx264', {
+ * const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
  *   type: 'video',
  *   width: 1920,
  *   height: 1080,
@@ -39,17 +39,18 @@ import type { EncoderOptions, StreamInfo } from './types.js';
  *
  * @example
  * ```typescript
- * // Hardware-accelerated encoding
+ * // Hardware-accelerated encoding with lazy initialization
  * import { HardwareContext } from 'node-av/api';
- * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
+ * import { FF_ENCODER_H264_VIDEOTOOLBOX } from 'node-av/constants';
  *
- * const hw = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
- * const encoder = await Encoder.create('h264_nvenc', streamInfo, {
- *   hardware: hw,
+ * const hw = HardwareContext.auto();
+ * const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_H264_VIDEOTOOLBOX;
+ * const encoder = await Encoder.create(encoderCodec, {
+ *   timeBase: video.timeBase,
  *   bitrate: '10M'
  * });
  *
- * // Frames with hw_frames_ctx will be encoded on GPU
+ * // Hardware context will be detected from first frame's hw_frames_ctx
  * for await (const packet of encoder.packets(frames)) {
  *   await output.writePacket(packet);
  *   packet.free();
@@ -64,12 +65,13 @@ export declare class Encoder implements Disposable {
     private codecContext;
     private packet;
     private codec;
-    private isOpen;
-    private hardware?;
+    private initialized;
+    private isClosed;
+    private opts?;
     /**
      * @param codecContext - Configured codec context
      * @param codec - Encoder codec
-     * @param hardware - Optional hardware context
+     * @param opts - Encoder options as Dictionary
      * @internal
      */
     private constructor();
@@ -77,24 +79,24 @@ export declare class Encoder implements Disposable {
      * Create an encoder with specified codec and options.
      *
      * Initializes an encoder with the appropriate codec and configuration.
-     * Automatically configures parameters based on input stream info.
-     * Handles hardware acceleration setup if provided.
+     * Uses lazy initialization - encoder is opened when first frame is received.
+     * Hardware context will be automatically detected from first frame if not provided.
      *
      * Direct mapping to avcodec_find_encoder_by_name() or avcodec_find_encoder().
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
-     * @param input - Stream information to configure encoder
-     * @param options - Encoder configuration options
+     * @param options - Encoder configuration options including required timeBase
      * @returns Configured encoder instance
      *
-     * @throws {Error} If encoder not found or unsupported format
-     * @throws {FFmpegError} If codec initialization fails
+     * @throws {Error} If encoder not found or timeBase not provided
+     *
+     * @throws {FFmpegError} If codec allocation fails
      *
      * @example
      * ```typescript
      * // From decoder stream info
-     * const streamInfo = decoder.getOutputStreamInfo();
-     * const encoder = await Encoder.create('libx264', streamInfo, {
+     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+     *   timeBase: video.timeBase,
      *   bitrate: '5M',
      *   gopSize: 60,
      *   options: {
@@ -107,13 +109,8 @@ export declare class Encoder implements Disposable {
      * @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 }
-     * }, {
+     * const encoder = await Encoder.create(FF_ENCODER_AAC, {
+     *   timeBase: audio.timeBase,
      *   bitrate: '192k'
      * });
      * ```
@@ -122,16 +119,16 @@ export declare class Encoder implements Disposable {
      * ```typescript
      * // Hardware encoder
      * const hw = HardwareContext.auto();
-     * const encoder = await Encoder.create('hevc_videotoolbox', streamInfo, {
-     *   hardware: hw,
+     * const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_H264_VIDEOTOOLBOX;
+     * const encoder = await Encoder.create(encoderCodec, {
+     *   timeBase: video.timeBase,
      *   bitrate: '8M'
      * });
      * ```
      *
-     * @see {@link Decoder.getOutputStreamInfo} For stream info source
      * @see {@link EncoderOptions} For configuration options
      */
-    static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, input: StreamInfo, options?: EncoderOptions): Promise<Encoder>;
+    static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options: EncoderOptions): Promise<Encoder>;
     /**
      * Check if encoder is open.
      *
@@ -143,6 +140,22 @@ export declare class Encoder implements Disposable {
      * ```
      */
     get isEncoderOpen(): boolean;
+    /**
+     * Check if encoder has been initialized.
+     *
+     * Returns true after first frame has been processed and encoder opened.
+     * Useful for checking if encoder has received frame properties.
+     *
+     * @returns true if encoder has been initialized with frame data
+     *
+     * @example
+     * ```typescript
+     * if (!encoder.isEncoderInitialized) {
+     *   console.log('Encoder will initialize on first frame');
+     * }
+     * ```
+     */
+    get isEncoderInitialized(): boolean;
     /**
      * Check if encoder uses hardware acceleration.
      *
@@ -158,12 +171,25 @@ export declare class Encoder implements Disposable {
      * @see {@link HardwareContext} For hardware setup
      */
     isHardware(): boolean;
+    /**
+     * Check if encoder is ready for processing.
+     *
+     * @returns true if initialized and ready
+     *
+     * @example
+     * ```typescript
+     * if (encoder.isReady()) {
+     *   const packet = await encoder.encode(frame);
+     * }
+     * ```
+     */
+    isReady(): boolean;
     /**
      * Encode a frame to a packet.
      *
      * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * On first frame, automatically initializes encoder with frame properties.
      * Handles internal buffering - may return null if more frames needed.
-     * Automatically manages encoder state and hardware context binding.
      *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
@@ -171,6 +197,7 @@ export declare class Encoder implements Disposable {
      * @returns Encoded packet or null if more data needed
      *
      * @throws {Error} If encoder is closed
+     *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
@@ -209,8 +236,9 @@ export declare class Encoder implements Disposable {
      * Primary interface for stream-based encoding.
      *
      * @param frames - Async iterable of frames (freed automatically)
-     * @yields Encoded packets (caller must free)
+     * @yields {Packet} Encoded packets (caller must free)
      * @throws {Error} If encoder is closed
+     *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
@@ -227,11 +255,11 @@ export declare class Encoder implements Disposable {
      * // With frame filtering
      * async function* filteredFrames() {
      *   for await (const frame of decoder.frames(input.packets())) {
-     *     await filter.filterFrame(frame);
-     *     const filtered = await filter.getFrame();
+     *     const filtered = await filter.process(frame);
      *     if (filtered) {
      *       yield filtered;
      *     }
+     *     frame.free();
      *   }
      * }
      *
@@ -260,23 +288,22 @@ export declare class Encoder implements Disposable {
      */
     packets(frames: AsyncIterable<Frame>): AsyncGenerator<Packet>;
     /**
-     * Flush encoder and get buffered packet.
+     * Flush encoder and signal end-of-stream.
      *
-     * Signals end-of-stream and retrieves remaining packets.
-     * Call repeatedly until null to get all buffered packets.
-     * Essential for ensuring all frames are encoded.
+     * Sends null frame to encoder to signal end-of-stream.
+     * Does nothing if encoder was never initialized or is closed.
+     * Must call receive() to get remaining buffered packets.
      *
      * Direct mapping to avcodec_send_frame(NULL).
      *
-     * @returns Buffered packet or null if none remaining
-     *
-     * @throws {Error} If encoder is closed
-     *
      * @example
      * ```typescript
-     * // Flush remaining packets
+     * // Signal end of stream
+     * await encoder.flush();
+     *
+     * // Then get remaining packets
      * let packet;
-     * while ((packet = await encoder.flush()) !== null) {
+     * while ((packet = await encoder.receive()) !== null) {
      *   console.log('Got buffered packet');
      *   await output.writePacket(packet);
      *   packet.free();
@@ -284,18 +311,17 @@ export declare class Encoder implements Disposable {
      * ```
      *
      * @see {@link flushPackets} For async iteration
-     * @see {@link packets} For complete encoding pipeline
+     * @see {@link receive} For getting buffered packets
      */
-    flush(): Promise<Packet | null>;
+    flush(): Promise<void>;
     /**
      * Flush all buffered packets as async generator.
      *
      * Convenient async iteration over remaining packets.
-     * Automatically handles repeated flush calls.
-     * Useful for end-of-stream processing.
+     * Automatically handles flush and repeated receive calls.
+     * Returns immediately if encoder was never initialized or is closed.
      *
-     * @yields Buffered packets
-     * @throws {Error} If encoder is closed
+     * @yields {Packet} Buffered packets
      *
      * @example
      * ```typescript
@@ -307,21 +333,59 @@ export declare class Encoder implements Disposable {
      * }
      * ```
      *
-     * @see {@link flush} For single packet flush
+     * @see {@link flush} For signaling end-of-stream
      * @see {@link packets} For complete pipeline
      */
     flushPackets(): AsyncGenerator<Packet>;
+    /**
+     * Receive packet from encoder.
+     *
+     * 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.
+     *
+     * Direct mapping to avcodec_receive_packet().
+     *
+     * @returns Cloned packet or null if no packets available
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
+     *
+     * @example
+     * ```typescript
+     * const packet = await encoder.receive();
+     * if (packet) {
+     *   console.log(`Got packet with PTS: ${packet.pts}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered packets
+     * let packet;
+     * while ((packet = await encoder.receive()) !== null) {
+     *   console.log(`Packet size: ${packet.size}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link encode} For sending frames and receiving packets
+     * @see {@link flush} For signaling end-of-stream
+     */
+    receive(): Promise<Packet | null>;
     /**
      * Close encoder and free resources.
      *
      * 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.
      *
      * @example
      * ```typescript
-     * const encoder = await Encoder.create('libx264', streamInfo);
+     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, { ... });
      * try {
      *   // Use encoder
      * } finally {
@@ -332,6 +396,20 @@ export declare class Encoder implements Disposable {
      * @see {@link Symbol.dispose} For automatic cleanup
      */
     close(): void;
+    /**
+     * Initialize encoder from first frame.
+     *
+     * Sets codec context parameters from frame properties.
+     * Configures hardware context if present in frame.
+     * Opens encoder with accumulated options.
+     *
+     * @param frame - First frame to encode
+     *
+     * @throws {FFmpegError} If encoder open fails
+     *
+     * @internal
+     */
+    private initialize;
     /**
      * Get encoder codec.
      *
@@ -340,40 +418,25 @@ export declare class Encoder implements Disposable {
      *
      * @returns Codec instance
      *
-     * @example
-     * ```typescript
-     * const codec = encoder.getCodec();
-     * console.log(`Using codec: ${codec.name}`);
-     * console.log(`Capabilities: ${codec.capabilities}`);
-     * ```
+     * @internal
      *
-     * @see {@link Codec} For codec properties
+     * @see {@link Codec} For codec details
      */
     getCodec(): Codec;
     /**
      * Get underlying codec context.
      *
-     * Returns the internal codec context for advanced operations.
-     * Returns null if encoder is closed.
+     * 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
+     * @returns Codec context or null if closed/not initialized
      *
      * @internal
-     */
-    getCodecContext(): CodecContext | null;
-    /**
-     * Receive packet from encoder.
      *
-     * Internal method to get encoded packets from codec.
-     * Handles packet cloning and error checking.
-     *
-     * Direct mapping to avcodec_receive_packet().
-     *
-     * @returns Cloned packet or null
-     *
-     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
+     * @see {@link CodecContext} For context details
      */
-    private receivePacket;
+    getCodecContext(): CodecContext | null;
     /**
      * Dispose of encoder.
      *
@@ -383,7 +446,7 @@ export declare class Encoder implements Disposable {
      * @example
      * ```typescript
      * {
-     *   using encoder = await Encoder.create('libx264', streamInfo);
+     *   using encoder = await Encoder.create(FF_ENCODER_LIBX264, { ... });
      *   // Encode frames...
      * } // Automatically closed
      * ```