node-av 5.2.4 → 6.0.0-beta.11

package/dist/api/encoder.js

@@ -50,7 +50,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE, AV_CODEC_CAP_PARAM_CHANGE, AV_CODEC_FLAG_COPY_OPAQUE, AV_CODEC_FLAG_FRAME_DURATION, AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX, AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AV_PICTURE_TYPE_NONE, AV_PIX_FMT_NONE, AV_PKT_FLAG_TRUSTED, AVCHROMA_LOC_UNSPECIFIED, AVERROR_EAGAIN, AVERROR_ENCODER_NOT_FOUND, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, EOF, } from '../constants/constants.js';
+/* eslint-disable @stylistic/indent-binary-ops */
+import { AV_CHANNEL_ORDER_UNSPEC, AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE, AV_CODEC_CAP_PARAM_CHANGE, AV_CODEC_FLAG_COPY_OPAQUE, AV_CODEC_FLAG_FRAME_DURATION, AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX, AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AV_PICTURE_TYPE_NONE, AV_PIX_FMT_NONE, AV_PKT_FLAG_TRUSTED, AVCHROMA_LOC_UNSPECIFIED, AVERROR_EAGAIN, AVERROR_ENCODER_NOT_FOUND, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, EOF, SWS_BILINEAR, } from '../constants/constants.js';
 import { CodecContext } from '../lib/codec-context.js';
 import { Codec } from '../lib/codec.js';
 import { Dictionary } from '../lib/dictionary.js';
@@ -58,10 +59,13 @@ import { FFmpegError } from '../lib/error.js';
 import { Frame } from '../lib/frame.js';
 import { Packet } from '../lib/packet.js';
 import { Rational } from '../lib/rational.js';
-import { avRescaleQ } from '../lib/utilities.js';
+import { SoftwareResampleContext } from '../lib/software-resample-context.js';
+import { SoftwareScaleContext } from '../lib/software-scale-context.js';
+import { avChannelLayoutDefault, avGetPixFmtName, avGetSampleFmtName, avRescaleQ } from '../lib/utilities.js';
 import { AudioFrameBuffer } from './audio-frame-buffer.js';
 import { FRAME_THREAD_QUEUE_SIZE, PACKET_THREAD_QUEUE_SIZE } from './constants.js';
 import { AsyncQueue } from './utilities/async-queue.js';
