node-av-lgpl 0.0.0 → 7.1.0-beta.1

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

@@ -0,0 +1,497 @@
+import { RtpPacket } from 'werift';
+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.
+ */
+export interface RTPStreamOptions {
+    /**
+     * Callback invoked for each video RTP packet.
+     * Use this to send packets to your RTP implementation.
+     *
+     * @param packet - Serialized RTP packet ready for transmission
+     */
+    onVideoPacket?: (packet: RtpPacket) => void;
+    /**
+     * Callback invoked for each audio RTP packet.
+     * Use this to send packets to your RTP implementation.
+     *
+     * @param packet - Serialized RTP packet ready for transmission
+     */
+    onAudioPacket?: (packet: RtpPacket) => void;
+    /**
+     * 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.
+     * 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;
+    /**
+     * Supported video codec IDs for transcoding decisions.
+     * If not provided or empty, all video codecs are supported (passthrough only, no transcoding).
+     * If provided, only the specified codecs are supported and transcoding will be performed if needed.
+     */
+    supportedVideoCodecs?: (AVCodecID | FFVideoEncoder)[];
+    /**
+     * Supported audio codec IDs for transcoding decisions.
+     * If not provided or empty, all audio codecs are supported (passthrough only, no transcoding).
+     * If provided, only the specified codecs are supported and transcoding will be performed if needed.
+     */
+    supportedAudioCodecs?: (AVCodecID | FFAudioEncoder)[];
+    /**
+     * Hardware acceleration configuration.
+     *
+     * - `'auto'` - Automatically detect and use available hardware acceleration
+     * - Object with deviceType - Manually specify hardware acceleration type
+     *
+     * @default { deviceType: AV_HWDEVICE_TYPE_NONE }
+     */
+    hardware?: 'auto' | {
+        deviceType: AVHWDeviceType | FFHWDeviceType;
+        device?: string;
+        options?: Record<string, string>;
+    };
+    /**
+     * Input media options passed to Demuxer.
+     */
+    inputOptions?: DemuxerOptions;
+    /**
+     * Video stream configuration.
+     */
+    video?: {
+        ssrc?: number;
+        payloadType?: number;
+        mtu?: number;
+        fps?: number;
+        width?: number;
+        height?: number;
+        bitrate?: number;
+        dumpExtra?: boolean;
+        /** Transcode even when the source codec is one of `supportedVideoCodecs`. */
+        transcode?: boolean;
+        encoderOptions?: EncoderOptions['options'];
+    };
+    /**
+     * Audio stream configuration.
+     */
+    audio?: {
+        ssrc?: number;
+        payloadType?: number;
+        mtu?: number;
+        sampleFormat?: AVSampleFormat;
+        sampleRate?: number;
+        channels?: number;
+        /** Transcode even when the source codec is one of `supportedAudioCodecs`. */
+        transcode?: boolean;
+        encoderOptions?: EncoderOptions['options'];
+    };
+    /**
+     * AbortSignal for cancellation.
+     *
+     * When aborted, the stream stops gracefully, equivalent to calling stop().
+     * If already aborted when start() is called, throws AbortError.
+     */
+    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.
+ *
+ * Provides library-agnostic RTP streaming for various applications.
+ * Automatically detects input codecs and transcodes non-compatible formats.
+ * Supports hardware acceleration for video transcoding.
+ * Essential component for building RTP streaming servers.
+ *
+ * @example
+ * ```typescript
+ * import { RTPStream } from 'node-av/api';
+ *
+ * // Create stream with RTP packet callbacks
+ * const stream = RTPStream.create('rtsp://camera.local/stream', {
+ *   mtu: 1200,
+ *   hardware: 'auto',
+ *   onVideoPacket: (rtp) => {
+ *     // Send RTP packet
+ *     sendRtpPacket(rtp);
+ *   },
+ *   onAudioPacket: (rtp) => {
+ *     sendRtpPacket(rtp);
+ *   }
+ * });
+ *
+ * // Start streaming
+ * await stream.start();
+ * ```
+ *
+ * @see {@link Demuxer} For input media handling
+ * @see {@link HardwareContext} For GPU acceleration
+ */
+export declare class RTPStream {
+    private options;
+    private inputUrl;
+    private inputOptions;
+    private input?;
+    private source?;
+    private videoOutput?;
+    private audioOutput?;
+    private hardwareContext?;
+    private videoDecoder?;
+    private videoFilter?;
+    private videoEncoder?;
+    private videoBitstreamFilter?;
+    private audioDecoder?;
+    private audioFilter?;
+    private audioEncoder?;
+    private pipeline?;
+    private startPromise?;
+    private signal?;
+    private supportedVideoCodecs;
+    private supportedAudioCodecs;
+    private abortHandler?;
+    private stopRequested;
+    private stopPromise?;
+    private startAbort?;
+    private stopSignal;
+    /**
+     * @param input - Media input URL or pre-opened Demuxer
+     *
+     * @param options - Stream configuration options
+     *
+     * Use {@link create} factory method
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create an RTP stream from a media source.
+     *
+     * Configures the stream with input URL and options. The input is not opened
+     * until start() is called, allowing the stream to be reused after stop().
+     *
+     * @param input - Media source URL (RTSP, file path, HTTP, etc.) or a pre-opened {@link Demuxer}
+     *
+     * @param options - Stream configuration options
+     *
+     * @returns Configured RTP stream instance
+     *
+     * @example
+     * ```typescript
+     * // Stream from RTSP camera
+     * const stream = RTPStream.create('rtsp://camera.local/stream', {
+     *   mtu: 1200,
+     *   onVideoPacket: (rtp) => sendPacket(rtp),
+     *   onAudioPacket: (rtp) => sendPacket(rtp)
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream file with auto hardware acceleration
+     * const stream = RTPStream.create('video.mp4', {
+     *   hardware: 'auto'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream from a pre-opened Demuxer (e.g. Device.openScreen())
+     * const demuxer = await Device.openScreen({ frameRate: 30 });
+     * const stream = RTPStream.create(demuxer, {
+     *   hardware: 'auto',
+     *   onVideoPacket: (rtp) => sendPacket(rtp)
+     * });
+     * ```
+     */
+    static create(input: string | Demuxer | MediaFrameSource, options?: RTPStreamOptions): RTPStream;
+    /**
+     * Check if the stream is active.
+     *
+     * Stays true while a requested stop is still unwinding: the pipeline reports
+     * itself stopped as soon as stop() is called, but its packets keep flowing
+     * and its native resources stay open until completion settles.
+     *
+     * @returns True if the stream is active, false otherwise
+     */
+    get isStreamActive(): boolean;
+    /**
+     * Get the demuxer instance.
+     *
+     * Used for accessing the underlying demuxer.
+     * Only available after start() is called.
+     *
+     * @returns Demuxer instance or undefined if not started
+     *
+     * @example
+     * ```typescript
+     * const stream = RTPStream.create('input.mp4', {
+     *   onVideoPacket: (rtp) => sendRtp(rtp)
+     * });
+     * await stream.start();
+     * const input = stream.getInput();
+     * console.log('Bitrate:', input?.bitRate);
+     * ```
+     */
+    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. Effective whenever the video is encoded, from
+     * frame sources and from a transcoded URL or {@link Demuxer} input; a stream
+     * passed through keeps the source's keyframes.
+     *
+     * @example
+     * ```typescript
+     * transceiver.sender.onPictureLossIndication.subscribe(() => {
+     *   stream.requestVideoKeyframe();
+     * });
+     * ```
+     */
+    requestVideoKeyframe(): void;
+    /**
+     * Start streaming media to RTP packets.
+     *
+     * Begins the media processing pipeline, reading packets from input,
+     * transcoding if necessary, and invoking RTP packet callbacks.
+     * Automatically handles video and audio streams in parallel.
+     * This method returns immediately after starting the pipeline.
+     *
+     * @returns Promise that resolves when pipeline is started
+     *
+     * @throws {Error} If no video stream found in input
+     *
+     * @throws {FFmpegError} If setup fails
+     *
+     * @example
+     * ```typescript
+     * const stream = RTPStream.create('rtsp://camera.local/stream', {
+     *   onVideoPacket: (rtp) => sendRtp(rtp)
+     * });
+     *
+     * // Start streaming (returns immediately)
+     * await stream.start();
+     *
+     * // Later: stop streaming
+     * await stream.stop();
+     * ```
+     */
+    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;
+    /**
+     * Wire the pipeline completion to the onClose/error callbacks.
+     *
+     * On success invokes `onClose()`; on error stops the stream and invokes
+     * `onClose(error)`. Either way `onClose` runs exactly once and the detached
+     * chain never rejects. Runs in the background (not awaited).
+     *
+     * @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 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.
+     *
+     * @internal
+     */
+    private runPipeline;
+    /**
+     * Stop streaming gracefully and clean up all resources.
+     *
+     * 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. Resolves even if the pipeline had failed; that
+     * error is reported through `onClose(error)`.
+     *
+     * @example
+     * ```typescript
+     * const stream = RTPStream.create('input.mp4', {
+     *   onVideoPacket: (rtp) => sendRtp(rtp)
+     * });
+     * await stream.start();
+     *
+     * // Stop after 10 seconds
+     * setTimeout(async () => await stream.stop(), 10000);
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Perform the actual teardown (see {@link stop}).
+     *
+     * @internal
+     */
+    private doStop;
+    /**
+     * Check if the given audio codec is supported.
+     *
+     * @param codecId - The AVCodecID to check
+     *
+     * @returns True if the codec is supported, false otherwise
+     *
+     * @internal
+     */
+    private isAudioCodecSupported;
+    /**
+     * Find the encoder for a target video codec, on the device when it works there.
+     *
+     * @param target - Codec ID, or the name of a specific encoder to use as it is
+     *
+     * @param size - The output size, when known before the first frame
+     *
+     * @param size.width - Width
+     *
+     * @param size.height - Height
+     *
+     * @returns The encoder, or null if none exists
+     *
+     * @internal
+     */
+    private findVideoEncoder;
+    /**
+     * Check if the given video codec is supported.
+     *
+     * @param codecId - The AVCodecID to check
+     *
+     * @returns True if the codec is supported, false otherwise
+     *
+     * @internal
+     */
+    private isVideoCodecSupported;
+    /**
+     * Select a codec-supported sample format for the desired one.
+     *
+     * Delegates to the shared {@link pickSupportedSampleFormat} so the RTP path and
+     * the encoder negotiate formats identically.
+     *
+     * @param codec - Audio encoder codec
+     *
+     * @param desiredFormat - Desired sample format
+     *
+     * @returns A sample format the codec accepts
+     *
+     * @internal
+     */
+    private selectSampleFormat;
+    /**
+     * Select a codec-supported sample rate for the desired one.
+     *
+     * Delegates to the shared {@link pickSupportedRate} (keeps the desired rate when
+     * accepted, otherwise the nearest supported one).
+     *
+     * @param codec - Audio encoder codec
+     *
+     * @param desiredRate - Desired sample rate
+     *
+     * @returns A sample rate the codec accepts
+     *
+     * @internal
+     */
+    private selectSampleRate;
+    /**
+     * Select a codec-supported channel layout for the desired channel count, as an
+     * SDP layout string.
+     *
+     * Delegates the choice to the shared {@link pickSupportedLayout} (nearest channel
+     * count when the exact count is unsupported), then renders it as `'mono'`,
+     * `'stereo'`, or the layout mask.
+     *
+     * @param codec - Audio encoder codec
+     *
+     * @param desiredChannels - Desired number of channels
+     *
+     * @returns Channel layout string the codec accepts
+     *
+     * @internal
+     */
+    private selectChannelLayout;
+}