node-av 6.2.0-beta.2 → 6.2.0-beta.21

package/dist/api/fmp4-stream.d.ts

@@ -10,9 +10,9 @@ export type MP4BoxType = 'ftyp' | 'styp' | 'moov' | 'moof' | 'mdat' | 'free' | '
 export interface MP4Box {
     /** Four-character code identifying the box type (e.g., 'ftyp', 'moov', 'moof') */
     type: MP4BoxType;
-    /** Total size of the box in bytes (including 8-byte header) */
+    /** Total size of the box in bytes (including the 8-byte header, or 16-byte for 64-bit boxes) */
     size: number;
-    /** Box payload data (excluding the 8-byte header) */
+    /** Box payload data (excluding the 8-byte header, or 16-byte for 64-bit boxes) */
     data: Buffer;
     /** Offset of this box in the original buffer */
     offset: number;
@@ -66,12 +66,53 @@ export interface FMP4StreamOptions {
     supportedCodecs?: string;
     /**
      * Fragment duration in microseconds.
+     *
+     * Passed to the mp4 muxer as `frag_duration`, which creates a new fragment
+     * whenever the current one exceeds this duration (in addition to any cuts
+     * requested via movFlags such as `frag_keyframe`).
      * Smaller values reduce latency but increase overhead.
      * Set to 1 to send data as soon as possible.
      *
      * @default 1
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   fragDuration: 2_000_000, // 2 seconds in microseconds
+     * });
+     * ```
      */
     fragDuration?: number;
+    /**
+     * Maximum number of media fragments buffered for a {@link FMP4Stream.fragments}
+     * consumer before the oldest are dropped.
+     *
+     * Live sources (RTSP cameras) produce fragments at a fixed rate regardless of
+     * consumer speed. Without a bound, a slow or stalled consumer would grow the
+     * queue until the process runs out of memory. When the backlog exceeds this
+     * limit, the oldest media fragments are dropped (never the init segment,
+     * which is kept separately via {@link FMP4Stream.initSegment}) and
+     * {@link FMP4Stream.droppedFragments} is incremented.
+     *
+     * @default 16
+     *
+     * @example
+     * ```typescript
+     * const stream = FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   boxMode: true,
+     *   maxQueuedFragments: 8,
+     * });
+     *
+     * await stream.start();
+     * for await (const fragment of stream.fragments()) {
+     *   await sendToClient(fragment.data); // Slow consumer - oldest fragments dropped
+     * }
+     * console.log(`Dropped ${stream.droppedFragments} fragments`);
+     * ```
+     */
+    maxQueuedFragments?: number;
     /**
      * Hardware acceleration configuration for video transcoding.
      *
@@ -96,6 +137,7 @@ export interface FMP4StreamOptions {
         fps?: number;
         width?: number;
         height?: number;
+        bitrate?: number;
         encoderOptions?: EncoderOptions['options'];
     };
     /**
@@ -112,7 +154,10 @@ export interface FMP4StreamOptions {
     bufferSize?: number;
     /**
      * Enable box mode - buffers data until complete MP4 boxes are available.
-     * When true, onData receives complete boxes with parsed box information.
+     * When true, onData receives complete boxes with parsed box information,
+     * and media fragments are emitted fragment-aligned: a callback that contains
+     * a `moof` always contains its `mdat` too, regardless of how the muxer's
+     * I/O buffer split the write (large fragments arrive in several chunks).
      * When false, onData receives raw chunks as they arrive from FFmpeg.
      *
      * @default false
@@ -204,9 +249,17 @@ export declare class FMP4Stream {
     private signal?;
     private supportedCodecs;
     private incompleteBoxBuffer;
+    private pendingFragment;
+    private abortHandler?;
+    private stopRequested;
+    private stopPromise?;
+    private startAbort?;
+    private stopSignal;
     private fragmentQueue;
+    private _droppedFragments;
     private _initSegment;
     private _initSegmentResolve;
+    private _initSegmentReject;
     private _initSegmentPromise;
     private _ftypData;
     private _moovData;
@@ -257,10 +310,32 @@ export declare 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
      */
     get initSegment(): Promise<Buffer>;
+    /**
+     * 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(): number;
     /**
      * Get the demuxer instance.
      *
@@ -334,6 +409,35 @@ export declare class FMP4Stream {
      * @internal
      */
     private doStart;
+    /**
+     * 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
+     */
+    private throwIfStopRequested;
+    /**
+     * 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
+     */
+    private applyBitrate;
     /**
      * Create the fMP4 output muxer with the fragment-emitting write callback.
      *
@@ -356,6 +460,16 @@ export declare class FMP4Stream {
      * @internal
      */
     private attachCompletion;
+    /**
+     * 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
+     */
+    private isDeliberateStop;
     /**
      * 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
@@ -388,6 +502,12 @@ export declare class FMP4Stream {
      * ```
      */
     stop(): Promise<void>;
+    /**
+     * Perform the actual teardown (see {@link stop}).
+     *
+     * @internal
+     */
+    private doStop;
     /**
      * Async generator that yields media fragments (moof+mdat chunks).
      *
@@ -399,8 +519,16 @@ export declare 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', {
@@ -446,11 +574,35 @@ export declare 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
      */
     private processBoxMode;
+    /**
+     * 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
+     */
+    private emitBoxGroup;
     /**
      * Push a fragment to the fragment queue for the async generator.
      *
@@ -461,6 +613,18 @@ export declare class FMP4Stream {
      * @internal
      */
     private pushFragment;
+    /**
+     * 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
+     */
+    private rejectInitSegment;
     /**
      * Signal the fragment queue that no more fragments will arrive.
      *