node-av 5.2.4 → 6.0.0-beta.11

package/dist/api/decoder.d.ts

@@ -3,16 +3,16 @@ import { Codec } from '../lib/codec.js';
 import { Frame } from '../lib/frame.js';
 import { Packet } from '../lib/packet.js';
 import { Scheduler } from './utilities/scheduler.js';
-import type { AVCodecID, AVPixelFormat, AVThreadType, EOFSignal, FFDecoderCodec } from '../constants/index.js';
+import type { AVCodecID, AVPixelFormat, AVSampleFormat, AVThreadType, DecoderOptionsFor, EOFSignal, FFDecoderCodec } from '../constants/index.js';
 import type { Stream } from '../lib/stream.js';
-import type { IRational } from '../lib/types.js';
+import type { ChannelLayout, IRational } from '../lib/types.js';
 import type { Encoder } from './encoder.js';
 import type { FilterAPI } from './filter.js';
 import type { HardwareContext } from './hardware.js';
 /**
  * Options for decoder creation.
  */
-export interface DecoderOptions {
+export interface DecoderOptions<C = unknown> {
     /**
      * Exit immediately on first decode error.
      *
@@ -36,13 +36,6 @@ export interface DecoderOptions {
      * Some hardware decoders need extra frames for reference or look-ahead.
      */
     extraHWFrames?: number;
-    /**
-     * Hardware frame output format.
-     *
-     * When set, hardware frames will be automatically transferred to this software pixel format.
-     * Useful when you need software frames for further processing but want to use hardware decoding.
-     */
-    hwaccelOutputFormat?: AVPixelFormat;
     /**
      * Force constant framerate mode.
      *
@@ -68,6 +61,57 @@ export interface DecoderOptions {
      * @default false
      */
     applyCropping?: boolean;
+    /**
+     * Resample decoded audio to a target format (audio only).
+     *
+     * When set, decoded audio frames are transparently converted to the requested
+     * sample rate, sample format, and/or channel layout before they are returned —
+     * the audio mirror of {@link rescale}. Any omitted field keeps the decoded
+     * value, and conversion is skipped entirely when the source already matches the
+     * target. Useful when a capture device delivers a rate you cannot control (e.g.
+     * avfoundation ignoring a microphone sample-rate request) and you want every
+     * downstream stage to receive the rate you asked for.
+     *
+     * @example
+     * ```typescript
+     * // Guarantee 48 kHz frames regardless of the device's actual rate
+     * const decoder = await Decoder.create(stream, { resample: { sampleRate: 48000 } });
+     * ```
+     */
+    resample?: {
+        sampleRate?: number;
+        sampleFormat?: AVSampleFormat;
+        channelLayout?: ChannelLayout;
+    };
+    /**
+     * Rescale decoded video to a target pixel format and/or size (video only).
+     *
+     * When set, decoded video frames are transparently converted to the requested
+     * pixel format and/or dimensions before they are returned — the video mirror of
+     * {@link resample}. Any omitted field keeps the decoded value, and conversion is
+     * skipped entirely when the source already matches the target.
+     *
+     * Hardware frames are automatically transferred to a supported software format
+     * first and then converted to the requested one; software frames are converted
+     * directly. Hardware frames are left untouched (kept on the GPU, zero-copy) when
+     * `rescale` is not set. This replaces the former `hwaccelOutputFormat` option:
+     * use `rescale: { pixelFormat }` to get decoded frames in a fixed software format.
+     *
+     * Useful to normalize a heterogeneous set of sources (e.g. RTSP cameras that each
+     * deliver a different pixel format) so every downstream stage receives a uniform
+     * format/size, regardless of whether a stream was hardware- or software-decoded.
+     *
+     * @example
+     * ```typescript
+     * // Normalize any source to yuv420p, whether it was hardware- or software-decoded
+     * const decoder = await Decoder.create(stream, { hardware: hw, rescale: { pixelFormat: AV_PIX_FMT_YUV420P } });
+     * ```
+     */
+    rescale?: {
+        width?: number;
+        height?: number;
+        pixelFormat?: AVPixelFormat;
+    };
     /**
      * Number of threads to use for decoding.
      *
@@ -92,10 +136,12 @@ export interface DecoderOptions {
     /**
      * Additional codec-specific options.
      *
-     * Key-value pairs of FFmpeg AVCodecContext options.
-     * These are passed directly to the decoder.
+     * Key-value pairs of FFmpeg private codec options, passed directly to the decoder.
+     * When the codec is created from a branded constant (e.g. `FF_DECODER_H264_CUVID`),
+     * 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?: DecoderOptionsFor<C>;
     /**
      * AbortSignal for cancellation.
      *
@@ -158,6 +204,15 @@ export declare class Decoder implements Disposable {
     private lastFrameTb;
     private lastFrameSampleRate;
     private lastFilterInRescaleDelta;
+    private audioResampler?;
+    private resampledFrame?;
+    private resampleTarget?;
+    private resampleInputLayout?;
+    private audioResamplerSetup;
+    private audioResamplerDrained;
+    private videoScaler?;
+    private scaledFrame?;
+    private hwTransferFormat?;
     private inputQueue;
     private outputQueue;
     private workerPromise;
@@ -235,7 +290,7 @@ export declare class Decoder implements Disposable {
      * @see {@link createSync} For synchronous version
      */
     static create(stream: Stream, options?: DecoderOptions): Promise<Decoder>;
-    static create(stream: Stream, decoderCodec?: FFDecoderCodec | AVCodecID | Codec, options?: DecoderOptions): Promise<Decoder>;
+    static create<const C extends FFDecoderCodec | AVCodecID | Codec>(stream: Stream, decoderCodec: C, options?: DecoderOptions<C>): Promise<Decoder>;
     /**
      * Create a decoder for a media stream synchronously.
      * Synchronous version of create.
@@ -292,7 +347,7 @@ export declare class Decoder implements Disposable {
      * @see {@link create} For async version
      */
     static createSync(stream: Stream, options?: DecoderOptions): Decoder;
-    static createSync(stream: Stream, decoderCodec?: FFDecoderCodec | AVCodecID | Codec, options?: DecoderOptions): Decoder;
+    static createSync<const C extends FFDecoderCodec | AVCodecID | Codec>(stream: Stream, decoderCodec: C, options?: DecoderOptions<C>): Decoder;
     /**
      * Check if decoder is open.
      *
@@ -1068,6 +1123,113 @@ export declare class Decoder implements Disposable {
      * @internal
      */
     private processAudioFrame;
+    /**
+     * Lazily configure the audio output resampler from the first decoded frame.
+     *
+     * Reads the source format from the frame, resolves the target from
+     * `options.resample` (omitted fields keep the source value), and builds a
+     * `SoftwareResampleContext` only when something actually differs. Runs once.
+     *
+     * @param frame - First decoded audio frame
+     *
+     * @throws {FFmpegError} If the resampler cannot be configured or initialized
+     *
+     * @internal
+     */
+    private setupAudioResampler;
+    /**
+     * Lazily allocate the reused resampler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    private getResampleFrame;
+    /**
+     * Resample a decoded audio frame to the target format and clone it for the user.
+     *
+     * `swr_convert_frame` allocates/sizes the output buffer; the sample timestamp
+     * (carried in the frame's own timebase) is preserved, while `nb_samples` and
+     * `sample_rate` reflect the new rate. Returns null when the resampler buffered
+     * the input without emitting samples yet (caller should feed more).
+     *
+     * @param frame - Decoded source audio frame
+     *
+     * @returns Cloned resampled frame owned by the caller, or null if none emitted
+     *
+     * @throws {FFmpegError} If resampling fails
+     *
+     * @internal
+     */
+    private resampleAudioClone;
+    /**
+     * Drain samples buffered inside the resampler (rate-conversion delay) at EOF.
+     *
+     * @returns Cloned drained frame owned by the caller, or null when empty
+     *
+     * @throws {FFmpegError} If draining fails
+     *
+     * @internal
+     */
+    private drainResamplerClone;
+    /**
+     * Resolve (once, then cache) the software format to download hardware frames to.
+     *
+     * When `rescale.pixelFormat` is set and the frame's hardware frames context can
+     * transfer directly to it, that format is used so the subsequent swscale can be
+     * skipped entirely (when no resize is requested) or stay format-preserving. When
+     * it cannot, `AV_PIX_FMT_NONE` is returned so `av_hwframe_transfer_data` picks a
+     * supported format and the swscale handles the final conversion. Cached because
+     * the hardware frames context is stable for the lifetime of the decoder.
+     *
+     * @param frame - First hardware frame (used to read the hardware frames context)
+     *
+     * @returns The download format, or `AV_PIX_FMT_NONE` to let FFmpeg choose
+     *
+     * @internal
+     */
+    private resolveHwTransferFormat;
+    /**
+     * Transfer a hardware frame down to system memory, replacing it in place.
+     *
+     * The destination software format is the requested one when the GPU can transfer
+     * to it directly (see {@link resolveHwTransferFormat}), otherwise one chosen
+     * automatically by FFmpeg. The downloaded data replaces the hardware frame's
+     * contents so the rest of the pipeline operates on a software frame.
+     *
+     * @param frame - Hardware frame to download (modified in place)
+     *
+     * @returns True on success; false when the transfer failed and `exitOnError` is off
+     *
+     * @throws {FFmpegError} If the transfer fails and `exitOnError` is enabled
+     *
+     * @internal
+     */
+    private transferHwFrameToSoftware;
+    /**
+     * Lazily allocate the reused rescaler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    private getScaledFrame;
+    /**
+     * Convert a (software) video frame to the requested `rescale` pixel format and/or
+     * size, replacing it in place.
+     *
+     * Each omitted target field keeps the source value, and the conversion is skipped
+     * entirely when the frame already matches. The swscale context is configured
+     * lazily from the first frame that needs conversion. `sws_scale_frame` copies the
+     * frame properties (timing, colorimetry, aspect ratio).
+     *
+     * @param frame - Software video frame to convert (modified in place)
+     *
+     * @throws {FFmpegError} If the rescaler fails to configure or convert and `exitOnError` is enabled
+     *
+     * @internal
+     */
+    private rescaleVideoInPlace;
     /**
      * Dispose of decoder.
      *