node-av 6.1.1 → 6.2.0-beta.10

package/dist/api/fmp4-stream.js

@@ -1,7 +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_SAMPLE_FMT_FLTP, } from '../constants/constants.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_PIX_FMT_YUV420P, AV_SAMPLE_FMT_FLTP, } from '../constants/constants.js';
 import { FF_ENCODER_AAC, FF_ENCODER_LIBX264 } from '../constants/encoders.js';
 import { Codec } from '../lib/codec.js';
-import { avGetCodecString } from '../lib/utilities.js';
+import { Rational } from '../lib/rational.js';
+import { avGetCodecString, avGetPixFmtName } from '../lib/utilities.js';
 import { Decoder } from './decoder.js';
 import { Demuxer } from './demuxer.js';
 import { Encoder } from './encoder.js';
@@ -9,7 +10,8 @@ import { FilterPreset } from './filter-presets.js';
 import { FilterAPI } from './filter.js';
 import { HardwareContext } from './hardware.js';
 import { Muxer } from './muxer.js';
-import { pipeline } from './pipeline.js';
+import { consumeStreamInParallel, pipeline, PipelineControlImpl } from './pipeline.js';
+import { pickSupportedPixelFormat } from './utilities/codec-format.js';
 /**
  * Target codec strings for fMP4 streaming.
  */
