node-av 6.2.0-beta.9 → 6.2.0

package/dist/api/rtp-stream.js

@@ -1,9 +1,10 @@
 import { isRtcp, RtpPacket } from 'werift';
-import { AV_HWDEVICE_TYPE_NONE, AV_PICTURE_TYPE_I, AV_PIX_FMT_YUV420P, AV_SAMPLE_FMT_FLTP } from '../constants/constants.js';
+import { AV_CODEC_ID_HEVC, AV_HWDEVICE_TYPE_NONE, AV_SAMPLE_FMT_FLTP } from '../constants/constants.js';
 import { FF_ENCODER_LIBOPUS, FF_ENCODER_LIBX264, FF_ENCODER_LIBX265 } from '../constants/encoders.js';
 import { Codec } from '../lib/codec.js';
 import { Rational } from '../lib/rational.js';
-import { avChannelLayoutDefault, avGetPixFmtName } from '../lib/utilities.js';
+import { avChannelLayoutDefault } from '../lib/utilities.js';
+import { BitStreamFilterAPI } from './bitstream-filter.js';
 import { MAX_PACKET_SIZE } from './constants.js';
 import { Decoder } from './decoder.js';
 import { Demuxer } from './demuxer.js';
@@ -12,8 +13,11 @@ import { FilterPreset } from './filter-presets.js';
 import { FilterAPI } from './filter.js';
 import { HardwareContext } from './hardware.js';
 import { Muxer } from './muxer.js';
