node-av 5.2.4 → 6.0.0-beta.11

package/dist/api/encoder.d.ts

@@ -3,7 +3,7 @@ import { Codec } from '../lib/codec.js';
 import { Frame } from '../lib/frame.js';
 import { Packet } from '../lib/packet.js';
 import { SchedulerControl } from './utilities/scheduler.js';
-import type { AVCodecFlag, AVCodecID, AVThreadType, EOFSignal, FFEncoderCodec } from '../constants/index.js';
+import type { AVCodecFlag, AVCodecID, AVThreadType, EncoderOptionsFor, EOFSignal, FFEncoderCodec } from '../constants/index.js';
 import type { Decoder } from './decoder.js';
 import type { FilterComplexAPI } from './filter-complex.js';
 import type { FilterAPI } from './filter.js';
@@ -11,7 +11,7 @@ import type { Muxer } from './muxer.js';
 /**
  * Options for encoder creation.
  */
-export interface EncoderOptions {
+export interface EncoderOptions<C = unknown> {
     /**
      * Target bitrate.
      *
@@ -90,13 +90,47 @@ export interface EncoderOptions {
      * @default FFmpeg default (both methods, codec chooses best)
      */
     threadType?: AVThreadType;
+    /**
+     * Automatically resample incoming audio to a format the codec supports.
+     *
+     * Audio encoders only accept specific sample rates, sample formats, and channel
+     * layouts (e.g. libmp3lame rejects 96 kHz; AAC needs planar `fltp`). When `true`,
+     * the encoder transparently converts each frame to the nearest supported
+     * sample rate / sample format / channel layout (like `ffmpeg`'s automatic
+     * `aresample`). When `false` (default), an unsupported input raises a descriptive
+     * error instead — keeping behaviour explicit and 1:1 with the codec.
+     *
+     * Has no effect on video.
+     *
+     * @default false
+     */
+    autoResample?: boolean;
+    /**
+     * Automatically convert incoming video to a pixel format the codec supports.
+     *
+     * Video encoders only accept specific pixel formats (e.g. libx264 wants planar
+     * YUV like `yuv420p` and rejects `rgb24`). When `true`, the encoder transparently
+     * converts each frame to the least-loss supported pixel format via swscale (like
+     * `ffmpeg`'s automatic `format` filter), keeping the same resolution. When `false`
+     * (default), an unsupported input raises a descriptive error instead — keeping
+     * behaviour explicit and 1:1 with the codec.
+     *
+     * Resolution is never changed (the encoder already adopts the frame's dimensions),
+     * and hardware frames are left untouched (their format is negotiated via the
+     * hardware frames context). Has no effect on audio.
+     *
+     * @default false
+     */
+    autoFormat?: boolean;
     /**
      * Additional codec-specific options.
      *
-     * Key-value pairs of FFmpeg AVCodecContext options.
-     * These are passed directly to the encoder.
+     * Key-value pairs of FFmpeg private codec options, passed directly to the encoder.
+     * When the codec is created from a branded constant (e.g. `FF_ENCODER_LIBX264`),
+     * these are strongly typed to that codec's known options (autocomplete + validation);
+     * otherwise any string/number/boolean values are accepted.
      */
-    options?: Record<string, string | number | boolean | undefined | null>;
+    options?: EncoderOptionsFor<C>;
     /**
      * AbortSignal for cancellation.
      *
@@ -172,6 +206,14 @@ export declare class Encoder implements Disposable {
     private opts?;
     private options;
     private audioFrameBuffer?;
+    private autoResample;
+    private audioResampler?;
+    private resampledFrame?;
+    private audioInputLayout?;
+    private autoFormat;
+    private videoScaler?;
+    private scaledFrame?;
+    private videoTargetFormat?;
     private inputQueue;
     private outputQueue;
     private workerPromise;
@@ -243,7 +285,7 @@ export declare class Encoder implements Disposable {
      * @see {@link EncoderOptions} For configuration options
      * @see {@link createSync} For synchronous version
      */
-    static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options?: EncoderOptions): Promise<Encoder>;
+    static create<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, options?: EncoderOptions<C>): Promise<Encoder>;
     /**
      * Create an encoder with specified codec and options synchronously.
      * Synchronous version of create.
@@ -301,7 +343,65 @@ export declare class Encoder implements Disposable {
      * @see {@link EncoderOptions} For configuration options
      * @see {@link create} For async version
      */
