node-av 6.2.0-beta.9 → 7.0.0-beta.1

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

@@ -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;
@@ -72,6 +78,9 @@ export interface FMP4StreamOptions {
      * 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
      *
@@ -138,6 +147,14 @@ export interface FMP4StreamOptions {
         width?: number;
         height?: number;
         bitrate?: number;
+        /**
+         * Transcode to H.264 even when the source codec is one of `supportedCodecs`, so `width`, `height`, `fps` and `bitrate` apply.
+         */
+        transcode?: boolean;
+        /**
+         * FourCC sample entry tag for the HEVC video stream, e.g. `hvc1`. Only applied to HEVC output.
+         */
+        tag?: string;
         encoderOptions?: EncoderOptions['options'];
     };
     /**
@@ -169,6 +186,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.
      *
@@ -177,6 +248,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.
  */
@@ -192,7 +276,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.
  *
@@ -234,6 +319,7 @@ export declare class FMP4Stream {
     private options;
     private inputUrl;
     private inputOptions;
+    private liveInput;
     private input?;
     private source?;
     private output?;
@@ -252,9 +338,12 @@ export declare class FMP4Stream {
     private pendingFragment;
     private abortHandler?;
     private stopRequested;
+    private discardOutput;
     private stopPromise?;
     private startAbort?;
+    private stopSignal;
     private fragmentQueue;
+    private packetAgeWatchdog?;
     private _droppedFragments;
     private _initSegment;
     private _initSegmentResolve;
@@ -269,6 +358,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();
@@ -284,6 +375,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
@@ -374,13 +467,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
@@ -421,27 +530,27 @@ export declare class FMP4Stream {
      */
     private throwIfStopRequested;
     /**
-     * Cap the video bitrate on the encoder context.
+     * GOP size for the video encoder that starts every fragment with a keyframe.
      *
-     * Applies a VBV rate cap (maxrate + a 1s buffer) WITHOUT setting a target
-     * bitrate, so the encoder keeps its default constant-quality mode but can
-     * never exceed the negotiated ceiling. Setting the bitrate as an ABR target
-     * instead would push a normally-lighter stream UP to fill it, overshooting on
-     * bursts - the opposite of what strict rate-capped consumers want.
-     * No-op when no bitrate was requested.
+     * frag_duration flushes a fragment once it is that long, mid-GOP on a
+     * P-frame unless the GOP has the same length, and strict consumers reject
+     * such fragments. Shorter fragments (the 1 µs default flushes after every
+     * frame) are not matched: a GOP of a few frames multiplies the bitrate, so
+     * below MIN_FRAGMENT_GOP the GOP is 2 s, as with a fragDuration of 0.
      *
-     * @param ctx - Encoder codec context
+     * @param fps - Output frame rate
      *
-     * @param bitrate - Maximum bitrate in bits per second, or undefined
+     * @returns GOP size in frames
      *
      * @internal
      */
-    private applyBitrate;
+    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
      *
@@ -452,13 +561,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
@@ -477,7 +609,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
@@ -540,6 +673,16 @@ export declare class FMP4Stream {
      * @internal
      */
     private runPipeline;
+    /**
+     * 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
+     */
+    private transcodesVideo;
     /**
      * Check if video codec is supported.
      *
@@ -550,6 +693,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.
      *