node-av 6.2.0-beta.9 → 6.2.0

package/dist/api/fmp4-stream.js

@@ -1,8 +1,8 @@
-import { AV_CODEC_ID_AAC, AV_CODEC_ID_AV1, AV_CODEC_ID_FLAC, AV_CODEC_ID_H264, AV_CODEC_ID_HEVC, AV_CODEC_ID_OPUS, AV_HWDEVICE_TYPE_NONE, AV_PIX_FMT_YUV420P, AV_SAMPLE_FMT_FLTP, } from '../constants/constants.js';
-import { FF_ENCODER_AAC, FF_ENCODER_LIBX264 } from '../constants/encoders.js';
+import { AV_CODEC_ID_AAC, AV_CODEC_ID_AV1, AV_CODEC_ID_FLAC, AV_CODEC_ID_H264, AV_CODEC_ID_HEVC, AV_CODEC_ID_OPUS, AV_HWDEVICE_TYPE_NONE, AV_SAMPLE_FMT_FLT, AV_SAMPLE_FMT_FLTP, } from '../constants/constants.js';
+import { FF_ENCODER_AAC, FF_ENCODER_LIBOPUS, FF_ENCODER_LIBX264 } from '../constants/encoders.js';
 import { Codec } from '../lib/codec.js';
 import { Rational } from '../lib/rational.js';
-import { avGetCodecString, avGetPixFmtName } from '../lib/utilities.js';
+import { avGetCodecString, avGetMediaTypeString } from '../lib/utilities.js';
 import { Decoder } from './decoder.js';
 import { Demuxer } from './demuxer.js';
 import { Encoder } from './encoder.js';
@@ -10,8 +10,11 @@ import { FilterPreset } from './filter-presets.js';
 import { FilterAPI } from './filter.js';
 import { HardwareContext } from './hardware.js';
 import { Muxer } from './muxer.js';
-import { consumeStreamInParallel, pipeline, PipelineControlImpl } from './pipeline.js';
-import { pickSupportedPixelFormat } from './utilities/codec-format.js';
+import { consumeStreamInParallel, interruptibleFrameSource, pipeline, PipelineControlImpl } from './pipeline.js';
+import { configureLiveDecoderThreading } from './utilities/live-decoding.js';
+import { PacketAgeWatchdog } from './utilities/packet-age-watchdog.js';
+import { transcodeScale } from './utilities/scale-size.js';
+import { applyVideoBitrate, createVideoTranscodeFilter, findUsableHardwareEncoder, openTranscodeDecoder } from './utilities/video-transcode.js';
 /**
  * Target codec strings for fMP4 streaming.
  */
@@ -23,11 +26,18 @@ export const FMP4_CODECS = {
     FLAC: 'flac',
     OPUS: 'opus',
 };