+import { pickSupportedLayout, pickSupportedPixelFormat, pickSupportedRate, pickSupportedSampleFormat } from './utilities/codec-format.js';
 import { SchedulerControl } from './utilities/scheduler.js';
 import { parseBitrate } from './utils.js';
 /**
@@ -132,6 +136,14 @@ export class Encoder {
     opts;
     options;
     audioFrameBuffer;
+    autoResample;
+    audioResampler;
+    resampledFrame;
+    audioInputLayout;
+    autoFormat;
+    videoScaler;
+    scaledFrame;
+    videoTargetFormat;
     // Worker pattern for push-based processing
     inputQueue;
     outputQueue;
@@ -154,10 +166,12 @@ export class Encoder {
         this.codec = codec;
         this.options = options;
         this.opts = opts;
+        this.autoResample = options.autoResample ?? false;
+        this.autoFormat = options.autoFormat ?? false;
         this.packet = new Packet();
         this.packet.alloc();
-        this.inputQueue = new AsyncQueue(FRAME_THREAD_QUEUE_SIZE);
-        this.outputQueue = new AsyncQueue(PACKET_THREAD_QUEUE_SIZE);
+        this.inputQueue = new AsyncQueue(FRAME_THREAD_QUEUE_SIZE, (f) => f.free());
+        this.outputQueue = new AsyncQueue(PACKET_THREAD_QUEUE_SIZE, (p) => p.free());
     }
     /**
      * Create an encoder with specified codec and options.
@@ -262,8 +276,11 @@ export class Encoder {
         if (options.threadType !== undefined) {
             codecContext.threadType = options.threadType;
         }
-        const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
-        const encoder = new Encoder(codecContext, codec, options, opts);
+        // Loose view for internal use: the public signature narrows `options` to the
+        // codec, but internally codec options are handled as a generic dictionary.
+        const looseOptions = options;
+        const opts = looseOptions.options ? Dictionary.fromObject(looseOptions.options) : undefined;
+        const encoder = new Encoder(codecContext, codec, looseOptions, opts);
         if (options.signal) {
             options.signal.throwIfAborted();
             encoder.signal = options.signal;
@@ -375,14 +392,125 @@ export class Encoder {
         if (options.threadType !== undefined) {
             codecContext.threadType = options.threadType;
         }
-        const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
-        const encoder = new Encoder(codecContext, codec, options, opts);
+        // Loose view for internal use: the public signature narrows `options` to the
+        // codec, but internally codec options are handled as a generic dictionary.
+        const looseOptions = options;
+        const opts = looseOptions.options ? Dictionary.fromObject(looseOptions.options) : undefined;
+        const encoder = new Encoder(codecContext, codec, looseOptions, opts);
         if (options.signal) {
             options.signal.throwIfAborted();
             encoder.signal = options.signal;
         }
         return 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 async encodeOne(encoderCodec, frame, options = {}) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const encoder = __addDisposableResource(env_1, await Encoder.create(encoderCodec, options), false);
+            const packets = [...(await encoder.encodeAll(frame)), ...(await encoder.encodeAll(null))];
+            try {
+                const data = packets[0]?.data;
+                if (!data) {
+                    throw new Error(`Encoder '${encoder.getCodec().name}' produced no output for frame`);
+                }
+                return data;
+            }
+            finally {
+                for (const packet of packets) {
+                    packet.free();
+                }
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    /**
+     * 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(encoderCodec, frame, options = {}) {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const encoder = __addDisposableResource(env_2, Encoder.createSync(encoderCodec, options), false);
+            const packets = [...encoder.encodeAllSync(frame), ...encoder.encodeAllSync(null)];
+            try {
+                const data = packets[0]?.data;
+                if (!data) {
+                    throw new Error(`Encoder '${encoder.getCodec().name}' produced no output for frame`);
+                }
+                return data;
+            }
+            finally {
+                for (const packet of packets) {
+                    packet.free();
+                }
+            }
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
+    }
     /**
      * Check if encoder is open.
      *
@@ -622,8 +750,15 @@ export class Encoder {
         // Open encoder if not already done
         this.initializePromise ??= this.initialize(frame);
         await this.initializePromise;
+        // Give an unspecified-layout frame the concrete native layout the codec was
+        // opened with (and the resampler configured for), so both accept it.
+        if (this.audioInputLayout) {
+            frame.channelLayout = this.audioInputLayout;
+        }
+        // Convert to the codec's format first (audio resample / video pixfmt).
+        const input = this.audioResampler ? this.resampleAudio(frame) : this.videoScaler ? this.scaleVideo(frame) : frame;
         // Prepare frame for encoding (set quality, validate channel count)
-        this.prepareFrameForEncoding(frame);
+        this.prepareFrameForEncoding(input);
         const encode = async (newFrame) => {
             const sendRet = await this.codecContext.sendFrame(newFrame);
             if (sendRet < 0 && sendRet !== AVERROR_EOF) {
@@ -633,10 +768,10 @@ export class Encoder {
         };
         if (this.audioFrameBuffer) {
             // Push frame into buffer - actual sending happens in receive()
-            await this.audioFrameBuffer.push(frame);
+            await this.audioFrameBuffer.push(input);
         }
         else {
-            await encode(frame);
+            await encode(input);
         }
     }
     /**
@@ -690,8 +825,15 @@ export class Encoder {
         if (!this.initialized) {
             this.initializeSync(frame);
         }
+        // Give an unspecified-layout frame the concrete native layout the codec was
+        // opened with (and the resampler configured for), so both accept it.
+        if (this.audioInputLayout) {
+            frame.channelLayout = this.audioInputLayout;
+        }
+        // Convert to the codec's format first (audio resample / video pixfmt).
+        const input = this.audioResampler ? this.resampleAudio(frame) : this.videoScaler ? this.scaleVideo(frame) : frame;
         // Prepare frame for encoding (set quality, validate channel count)
-        this.prepareFrameForEncoding(frame);
+        this.prepareFrameForEncoding(input);
         const encode = (newFrame) => {
             const sendRet = this.codecContext.sendFrameSync(newFrame);
             if (sendRet < 0 && sendRet !== AVERROR_EOF) {
@@ -701,10 +843,10 @@ export class Encoder {
         };
         if (this.audioFrameBuffer) {
             // Push frame into buffer - actual sending happens in receiveSync()
-            this.audioFrameBuffer.pushSync(frame);
+            this.audioFrameBuffer.pushSync(input);
         }
         else {
-            encode(frame);
+            encode(input);
         }
     }
     /**
@@ -906,9 +1048,9 @@ export class Encoder {
             return;
         }
         for await (const frame_1 of frames) {
-            const env_1 = { stack: [], error: void 0, hasError: false };
+            const env_3 = { stack: [], error: void 0, hasError: false };
             try {
-                const frame = __addDisposableResource(env_1, frame_1, false);
+                const frame = __addDisposableResource(env_3, frame_1, false);
                 this.signal?.throwIfAborted();
                 if (frame === null) {
                     yield* finalize();
@@ -916,12 +1058,12 @@ export class Encoder {
                 }
                 yield* processFrame(frame);
             }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
+            catch (e_3) {
+                env_3.error = e_3;
+                env_3.hasError = true;
             }
             finally {
-                __disposeResources(env_1);
+                __disposeResources(env_3);
             }
         }
     }
@@ -1017,9 +1159,9 @@ export class Encoder {
         }
         // Case 3: Iterable of frames
         for (const frame_2 of frames) {
-            const env_2 = { stack: [], error: void 0, hasError: false };
+            const env_4 = { stack: [], error: void 0, hasError: false };
             try {
-                const frame = __addDisposableResource(env_2, frame_2, false);
+                const frame = __addDisposableResource(env_4, frame_2, false);
                 // Check for EOF signal from upstream
                 if (frame === null) {
                     yield* finalize();
@@ -1027,12 +1169,12 @@ export class Encoder {
                 }
                 yield* processFrame(frame);
             }
-            catch (e_2) {
-                env_2.error = e_2;
-                env_2.hasError = true;
+            catch (e_4) {
+                env_4.error = e_4;
+                env_4.hasError = true;
             }
             finally {
-                __disposeResources(env_2);
+                __disposeResources(env_4);
             }
         }
         // No fallback flush - only flush on explicit EOF
@@ -1069,23 +1211,33 @@ export class Encoder {
         if (this.isClosed || !this.initialized) {
             return;
         }
+        // Drain samples buffered inside the resampler into the FIFO/encoder first.
+        const drained = this.drainResampler();
+        if (drained) {
+            if (this.audioFrameBuffer) {
+                await this.audioFrameBuffer.push(drained);
+            }
+            else {
+                await this.codecContext.sendFrame(drained);
+            }
+        }
         // If using AudioFrameBuffer, flush remaining buffered samples first
         if (this.audioFrameBuffer && this.audioFrameBuffer.size > 0) {
             // Pull any remaining partial frame (may be less than frameSize)
             // For the final frame, we pad or truncate as needed
             let _bufferedFrame;
             while (!this.isClosed && (_bufferedFrame = await this.audioFrameBuffer.pull()) !== null) {
-                const env_3 = { stack: [], error: void 0, hasError: false };
+                const env_5 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const bufferedFrame = __addDisposableResource(env_3, _bufferedFrame, false);
+                    const bufferedFrame = __addDisposableResource(env_5, _bufferedFrame, false);
                     await this.codecContext.sendFrame(bufferedFrame);
                 }
-                catch (e_3) {
-                    env_3.error = e_3;
-                    env_3.hasError = true;
+                catch (e_5) {
+                    env_5.error = e_5;
+                    env_5.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_3);
+                    __disposeResources(env_5);
                 }
             }
         }
@@ -1129,23 +1281,33 @@ export class Encoder {
         if (this.isClosed || !this.initialized) {
             return;
         }
+        // Drain samples buffered inside the resampler into the FIFO/encoder first.
+        const drained = this.drainResampler();
+        if (drained) {
+            if (this.audioFrameBuffer) {
+                this.audioFrameBuffer.pushSync(drained);
+            }
+            else {
+                this.codecContext.sendFrameSync(drained);
+            }
+        }
         // If using AudioFrameBuffer, flush remaining buffered samples first
         if (this.audioFrameBuffer && this.audioFrameBuffer.size > 0) {
             // Pull any remaining partial frame (may be less than frameSize)
             // For the final frame, we pad or truncate as needed
             let _bufferedFrame;
             while (!this.isClosed && (_bufferedFrame = this.audioFrameBuffer.pullSync()) !== null) {
-                const env_4 = { stack: [], error: void 0, hasError: false };
+                const env_6 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const bufferedFrame = __addDisposableResource(env_4, _bufferedFrame, false);
+                    const bufferedFrame = __addDisposableResource(env_6, _bufferedFrame, false);
                     this.codecContext.sendFrameSync(bufferedFrame);
                 }
-                catch (e_4) {
-                    env_4.error = e_4;
-                    env_4.hasError = true;
+                catch (e_6) {
+                    env_6.error = e_6;
+                    env_6.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_4);
+                    __disposeResources(env_6);
                 }
             }
         }
@@ -1288,19 +1450,19 @@ export class Encoder {
         // Clear previous packet data
         this.packet.unref();
         if (this.audioFrameBuffer?.hasFrame()) {
-            const env_5 = { stack: [], error: void 0, hasError: false };
+            const env_7 = { stack: [], error: void 0, hasError: false };
             try {
-                const bufferedFrame = __addDisposableResource(env_5, await this.audioFrameBuffer.pull(), false);
+                const bufferedFrame = __addDisposableResource(env_7, await this.audioFrameBuffer.pull(), false);
                 if (bufferedFrame) {
                     await this.codecContext.sendFrame(bufferedFrame);
                 }
             }
-            catch (e_5) {
-                env_5.error = e_5;
-                env_5.hasError = true;
+            catch (e_7) {
+                env_7.error = e_7;
+                env_7.hasError = true;
             }
             finally {
-                __disposeResources(env_5);
+                __disposeResources(env_7);
             }
         }
         const ret = await this.codecContext.receivePacket(this.packet);
@@ -1393,19 +1555,19 @@ export class Encoder {
         // Clear previous packet data
         this.packet.unref();
         if (this.audioFrameBuffer?.hasFrame()) {
-            const env_6 = { stack: [], error: void 0, hasError: false };
+            const env_8 = { stack: [], error: void 0, hasError: false };
             try {
-                const bufferedFrame = __addDisposableResource(env_6, this.audioFrameBuffer.pullSync(), false);
+                const bufferedFrame = __addDisposableResource(env_8, this.audioFrameBuffer.pullSync(), false);
                 if (bufferedFrame) {
                     this.codecContext.sendFrameSync(bufferedFrame);
                 }
             }
-            catch (e_6) {
-                env_6.error = e_6;
-                env_6.hasError = true;
+            catch (e_8) {
+                env_8.error = e_8;
+                env_8.hasError = true;
             }
             finally {
-                __disposeResources(env_6);
+                __disposeResources(env_8);
             }
         }
         const ret = this.codecContext.receivePacketSync(this.packet);
@@ -1488,10 +1650,21 @@ export class Encoder {
             return;
         }
         this.isClosed = true;
-        // Close queues
         this.inputQueue.close();
         this.outputQueue.close();
+        this.inputQueue.clear();
+        this.outputQueue.clear();
         this.packet.free();
+        this.audioFrameBuffer?.[Symbol.dispose]();
+        this.audioFrameBuffer = undefined;
+        this.audioResampler?.[Symbol.dispose]();
+        this.audioResampler = undefined;
+        this.resampledFrame?.free();
+        this.resampledFrame = undefined;
+        this.videoScaler?.[Symbol.dispose]();
+        this.videoScaler = undefined;
+        this.scaledFrame?.free();
+        this.scaledFrame = undefined;
         this.codecContext.freeContext();
         this.initialized = false;
     }
@@ -1535,9 +1708,9 @@ export class Encoder {
         try {
             // Outer loop - receive frames
             while (!this.inputQueue.isClosed) {
-                const env_7 = { stack: [], error: void 0, hasError: false };
+                const env_9 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const frame = __addDisposableResource(env_7, await this.inputQueue.receive(), false);
+                    const frame = __addDisposableResource(env_9, await this.inputQueue.receive(), false);
                     if (!frame)
                         break;
                     // Open encoder if not already done
@@ -1556,12 +1729,12 @@ export class Encoder {
                         await this.outputQueue.send(packet); // Only send actual packets
                     }
                 }
-                catch (e_7) {
-                    env_7.error = e_7;
-                    env_7.hasError = true;
+                catch (e_9) {
+                    env_9.error = e_9;
+                    env_9.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_7);
+                    __disposeResources(env_9);
                 }
             }
             // Flush encoder at end
@@ -1685,7 +1858,8 @@ export class Encoder {
             }
             this.codecContext.width = frame.width;
             this.codecContext.height = frame.height;
-            this.codecContext.pixelFormat = frame.format;
+            // Pick a codec-supported pixel format (converting on demand when autoFormat).
+            this.setupVideoFormat(frame);
             this.codecContext.sampleAspectRatio = frame.sampleAspectRatio;
             this.codecContext.colorRange = frame.colorRange;
             this.codecContext.colorPrimaries = frame.colorPrimaries;
@@ -1697,12 +1871,8 @@ export class Encoder {
             }
         }
         else {
-            // Audio: Always use frame timebase (which is typically 1/sample_rate)
-            // This ensures correct PTS progression for audio frames
-            this.codecContext.timeBase = frame.timeBase;
-            this.codecContext.sampleRate = frame.sampleRate;
-            this.codecContext.sampleFormat = frame.format;
-            this.codecContext.channelLayout = frame.channelLayout;
+            // Audio: pick codec-supported sample rate/format/layout (resampling on demand).
+            this.setupAudioParams(frame);
         }
         // Setup hardware acceleration with validation
         this.setupHardwareAcceleration(frame);
@@ -1778,7 +1948,8 @@ export class Encoder {
             }
             this.codecContext.width = frame.width;
             this.codecContext.height = frame.height;
-            this.codecContext.pixelFormat = frame.format;
+            // Pick a codec-supported pixel format (converting on demand when autoFormat).
+            this.setupVideoFormat(frame);
             this.codecContext.sampleAspectRatio = frame.sampleAspectRatio;
             this.codecContext.colorRange = frame.colorRange;
             this.codecContext.colorPrimaries = frame.colorPrimaries;
@@ -1790,12 +1961,8 @@ export class Encoder {
             }
         }
         else {
-            // Audio: Always use frame timebase (which is typically 1/sample_rate)
-            // This ensures correct PTS progression for audio frames
-            this.codecContext.timeBase = frame.timeBase;
-            this.codecContext.sampleRate = frame.sampleRate;
-            this.codecContext.sampleFormat = frame.format;
-            this.codecContext.channelLayout = frame.channelLayout;
+            // Audio: pick codec-supported sample rate/format/layout (resampling on demand).
+            this.setupAudioParams(frame);
         }
         // Setup hardware acceleration with validation
         this.setupHardwareAcceleration(frame);
@@ -1888,6 +2055,199 @@ export class Encoder {
             }
         }
     }
+    /**
+     * 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
+     */
+    setupAudioParams(frame) {
+        // Always use frame timebase (typically 1/sample_rate) for correct audio PTS.
+        this.codecContext.timeBase = frame.timeBase;
+        const inRate = frame.sampleRate;
+        const inFmt = frame.format;
+        // Codec open and swr both need a concrete layout. PCM/raw frames often carry
+        // an unspecified layout (order UNSPEC, mask 0); normalize it to the canonical
+        // native layout and re-apply it to each incoming frame (see encode()) so it
+        // matches the opened codec context / resampler input.
+        let inLayout = frame.channelLayout;
+        if (inLayout.order === AV_CHANNEL_ORDER_UNSPEC) {
+            inLayout = avChannelLayoutDefault(inLayout.nbChannels);
+            this.audioInputLayout = inLayout;
+        }
+        const targetRate = pickSupportedRate(inRate, this.codec.supportedSamplerates);
+        const targetFmt = pickSupportedSampleFormat(inFmt, this.codec.sampleFormats);
+        const targetLayout = pickSupportedLayout(inLayout, this.codec.channelLayouts);
+        const needsResample = targetRate !== inRate || targetFmt !== inFmt || targetLayout.nbChannels !== inLayout.nbChannels;
+        if (needsResample && !this.autoResample) {
+            const rates = this.codec.supportedSamplerates;
+            throw new Error(`Encoder '${this.codec.name}' does not support the input audio format ` +
+                `(${inRate} Hz, ${avGetSampleFmtName(inFmt) ?? inFmt}, ${inLayout.nbChannels}ch)` +
+                (rates && rates.length > 0 ? `. Supported sample rates: ${rates.join(', ')}` : '') +
+                '. Set { autoResample: true } on the encoder, or convert the input with an aresample/aformat filter first.');
+        }
+        this.codecContext.sampleRate = targetRate;
+        this.codecContext.sampleFormat = targetFmt;
+        this.codecContext.channelLayout = targetLayout;
+        if (needsResample) {
+            const swr = new SoftwareResampleContext();
+            FFmpegError.throwIfError(swr.allocSetOpts2(targetLayout, targetFmt, targetRate, inLayout, inFmt, inRate), 'Failed to configure audio resampler');
+            FFmpegError.throwIfError(swr.init(), 'Failed to initialize audio resampler');
+            this.audioResampler = swr;
+        }
+    }
+    /**
+     * Lazily allocate the reused resampler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    getResampleFrame() {
+        if (!this.resampledFrame) {
+            this.resampledFrame = new Frame();
+            this.resampledFrame.alloc();
+        }
+        return this.resampledFrame;
+    }
+    /**
+     * 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
+     */
+    resampleAudio(frame) {
+        const out = this.getResampleFrame();
+        out.unref();
+        out.format = this.codecContext.sampleFormat;
+        out.sampleRate = this.codecContext.sampleRate;
+        out.channelLayout = this.codecContext.channelLayout;
+        FFmpegError.throwIfError(this.audioResampler.convertFrame(out, frame), 'Failed to resample audio frame');
+        out.timeBase = frame.timeBase;
+        out.pts = frame.pts;
+        return out;
+    }
+    /**
+     * 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
+     */
+    drainResampler() {
+        if (!this.audioResampler) {
+            return null;
+        }
+        const out = this.getResampleFrame();
+        out.unref();
+        out.format = this.codecContext.sampleFormat;
+        out.sampleRate = this.codecContext.sampleRate;
+        out.channelLayout = this.codecContext.channelLayout;
+        const ret = this.audioResampler.convertFrame(out, null);
+        if (ret < 0 || out.nbSamples <= 0) {
+            return null;
+        }
+        return out;
+    }
+    /**
+     * 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
+     */
+    setupVideoFormat(frame) {
+        const inFmt = frame.format;
+        // Hardware frames carry a hw pixfmt negotiated via hw_frames_ctx; swscale can't
+        // touch them - leave the format untouched.
+        if (frame.isHwFrame()) {
+            this.codecContext.pixelFormat = inFmt;
+            return;
+        }
+        const targetFmt = pickSupportedPixelFormat(inFmt, this.codec.pixelFormats);
+        const needsConversion = targetFmt !== inFmt;
+        if (needsConversion && !this.autoFormat) {
+            const supported = this.codec.pixelFormats;
+            throw new Error(`Encoder '${this.codec.name}' does not support the input pixel format ` +
+                `(${avGetPixFmtName(inFmt) ?? inFmt}). Supported: ${supported.map((f) => avGetPixFmtName(f) ?? f).join(', ')}` +
+                '. Set { autoFormat: true } on the encoder, or convert the input with a scale/format filter first.');
+        }
+        this.codecContext.pixelFormat = targetFmt;
+        // Set up a same-size swscale converter when the codec needs a different format.
+        if (needsConversion) {
+            this.videoTargetFormat = targetFmt;
+            const sws = new SoftwareScaleContext();
+            sws.getContext(frame.width, frame.height, inFmt, frame.width, frame.height, targetFmt, SWS_BILINEAR);
+            FFmpegError.throwIfError(sws.initContext(), 'Failed to configure pixel-format converter');
+            this.videoScaler = sws;
+        }
+    }
+    /**
+     * Lazily allocate the reused scaler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    getScaledFrame() {
+        if (!this.scaledFrame) {
+            this.scaledFrame = new Frame();
+            this.scaledFrame.alloc();
+        }
+        return this.scaledFrame;
+    }
+    /**
+     * 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
+     */
+    scaleVideo(frame) {
+        const out = this.getScaledFrame();
+        out.unref();
+        out.format = this.videoTargetFormat;
+        out.width = frame.width;
+        out.height = frame.height;
+        FFmpegError.throwIfError(this.videoScaler.scaleFrameSync(out, frame), 'Failed to convert video frame format');
+        out.timeBase = frame.timeBase;
+        out.pts = frame.pts;
+        out.duration = frame.duration;
+        return out;
+    }
     /**
      * Prepare frame for encoding.
      *