node-av-lgpl 0.0.0 → 7.1.0-beta.1

package/dist/api/fmp4-stream.js

@@ -0,0 +1,1428 @@
+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, avGetMediaTypeString } from '../lib/utilities.js';
+import { Demuxer } from './demuxer.js';
+import { Encoder } from './encoder.js';
+import { FilterPreset } from './filter-presets.js';
+import { FilterAPI } from './filter.js';
+import { HardwareContext } from './hardware.js';
+import { Muxer } from './muxer.js';
+import { consumeStreamInParallel, interruptibleFrameSource, pipeline, PipelineControlImpl } from './pipeline.js';
+import { openAudioDecoder } from './utilities/audio-transcode.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.
+ */
+export const FMP4_CODECS = {
+    H264: 'avc1.640029',
+    H265: 'hvc1.1.6.L153.B0',
+    AV1: 'av01.0.00M.08',
+    AAC: 'mp4a.40.2',
+    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 (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.
+ *
+ * @example
+ * ```typescript
+ * import { FMP4Stream } from 'node-av/api';
+ *
+ * // Client sends supported codecs
+ * const supportedCodecs = 'avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2,flac';
+ *
+ * // Create stream with codec negotiation
+ * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+ *   supportedCodecs,
+ *   onData: (data) => ws.send(data.data)
+ * });
+ *
+ * // Start streaming (auto-transcodes if needed)
+ * await stream.start();
+ *
+ * // Stop when done
+ * await stream.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream with hardware acceleration
+ * const stream = FMP4Stream.create('input.mp4', {
+ *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+ *   hardware: 'auto',
+ *   fragDuration: 1,
+ *   onData: (data) => sendToClient(data.data)
+ * });
+ *
+ * await stream.start();
+ * await stream.stop();
+ * ```
+ */
+export class FMP4Stream {
+    options;
+    inputUrl;
+    inputOptions;
+    liveInput;
+    input;
+    source;
+    output;
+    hardwareContext;
+    videoDecoder;
+    videoFilter;
+    videoEncoder;
+    audioDecoder;
+    audioFilter;
+    audioEncoder;
+    pipeline;
+    startPromise;
+    signal;
+    supportedCodecs;
+    incompleteBoxBuffer = null;
+    pendingFragment = [];
+    abortHandler;
+    stopRequested = false;
+    discardOutput = false;
+    stopPromise;
+    startAbort;
+    stopSignal = Promise.withResolvers();
+    fragmentQueue = null;
+    packetAgeWatchdog;
+    _droppedFragments = 0;
+    _initSegment = null;
+    _initSegmentResolve = null;
+    _initSegmentReject = null;
+    _initSegmentPromise = null;
+    _ftypData = null;
+    _moovData = null;
+    /**
+     * @param input - Media input URL or pre-opened Demuxer
+     *
+     * @param options - Stream configuration options
+     *
+     * 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;
+        }
+        else if (input instanceof Demuxer) {
+            this.inputUrl = null;
+            this.input = input;
+        }
+        else {
+            this.inputUrl = null;
+            this.source = input;
+        }
+        const inputUrl = this.inputUrl ?? '';
+        this.inputOptions = {
+            ...options.inputOptions,
+            options: {
+                ...(isLiveInput ? { flags: 'low_delay', fflags: 'nobuffer' } : {}),
+                timeout: 10000000,
+                rtsp_transport: inputUrl.toLowerCase().startsWith('rtsp') ? 'tcp' : undefined,
+                ...options.inputOptions?.options,
+            },
+        };
+        this.options = {
+            onData: options.onData ?? (() => { }),
+            onClose: options.onClose ?? (() => { }),
+            supportedCodecs: options.supportedCodecs ?? '',
+            fragDuration: options.fragDuration ?? 1,
+            hardware: options.hardware ?? { deviceType: AV_HWDEVICE_TYPE_NONE },
+            inputOptions: options.inputOptions,
+            video: {
+                fps: options.video?.fps,
+                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: {
+                encoderOptions: options.audio?.encoderOptions ?? {},
+            },
+            bufferSize: options.bufferSize ?? 2 * 1024 * 1024,
+            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
+        this.supportedCodecs = new Set(this.options.supportedCodecs
+            .split(',')
+            .map((c) => c.trim())
+            .filter(Boolean));
+    }
+    /**
+     * Create a fMP4 stream from a media source.
+     *
+     * Configures the stream with input URL and options. The input is not opened
+     * until start() is called, allowing the stream to be reused after stop().
+     *
+     * @param input - Media source URL (RTSP, file path, HTTP, etc.) or a pre-opened {@link Demuxer}
+     *
+     * @param options - Stream configuration options with supported codecs
+     *
+     * @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
+     * const stream = FMP4Stream.create('video.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onData: (data) => ws.send(data.data)
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream from RTSP with auto hardware acceleration
+     * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2',
+     *   hardware: 'auto',
+     *   fragDuration: 0.5
+     * });
+     * ```
+     */
+    static create(input, options = {}) {
+        return new FMP4Stream(input, options);
+    }
+    /**
+     * Promise that resolves with the init segment (ftyp+moov).
+     *
+     * Only available when boxMode is enabled.
+     * Resolves once the first ftyp and moov boxes have been received.
+     * Rejects if the stream fails or is stopped before the init segment
+     * was produced, so awaiting it never hangs.
+     *
+     * @throws {Error} If boxMode is not enabled
+     */
+    get initSegment() {
+        if (!this.options.boxMode) {
+            throw new Error('initSegment is only available in box mode');
+        }
+        this._initSegmentPromise ??= new Promise((resolve, reject) => {
+            if (this._initSegment) {
+                resolve(this._initSegment);
+            }
+            else {
+                this._initSegmentResolve = resolve;
+                this._initSegmentReject = reject;
+            }
+        });
+        return this._initSegmentPromise;
+    }
+    /**
+     * Number of media fragments dropped due to consumer backpressure.
+     *
+     * Incremented whenever the {@link fragments} backlog exceeds
+     * `maxQueuedFragments` and the oldest fragment is discarded.
+     * Reset to 0 when the stream is (re)started.
+     *
+     * @returns Total dropped fragments for the current run
+     *
+     * @example
+     * ```typescript
+     * for await (const fragment of stream.fragments()) {
+     *   await sendToClient(fragment.data);
+     *   if (stream.droppedFragments > 0) {
+     *     console.warn(`Consumer too slow: ${stream.droppedFragments} fragments dropped`);
+     *   }
+     * }
+     * ```
+     */
+    get droppedFragments() {
+        return this._droppedFragments;
+    }
+    /**
+     * Get the demuxer instance.
+     *
+     * Used for accessing the underlying demuxer.
+     * Only available after start() is called.
+     *
+     * @returns Demuxer instance or undefined if not started
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('input.mp4', {
+     * const input = stream.getInput();
+     * console.log('Bitrate:', input?.bitRate);
+     * ```
+     */
+    getInput() {
+        return this.input;
+    }
+    /**
+     * Get the codec string that will be used by client.
+     *
+     * Returns the MIME type codec string based on input codecs and transcoding decisions.
+     * Call this after start() is called to know what codec string to use for addSourceBuffer().
+     *
+     * @returns MIME type codec string (e.g., "avc1.640029,mp4a.40.2")
+     *
+     * @throws {Error} If called before start() is called
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     *
+     * await stream.start(); // Must start first
+     * const codecString = stream.getCodecString();
+     * console.log(codecString); // "avc1.640029,mp4a.40.2"
+     * // Use this for: sourceBuffer = mediaSource.addSourceBuffer(`video/mp4; codecs="${codecString}"`);
+     * ```
+     */
+    getCodecString() {
+        // Frame-source path: there is no input codec - frames are always encoded
+        // to the fMP4 target codecs.
+        if (this.source) {
+            const parts = [];
+            if (this.source.video) {
+                parts.push(FMP4_CODECS.H264);
+            }
+            if (this.source.audio) {
+                parts.push(this.audioTranscodeTarget());
+            }
+            return parts.join(',');
+        }
+        if (!this.input) {
+            throw new Error('Input not opened. Call start() first to open the input.');
+        }
+        const videoStream = this.input.video();
+        const audioStream = this.input.audio();
+        const videoCodecId = videoStream?.codecpar.codecId;
+        const audioCodecId = audioStream?.codecpar.codecId;
+        // Determine video codec string
+        let videoCodec = null;
+        if (videoCodecId) {
+            const needsVideoTranscode = this.transcodesVideo(videoCodecId);
+            if (needsVideoTranscode) {
+                // Transcoding to H.264
+                videoCodec = FMP4_CODECS.H264;
+            }
+            else if (videoCodecId === AV_CODEC_ID_H264) {
+                // H.264 - use RFC 6381 codec string from input
+                const codecString = avGetCodecString(videoStream.codecpar);
+                videoCodec = codecString ?? FMP4_CODECS.H264;
+            }
+            else if (videoCodecId === AV_CODEC_ID_HEVC) {
+                // H.265 - use RFC 6381 codec string from input
+                const codecString = avGetCodecString(videoStream.codecpar);
+                videoCodec = codecString ?? FMP4_CODECS.H265;
+            }
+            else if (videoCodecId === AV_CODEC_ID_AV1) {
+                // AV1 - use RFC 6381 codec string from input
+                const codecString = avGetCodecString(videoStream.codecpar);
+                videoCodec = codecString ?? FMP4_CODECS.AV1;
+            }
+            else {
+                // Fallback to H.264 (should not happen as we transcode unsupported codecs)
+                videoCodec = FMP4_CODECS.H264;
+            }
+        }
+        // Determine audio codec string
+        let audioCodec = null;
+        if (audioCodecId) {
+            const needsAudioTranscode = !this.isAudioCodecSupported(audioCodecId);
+            if (needsAudioTranscode) {
+                audioCodec = this.audioTranscodeTarget();
+            }
+            else if (audioCodecId === AV_CODEC_ID_AAC) {
+                // AAC - use fixed codec string
+                audioCodec = FMP4_CODECS.AAC;
+            }
+            else if (audioCodecId === AV_CODEC_ID_FLAC) {
+                // FLAC
+                audioCodec = FMP4_CODECS.FLAC;
+            }
+            else if (audioCodecId === AV_CODEC_ID_OPUS) {
+                // Opus
+                audioCodec = FMP4_CODECS.OPUS;
+            }
+            else {
+                // Fallback to AAC (should not happen as we transcode unsupported codecs)
+                audioCodec = FMP4_CODECS.AAC;
+            }
+        }
+        // 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 (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
+     *
+     * @throws {FFmpegError} If setup fails
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onData: (data) => sendToClient(data.data)
+     * });
+     *
+     * // Start streaming (returns immediately)
+     * await stream.start();
+     *
+     * // Later: stop streaming
+     * await stream.stop();
+     * ```
+     */
+    async start() {
+        this.startPromise ??= this.doStart().catch((error) => {
+            this.startPromise = undefined;
+            // A pending initSegment consumer must not hang when startup fails.
+            this.rejectInitSegment(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        });
+        await this.startPromise;
+    }
+    /**
+     * Perform the actual startup (see {@link start}).
+     *
+     * @internal
+     */
+    async doStart() {
+        // A start racing an in-flight stop() waits for the teardown to finish,
+        // otherwise it would build the pipeline on top of freed resources.
+        if (this.stopPromise) {
+            await this.stopPromise;
+        }
+        if (this.pipeline) {
+            return;
+        }
+        this.signal?.throwIfAborted();
+        // Store the handler so stop() can remove it - otherwise listeners would
+        // accumulate across restarts. Teardown errors are swallowed here: they are
+        // already surfaced via onClose(error) by the completion handler.
+        this.abortHandler = () => {
+            this.stop().catch(() => { });
+        };
+        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();
+        // Frame-source path: encode pre-composited frames directly (no demuxer/decoder).
+        if (this.source) {
+            await this.startFromFrames();
+            return;
+        }
+        // Open input if not already open
+        if (!this.input) {
+            if (!this.inputUrl) {
+                throw new Error('No input URL or Demuxer provided');
+            }
+            const openSignal = this.signal ? AbortSignal.any([this.signal, this.startAbort.signal]) : this.startAbort.signal;
+            this.input = await Demuxer.open(this.inputUrl, { ...this.inputOptions, signal: openSignal });
+        }
+        this.throwIfStopRequested();
+        const videoStream = this.input.video();
+        const audioStream = this.input.audio();
+        // Check if video needs transcoding
+        const needsVideoTranscode = videoStream && this.transcodesVideo(videoStream.codecpar.codecId);
+        if (needsVideoTranscode) {
+            // Check if we need hardware acceleration
+            if (this.options.hardware === 'auto') {
+                this.hardwareContext = HardwareContext.auto();
+            }
+            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);
+            }
+            // Transcode to H.264
+            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)) ?? this.softwareH264Encoder();
+            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();
+            // 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';
+                encoderOptions.tune = 'zerolatency';
+            }
+            encoderOptions = {
+                ...encoderOptions,
+                ...this.options.video.encoderOptions,
+            };
+            const effectiveFps = this.options.video.fps ?? currentFps;
+            const fpsForGop = isFinite(effectiveFps) && effectiveFps > 0 ? effectiveFps : 30;
+            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 = this.gopSize(fpsForGop);
+                    applyVideoBitrate(ctx, bitrate);
+                },
+            });
+            this.throwIfStopRequested();
+        }
+        // Check if audio needs transcoding
+        const needsAudioTranscode = audioStream && !this.isAudioCodecSupported(audioStream.codecpar.codecId);
+        if (needsAudioTranscode) {
+            this.audioDecoder = await openAudioDecoder(audioStream, {
+                exitOnError: false,
+            });
+            await this.createAudioEncoder(this.audioDecoder, audioStream.codecpar.channels);
+            this.throwIfStopRequested();
+        }
+        // Setup output with callback
+        this.output = await this.createOutput();
+        this.throwIfStopRequested();
+        this.attachCompletion(this.runPipeline());
+    }
+    /**
+     * Abort an in-flight startup once stop() was requested.
+     *
+     * Checked after every await in the startup path: the resources created so
+     * far are all assigned to instance fields, so the stop() that is waiting on
+     * this startup tears them down the moment it unwinds.
+     *
+     * @throws {Error} If stop() was called while starting
+     *
+     * @internal
+     */
+    throwIfStopRequested() {
+        if (this.stopRequested) {
+            throw new Error('FMP4Stream stopped during start');
+        }
+    }
+    /**
+     * libx264, the encoder for H.264 output when no hardware encoder is usable.
+     *
+     * @returns The libx264 encoder
+     *
+     * @throws {Error} If the FFmpeg build has no libx264 (node-av-lgpl)
+     *
+     * @internal
+     */
+    softwareH264Encoder() {
+        const codec = Codec.findEncoderByName(FF_ENCODER_LIBX264);
+        if (!codec) {
+            throw new Error('No H.264 encoder available: no usable hardware encoder and this FFmpeg build has no libx264 (node-av-lgpl encodes H.264 only in hardware)');
+        }
+        return codec;
+    }
+    /**
+     * GOP size for the video encoder that starts every fragment with a keyframe.
+     *
+     * 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 fps - Output frame rate
+     *
+     * @returns GOP size in frames
+     *
+     * @internal
+     */
+    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. Attaches a fresh packet age watchdog unless
+     * `maxPacketAge` is 0.
+     *
+     * @returns The configured muxer
+     *
+     * @internal
+     */
+    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);
+                }
+                return buffer.length;
+            },
+        };
+        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, 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) {
+        // 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.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);
+            // 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
+     * encoded straight into the fragmented container. Both streams share the ONE
+     * muxer, so neither may close it on its own: each source is encoded to packets
+     * and written concurrently (the muxer interleaves), and the muxer is closed
+     * once all streams have finished.
+     *
+     * @throws {Error} If the source has neither video nor audio frames
+     *
+     * @internal
+     */
+    async startFromFrames() {
+        const source = this.source;
+        if (!source.video && !source.audio) {
+            throw new Error('Frame source must provide video and/or audio frames');
+        }
+        // Video encoder - the encoder adopts width/height/pixelFormat/timeBase from
+        // the first composited frame.
+        if (source.video) {
+            if (this.options.hardware === 'auto') {
+                this.hardwareContext = HardwareContext.auto();
+            }
+            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 = (await findUsableHardwareEncoder(this.hardwareContext, 'h264', this.options.video.encoderOptions)) ?? this.softwareH264Encoder();
+            this.throwIfStopRequested();
+            let encoderOptions = {};
+            if (encoderCodec.name === FF_ENCODER_LIBX264) {
+                encoderOptions.preset = 'ultrafast';
+                encoderOptions.tune = 'zerolatency';
+            }
+            encoderOptions = { ...encoderOptions, ...this.options.video.encoderOptions };
+            let fps = this.options.video.fps ?? 30;
+            if (!isFinite(fps) || fps <= 0 || isNaN(fps)) {
+                fps = 30;
+            }
+            // Set the framerate explicitly - without a decoder the encoder would infer
+            // 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 = 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 });
+        }
+        if (source.audio) {
+            await this.createAudioEncoder();
+        }
+        this.throwIfStopRequested();
+        this.output = await this.createOutput();
+        this.throwIfStopRequested();
+        // eslint-disable-next-line prefer-const
+        let control;
+        const shouldStop = () => control?.isStopped() ?? false;
+        const tasks = [];
+        // 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);
+            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);
+            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 () => {
+            await this.output?.close();
+        });
+        control = new PipelineControlImpl(run, this.signal);
+        this.pipeline = control;
+        this.attachCompletion(this.pipeline.completion);
+    }
+    /**
+     * Stop streaming gracefully and clean up all resources.
+     *
+     * 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. Resolves even if the pipeline had failed; that
+     * error is reported through `onClose(error)`.
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     * await stream.start();
+     *
+     * // Stop after 10 seconds
+     * setTimeout(async () => await stream.stop(), 10000);
+     * ```
+     */
+    async stop() {
+        // Memoized: concurrent stop() calls share one teardown instead of
+        // double-closing native resources.
+        this.stopPromise ??= this.doStop().finally(() => {
+            this.stopPromise = undefined;
+        });
+        await this.stopPromise;
+    }
+    /**
+     * Perform the actual teardown (see {@link stop}).
+     *
+     * @internal
+     */
+    async doStop() {
+        // An in-flight start() must unwind before teardown - otherwise it would
+        // keep building the pipeline on top of freed resources and leave an
+        // orphaned transcode running forever. The flag makes doStart() bail at its
+        // next checkpoint, the abort unblocks a startup stuck in the input open.
+        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;
+        if (inflightStart) {
+            try {
+                await inflightStart;
+            }
+            catch {
+                // Aborted or failed startup - resources are torn down below either way.
+            }
+        }
+        try {
+            this.endFragments();
+            // A consumer awaiting the init segment must not hang forever.
+            this.rejectInitSegment(new Error('FMP4Stream stopped before init segment was produced'));
+            // Remove the abort listener so it does not accumulate across restarts.
+            if (this.abortHandler) {
+                this.signal?.removeEventListener('abort', this.abortHandler);
+                this.abortHandler = undefined;
+            }
+            // 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.
+            const pipeline = this.pipeline;
+            if (pipeline) {
+                if (!pipeline.isStopped()) {
+                    pipeline.stop();
+                }
+                try {
+                    await pipeline.completion;
+                }
+                catch {
+                    // Pipeline errored - proceed with teardown regardless.
+                }
+                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.
+            // 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;
+            // A codec that refuses to close (still busy) must not leave the input,
+            // an RTSP connection, open.
+            try {
+                this.videoDecoder?.close();
+                this.videoDecoder = undefined;
+                this.videoFilter?.close();
+                this.videoFilter = undefined;
+                this.videoEncoder?.close();
+                this.videoEncoder = undefined;
+                this.audioDecoder?.close();
+                this.audioDecoder = undefined;
+                this.audioFilter?.close();
+                this.audioFilter = undefined;
+                this.audioEncoder?.close();
+                this.audioEncoder = undefined;
+                this.hardwareContext?.dispose();
+                this.hardwareContext = undefined;
+            }
+            finally {
+                await this.input?.close();
+                this.input = undefined;
+            }
+            // Reset parser and init segment state so a restart parses a clean stream.
+            this.incompleteBoxBuffer = null;
+            this.pendingFragment = [];
+            this._initSegment = null;
+            this._initSegmentResolve = null;
+            this._initSegmentReject = null;
+            this._initSegmentPromise = null;
+            this._ftypData = null;
+            this._moovData = null;
+        }
+        finally {
+            this.stopRequested = false;
+        }
+    }
+    /**
+     * Async generator that yields media fragments (moof+mdat chunks).
+     *
+     * In box mode, yields only media fragments (chunks containing moof boxes),
+     * NOT the init segment. Use {@link initSegment} to get the ftyp+moov data.
+     *
+     * In chunk mode (boxMode disabled), yields every chunk as-is since
+     * box-level filtering is not possible without box parsing.
+     *
+     * The generator completes when the stream stops or the pipeline ends.
+     *
+     * Only a single consumer is supported: a second concurrent fragments() call
+     * would silently strand the first consumer, so it throws instead. The
+     * backlog is bounded by `maxQueuedFragments` - if the consumer falls behind
+     * a live source, the oldest fragments are dropped (see
+     * {@link droppedFragments}).
+     *
+     * @yields {FMP4Fragment} Media fragment with data buffer and box info
+     *
+     * @throws {Error} If another fragments() iterator is already active
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('rtsp://camera/stream', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   boxMode: true,
+     * });
+     *
+     * await stream.start();
+     * const init = await stream.initSegment;
+     *
+     * for await (const fragment of stream.fragments()) {
+     *   sendToClient(fragment.data);
+     * }
+     * ```
+     */
+    async *fragments() {
+        if (this.fragmentQueue) {
+            throw new Error('fragments() supports only a single consumer; the previous iterator is still active');
+        }
+        this.fragmentQueue = { queue: [], resolve: null, done: false };
+        try {
+            while (true) {
+                const result = await new Promise((resolve) => {
+                    if (this.fragmentQueue.queue.length > 0) {
+                        resolve({ value: this.fragmentQueue.queue.shift(), done: false });
+                        return;
+                    }
+                    if (this.fragmentQueue.done) {
+                        resolve({ value: undefined, done: true });
+                        return;
+                    }
+                    this.fragmentQueue.resolve = resolve;
+                });
+                if (result.done)
+                    break;
+                yield result.value;
+            }
+        }
+        finally {
+            this.fragmentQueue = null;
+        }
+    }
+    /**
+     * Run the streaming pipeline until completion or stopped.
+     *
+     * @internal
+     */
+    async runPipeline() {
+        if (!this.input || !this.output) {
+            return;
+        }
+        const hasVideo = this.input?.video() !== undefined;
+        const hasAudio = this.input?.audio() !== undefined;
+        const opts = this.signal ? { signal: this.signal } : undefined;
+        if (hasAudio && hasVideo) {
+            this.pipeline = pipeline(this.input, {
+                video: [this.videoDecoder, this.videoFilter, this.videoEncoder],
+                audio: [this.audioDecoder, this.audioFilter, this.audioEncoder],
+            }, this.output, opts);
+        }
+        else if (hasVideo) {
+            this.pipeline = pipeline(this.input, {
+                video: [this.videoDecoder, this.videoFilter, this.videoEncoder],
+            }, this.output, opts);
+        }
+        else if (hasAudio) {
+            this.pipeline = pipeline(this.input, {
+                audio: [this.audioDecoder, this.audioFilter, this.audioEncoder],
+            }, this.output, opts);
+        }
+        else {
+            throw new Error('No audio or video streams found in input');
+        }
+        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.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if H.264, H.265, or AV1 is in supported codecs
+     *
+     * @internal
+     */
+    isVideoCodecSupported(codecId) {
+        if (codecId === AV_CODEC_ID_H264 && (this.supportedCodecs.has(FMP4_CODECS.H264) || this.supportedCodecs.has('avc1'))) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_HEVC && (this.supportedCodecs.has(FMP4_CODECS.H265) || this.supportedCodecs.has('hvc1') || this.supportedCodecs.has('hev1'))) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_AV1 && (this.supportedCodecs.has(FMP4_CODECS.AV1) || this.supportedCodecs.has('av01'))) {
+            return true;
+        }
+        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.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if AAC, FLAC, or Opus is in supported codecs
+     *
+     * @internal
+     */
+    isAudioCodecSupported(codecId) {
+        if (codecId === AV_CODEC_ID_AAC && this.supportedCodecs.has(FMP4_CODECS.AAC)) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_FLAC && this.supportedCodecs.has(FMP4_CODECS.FLAC)) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_OPUS && this.supportedCodecs.has(FMP4_CODECS.OPUS)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Process buffer in box mode - buffers until complete boxes are available.
+     *
+     * The muxer splits writes at arbitrary positions, so a chunk may end
+     * anywhere - including inside a box header. Any trailing partial box
+     * (header or body) is buffered for the next chunk; the parser never
+     * loses bytes regardless of where the split falls.
+     *
+     * Emission is fragment-aligned: a `moof` is held back until its `mdat` has
+     * arrived, then both are emitted as ONE onData call. The avio buffer flushes
+     * at arbitrary points (a fragment larger than the buffer always splits), so
+     * without this a consumer would see a bare `moof` followed by a detached
+     * `mdat` - unplayable framing for fMP4 consumers.
+     * Non-fragment boxes (ftyp, moov, mfra, ...) are emitted as they complete.
+     *
+     * @param chunk - Incoming data chunk from FFmpeg
+     *
+     * @internal
+     */
+    processBoxMode(chunk) {
+        // If we have an incomplete box from previous chunk, append to it
+        if (this.incompleteBoxBuffer) {
+            chunk = Buffer.concat([this.incompleteBoxBuffer, chunk]);
+            this.incompleteBoxBuffer = null;
+        }
+        let offset = 0;
+        let immediate = [];
+        const flushImmediate = () => {
+            if (immediate.length > 0) {
+                this.emitBoxGroup(immediate);
+                immediate = [];
+            }
+        };
+        while (offset < chunk.length) {
+            const remaining = chunk.length - offset;
+            // Partial 32-bit header - buffer the tail for the next chunk. Dropping
+            // it would desynchronize the parser for the rest of the stream.
+            if (remaining < 8) {
+                this.incompleteBoxBuffer = chunk.subarray(offset);
+                break;
+            }
+            // Read box header
+            const size32 = chunk.readUInt32BE(offset);
+            let headerSize = 8;
+            let boxSize = size32;
+            if (size32 === 1) {
+                // 64-bit box: the actual size follows the type field as a 64-bit
+                // largesize (16-byte header total). movenc emits this for mdat > 4 GB.
+                if (remaining < 16) {
+                    this.incompleteBoxBuffer = chunk.subarray(offset);
+                    break;
+                }
+                headerSize = 16;
+                boxSize = Number(chunk.readBigUInt64BE(offset + 8));
+            }
+            // Safety check: invalid box size. size==0 ("box extends to end of file")
+            // cannot be framed in a live stream and any size below the header size
+            // 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
+            if (offset + boxSize > chunk.length) {
+                // Box body is incomplete - save the whole box for the next chunk
+                this.incompleteBoxBuffer = chunk.subarray(offset);
+                break;
+            }
+            const parsed = {
+                type: chunk.toString('ascii', offset + 4, offset + 8),
+                size: boxSize,
+                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) {
+                    // a moof without a following mdat never happens with movenc, emit
+                    // the stale fragment as-is rather than silently dropping bytes
+                    this.emitBoxGroup(this.pendingFragment);
+                    this.pendingFragment = [];
+                }
+                this.pendingFragment.push(parsed);
+            }
+            else if (this.pendingFragment.length > 0) {
+                this.pendingFragment.push(parsed);
+                if (parsed.type === 'mdat') {
+                    this.emitBoxGroup(this.pendingFragment);
+                    this.pendingFragment = [];
+                }
+            }
+            else {
+                immediate.push(parsed);
+            }
+            // Move to next box
+            offset += boxSize;
+        }
+        flushImmediate();
+    }
+    /**
+     * Emit a group of complete boxes as one onData call.
+     *
+     * Concatenates the raw box bytes, rebuilds the box list with offsets
+     * relative to the emitted buffer, tracks the init segment, and feeds the
+     * fragments() queue when the group is a media fragment.
+     *
+     * @param entries - Complete boxes in stream order
+     *
+     * @internal
+     */
+    emitBoxGroup(entries) {
+        const data = entries.length === 1 ? entries[0].raw : Buffer.concat(entries.map((e) => e.raw));
+        let position = 0;
+        const boxes = entries.map((entry) => {
+            const box = {
+                type: entry.type,
+                size: entry.size,
+                data: data.subarray(position + entry.headerSize, position + entry.size),
+                offset: position,
+            };
+            position += entry.size;
+            return box;
+        });
+        const info = { isComplete: true, boxes };
+        this.options.onData(data, info);
+        // Init segment tracking: collect ftyp and moov data
+        if (!this._initSegment) {
+            for (const box of boxes) {
+                if (box.type === 'ftyp' && !this._ftypData) {
+                    this._ftypData = data.subarray(box.offset, box.offset + box.size);
+                }
+                if (box.type === 'moov' && !this._moovData) {
+                    this._moovData = data.subarray(box.offset, box.offset + box.size);
+                }
+            }
+            if (this._ftypData && this._moovData) {
+                this._initSegment = Buffer.concat([this._ftypData, this._moovData]);
+                this._initSegmentResolve?.(this._initSegment);
+                this._initSegmentResolve = null;
+                this._initSegmentReject = null;
+            }
+        }
+        // fragments() generator gets only media fragments (moof+mdat)
+        if (boxes.some((b) => b.type === 'moof')) {
+            this.pushFragment(data, info);
+        }
+    }
+    /**
+     * Push a fragment to the fragment queue for the async generator.
+     *
+     * @param data - fMP4 data buffer
+     *
+     * @param info - Parsed box information
+     *
+     * @internal
+     */
+    pushFragment(data, info) {
+        if (!this.fragmentQueue)
+            return;
+        const fragment = { data, info };
+        if (this.fragmentQueue.resolve) {
+            this.fragmentQueue.resolve({ value: fragment, done: false });
+            this.fragmentQueue.resolve = null;
+        }
+        else {
+            this.fragmentQueue.queue.push(fragment);
+            // Live sources keep producing regardless of consumer speed - bound the
+            // backlog by dropping the oldest media fragments. The init segment never
+            // enters this queue in box mode (kept separately via initSegment).
+            while (this.fragmentQueue.queue.length > this.options.maxQueuedFragments) {
+                this.fragmentQueue.queue.shift();
+                this._droppedFragments++;
+            }
+        }
+    }
+    /**
+     * Reject a pending initSegment promise so consumers never hang.
+     *
+     * No-op when the promise was never requested or has already settled. The
+     * promise is marked as handled to avoid an unhandled rejection when no
+     * consumer is currently awaiting it.
+     *
+     * @param error - Rejection reason (pipeline error or stop-before-init)
+     *
+     * @internal
+     */
+    rejectInitSegment(error) {
+        if (!this._initSegmentReject)
+            return;
+        this._initSegmentPromise?.catch(() => { });
+        this._initSegmentReject(error);
+        this._initSegmentReject = null;
+        this._initSegmentResolve = null;
+    }
+    /**
+     * Signal the fragment queue that no more fragments will arrive.
+     *
+     * @internal
+     */
+    endFragments() {
+        if (!this.fragmentQueue)
+            return;
+        this.fragmentQueue.done = true;
+        if (this.fragmentQueue.resolve) {
+            this.fragmentQueue.resolve({ value: undefined, done: true });
+            this.fragmentQueue.resolve = null;
+        }
+    }
+}
+//# sourceMappingURL=fmp4-stream.js.map