@@ -68,6 +70,7 @@ export class FMP4Stream {
     inputUrl;
     inputOptions;
     input;
+    source;
     output;
     hardwareContext;
     videoDecoder;
@@ -77,12 +80,20 @@ export class FMP4Stream {
     audioFilter;
     audioEncoder;
     pipeline;
+    startPromise;
     signal;
     supportedCodecs;
     incompleteBoxBuffer = null;
+    pendingFragment = [];
+    abortHandler;
+    stopRequested = false;
+    stopPromise;
+    startAbort;
     fragmentQueue = null;
+    _droppedFragments = 0;
     _initSegment = null;
     _initSegmentResolve = null;
+    _initSegmentReject = null;
     _initSegmentPromise = null;
     _ftypData = null;
     _moovData = null;
@@ -99,18 +110,20 @@ export class FMP4Stream {
         if (typeof input === 'string') {
             this.inputUrl = input;
         }
-        else {
+        else if (input instanceof Demuxer) {
             this.inputUrl = null;
             this.input = input;
         }
+        else {
+            this.inputUrl = null;
+            this.source = input;
+        }
         const inputUrl = this.inputUrl ?? '';
+        const isLiveInput = /^(rtsp|rtmp|rtp|udp|srt|tcp|sctp):/i.test(inputUrl);
         this.inputOptions = {
             ...options.inputOptions,
             options: {
-                flags: 'low_delay',
-                fflags: 'nobuffer',
-                // analyzeduration: 0,
-                // probesize: 32,
+                ...(isLiveInput ? { flags: 'low_delay', fflags: 'nobuffer' } : {}),
                 timeout: 10000000,
                 rtsp_transport: inputUrl.toLowerCase().startsWith('rtsp') ? 'tcp' : undefined,
                 ...options.inputOptions?.options,
@@ -127,6 +140,7 @@ export class FMP4Stream {
                 fps: options.video?.fps,
                 width: options.video?.width,
                 height: options.video?.height,
+                bitrate: options.video?.bitrate,
                 encoderOptions: options.video?.encoderOptions ?? {},
             },
             audio: {
@@ -134,6 +148,7 @@ export class FMP4Stream {
             },
             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',
         };
         this.signal = options.signal;
@@ -182,6 +197,8 @@ export class FMP4Stream {
      *
      * 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
      */
@@ -189,16 +206,39 @@ export class FMP4Stream {
         if (!this.options.boxMode) {
             throw new Error('initSegment is only available in box mode');
         }
-        this._initSegmentPromise ??= new Promise((resolve) => {
+        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.
      *
@@ -240,6 +280,18 @@ export class FMP4Stream {
      * ```
      */
     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(FMP4_CODECS.AAC);
+            }
+            return parts.join(',');
+        }
         if (!this.input) {
             throw new Error('Input not opened. Call start() first to open the input.');
         }
@@ -331,18 +383,54 @@ export class FMP4Stream {
      * ```
      */
     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();
-        this.signal?.addEventListener('abort', () => this.stop(), { once: true });
+        // 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;
+        // 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');
             }
-            this.input = await Demuxer.open(this.inputUrl, this.inputOptions);
+            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
@@ -360,6 +448,7 @@ export class FMP4Stream {
                 hardware: this.hardwareContext,
                 exitOnError: false,
             });
+            this.throwIfStopRequested();
             // Determine if we need filters by comparing with current stream properties
             const currentWidth = videoStream.codecpar.width;
             const currentHeight = videoStream.codecpar.height;
@@ -367,6 +456,7 @@ export class FMP4Stream {
             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);
@@ -380,13 +470,28 @@ export class FMP4Stream {
                 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,
                 });
             }
-            const encoderCodec = this.hardwareContext?.getEncoderCodec('h264') ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
             let encoderOptions = {};
-            if (encoderCodec.name === FF_ENCODER_LIBX264 || encoderCodec.name === FF_ENCODER_LIBX264) {
+            if (encoderCodec.name === FF_ENCODER_LIBX264) {
                 encoderOptions.preset = 'ultrafast';
                 encoderOptions.tune = 'zerolatency';
             }
@@ -394,10 +499,19 @@ export class FMP4Stream {
                 ...encoderOptions,
                 ...this.options.video.encoderOptions,
             };
+            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,
                 options: encoderOptions,
+                configure: (ctx) => {
+                    ctx.gopSize = Math.max(1, Math.round(fpsForGop * fragSeconds));
+                    this.applyBitrate(ctx, bitrate);
+                },
             });
+            this.throwIfStopRequested();
         }
         // Check if audio needs transcoding
         const needsAudioTranscode = audioStream && !this.isAudioCodecSupported(audioStream.codecpar.codecId);
@@ -414,8 +528,65 @@ export class FMP4Stream {
                 filter: this.audioFilter,
                 options: this.options.audio.encoderOptions,
             });
+            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');
+        }
+    }
+    /**
+     * Cap the video bitrate on the encoder context.
+     *
+     * Applies a VBV rate cap (maxrate + a 1s buffer) WITHOUT setting a target
+     * bitrate, so the encoder keeps its default constant-quality mode but can
+     * never exceed the negotiated ceiling. Setting the bitrate as an ABR target
+     * instead would push a normally-lighter stream UP to fill it, overshooting on
+     * bursts - the opposite of what strict rate-capped consumers want.
+     * No-op when no bitrate was requested.
+     *
+     * @param ctx - Encoder codec context
+     *
+     * @param bitrate - Maximum bitrate in bits per second, or undefined
+     *
+     * @internal
+     */
+    applyBitrate(ctx, bitrate) {
+        if (!bitrate || bitrate <= 0) {
+            return;
+        }
+        ctx.rcMaxRate = BigInt(Math.round(bitrate));
+        // 1s buffer keeps per-fragment size close to the cap instead of allowing
+        // multi-second bursts over it.
+        ctx.rcBufferSize = Math.round(bitrate);
+    }
+    /**
+     * 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.
+     *
+     * @returns The configured muxer
+     *
+     * @internal
+     */
+    async createOutput() {
         const cb = {
             write: (buffer) => {
                 if (this.options.boxMode) {
@@ -431,7 +602,7 @@ export class FMP4Stream {
                 return buffer.length;
             },
         };
-        this.output = await Muxer.open(cb, {
+        return await Muxer.open(cb, {
             input: this.input,
             format: 'mp4',
             bufferSize: this.options.bufferSize,
@@ -441,17 +612,140 @@ export class FMP4Stream {
                 frag_duration: this.options.fragDuration,
             },
         });
-        this.runPipeline()
+    }
+    /**
+     * 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.
+     *
+     * @param completion - The pipeline completion promise
+     *
+     * @internal
+     */
+    attachCompletion(completion) {
+        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.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)));
+            // 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.
+            if (this.isDeliberateStop(error)) {
+                await this.stop().catch(() => { });
+                this.options.onClose?.();
+                return;
+            }
             await this.stop();
             this.options.onClose?.(error);
         });
     }
+    /**
+     * 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 = this.hardwareContext?.getEncoderCodec('h264') ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
+            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. 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;
+            const bitrate = this.options.video.bitrate;
+            this.videoEncoder = await Encoder.create(encoderCodec, {
+                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);
+                },
+            });
+        }
+        // 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,
+            });
+        }
+        this.throwIfStopRequested();
+        this.output = await this.createOutput();
+        this.throwIfStopRequested();
+        // eslint-disable-next-line prefer-const
+        let control;
+        const shouldStop = () => control?.isStopped() ?? false;
+        const tasks = [];
+        if (source.video && this.videoEncoder) {
+            const streamIndex = this.output.addStream(this.videoEncoder);
+            tasks.push(consumeStreamInParallel(this.videoEncoder.packets(source.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));
+        }
+        // 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.
      *
@@ -471,37 +765,94 @@ export class FMP4Stream {
      * ```
      */
     async stop() {
-        this.endFragments();
-        // Stop pipeline if running and wait for completion
-        if (this.pipeline && !this.pipeline.isStopped()) {
-            this.pipeline.stop();
-            await this.pipeline.completion;
-            this.pipeline = undefined;
-        }
-        // Close all resources
-        await this.input?.close();
-        this.input = undefined;
-        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;
-        await this.output?.close();
-        this.output = undefined;
-        this._initSegment = null;
-        this._initSegmentResolve = null;
-        this._initSegmentPromise = null;
-        this._ftypData = null;
-        this._moovData = null;
+        // 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;
+        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.
+            if (this.pipeline && !this.pipeline.isStopped()) {
+                this.pipeline.stop();
+                try {
+                    await this.pipeline.completion;
+                }
+                catch {
+                    // Pipeline errored - proceed with teardown regardless.
+                }
+                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();
+            this.output = undefined;
+            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;
+            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).
@@ -514,8 +865,16 @@ export class FMP4Stream {
      *
      * 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', {
@@ -532,6 +891,9 @@ export class FMP4Stream {
      * ```
      */
     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) {
@@ -634,6 +996,18 @@ export class FMP4Stream {
     /**
      * 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
@@ -645,60 +1019,126 @@ export class FMP4Stream {
             this.incompleteBoxBuffer = null;
         }
         let offset = 0;
-        const boxes = [];
-        while (offset + 8 <= chunk.length) {
+        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 boxSize = chunk.readUInt32BE(offset);
-            const boxType = chunk.toString('ascii', offset + 4, offset + 8);
+            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) {
+                break;
+            }
             // Check if we have the complete box
             if (offset + boxSize > chunk.length) {
-                // Box is incomplete - save for next chunk
+                // Box body is incomplete - save the whole box for the next chunk
                 this.incompleteBoxBuffer = chunk.subarray(offset);
                 break;
             }
-            // We have the complete box - parse it
-            const box = {
-                type: boxType,
+            const parsed = {
+                type: chunk.toString('ascii', offset + 4, offset + 8),
                 size: boxSize,
-                data: chunk.subarray(offset + 8, offset + boxSize),
-                offset: offset,
+                headerSize,
+                raw: chunk.subarray(offset, offset + boxSize),
             };
-            boxes.push(box);
+            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;
-            // Safety check: invalid box size
-            if (boxSize < 8) {
-                break;
-            }
         }
-        // If we have complete boxes, send them to the callback
-        if (boxes.length > 0) {
-            const boxData = chunk.subarray(0, offset);
-            const info = { isComplete: true, boxes };
-            // onData callback gets everything
-            this.options.onData(boxData, 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 = chunk.subarray(box.offset, box.offset + box.size);
-                    }
-                    if (box.type === 'moov' && !this._moovData) {
-                        this._moovData = chunk.subarray(box.offset, box.offset + box.size);
-                    }
+        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 (this._ftypData && this._moovData) {
-                    this._initSegment = Buffer.concat([this._ftypData, this._moovData]);
-                    this._initSegmentResolve?.(this._initSegment);
-                    this._initSegmentResolve = null;
+                if (box.type === 'moov' && !this._moovData) {
+                    this._moovData = data.subarray(box.offset, box.offset + box.size);
                 }
             }
-            // fragments() generator gets only media fragments (moof+mdat)
-            const isMediaFragment = boxes.some((b) => b.type === 'moof');
-            if (isMediaFragment) {
-                this.pushFragment(boxData, info);
+            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.
@@ -719,8 +1159,34 @@ export class FMP4Stream {
         }
         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.
      *