-    static createSync(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options?: EncoderOptions): Encoder;
+    static createSync<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, options?: EncoderOptions<C>): Encoder;
+    /**
+     * Encode a single frame into a self-contained image buffer.
+     *
+     * One-shot, stateless helper for intra-only image codecs (MJPEG, PNG, WebP, ...).
+     * Creates a fresh encoder, encodes the frame, flushes and frees everything in one call.
+     * The encoder adopts dimensions, pixel format and hardware context from the frame,
+     * so any frame size works without reconfiguration.
+     *
+     * @param encoderCodec - Encoder codec (name, ID, branded constant, or Codec)
+     *
+     * @param frame - Frame to encode
+     *
+     * @param options - Optional encoder configuration (e.g. `{ options: { q: 3 } }` for MJPEG quality)
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {FFmpegError} If the encoder is not found or encoding fails
+     *
+     * @throws {Error} If the encoder produced no output
+     *
+     * @example
+     * ```typescript
+     * const jpeg = await Encoder.encodeOne(FF_ENCODER_MJPEG, frame, { options: { q: 3 } });
+     * ```
+     *
+     * @see {@link EncoderPool} For reusing encoders across recurring resolutions
+     */
+    static encodeOne<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, frame: Frame, options?: EncoderOptions<C>): Promise<Buffer>;
+    /**
+     * Encode a single frame into a self-contained image buffer synchronously.
+     * Synchronous version of encodeOne.
+     *
+     * One-shot, stateless helper for intra-only image codecs (MJPEG, PNG, WebP, ...).
+     * Creates a fresh encoder, encodes the frame, flushes and frees everything in one call.
+     * The encoder adopts dimensions, pixel format and hardware context from the frame,
+     * so any frame size works without reconfiguration.
+     *
+     * @param encoderCodec - Encoder codec (name, ID, branded constant, or Codec)
+     *
+     * @param frame - Frame to encode
+     *
+     * @param options - Optional encoder configuration (e.g. `{ options: { q: 3 } }` for MJPEG quality)
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {FFmpegError} If the encoder is not found or encoding fails
+     *
+     * @throws {Error} If the encoder produced no output
+     *
+     * @example
+     * ```typescript
+     * const jpeg = Encoder.encodeOneSync(FF_ENCODER_MJPEG, frame, { options: { q: 3 } });
+     * ```
+     *
+     * @see {@link encodeOne} For async version
+     * @see {@link EncoderPool} For reusing encoders across recurring resolutions
+     */
+    static encodeOneSync<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, frame: Frame, options?: EncoderOptions<C>): Buffer;
     /**
      * Check if encoder is open.
      *
@@ -1096,6 +1196,93 @@ export declare class Encoder implements Disposable {
      * @internal
      */
     private setupHardwareAcceleration;
+    /**
+     * Configure the codec context's audio parameters from the first frame.
+     *
+     * Audio encoders only accept specific sample rates / sample formats / channel
+     * layouts. This picks codec-supported targets; if they differ from the input it
+     * either sets up a resampler (when `autoResample`) or throws a descriptive error.
+     *
+     * @param frame - First audio frame
+     *
+     * @throws {Error} If the input is unsupported and `autoResample` is disabled
+     *
+     * @throws {FFmpegError} If the resampler fails to configure
+     *
+     * @internal
+     */
+    private setupAudioParams;
+    /**
+     * Lazily allocate the reused resampler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    private getResampleFrame;
+    /**
+     * Resample an incoming audio frame to the codec's target format.
+     *
+     * Reuses a single output frame; `swr_convert_frame` allocates/sizes its buffer.
+     * The (fixed-frame-size) audio FIFO copies the samples and re-stamps PTS, so the
+     * reused frame and its carried timing are only relevant on the non-FIFO path.
+     *
+     * @param frame - Source audio frame
+     *
+     * @returns The resampled frame (owned by the encoder, reused across calls)
+     *
+     * @internal
+     */
+    private resampleAudio;
+    /**
+     * Drain samples buffered inside the resampler (rate-conversion delay) into the
+     * encoder path. Returns the drained frame if any, else null.
+     *
+     * @returns The drained frame (reused), or null when the resampler is empty
+     *
+     * @internal
+     */
+    private drainResampler;
+    /**
+     * Configure the codec context's pixel format from the first video frame.
+     *
+     * Video encoders only accept specific pixel formats. This keeps the input format
+     * when the codec accepts it; otherwise it either sets up a swscale converter to
+     * the least-loss supported format (when `autoFormat`) or throws a descriptive
+     * error. Hardware frames are left untouched - their format is negotiated through
+     * the hardware frames context, not swscale.
+     *
+     * @param frame - First video frame
+     *
+     * @throws {Error} If the input is unsupported and `autoFormat` is disabled
+     *
+     * @throws {FFmpegError} If the converter fails to configure
+     *
+     * @internal
+     */
+    private setupVideoFormat;
+    /**
+     * Lazily allocate the reused scaler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    private getScaledFrame;
+    /**
+     * Convert an incoming video frame to the codec's target pixel format.
+     *
+     * Reuses a single output frame; `sws_scale_frame` allocates/sizes its buffer.
+     * Resolution is unchanged - only the pixel format differs. Timing is carried over
+     * explicitly so the encoder's PTS rescale stays correct.
+     *
+     * @param frame - Source video frame
+     *
+     * @returns The converted frame (owned by the encoder, reused across calls)
+     *
+     * @internal
+     */
+    private scaleVideo;
     /**
      * Prepare frame for encoding.
      *