node-av 6.2.0-beta.3 → 6.2.0-beta.30

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;
@@ -54,6 +54,12 @@ export interface FMP4StreamOptions {
     /**
      * Callback invoked when the stream is closed or encounters an error.
      *
+     * Called once per started session. On an error the stream has already been
+     * stopped and its resources (including the input connection) released.
+     * Output the muxer still held at the error is discarded, so no `onData` call
+     * follows the failure. Exceptions thrown by the callback are logged and do
+     * not propagate.
+     *
      * @param error - Optional error if stream closed due to an error
      */
     onClose?: (error?: Error) => void;
@@ -66,12 +72,56 @@ 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.
+     * Transcoded video gets a GOP of the fragment duration from 0.5 s on, so
+     * every fragment starts with a keyframe; below that, and with 0, it gets a
+     * 2 s GOP.
      *
      * @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 +146,11 @@ export interface FMP4StreamOptions {
         fps?: number;
         width?: number;
         height?: number;
+        bitrate?: number;
+        /**
+         * FourCC sample entry tag for the HEVC video stream, e.g. `hvc1`. Only applied to HEVC output.
+         */
+        tag?: string;
         encoderOptions?: EncoderOptions['options'];
     };
     /**
@@ -112,7 +167,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
@@ -124,6 +182,60 @@ export interface FMP4StreamOptions {
      * @default '+frag_keyframe+separate_moof+default_base_moof+empty_moov'
      */
     movFlags?: string;
+    /**
+     * Backward DTS jump in seconds above which the stream ends with an error.
+     *
+     * A live source that restarts its clock (a camera reboot behind a restreamer)
+     * would otherwise leave every following packet clamped to one tick past the
+     * previous one, so fragments carry no media for as long as the jump. The stream
+     * instead stops and reports the error through `onClose(error)`, and the owner
+     * can restart it on a fresh timeline. Smaller jumps are clamped. `0` disables
+     * the check. Same semantics as the `Muxer` option of the same name.
+     *
+     * @default 10
+     */
+    dtsBackwardThreshold?: number;
+    /**
+     * Forward DTS jump in seconds, beyond the real time that passed, above which
+     * the stream ends with an error.
+     *
+     * A live source that restarts its clock (a camera reboot behind a
+     * restreamer) can continue with timestamps far ahead of the time that
+     * passed. Muxing that would leave a sample spanning the jump, or, when the
+     * timeline later returns, a stream clamped behind it. The stream instead
+     * stops and reports the error through `onClose(error)`, and the owner can
+     * restart it on a fresh timeline. Gaps in the source come with a matching
+     * wait and pass. Only meaningful for inputs read in real time, so it is off
+     * for files, a pre-opened Demuxer and frame sources unless set; pass it for
+     * live inputs read over HTTP (HLS, HTTP-FLV) as well. Same semantics as the
+     * `Muxer` option of the same name; `0` disables the check.
+     *
+     * @default 10 for rtsp, rtsps, rtmp (and rtmps, rtmpt, rtmpe, rtmpte, rtmpts), rtp, srtp, udp, srt, tcp, tls and sctp URLs, 0 otherwise
+     */
+    dtsForwardThreshold?: number;
+    /**
+     * Longest time in seconds a packet may wait inside the muxer before it is
+     * emitted in a fragment.
+     *
+     * The mp4 muxer holds packets back to interleave the streams by timestamp.
+     * When a stream's timestamps stop advancing or run far ahead of a silent
+     * stream (a camera restarting its clock behind a restreamer, missing
+     * timestamps), packets can pile up without ever being emitted while memory
+     * grows. The age is measured per stream in real time while the input
+     * delivers packets and is independent of the timestamps; once the oldest
+     * pending packet of any stream is older than this, the stream stops and
+     * reports the error through `onClose(error)`. A pause of the whole input
+     * counts at most 2 s, so a source that goes quiet and resumes does not end
+     * the session. Healthy sessions stay below the default: up to the fragment
+     * duration (the GOP length with `fragDuration: 0`) plus about 10 s of
+     * interleaving delay while a stream is silent. Inputs read faster than real
+     * time can pile up correspondingly more media before it fires, inputs that
+     * deliver packets more than 2 s apart take correspondingly longer. `0`
+     * disables the check.
+     *
+     * @default 60
+     */
+    maxPacketAge?: number;
     /**
      * AbortSignal for cancellation.
      *
@@ -132,6 +244,19 @@ export interface FMP4StreamOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * Video description of the muxed fMP4 output.
+ */
+export interface FMP4VideoInfo {
+    /** Output codec family. */
+    codec: 'h264' | 'hevc' | 'av1' | 'unknown';
+    /** RFC 6381 codec string of the output (e.g. `hvc1.1.6.L120.B0`). */
+    codecString: string;
+    width: number;
+    height: number;
+    /** Frames per second, 0 when unknown. */
+    fps: number;
+}
 /**
  * Target codec strings for fMP4 streaming.
  */
@@ -147,7 +272,8 @@ export declare const FMP4_CODECS: {
  * High-level fMP4 streaming with automatic codec detection and transcoding.
  *
  * Provides fragmented MP4 streaming for clients.
- * Automatically transcodes video to H.264 and audio to AAC if not supported by client.
+ * Automatically transcodes video to H.264 and audio to AAC (Opus when the client
+ * lists Opus but not AAC) if not supported by client.
  * Client sends supported codecs, server transcodes accordingly.
  * Essential component for building adaptive streaming servers.
  *
@@ -204,9 +330,19 @@ export declare class FMP4Stream {
     private signal?;
     private supportedCodecs;
     private incompleteBoxBuffer;
+    private pendingFragment;
+    private abortHandler?;
+    private stopRequested;
+    private discardOutput;
+    private stopPromise?;
+    private startAbort?;
+    private stopSignal;
     private fragmentQueue;
+    private packetAgeWatchdog?;
+    private _droppedFragments;
     private _initSegment;
     private _initSegmentResolve;
+    private _initSegmentReject;
     private _initSegmentPromise;
     private _ftypData;
     private _moovData;
@@ -217,6 +353,8 @@ export declare class FMP4Stream {
      *
      * Use {@link create} factory method
      *
+     * @throws {RangeError} If dtsBackwardThreshold, dtsForwardThreshold or maxPacketAge is not a finite number >= 0
+     *
      * @internal
      */
     private constructor();
@@ -232,6 +370,8 @@ export declare class FMP4Stream {
      *
      * @returns Configured fMP4 stream instance
      *
+     * @throws {RangeError} If dtsBackwardThreshold, dtsForwardThreshold or maxPacketAge is not a finite number >= 0
+     *
      * @example
      * ```typescript
      * // Stream from file with codec negotiation
@@ -257,10 +397,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.
      *
@@ -300,13 +462,29 @@ export declare class FMP4Stream {
      * ```
      */
     getCodecString(): string;
+    /**
+     * 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(): FMP4VideoInfo | undefined;
     /**
      * Start streaming media to fMP4 chunks.
      *
      * Begins the media processing pipeline, reading packets from input,
      * transcoding based on supported codecs, and generating fMP4 chunks.
      * Video transcodes to H.264 if H.264/H.265 not supported.
-     * Audio transcodes to AAC if AAC/FLAC/Opus not supported.
+     * Audio transcodes to AAC (Opus when only Opus is listed) if the input codec is not supported.
      * This method returns immediately after starting the pipeline.
      *
      * @returns Promise that resolves when pipeline is started
@@ -334,11 +512,57 @@ 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;
+    /**
+     * 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
+     */
+    private gopSize;
     /**
      * Create the fMP4 output muxer with the fragment-emitting write callback.
      *
      * Uses `this.input` when present (demuxer path) and no input for the
-     * frame-source path.
+     * frame-source path. Attaches a fresh packet age watchdog unless
+     * `maxPacketAge` is 0.
      *
      * @returns The configured muxer
      *
@@ -349,13 +573,36 @@ export declare class FMP4Stream {
      * Wire the pipeline completion to the fragment/close callbacks.
      *
      * On success ends the fragment iterator and invokes `onClose()`; on error
-     * stops the stream and invokes `onClose(error)`. Runs in the background.
+     * stops the stream, discarding the output the muxer still holds, and invokes
+     * `onClose(error)`. Either way `onClose` runs exactly once and the detached
+     * chain never rejects. Runs in the background.
      *
      * @param completion - The pipeline completion promise
      *
      * @internal
      */
     private attachCompletion;
+    /**
+     * 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
+     */
+    private emitClose;
+    /**
+     * 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
@@ -374,7 +621,8 @@ export declare class FMP4Stream {
      *
      * Stops the pipeline, closes output, and releases all FFmpeg resources.
      * Safe to call multiple times. After stopping, you can call start() again
-     * to restart the stream.
+     * to restart the stream. Resolves even if the pipeline had failed; that
+     * error is reported through `onClose(error)`.
      *
      * @example
      * ```typescript
@@ -388,6 +636,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 +653,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', {
@@ -433,6 +695,27 @@ export declare class FMP4Stream {
      * @internal
      */
     private isVideoCodecSupported;
+    /**
+     * Codec that unsupported audio is transcoded to.
+     *
+     * @returns Opus when the client lists Opus but not AAC, otherwise AAC
+     *
+     * @internal
+     */
+    private audioTranscodeTarget;
+    /**
+     * 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
+     */
+    private createAudioEncoder;
     /**
      * Check if audio codec is supported.
      *
@@ -446,11 +729,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 +768,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.
      *