-import { pipeline } from './pipeline.js';
-import { pickSupportedLayout, pickSupportedPixelFormat, pickSupportedRate, pickSupportedSampleFormat } from './utilities/codec-format.js';
+import { interruptibleFrameSource, pipeline } from './pipeline.js';
+import { pickSupportedLayout, pickSupportedRate, pickSupportedSampleFormat } from './utilities/codec-format.js';
+import { configureLiveDecoderThreading } from './utilities/live-decoding.js';
+import { transcodeScale } from './utilities/scale-size.js';
+import { applyVideoBitrate, createVideoTranscodeFilter, findSoftwareEncoder, findUsableHardwareEncoder, openTranscodeDecoder } from './utilities/video-transcode.js';
 /**
  * Check whether a streaming-class input is a frame source (not a URL or Demuxer).
  *
@@ -100,6 +104,7 @@ export class RTPStream {
     videoDecoder;
     videoFilter;
     videoEncoder;
+    videoBitstreamFilter;
     audioDecoder;
     audioFilter;
     audioEncoder;
@@ -108,11 +113,11 @@ export class RTPStream {
     signal;
     supportedVideoCodecs;
     supportedAudioCodecs;
-    videoKeyframeRequested = false;
     abortHandler;
     stopRequested = false;
     stopPromise;
     startAbort;
+    stopSignal = Promise.withResolvers();
     /**
      * @param input - Media input URL or pre-opened Demuxer
      *
@@ -148,11 +153,9 @@ export class RTPStream {
             },
         };
         this.signal = options.signal;
-        options.supportedVideoCodecs = options.supportedVideoCodecs?.filter(Boolean);
-        options.supportedAudioCodecs = options.supportedAudioCodecs?.filter(Boolean);
         // If no supported codecs specified, empty set means ALL codecs are supported (passthrough only)
-        this.supportedVideoCodecs = new Set(options.supportedVideoCodecs && options.supportedVideoCodecs.length > 0 ? options.supportedVideoCodecs : []);
-        this.supportedAudioCodecs = new Set(options.supportedAudioCodecs && options.supportedAudioCodecs.length > 0 ? options.supportedAudioCodecs : []);
+        this.supportedVideoCodecs = new Set(options.supportedVideoCodecs?.filter(Boolean));
+        this.supportedAudioCodecs = new Set(options.supportedAudioCodecs?.filter(Boolean));
         this.options = {
             onVideoPacket: options.onVideoPacket ?? (() => { }),
             onAudioPacket: options.onAudioPacket ?? (() => { }),
@@ -169,6 +172,8 @@ export class RTPStream {
                 width: options.video?.width,
                 height: options.video?.height,
                 bitrate: options.video?.bitrate,
+                dumpExtra: options.video?.dumpExtra,
+                transcode: options.video?.transcode,
                 encoderOptions: options.video?.encoderOptions ?? {},
             },
             audio: {
@@ -228,10 +233,14 @@ export class RTPStream {
     /**
      * Check if the stream is active.
      *
+     * Stays true while a requested stop is still unwinding: the pipeline reports
+     * itself stopped as soon as stop() is called, but its packets keep flowing
+     * and its native resources stay open until completion settles.
+     *
      * @returns True if the stream is active, false otherwise
      */
     get isStreamActive() {
-        return this.pipeline !== undefined && !this.pipeline.isStopped();
+        return this.pipeline !== undefined;
     }
     /**
      * Get the demuxer instance.
@@ -259,9 +268,9 @@ export class RTPStream {
      *
      * Used to answer receiver feedback (e.g. a WebRTC PLI) so a receiver that
      * missed the stream start or lost packets can resync without waiting for the
-     * next scheduled GOP keyframe. Currently effective for frame-source inputs
-     * ({@link MediaFrameSource}); for demuxer inputs the encoder's regular GOP
-     * cadence applies.
+     * next scheduled GOP keyframe. Effective whenever the video is encoded, from
+     * frame sources and from a transcoded URL or {@link Demuxer} input; a stream
+     * passed through keeps the source's keyframes.
      *
      * @example
      * ```typescript
@@ -271,29 +280,7 @@ export class RTPStream {
      * ```
      */
     requestVideoKeyframe() {
-        this.videoKeyframeRequested = true;
-    }
-    /**
-     * Pass video frames through, forcing a keyframe when one was requested.
-     *
-     * Sets `pictType = I` on the next frame after {@link requestVideoKeyframe};
-     * combined with the encoder's `forced-idr` option this produces an IDR the
-     * receiver can resync on.
-     *
-     * @param src - The user-provided video frame source
-     *
-     * @yields {Frame | null} The unchanged frames (with pictType forced when requested)
-     *
-     * @internal
-     */
-    async *wrapVideoSource(src) {
-        for await (const frame of src) {
-            if (frame && this.videoKeyframeRequested) {
-                this.videoKeyframeRequested = false;
-                frame.pictType = AV_PICTURE_TYPE_I;
-            }
-            yield frame;
-        }
+        this.videoEncoder?.requestKeyframe();
     }
     /**
      * Start streaming media to RTP packets.
@@ -356,6 +343,8 @@ export class RTPStream {
             };
             this.signal.addEventListener('abort', this.abortHandler, { once: true });
         }
+        // Re-armed per start so a restart is not torn down by the previous run.
+        this.stopSignal = Promise.withResolvers();
         // Lets stop() interrupt a startup that is blocked in the input open
         // (an RTSP connect can take seconds).
         this.startAbort = new AbortController();
@@ -374,8 +363,9 @@ export class RTPStream {
         this.throwIfStopRequested();
         const videoStream = this.input.video();
         const audioStream = this.input.audio();
+        let videoOutputIsHevc = videoStream?.codecpar.codecId === AV_CODEC_ID_HEVC;
         // Setup video transcoding if needed
-        if (videoStream && !this.isVideoCodecSupported(videoStream.codecpar.codecId)) {
+        if (videoStream && (this.options.video.transcode || !this.isVideoCodecSupported(videoStream.codecpar.codecId))) {
             // Check if we need hardware acceleration
             if (this.options.hardware === 'auto') {
                 this.hardwareContext = HardwareContext.auto();
@@ -383,84 +373,54 @@ export class RTPStream {
             else if (this.options.hardware.deviceType !== AV_HWDEVICE_TYPE_NONE) {
                 this.hardwareContext = HardwareContext.create(this.options.hardware.deviceType, this.options.hardware.device, this.options.hardware.options);
             }
-            this.videoDecoder = await Decoder.create(videoStream, {
-                exitOnError: false,
-                hardware: this.hardwareContext,
-            });
-            // Determine if we need filters by comparing with current stream properties
-            const currentWidth = videoStream.codecpar.width;
-            const currentHeight = videoStream.codecpar.height;
             const currentFps = videoStream.avgFrameRate.num / videoStream.avgFrameRate.den;
-            const needsScale = (this.options.video.width !== undefined && this.options.video.width !== currentWidth) ||
-                (this.options.video.height !== undefined && this.options.video.height !== currentHeight);
             const needsFps = this.options.video.fps !== undefined && isFinite(currentFps) && this.options.video.fps !== currentFps;
             // Get first supported codec
             const targetCodecId = this.options.supportedVideoCodecs[0];
             if (!targetCodecId) {
                 throw new Error('No supported video codec specified for transcoding');
             }
-            let encoderCodec = null;
-            if (typeof targetCodecId === 'string') {
-                encoderCodec = Codec.findEncoderByName(targetCodecId);
-            }
-            else {
-                encoderCodec = this.hardwareContext?.getEncoderCodec(targetCodecId) ?? Codec.findEncoder(targetCodecId);
-            }
+            const { codecpar } = videoStream;
+            const scale = transcodeScale(codecpar.width, codecpar.height, this.options.video.width, this.options.video.height);
+            // a GPU encodes up to a size of its own, test it with the size it will get
+            const encoderCodec = await this.findVideoEncoder(targetCodecId, scale.output);
             if (!encoderCodec) {
                 throw new Error(`No encoder found for codec ID ${targetCodecId}`);
             }
-            // Create filter chain only if needed
-            if (needsScale || needsFps) {
-                const filterChain = FilterPreset.chain(this.hardwareContext);
-                // Add scale filter if dimensions differ
-                if (needsScale) {
-                    const targetWidth = this.options.video.width ?? -1;
-                    const targetHeight = this.options.video.height ?? -1;
-                    filterChain.scale(targetWidth, targetHeight);
-                }
-                // Add fps filter if fps differs
-                if (needsFps) {
-                    filterChain.filter('fps', { fps: this.options.video.fps });
-                }
-                // Software scaling leaves the graph output format unconstrained, so swscale keeps the
-                // source format on both sides of the scale. Packed formats like yuyv422 can't be scaled
-                // in place (yuyv422 -> yuyv422 fails with ENOSYS), and the encoder wouldn't accept them
-                // anyway. Pin the output to yuv420p so the graph negotiates a real conversion: it is the
-                // one format every browser/player can decode over WebRTC (unlike e.g. the 4:2:2 High
-                // profile that a least-loss pick would choose for a yuyv422 source). Fall back to a
-                // codec-supported format only if the encoder genuinely can't take yuv420p. Hardware chains
-                // negotiate their format through the frames context instead.
-                if (needsScale && !this.hardwareContext) {
-                    const formats = encoderCodec.pixelFormats;
-                    const targetFmt = !formats || formats.includes(AV_PIX_FMT_YUV420P) ? AV_PIX_FMT_YUV420P : pickSupportedPixelFormat(videoStream.codecpar.format, formats);
-                    const targetFmtName = avGetPixFmtName(targetFmt);
-                    if (targetFmtName) {
-                        filterChain.filter('format', { pix_fmts: targetFmtName });
-                    }
-                }
-                this.videoFilter = FilterAPI.create(filterChain.build(), {
-                    hardware: this.hardwareContext,
-                });
-            }
-            let encoderOptions = {};
-            if (encoderCodec.name === FF_ENCODER_LIBX264 || encoderCodec.name === FF_ENCODER_LIBX265) {
-                encoderOptions.preset = 'ultrafast';
-                encoderOptions.tune = 'zerolatency';
-            }
-            encoderOptions = {
-                ...encoderOptions,
-                ...this.options.video.encoderOptions,
-            };
+            this.throwIfStopRequested();
+            this.videoDecoder = await openTranscodeDecoder(videoStream, this.hardwareContext, {
+                exitOnError: false,
+                // Frame threading holds back one frame per thread before the first output
+                configure: configureLiveDecoderThreading,
+            });
+            // The graph follows the frames: whether they come from the device and in
+            // which format shows only once they are decoded
+            this.videoFilter = createVideoTranscodeFilter({
+                ...scale.target,
+                fps: needsFps ? this.options.video.fps : undefined,
+                encoder: encoderCodec,
+                hardware: this.hardwareContext,
+            });
+            const encoderOptions = liveVideoEncoderOptions(encoderCodec.name, this.options.video.encoderOptions);
             const bitrate = this.options.video.bitrate;
             this.videoEncoder = await Encoder.create(encoderCodec, {
                 decoder: this.videoDecoder,
+                filter: this.videoFilter,
                 maxBFrames: 0,
                 options: encoderOptions,
                 configure: (ctx) => {
-                    this.applyBitrate(ctx, bitrate);
+                    // encoder defaults are 120 (VAAPI) or 250 frames (libx264, NVENC), a receiver that lost a packet waits that long;
+                    // after the short probe the input rate is often unknown, the context has it from the frames
+                    const fps = ctx.framerate.num > 0 ? ctx.framerate.num / ctx.framerate.den : 30;
+                    ctx.gopSize = Math.max(1, Math.round(fps * 2));
+                    applyVideoBitrate(ctx, bitrate);
                 },
             });
             this.throwIfStopRequested();
+            videoOutputIsHevc = encoderCodec.id === AV_CODEC_ID_HEVC;
+        }
+        if (videoStream && videoOutputIsHevc && this.options.video?.dumpExtra) {
+            this.videoBitstreamFilter = BitStreamFilterAPI.create('dump_extra', this.videoEncoder ?? videoStream, { options: { freq: 'k' } });
         }
         // Setup video output
         this.videoOutput = await this.createVideoOutput();
@@ -510,6 +470,9 @@ export class RTPStream {
                 decoder: this.audioDecoder,
                 filter: this.audioFilter,
                 options: encoderOptions,
+                // Silence for an input gap would only go out once the input resumes, as a burst of
+                // late packets; receivers conceal a timestamp gap like packet loss instead
+                audioFrameBuffer: { maxGapFill: 0 },
             });
             this.throwIfStopRequested();
         }
@@ -537,50 +500,87 @@ export class RTPStream {
             throw new Error('RTPStream stopped during start');
         }
     }
-    /**
-     * Cap the video bitrate on the encoder context.
-     *
-     * Applies a VBV rate cap (maxrate + a 1s buffer) WITHOUT setting a target
-     * bitrate, so the encoder keeps its default constant-quality mode but can
-     * never exceed the negotiated ceiling. Setting the bitrate as an ABR target
-     * instead would push a normally-lighter stream UP to fill it, overshooting
-     * on bursts.
-     *
-     * @param ctx - Encoder codec context
-     *
-     * @param bitrate - Maximum bitrate in bits per second, or undefined
-     *
-     * @internal
-     */
-    applyBitrate(ctx, bitrate) {
-        if (!bitrate || bitrate <= 0) {
-            return;
-        }
-        ctx.rcMaxRate = BigInt(Math.round(bitrate));
-        ctx.rcBufferSize = Math.round(bitrate);
-    }
     /**
      * Wire the pipeline completion to the onClose/error callbacks.
      *
      * On success invokes `onClose()`; on error stops the stream and invokes
-     * `onClose(error)`. Runs in the background (not awaited).
+     * `onClose(error)`. Either way `onClose` runs exactly once and the detached
+     * chain never rejects. Runs in the background (not awaited).
      *
      * @param completion - The pipeline completion promise
      *
      * @internal
      */
     attachCompletion(completion) {
+        // Captured so a restart that installed a newer pipeline keeps it.
+        const control = this.pipeline;
+        // One then() with both handlers: a throwing onClose() in the success path
+        // must not fall through into the error path and fire onClose a second time.
         completion
             .then(() => {
             // Pipeline completed successfully
-            this.options.onClose?.();
+            this.emitClose();
+        }, async (reason) => {
+            const error = reason instanceof Error ? reason : new Error(String(reason));
+            // A stop() in flight or an aborted signal means the owner is tearing
+            // the stream down - the pipeline unwinding with an AbortError (or an
+            // interrupted FFmpeg call) is the expected shutdown path, not a failure.
+            // Decided before the stop() below, which would make every failure look deliberate.
+            const deliberate = this.isDeliberateStop(reason);
+            if (!deliberate) {
+                console.error('[RTPStream] Pipeline error:', error);
+            }
+            // A teardown failure must not swallow the onClose call: without it
+            // the owner never learns the stream is gone.
+            try {
+                await this.stop();
+            }
+            catch {
+                // doStop() already released whatever it could.
+            }
+            this.emitClose(deliberate ? undefined : error);
         })
-            .catch(async (error) => {
-            console.error('[RTPStream] Pipeline error:', error);
-            await this.stop();
-            this.options.onClose?.(error);
+            .finally(() => {
+            // Drop the finished pipeline so isStreamActive reports inactive. The
+            // demuxer path already clears it in runPipeline(); a frame source has
+            // no such step, so without this it would look active forever.
+            if (this.pipeline === control) {
+                this.pipeline = undefined;
+            }
         });
     }
+    /**
+     * Invoke the owner's onClose callback.
+     *
+     * The completion chain runs detached, so an exception from the callback
+     * could only surface as an unhandled rejection - it is logged instead.
+     *
+     * @param error - Pipeline error, or undefined for a clean end
+     *
+     * @internal
+     */
+    emitClose(error) {
+        try {
+            this.options.onClose(error);
+        }
+        catch (callbackError) {
+            // The stream is already closed; logged so a broken restart path in the
+            // owner does not vanish silently.
+            console.error('[RTPStream] onClose callback threw:', callbackError);
+        }
+    }
+    /**
+     * Whether a pipeline rejection was caused by an intentional shutdown.
+     *
+     * @param error - The pipeline rejection reason
+     *
+     * @returns True when stop() is in flight or the owner's signal aborted
+     *
+     * @internal
+     */
+    isDeliberateStop(error) {
+        return this.stopRequested || this.stopPromise !== undefined || this.signal?.aborted === true || (error instanceof Error && error.name === 'AbortError');
+    }
     /**
      * Set up encoders and RTP outputs for a pre-composited frame source and start
      * encoding. No demuxer or decoder is involved - the provided frames are encoded
@@ -607,25 +607,12 @@ export class RTPStream {
                 this.hardwareContext = HardwareContext.create(this.options.hardware.deviceType, this.options.hardware.device, this.options.hardware.options);
             }
             const targetCodecId = this.options.supportedVideoCodecs[0] ?? FF_ENCODER_LIBX264;
-            let encoderCodec = null;
-            if (typeof targetCodecId === 'string') {
-                encoderCodec = Codec.findEncoderByName(targetCodecId);
-            }
-            else {
-                encoderCodec = this.hardwareContext?.getEncoderCodec(targetCodecId) ?? Codec.findEncoder(targetCodecId);
-            }
+            const encoderCodec = await this.findVideoEncoder(targetCodecId);
             if (!encoderCodec) {
                 throw new Error(`No encoder found for video codec ${String(targetCodecId)}`);
             }
-            let encoderOptions = {};
-            if (encoderCodec.name === FF_ENCODER_LIBX264 || encoderCodec.name === FF_ENCODER_LIBX265) {
-                encoderOptions.preset = 'ultrafast';
-                encoderOptions.tune = 'zerolatency';
-                // Make a requested keyframe (frame.pictType = I) an actual IDR, so a
-                // receiver that missed the stream start can resync (PLI handling).
-                encoderOptions['forced-idr'] = true;
-            }
-            encoderOptions = { ...encoderOptions, ...this.options.video.encoderOptions };
+            this.throwIfStopRequested();
+            const encoderOptions = liveVideoEncoderOptions(encoderCodec.name, this.options.video.encoderOptions);
             let fps = this.options.video.fps ?? 20;
             if (!isFinite(fps) || fps <= 0 || isNaN(fps)) {
                 fps = 20;
@@ -644,12 +631,16 @@ export class RTPStream {
                 configure: (ctx) => {
                     ctx.framerate = new Rational(Math.round(fps), 1);
                     ctx.gopSize = Math.max(1, Math.round(fps * 2));
-                    this.applyBitrate(ctx, bitrate);
+                    applyVideoBitrate(ctx, bitrate);
                 },
             });
+            // Source frames may sit on another device or in a format the encoder rejects
+            this.videoFilter = createVideoTranscodeFilter({ width: -1, height: -1, encoder: encoderCodec, hardware: this.hardwareContext });
             this.videoOutput = await this.createVideoOutput();
             this.throwIfStopRequested();
-            controls.push(pipeline(this.wrapVideoSource(source.video), this.videoEncoder, this.videoOutput, opts));
+            // a frame source has no demuxer for stop() to interrupt, a silent one would block teardown
+            const video = interruptibleFrameSource(source.video, this.stopSignal.promise);
+            controls.push(pipeline(video, this.videoFilter, this.videoEncoder, this.videoOutput, opts));
         }
         // Audio
         if (source.audio) {
@@ -682,10 +673,12 @@ export class RTPStream {
             this.audioEncoder = await Encoder.create(encoderCodec, {
                 filter: this.audioFilter,
                 options: encoderOptions,
+                audioFrameBuffer: { maxGapFill: 0 },
             });
             this.audioOutput = await this.createAudioOutput();
             this.throwIfStopRequested();
-            controls.push(pipeline(source.audio, this.audioFilter, this.audioEncoder, this.audioOutput, opts));
+            const audio = interruptibleFrameSource(source.audio, this.stopSignal.promise);
+            controls.push(pipeline(audio, this.audioFilter, this.audioEncoder, this.audioOutput, opts));
         }
         this.pipeline = new CombinedPipelineControl(controls);
         this.attachCompletion(this.pipeline.completion);
@@ -797,7 +790,7 @@ export class RTPStream {
         const opts = this.signal ? { signal: this.signal } : undefined;
         if (hasAudio && hasVideo) {
             this.pipeline = pipeline(this.input, {
-                video: [this.videoDecoder, this.videoFilter, this.videoEncoder],
+                video: [this.videoDecoder, this.videoFilter, this.videoEncoder, this.videoBitstreamFilter],
                 audio: [this.audioDecoder, this.audioFilter, this.audioEncoder],
             }, {
                 video: this.videoOutput,
@@ -806,7 +799,7 @@ export class RTPStream {
         }
         else if (hasVideo) {
             this.pipeline = pipeline(this.input, {
-                video: [this.videoDecoder, this.videoFilter, this.videoEncoder],
+                video: [this.videoDecoder, this.videoFilter, this.videoEncoder, this.videoBitstreamFilter],
             }, this.videoOutput, opts);
         }
         else if (hasAudio) {
@@ -825,7 +818,8 @@ export class RTPStream {
      *
      * Stops the pipeline, closes output, and releases all FFmpeg resources.
      * Safe to call multiple times. After stopping, you can call start() again
-     * to restart the stream.
+     * to restart the stream. Resolves even if the pipeline had failed; that
+     * error is reported through `onClose(error)`.
      *
      * @example
      * ```typescript
@@ -859,6 +853,9 @@ export class RTPStream {
         this.stopRequested = true;
         this.startAbort?.abort();
         this.startAbort = undefined;
+        // Unblocks a frame source that went silent, so the completion barrier below
+        // cannot wait on a pull that will never settle.
+        this.stopSignal.resolve();
         const inflightStart = this.startPromise;
         // Allow a fresh start() after stopping.
         this.startPromise = undefined;
@@ -881,20 +878,38 @@ export class RTPStream {
             // the source demuxer's read (frame-source pipelines unwind via iterator.return
             // instead). Swallow a rejected completion here - the error is already surfaced
             // to the caller via the onClose(error) path; we just need cleanup to proceed.
-            if (this.pipeline && !this.pipeline.isStopped()) {
-                this.pipeline.stop();
+            const pipeline = this.pipeline;
+            if (pipeline) {
+                if (!pipeline.isStopped()) {
+                    pipeline.stop();
+                }
                 try {
-                    await this.pipeline.completion;
+                    await pipeline.completion;
                 }
                 catch {
                     // Pipeline errored - proceed with teardown regardless.
                 }
-                this.pipeline = undefined;
+                if (this.pipeline === pipeline) {
+                    this.pipeline = undefined;
+                }
+            }
+            // Close all resources. close() rethrows a failed background write after it
+            // freed the muxer. That error already ended the pipeline and reaches the
+            // owner through onClose(error), so it must not abort the teardown here and
+            // leak the other output, the codecs and the input (an RTSP connection).
+            try {
+                await this.videoOutput?.close();
+            }
+            catch {
+                // Surfaced through the pipeline completion.
             }
-            // Close all resources
-            await this.videoOutput?.close();
             this.videoOutput = undefined;
-            await this.audioOutput?.close();
+            try {
+                await this.audioOutput?.close();
+            }
+            catch {
+                // Surfaced through the pipeline completion.
+            }
             this.audioOutput = undefined;
             this.videoEncoder?.close();
             this.videoEncoder = undefined;
@@ -948,6 +963,27 @@ export class RTPStream {
         }
         return isSupported;
     }
+    /**
+     * Find the encoder for a target video codec, on the device when it works there.
+     *
+     * @param target - Codec ID, or the name of a specific encoder to use as it is
+     *
+     * @param size - The output size, when known before the first frame
+     *
+     * @param size.width - Width
+     *
+     * @param size.height - Height
+     *
+     * @returns The encoder, or null if none exists
+     *
+     * @internal
+     */
+    async findVideoEncoder(target, size) {
+        if (typeof target === 'string') {
+            return Codec.findEncoderByName(target);
+        }
+        return (await findUsableHardwareEncoder(this.hardwareContext, target, this.options.video.encoderOptions, size)) ?? findSoftwareEncoder(target);
+    }
     /**
      * Check if the given video codec is supported.
      *
@@ -1042,4 +1078,47 @@ export class RTPStream {
         return picked.mask.toString();
     }
 }
+/**
+ * Encoder options for live video: low-latency presets for x264/x265 and an IDR
+ * for every requested keyframe, so a receiver that lost packets can resync.
+ *
+ * @param name - The encoder's name
+ *
+ * @param overrides - Caller options, applied last
+ *
+ * @returns The encoder options
+ *
+ * @internal
+ */
+function liveVideoEncoderOptions(name, overrides) {
+    const options = {};
+    if (name === FF_ENCODER_LIBX264 || name === FF_ENCODER_LIBX265) {
+        options.preset = 'ultrafast';
+        options.tune = 'zerolatency';
+    }
+    // VAAPI, D3D12 and VideoToolbox make a forced I frame an IDR without an option
+    const forcedIdr = forcedIdrOption(name);
+    if (forcedIdr) {
+        options[forcedIdr] = true;
+    }
+    return { ...options, ...overrides };
+}
+/**
+ * The option that makes an encoder emit a forced I frame (frame.pictType = I) as IDR.
+ *
+ * @param name - The encoder's name
+ *
+ * @returns The option, or null when the encoder needs none or has none
+ *
+ * @internal
+ */
+function forcedIdrOption(name) {
+    if (name === FF_ENCODER_LIBX264 || name === FF_ENCODER_LIBX265 || name?.endsWith('_nvenc')) {
+        return 'forced-idr';
+    }
+    if (name?.endsWith('_qsv') || name?.endsWith('_amf')) {
+        return 'forced_idr';
+    }
+    return null;
+}
 //# sourceMappingURL=rtp-stream.js.map