node-av 6.1.1 → 6.2.0-beta.10

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

@@ -3,6 +3,7 @@ import { Demuxer } from './demuxer.js';
 import type { AVCodecID, AVHWDeviceType, AVSampleFormat, FFAudioEncoder, FFHWDeviceType, FFVideoEncoder } from '../constants/index.js';
 import type { DemuxerOptions } from './demuxer.js';
 import type { EncoderOptions } from './encoder.js';
+import type { MediaFrameSource } from './types.js';
 /**
  * Options for configuring RTP streaming.
  */
@@ -66,6 +67,7 @@ export interface RTPStreamOptions {
         fps?: number;
         width?: number;
         height?: number;
+        bitrate?: number;
         encoderOptions?: EncoderOptions['options'];
     };
     /**
@@ -88,6 +90,16 @@ export interface RTPStreamOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * Check whether a streaming-class input is a frame source (not a URL or Demuxer).
+ *
+ * @param input - The input passed to `create()`
+ *
+ * @returns True if `input` is a {@link MediaFrameSource}
+ *
+ * @internal
+ */
+export declare function isMediaFrameSource(input: string | Demuxer | MediaFrameSource): input is MediaFrameSource;
 /**
  * Generic RTP streaming with automatic codec detection and transcoding.
  *
@@ -125,6 +137,7 @@ export declare class RTPStream {
     private inputUrl;
     private inputOptions;
     private input?;
+    private source?;
     private videoOutput?;
     private audioOutput?;
     private hardwareContext?;
@@ -135,9 +148,15 @@ export declare class RTPStream {
     private audioFilter?;
     private audioEncoder?;
     private pipeline?;
+    private startPromise?;
     private signal?;
     private supportedVideoCodecs;
     private supportedAudioCodecs;
+    private videoKeyframeRequested;
+    private abortHandler?;
+    private stopRequested;
+    private stopPromise?;
+    private startAbort?;
     /**
      * @param input - Media input URL or pre-opened Demuxer
      *
@@ -188,7 +207,7 @@ export declare class RTPStream {
      * });
      * ```
      */
-    static create(input: string | Demuxer, options?: RTPStreamOptions): RTPStream;
+    static create(input: string | Demuxer | MediaFrameSource, options?: RTPStreamOptions): RTPStream;
     /**
      * Check if the stream is active.
      *
@@ -214,6 +233,37 @@ export declare class RTPStream {
      * ```
      */
     getInput(): Demuxer | undefined;
+    /**
+     * Request that the next encoded video frame is a keyframe.
+     *
+     * Used to answer receiver feedback (e.g. a WebRTC PLI) so a receiver that
+     * missed the stream start or lost packets can resync without waiting for the
+     * next scheduled GOP keyframe. Currently effective for frame-source inputs
+     * ({@link MediaFrameSource}); for demuxer inputs the encoder's regular GOP
+     * cadence applies.
+     *
+     * @example
+     * ```typescript
+     * transceiver.sender.onPictureLossIndication.subscribe(() => {
+     *   stream.requestVideoKeyframe();
+     * });
+     * ```
+     */
+    requestVideoKeyframe(): void;
+    /**
+     * Pass video frames through, forcing a keyframe when one was requested.
+     *
+     * Sets `pictType = I` on the next frame after {@link requestVideoKeyframe};
+     * combined with the encoder's `forced-idr` option this produces an IDR the
+     * receiver can resync on.
+     *
+     * @param src - The user-provided video frame source
+     *
+     * @yields {Frame | null} The unchanged frames (with pictType forced when requested)
+     *
+     * @internal
+     */
+    private wrapVideoSource;
     /**
      * Start streaming media to RTP packets.
      *
@@ -242,6 +292,95 @@ export declare class RTPStream {
      * ```
      */
     start(): Promise<void>;
+    /**
+     * Perform the actual startup (see {@link start}).
+     *
+     * @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.
+     *
+     * Sets the target bitrate together with a VBV cap (maxrate + a 1s buffer).
+     * Encoder.create() always seeds a default target bitrate (1 Mbps for video),
+     * so the target MUST be lowered along with the cap.
+     *
+     * @param ctx - Encoder codec context
+     *
+     * @param bitrate - Maximum bitrate in bits per second, or undefined
+     *
+     * @internal
+     */
+    private applyBitrate;
+    /**
+     * Wire the pipeline completion to the onClose/error callbacks.
+     *
+     * On success invokes `onClose()`; on error stops the stream and invokes
+     * `onClose(error)`. Runs in the background (not awaited).
+     *
+     * @param completion - The pipeline completion promise
+     *
+     * @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 RTP outputs for a pre-composited frame source and start
+     * encoding. No demuxer or decoder is involved - the provided frames are encoded
+     * straight to RTP. Video and audio (whichever are present) run as separate
+     * pipelines combined behind a single control.
+     *
+     * @throws {Error} If the source has neither video nor audio frames
+     *
+     * @internal
+     */
+    private startFromFrames;
+    /**
+     * Create the RTP video output muxer.
+     *
+     * Rewrites RTP sequence numbers (continuous) and rebases the PTS-derived
+     * timestamps (90 kHz) onto a random initial value in the write callback, then
+     * forwards each packet to `onVideoPacket`. Uses `this.input` when present
+     * (demuxer path) and no input for the frame-source path.
+     *
+     * @returns The configured video muxer
+     *
+     * @internal
+     */
+    private createVideoOutput;
+    /**
+     * Create the RTP audio output muxer.
+     *
+     * Rewrites RTP sequence numbers (continuous) in the write callback and forwards
+     * each packet to `onAudioPacket`. Uses `this.input` when present (demuxer path)
+     * and no input for the frame-source path.
+     *
+     * @returns The configured audio muxer
+     *
+     * @internal
+     */
+    private createAudioOutput;
     /**
      * Run the streaming pipeline until completion or stopped.
      *
@@ -267,6 +406,12 @@ export declare class RTPStream {
      * ```
      */
     stop(): Promise<void>;
+    /**
+     * Perform the actual teardown (see {@link stop}).
+     *
+     * @internal
+     */
+    private doStop;
     /**
      * Check if the given audio codec is supported.
      *