+/**
+ * Shortest fragDuration in seconds the transcoded video GOP follows.
+ *
+ * @internal
+ */
+const MIN_FRAGMENT_GOP = 0.5;
 /**
  * High-level fMP4 streaming with automatic codec detection and transcoding.
  *
  * Provides fragmented MP4 streaming for clients.
- * Automatically transcodes video to H.264 and audio to AAC if not supported by client.
+ * Automatically transcodes video to H.264 and audio to AAC (Opus when the client
+ * lists Opus but not AAC) if not supported by client.
  * Client sends supported codecs, server transcodes accordingly.
  * Essential component for building adaptive streaming servers.
  *
@@ -69,6 +79,7 @@ export class FMP4Stream {
     options;
     inputUrl;
     inputOptions;
+    liveInput;
     input;
     source;
     output;
@@ -87,9 +98,12 @@ export class FMP4Stream {
     pendingFragment = [];
     abortHandler;
     stopRequested = false;
+    discardOutput = false;
     stopPromise;
     startAbort;
+    stopSignal = Promise.withResolvers();
     fragmentQueue = null;
+    packetAgeWatchdog;
     _droppedFragments = 0;
     _initSegment = null;
     _initSegmentResolve = null;
@@ -104,9 +118,26 @@ export class FMP4Stream {
      *
      * Use {@link create} factory method
      *
+     * @throws {RangeError} If dtsBackwardThreshold, dtsForwardThreshold or maxPacketAge is not a finite number >= 0
+     *
      * @internal
      */
     constructor(input, options) {
+        const isLiveInput = typeof input === 'string' && /^(rtsps?|rtmp(?:e|s|t|te|ts)?|s?rtp|udp|srt|tcp|tls|sctp):/i.test(input);
+        this.liveInput = isLiveInput;
+        const dtsBackwardThreshold = options.dtsBackwardThreshold ?? 10;
+        // Only a source read in real time pairs a gap with the matching wait.
+        const dtsForwardThreshold = options.dtsForwardThreshold ?? (isLiveInput ? 10 : 0);
+        const maxPacketAge = options.maxPacketAge ?? 60;
+        for (const [name, value] of [
+            ['dtsBackwardThreshold', dtsBackwardThreshold],
+            ['dtsForwardThreshold', dtsForwardThreshold],
+            ['maxPacketAge', maxPacketAge],
+        ]) {
+            if (!Number.isFinite(value) || value < 0) {
+                throw new RangeError(`${name} must be a finite number of seconds >= 0, got ${value}`);
+            }
+        }
         if (typeof input === 'string') {
             this.inputUrl = input;
         }
@@ -119,7 +150,6 @@ export class FMP4Stream {
             this.source = input;
         }
         const inputUrl = this.inputUrl ?? '';
-        const isLiveInput = /^(rtsp|rtmp|rtp|udp|srt|tcp|sctp):/i.test(inputUrl);
         this.inputOptions = {
             ...options.inputOptions,
             options: {
@@ -141,6 +171,8 @@ export class FMP4Stream {
                 width: options.video?.width,
                 height: options.video?.height,
                 bitrate: options.video?.bitrate,
+                transcode: options.video?.transcode,
+                tag: options.video?.tag,
                 encoderOptions: options.video?.encoderOptions ?? {},
             },
             audio: {
@@ -150,6 +182,9 @@ export class FMP4Stream {
             boxMode: options.boxMode ?? false,
             maxQueuedFragments: options.maxQueuedFragments ?? 16,
             movFlags: options.movFlags ?? '+frag_keyframe+separate_moof+default_base_moof+empty_moov',
+            dtsBackwardThreshold,
+            dtsForwardThreshold,
+            maxPacketAge,
         };
         this.signal = options.signal;
         // Parse supported codecs
@@ -170,6 +205,8 @@ export class FMP4Stream {
      *
      * @returns Configured fMP4 stream instance
      *
+     * @throws {RangeError} If dtsBackwardThreshold, dtsForwardThreshold or maxPacketAge is not a finite number >= 0
+     *
      * @example
      * ```typescript
      * // Stream from file with codec negotiation
@@ -288,7 +325,7 @@ export class FMP4Stream {
                 parts.push(FMP4_CODECS.H264);
             }
             if (this.source.audio) {
-                parts.push(FMP4_CODECS.AAC);
+                parts.push(this.audioTranscodeTarget());
             }
             return parts.join(',');
         }
@@ -302,7 +339,7 @@ export class FMP4Stream {
         // Determine video codec string
         let videoCodec = null;
         if (videoCodecId) {
-            const needsVideoTranscode = !this.isVideoCodecSupported(videoCodecId);
+            const needsVideoTranscode = this.transcodesVideo(videoCodecId);
             if (needsVideoTranscode) {
                 // Transcoding to H.264
                 videoCodec = FMP4_CODECS.H264;
@@ -332,8 +369,7 @@ export class FMP4Stream {
         if (audioCodecId) {
             const needsAudioTranscode = !this.isAudioCodecSupported(audioCodecId);
             if (needsAudioTranscode) {
-                // Transcoding to AAC
-                audioCodec = FMP4_CODECS.AAC;
+                audioCodec = this.audioTranscodeTarget();
             }
             else if (audioCodecId === AV_CODEC_ID_AAC) {
                 // AAC - use fixed codec string
@@ -355,13 +391,60 @@ export class FMP4Stream {
         // Combine video and audio codec strings
         return [videoCodec, audioCodec].filter(Boolean).join(',');
     }
+    /**
+     * Video description of the muxed fMP4 output (output codec, RFC 6381 codec string, resolution, fps).
+     *
+     * Available after {@link start} has opened the input.
+     *
+     * @returns The output video info, or `undefined` when there is no video track.
+     *
+     * @example
+     * ```typescript
+     * const videoInfo = stream.getVideoInfo();
+     * if (videoInfo) {
+     *   console.log(`Codec: ${videoInfo.codec}, Resolution: ${videoInfo.width}x${videoInfo.height}, FPS: ${videoInfo.fps}`);
+     * }
+     * ```
+     */
+    getVideoInfo() {
+        if (this.source) {
+            if (!this.source.video) {
+                return undefined;
+            }
+            return {
+                codec: 'h264',
+                codecString: FMP4_CODECS.H264,
+                width: this.options.video?.width ?? 0,
+                height: this.options.video?.height ?? 0,
+                fps: this.options.video?.fps ?? 0,
+            };
+        }
+        const videoStream = this.input?.video();
+        if (!videoStream) {
+            return undefined;
+        }
+        const { codecpar } = videoStream;
+        const codecId = codecpar.codecId;
+        const transcode = this.transcodesVideo(codecId);
+        const codecString = transcode ? FMP4_CODECS.H264 : (avGetCodecString(codecpar) ?? FMP4_CODECS.H264);
+        const codec = transcode || codecId === AV_CODEC_ID_H264 ? 'h264' : codecId === AV_CODEC_ID_HEVC ? 'hevc' : codecId === AV_CODEC_ID_AV1 ? 'av1' : 'unknown';
+        const size = transcode ? transcodeScale(codecpar.width, codecpar.height, this.options.video.width, this.options.video.height).output : undefined;
+        const rate = videoStream.avgFrameRate;
+        return {
+            codec,
+            codecString,
+            width: size?.width ?? codecpar.width,
+            height: size?.height ?? codecpar.height,
+            fps: transcode && this.options.video?.fps ? this.options.video.fps : rate.den ? rate.num / rate.den : 0,
+        };
+    }
     /**
      * Start streaming media to fMP4 chunks.
      *
      * Begins the media processing pipeline, reading packets from input,
      * transcoding based on supported codecs, and generating fMP4 chunks.
      * Video transcodes to H.264 if H.264/H.265 not supported.
-     * Audio transcodes to AAC if AAC/FLAC/Opus not supported.
+     * Audio transcodes to AAC (Opus when only Opus is listed) if the input codec is not supported.
      * This method returns immediately after starting the pipeline.
      *
      * @returns Promise that resolves when pipeline is started
@@ -414,6 +497,9 @@ export class FMP4Stream {
         };
         this.signal?.addEventListener('abort', this.abortHandler, { once: true });
         this._droppedFragments = 0;
+        this.discardOutput = false;
+        // 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();
@@ -434,7 +520,7 @@ export class FMP4Stream {
         const videoStream = this.input.video();
         const audioStream = this.input.audio();
         // Check if video needs transcoding
-        const needsVideoTranscode = videoStream && !this.isVideoCodecSupported(videoStream.codecpar.codecId);
+        const needsVideoTranscode = videoStream && this.transcodesVideo(videoStream.codecpar.codecId);
         if (needsVideoTranscode) {
             // Check if we need hardware acceleration
             if (this.options.hardware === 'auto') {
@@ -444,52 +530,28 @@ export class FMP4Stream {
                 this.hardwareContext = HardwareContext.create(this.options.hardware.deviceType, this.options.hardware.device, this.options.hardware.options);
             }
             // Transcode to H.264
-            this.videoDecoder = await Decoder.create(videoStream, {
-                hardware: this.hardwareContext,
+            const currentFps = videoStream.avgFrameRate.num / videoStream.avgFrameRate.den;
+            const needsFps = this.options.video.fps !== undefined && isFinite(currentFps) && this.options.video.fps !== currentFps;
+            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 findUsableHardwareEncoder(this.hardwareContext, 'h264', this.options.video.encoderOptions, scale.output)) ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
+            this.throwIfStopRequested();
+            this.videoDecoder = await openTranscodeDecoder(videoStream, this.hardwareContext, {
                 exitOnError: false,
+                // Frame threading holds back one frame per thread before the first output;
+                // files keep the full thread count for throughput
+                ...(this.liveInput ? { configure: configureLiveDecoderThreading } : {}),
             });
             this.throwIfStopRequested();
-            // 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;
-            const encoderCodec = this.hardwareContext?.getEncoderCodec('h264') ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
-            // 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 via MSE (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,
-                });
-            }
+            // 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,
+            });
             let encoderOptions = {};
             if (encoderCodec.name === FF_ENCODER_LIBX264) {
                 encoderOptions.preset = 'ultrafast';
@@ -501,14 +563,17 @@ export class FMP4Stream {
             };
             const effectiveFps = this.options.video.fps ?? currentFps;
             const fpsForGop = isFinite(effectiveFps) && effectiveFps > 0 ? effectiveFps : 30;
-            const fragSeconds = this.options.fragDuration && this.options.fragDuration > 0 ? this.options.fragDuration / 1_000_000 : 2;
             const bitrate = this.options.video.bitrate;
             this.videoEncoder = await Encoder.create(encoderCodec, {
                 decoder: this.videoDecoder,
+                filter: this.videoFilter,
+                // Hardware encoders default to B-frames, which delay every fragment and
+                // fail on some D3D12 drivers that report support for them
+                context: { maxBFrames: 0 },
                 options: encoderOptions,
                 configure: (ctx) => {
-                    ctx.gopSize = Math.max(1, Math.round(fpsForGop * fragSeconds));
-                    this.applyBitrate(ctx, bitrate);
+                    ctx.gopSize = this.gopSize(fpsForGop);
+                    applyVideoBitrate(ctx, bitrate);
                 },
             });
             this.throwIfStopRequested();
@@ -516,18 +581,10 @@ export class FMP4Stream {
         // Check if audio needs transcoding
         const needsAudioTranscode = audioStream && !this.isAudioCodecSupported(audioStream.codecpar.codecId);
         if (needsAudioTranscode) {
-            // Transcode to AAC
             this.audioDecoder = await Decoder.create(audioStream, {
                 exitOnError: false,
             });
-            const targetSampleRate = 44100;
-            const filterChain = FilterPreset.chain().aformat(AV_SAMPLE_FMT_FLTP, targetSampleRate, 'stereo').build();
-            this.audioFilter = FilterAPI.create(filterChain);
-            this.audioEncoder = await Encoder.create(FF_ENCODER_AAC, {
-                decoder: this.audioDecoder,
-                filter: this.audioFilter,
-                options: this.options.audio.encoderOptions,
-            });
+            await this.createAudioEncoder(this.audioDecoder, audioStream.codecpar.channels);
             this.throwIfStopRequested();
         }
         // Setup output with callback
@@ -552,35 +609,31 @@ export class FMP4Stream {
         }
     }
     /**
-     * Cap the video bitrate on the encoder context.
+     * GOP size for the video encoder that starts every fragment with a keyframe.
      *
-     * 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 - the opposite of what strict rate-capped consumers want.
-     * No-op when no bitrate was requested.
+     * frag_duration flushes a fragment once it is that long, mid-GOP on a
+     * P-frame unless the GOP has the same length, and strict consumers reject
+     * such fragments. Shorter fragments (the 1 µs default flushes after every
+     * frame) are not matched: a GOP of a few frames multiplies the bitrate, so
+     * below MIN_FRAGMENT_GOP the GOP is 2 s, as with a fragDuration of 0.
      *
-     * @param ctx - Encoder codec context
+     * @param fps - Output frame rate
      *
-     * @param bitrate - Maximum bitrate in bits per second, or undefined
+     * @returns GOP size in frames
      *
      * @internal
      */
-    applyBitrate(ctx, bitrate) {
-        if (!bitrate || bitrate <= 0) {
-            return;
-        }
-        ctx.rcMaxRate = BigInt(Math.round(bitrate));
-        // 1s buffer keeps per-fragment size close to the cap instead of allowing
-        // multi-second bursts over it.
-        ctx.rcBufferSize = Math.round(bitrate);
+    gopSize(fps) {
+        const fragSeconds = this.options.fragDuration / 1_000_000;
+        const seconds = fragSeconds >= MIN_FRAGMENT_GOP ? fragSeconds : 2;
+        return Math.max(1, Math.round(fps * seconds));
     }
     /**
      * Create the fMP4 output muxer with the fragment-emitting write callback.
      *
      * Uses `this.input` when present (demuxer path) and no input for the
-     * frame-source path.
+     * frame-source path. Attaches a fresh packet age watchdog unless
+     * `maxPacketAge` is 0.
      *
      * @returns The configured muxer
      *
@@ -589,12 +642,17 @@ export class FMP4Stream {
     async createOutput() {
         const cb = {
             write: (buffer) => {
+                // Swallows what the teardown of a failed session flushes (see attachCompletion).
+                if (this.discardOutput) {
+                    return buffer.length;
+                }
                 if (this.options.boxMode) {
                     // Box mode: buffer until we have complete boxes
                     this.processBoxMode(buffer);
                 }
                 else {
                     // Chunk mode: send raw data immediately
+                    this.packetAgeWatchdog?.consumeChunk(buffer);
                     const info = { isComplete: false, boxes: [] };
                     this.options.onData(buffer, info);
                     this.pushFragment(buffer, info);
@@ -602,45 +660,126 @@ export class FMP4Stream {
                 return buffer.length;
             },
         };
-        return await Muxer.open(cb, {
+        const output = await Muxer.open(cb, {
             input: this.input,
             format: 'mp4',
             bufferSize: this.options.bufferSize,
             exitOnError: false,
+            dtsBackwardThreshold: this.options.dtsBackwardThreshold,
+            dtsForwardThreshold: this.options.dtsForwardThreshold,
+            configure: (fmt) => {
+                const tag = this.options.video?.tag;
+                if (!tag) {
+                    return;
+                }
+                for (const stream of fmt.streams) {
+                    if (stream.codecpar.codecId === AV_CODEC_ID_HEVC) {
+                        stream.codecpar.codecTag = tag;
+                    }
+                }
+            },
             options: {
                 movflags: this.options.movFlags,
                 frag_duration: this.options.fragDuration,
             },
         });
+        // Per session: a restart must not inherit the previous session's backlog.
+        if (this.options.maxPacketAge > 0) {
+            this.packetAgeWatchdog = new PacketAgeWatchdog(this.options.maxPacketAge, (index) => {
+                const codecType = output.getStream(index)?.codecpar.codecType;
+                return codecType === undefined ? '' : (avGetMediaTypeString(codecType) ?? '');
+            });
+            output.setPacketObserver(this.packetAgeWatchdog);
+        }
+        return output;
     }
     /**
      * Wire the pipeline completion to the fragment/close callbacks.
      *
      * On success ends the fragment iterator and invokes `onClose()`; on error
-     * stops the stream and invokes `onClose(error)`. Runs in the background.
+     * stops the stream, discarding the output the muxer still holds, and invokes
+     * `onClose(error)`. Either way `onClose` runs exactly once and the detached
+     * chain never rejects. Runs in the background.
      *
      * @param completion - The pipeline completion promise
      *
      * @internal
      */
     attachCompletion(completion) {
-        completion
-            .then(() => {
+        // 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(() => {
             this.endFragments();
             // No-op in the normal case (init segment resolved long ago) - only
             // fires if the stream ended without ever emitting ftyp+moov.
             this.rejectInitSegment(new Error('FMP4Stream ended before init segment was produced'));
-            this.options.onClose?.();
-        })
-            .catch(async (error) => {
+            this.emitClose();
+        }, async (reason) => {
+            const error = reason instanceof Error ? reason : new Error(String(reason));
             this.endFragments();
             // Reject with the pipeline error so an initSegment consumer sees the
             // actual failure instead of the generic "stopped" error from stop().
-            this.rejectInitSegment(error instanceof Error ? error : new Error(String(error)));
-            await this.stop();
-            this.options.onClose?.(error);
+            this.rejectInitSegment(error);
+            // A stop() in flight or an aborted signal means the owner is tearing
+            // the stream down - the pipeline unwinding with an AbortError 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);
+            // Closing the output flushes the muxer's backlog and the trailer. After
+            // a failure that backlog is suspect: when a backward jump ends the
+            // session, the packets the timeline had jumped ahead to are still
+            // queued and would leave as a fragment placed that far ahead; after a
+            // stall it holds up to maxPacketAge of retained samples. Nothing is
+            // emitted past the failure, through onData or fragments(). A
+            // deliberate stop keeps its tail.
+            if (!deliberate) {
+                this.discardOutput = true;
+            }
+            // Release the input (e.g. the RTSP connection) before reporting, so an
+            // owner that restarts from onClose never overlaps a live session. 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);
         });
     }
+    /**
+     * 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('[FMP4Stream] 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 the fMP4 muxer for a pre-composited frame source and
      * start encoding. No demuxer or decoder is involved - the provided frames are
@@ -667,7 +806,8 @@ export class FMP4Stream {
             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);
             }
-            const encoderCodec = this.hardwareContext?.getEncoderCodec('h264') ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
+            const encoderCodec = (await findUsableHardwareEncoder(this.hardwareContext, 'h264', this.options.video.encoderOptions)) ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
+            this.throwIfStopRequested();
             let encoderOptions = {};
             if (encoderCodec.name === FF_ENCODER_LIBX264) {
                 encoderOptions.preset = 'ultrafast';
@@ -679,29 +819,22 @@ export class FMP4Stream {
                 fps = 30;
             }
             // Set the framerate explicitly - without a decoder the encoder would infer
-            // it from the frame timebase and pick an absurd level. Bound the GOP to the
-            // fragment duration (2s default) so every fMP4 fragment starts with a
-            // keyframe; otherwise frag_duration flushes fragments mid-GOP on a P-frame
-            // and strict consumers reject them.
-            const fragSeconds = this.options.fragDuration && this.options.fragDuration > 0 ? this.options.fragDuration / 1_000_000 : 2;
+            // it from the frame timebase and pick an absurd level.
             const bitrate = this.options.video.bitrate;
             this.videoEncoder = await Encoder.create(encoderCodec, {
+                context: { maxBFrames: 0 },
                 options: encoderOptions,
                 configure: (ctx) => {
                     ctx.framerate = new Rational(Math.round(fps), 1);
-                    ctx.gopSize = Math.max(1, Math.round(fps * fragSeconds));
-                    this.applyBitrate(ctx, bitrate);
+                    ctx.gopSize = this.gopSize(fps);
+                    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 });
         }
-        // Audio encoder (AAC), resampling via aformat like the demuxer path.
         if (source.audio) {
-            const filterChain = FilterPreset.chain().aformat(AV_SAMPLE_FMT_FLTP, 44100, 'stereo').build();
-            this.audioFilter = FilterAPI.create(filterChain);
-            this.audioEncoder = await Encoder.create(FF_ENCODER_AAC, {
-                filter: this.audioFilter,
-                options: this.options.audio.encoderOptions,
-            });
+            await this.createAudioEncoder();
         }
         this.throwIfStopRequested();
         this.output = await this.createOutput();
@@ -710,13 +843,18 @@ export class FMP4Stream {
         let control;
         const shouldStop = () => control?.isStopped() ?? false;
         const tasks = [];
-        if (source.video && this.videoEncoder) {
+        // A frame source has no demuxer for stop() to interrupt, so wrap it to make
+        // a silent source releasable instead of blocking teardown forever.
+        const stopped = this.stopSignal.promise;
+        if (source.video && this.videoFilter && this.videoEncoder) {
             const streamIndex = this.output.addStream(this.videoEncoder);
-            tasks.push(consumeStreamInParallel(this.videoEncoder.packets(source.video), this.output, streamIndex, shouldStop));
+            const video = interruptibleFrameSource(source.video, stopped);
+            tasks.push(consumeStreamInParallel(this.videoEncoder.packets(this.videoFilter.frames(video)), this.output, streamIndex, shouldStop));
         }
         if (source.audio && this.audioFilter && this.audioEncoder) {
             const streamIndex = this.output.addStream(this.audioEncoder);
-            tasks.push(consumeStreamInParallel(this.audioEncoder.packets(this.audioFilter.frames(source.audio)), this.output, streamIndex, shouldStop));
+            const audio = interruptibleFrameSource(source.audio, stopped);
+            tasks.push(consumeStreamInParallel(this.audioEncoder.packets(this.audioFilter.frames(audio)), this.output, streamIndex, shouldStop));
         }
         // Close the shared muxer only after ALL streams are done (flushes the trailer).
         const run = Promise.all(tasks).then(async () => {
@@ -731,7 +869,8 @@ export class FMP4Stream {
      *
      * 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
@@ -765,6 +904,9 @@ export class FMP4Stream {
         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;
@@ -788,22 +930,42 @@ export class FMP4Stream {
             // Stop pipeline if running and wait for completion. Swallow a rejected
             // completion - the error is already surfaced 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. The output goes FIRST: its async write worker may
             // still be draining (header init reads the input's stream parameters),
             // so freeing the input before the muxer has fully settled is a
             // use-after-free on the worker thread.
-            await this.output?.close();
+            // After a failure nothing the output emits is used (see attachCompletion),
+            // so the trailer is skipped instead of flushed into the void.
+            if (this.discardOutput) {
+                this.output?.discardOnClose();
+            }
+            // 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
+            // codecs and the input (an RTSP connection) below.
+            try {
+                await this.output?.close();
+            }
+            catch {
+                // Surfaced through the pipeline completion.
+            }
             this.output = undefined;
+            this.packetAgeWatchdog = undefined;
             this.videoDecoder?.close();
             this.videoDecoder = undefined;
             this.videoFilter?.close();
@@ -931,6 +1093,18 @@ export class FMP4Stream {
         await this.pipeline.completion;
         this.pipeline = undefined;
     }
+    /**
+     * Check if the video is encoded again instead of passed through.
+     *
+     * @param codecId - Codec ID of the source video
+     *
+     * @returns True if `video.transcode` is set or the codec is not in supported codecs
+     *
+     * @internal
+     */
+    transcodesVideo(codecId) {
+        return this.options.video.transcode === true || !this.isVideoCodecSupported(codecId);
+    }
     /**
      * Check if video codec is supported.
      *
@@ -952,6 +1126,47 @@ export class FMP4Stream {
         }
         return false;
     }
+    /**
+     * Codec that unsupported audio is transcoded to.
+     *
+     * @returns Opus when the client lists Opus but not AAC, otherwise AAC
+     *
+     * @internal
+     */
+    audioTranscodeTarget() {
+        return this.supportedCodecs.has(FMP4_CODECS.OPUS) && !this.supportedCodecs.has(FMP4_CODECS.AAC) ? FMP4_CODECS.OPUS : FMP4_CODECS.AAC;
+    }
+    /**
+     * Create the audio filter and encoder for the transcode target.
+     *
+     * AAC is resampled to 44.1 kHz stereo. Opus is resampled to 48 kHz, the only
+     * rate it transmits, keeps mono input mono and uses 20 ms frames.
+     *
+     * @param decoder - Input audio decoder, absent for a frame source
+     *
+     * @param channels - Input channel count, 0 when unknown
+     *
+     * @internal
+     */
+    async createAudioEncoder(decoder, channels = 0) {
+        if (this.audioTranscodeTarget() === FMP4_CODECS.OPUS) {
+            this.audioFilter = FilterAPI.create(FilterPreset.chain()
+                .aformat(AV_SAMPLE_FMT_FLT, 48000, channels === 1 ? 'mono' : 'stereo')
+                .build());
+            this.audioEncoder = await Encoder.create(FF_ENCODER_LIBOPUS, {
+                decoder,
+                filter: this.audioFilter,
+                options: { frame_duration: 20, ...this.options.audio.encoderOptions },
+            });
+            return;
+        }
+        this.audioFilter = FilterAPI.create(FilterPreset.chain().aformat(AV_SAMPLE_FMT_FLTP, 44100, 'stereo').build());
+        this.audioEncoder = await Encoder.create(FF_ENCODER_AAC, {
+            decoder,
+            filter: this.audioFilter,
+            options: this.options.audio.encoderOptions,
+        });
+    }
     /**
      * Check if audio codec is supported.
      *
@@ -1033,6 +1248,9 @@ export class FMP4Stream {
             // is corrupt - recovery is impossible, so drop the rest of this chunk
             // rather than emit garbage framing downstream.
             if (boxSize < headerSize) {
+                // Emitted samples can no longer be counted - stop judging packet ages
+                // instead of mistaking the lost framing for a stalled muxer.
+                this.packetAgeWatchdog?.onFramingLost();
                 break;
             }
             // Check if we have the complete box
@@ -1047,6 +1265,9 @@ export class FMP4Stream {
                 headerSize,
                 raw: chunk.subarray(offset, offset + boxSize),
             };
+            if (parsed.type === 'moof' || parsed.type === 'moov') {
+                this.packetAgeWatchdog?.consumeBox(parsed.raw);
+            }
             if (parsed.type === 'moof') {
                 flushImmediate();
                 if (this.pendingFragment.length > 0) {