node-av 2.0.0 → 2.4.0

package/dist/api/encoder.d.ts

@@ -70,8 +70,11 @@ export declare class Encoder implements Disposable {
     private opts?;
     /**
      * @param codecContext - Configured codec context
+     *
      * @param codec - Encoder codec
+     *
      * @param opts - Encoder options as Dictionary
+     *
      * @internal
      */
     private constructor();
@@ -85,7 +88,9 @@ export declare class Encoder implements Disposable {
      * Direct mapping to avcodec_find_encoder_by_name() or avcodec_find_encoder().
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
+     *
      * @param options - Encoder configuration options including required timeBase
+     *
      * @returns Configured encoder instance
      *
      * @throws {Error} If encoder not found or timeBase not provided
@@ -129,6 +134,63 @@ export declare class Encoder implements Disposable {
      * @see {@link EncoderOptions} For configuration options
      */
     static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options: EncoderOptions): Promise<Encoder>;
+    /**
+     * Create an encoder with specified codec and options synchronously.
+     * Synchronous version of create.
+     *
+     * Initializes an encoder with the appropriate codec and configuration.
+     * 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 options - Encoder configuration options including required timeBase
+     *
+     * @returns Configured encoder instance
+     *
+     * @throws {Error} If encoder not found or timeBase not provided
+     *
+     * @throws {FFmpegError} If codec allocation fails
+     *
+     * @example
+     * ```typescript
+     * // From decoder stream info
+     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+     *   timeBase: video.timeBase,
+     *   bitrate: '5M',
+     *   gopSize: 60,
+     *   options: {
+     *     preset: 'fast',
+     *     crf: '23'
+     *   }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom stream info
+     * const encoder = await Encoder.create(FF_ENCODER_AAC, {
+     *   timeBase: audio.timeBase,
+     *   bitrate: '192k'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Hardware encoder
+     * const hw = HardwareContext.auto();
+     * const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_H264_VIDEOTOOLBOX;
+     * const encoder = await Encoder.create(encoderCodec, {
+     *   timeBase: video.timeBase,
+     *   bitrate: '8M'
+     * });
+     * ```
+     *
+     * @see {@link create} For async version
+     */
+    static createSync(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options: EncoderOptions): Encoder;
     /**
      * Check if encoder is open.
      *
@@ -194,6 +256,7 @@ export declare class Encoder implements Disposable {
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @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
@@ -227,6 +290,50 @@ export declare class Encoder implements Disposable {
      * @see {@link flush} For end-of-stream handling
      */
     encode(frame: Frame | null): Promise<Packet | null>;
+    /**
+     * Encode a frame to a packet synchronously.
+     * Synchronous version of encode.
+     *
+     * 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.
+     *
+     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
+     *
+     * @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
+     *
+     * @throws {FFmpegError} If encoding fails
+     *
+     * @example
+     * ```typescript
+     * const packet = encoder.encodeSync(frame);
+     * if (packet) {
+     *   console.log(`Encoded packet with PTS: ${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Encode loop
+     * for (const frame of decoder.framesSync(packets)) {
+     *   const packet = encoder.encodeSync(frame);
+     *   if (packet) {
+     *     output.writePacketSync(packet);
+     *     packet.free();
+     *   }
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link encode} For async version
+     */
+    encodeSync(frame: Frame | null): Packet | null;
     /**
      * Encode frame stream to packet stream.
      *
@@ -236,7 +343,9 @@ export declare class Encoder implements Disposable {
      * Primary interface for stream-based encoding.
      *
      * @param frames - Async iterable of frames (freed automatically)
+     *
      * @yields {Packet} Encoded packets (caller must free)
+     *
      * @throws {Error} If encoder is closed
      *
      * @throws {FFmpegError} If encoding fails
@@ -287,6 +396,54 @@ export declare class Encoder implements Disposable {
      * @see {@link Decoder.frames} For frame source
      */
     packets(frames: AsyncIterable<Frame>): AsyncGenerator<Packet>;
+    /**
+     * 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.
+     * Primary interface for stream-based encoding.
+     *
+     * @param frames - Iterable of frames (freed automatically)
+     *
+     * @yields {Packet} Encoded packets (caller must free)
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @throws {FFmpegError} If encoding fails
+     *
+     * @example
+     * ```typescript
+     * // Basic encoding pipeline
+     * for (const packet of encoder.packetsSync(decoder.framesSync(packets))) {
+     *   output.writePacketSync(packet);
+     *   packet.free(); // Must free output packets
+     * }
+     * ```
+     *
+     * @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();
+     *   }
+     * }
+     *
+     * for (const packet of encoder.packetsSync(filteredFrames())) {
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link packets} For async version
+     */
+    packetsSync(frames: Iterable<Frame>): Generator<Packet>;
     /**
      * Flush encoder and signal end-of-stream.
      *
@@ -314,6 +471,33 @@ export declare class Encoder implements Disposable {
      * @see {@link receive} For getting buffered packets
      */
     flush(): Promise<void>;
+    /**
+     * Flush encoder and signal end-of-stream synchronously.
+     * Synchronous version of flush.
+     *
+     * Sends null frame to encoder to signal end-of-stream.
+     * Does nothing if encoder was never initialized or is closed.
+     * Must call receiveSync() to get remaining buffered packets.
+     *
+     * Direct mapping to avcodec_send_frame(NULL).
+     *
+     * @example
+     * ```typescript
+     * // Signal end of stream
+     * encoder.flushSync();
+     *
+     * // Then get remaining packets
+     * let packet;
+     * while ((packet = encoder.receiveSync()) !== null) {
+     *   console.log('Got buffered packet');
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link flush} For async version
+     */
+    flushSync(): void;
     /**
      * Flush all buffered packets as async generator.
      *
@@ -337,6 +521,29 @@ export declare class Encoder implements Disposable {
      * @see {@link packets} For complete pipeline
      */
     flushPackets(): AsyncGenerator<Packet>;
+    /**
+     * Flush all buffered packets as generator synchronously.
+     * Synchronous version of flushPackets.
+     *
+     * Convenient sync iteration over remaining packets.
+     * Automatically handles flush and repeated receive calls.
+     * Returns immediately if encoder was never initialized or is closed.
+     *
+     * @yields {Packet} Buffered packets
+     *
+     * @example
+     * ```typescript
+     * // Flush at end of encoding
+     * for (const packet of encoder.flushPacketsSync()) {
+     *   console.log('Processing buffered packet');
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link flushPackets} For async version
+     */
+    flushPacketsSync(): Generator<Packet>;
     /**
      * Receive packet from encoder.
      *
@@ -376,6 +583,45 @@ export declare class Encoder implements Disposable {
      * @see {@link flush} For signaling end-of-stream
      */
     receive(): Promise<Packet | 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.
+     *
+     * 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 = encoder.receiveSync();
+     * if (packet) {
+     *   console.log(`Got packet with PTS: ${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered packets
+     * let packet;
+     * while ((packet = encoder.receiveSync()) !== null) {
+     *   console.log(`Packet size: ${packet.size}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link receive} For async version
+     */
+    receiveSync(): Packet | null;
     /**
      * Close encoder and free resources.
      *
@@ -410,6 +656,23 @@ export declare class Encoder implements Disposable {
      * @internal
      */
     private initialize;
+    /**
+     * Initialize encoder from first frame synchronously.
+     * Synchronous version of initialize.
+     *
+     * 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
+     *
+     * @see {@link initialize} For async version
+     */
+    private initializeSync;
     /**
      * Get encoder codec.
      *