node-av 3.0.5 → 3.1.0

package/dist/api/webrtc.d.ts

@@ -0,0 +1,656 @@
+import { RTCRtpCodecParameters, RtpPacket } from 'werift';
+import type { AVCodecID, AVHWDeviceType } from '../constants/constants.js';
+/**
+ * Codec information for WebRTC streaming.
+ *
+ * Contains RTP codec parameters and FFmpeg codec IDs for video and audio streams.
+ * Used for codec negotiation in WebRTC peer connections.
+ */
+export interface WebRTCCodecInfo {
+    /**
+     * Video codec configuration.
+     * Combines RTP parameters (mimeType, clockRate, etc.) with FFmpeg codec ID.
+     */
+    video: Partial<RTCRtpCodecParameters> & {
+        codecId: AVCodecID;
+    };
+    /**
+     * Optional audio codec configuration.
+     * Combines RTP parameters (mimeType, clockRate, channels) with FFmpeg codec ID.
+     */
+    audio?: Partial<RTCRtpCodecParameters> & {
+        codecId: AVCodecID;
+    };
+}
+/**
+ * Options for configuring WebRTC streaming.
+ */
+export interface WebRTCStreamOptions {
+    /**
+     * Callback invoked for each video RTP packet.
+     * Use this to send packets to your WebRTC 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 WebRTC implementation.
+     *
+     * @param packet - Serialized RTP packet ready for transmission
+     */
+    onAudioPacket?: (packet: RtpPacket) => void;
+    /**
+     * Maximum transmission unit (MTU) size in bytes.
+     * RTP packets will be fragmented to fit within this size.
+     *
+     * @default 1200
+     */
+    mtu?: number;
+    /**
+     * 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;
+        device?: string;
+        options?: Record<string, string>;
+    };
+}
+/**
+ * High-level WebRTC streaming with automatic codec detection and transcoding.
+ *
+ * Provides library-agnostic RTP streaming for WebRTC applications.
+ * Automatically detects input codecs and transcodes non-WebRTC-compatible formats.
+ * Handles video (H.264, H.265, VP8, VP9) and audio (Opus, PCMA, PCMU) codecs.
+ * Supports hardware acceleration for video transcoding.
+ * Essential component for building WebRTC streaming servers without direct WebRTC library coupling.
+ *
+ * @example
+ * ```typescript
+ * import { WebRTCStream } from 'node-av/api';
+ *
+ * // Create stream with RTP packet callbacks
+ * const stream = await WebRTCStream.create('rtsp://camera.local/stream', {
+ *   mtu: 1200,
+ *   hardware: 'auto',
+ *   onVideoPacket: (rtp) => {
+ *     // Send RTP packet to WebRTC peer connection
+ *     videoTrack.writeRtp(rtp);
+ *   },
+ *   onAudioPacket: (rtp) => {
+ *     audioTrack.writeRtp(rtp);
+ *   }
+ * });
+ *
+ * // Get detected codecs for SDP negotiation
+ * const codecs = stream.getCodecs();
+ * console.log('Video:', codecs.video.mimeType);
+ * console.log('Audio:', codecs.audio?.mimeType);
+ *
+ * // Start streaming
+ * await stream.start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream with hardware acceleration
+ * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
+ *
+ * const stream = await WebRTCStream.create('video.mp4', {
+ *   hardware: {
+ *     deviceType: AV_HWDEVICE_TYPE_CUDA,
+ *     device: '/dev/nvidia0'
+ *   },
+ *   onVideoPacket: (rtp) => sendToWebRTC(rtp)
+ * });
+ *
+ * await stream.start();
+ * stream.stop();
+ * stream.dispose();
+ * ```
+ *
+ * @see {@link WebRTCSession} For complete WebRTC session management with werift
+ * @see {@link MediaInput} For input media handling
+ * @see {@link HardwareContext} For GPU acceleration
+ */
+export declare class WebRTCStream implements Disposable {
+    private input;
+    private codecInfo;
+    private options;
+    private videoOutput;
+    private audioOutput;
+    private hardwareContext;
+    private videoDecoder;
+    private videoEncoder;
+    private audioDecoder;
+    private audioFilter;
+    private audioEncoder;
+    private streamActive;
+    /**
+     * @param input - Media input source
+     *
+     * @param options - Stream configuration options
+     *
+     * Use {@link create} factory method
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create a WebRTC stream from a media source.
+     *
+     * Opens the input media, detects video and audio codecs, and prepares
+     * transcoding pipelines for non-WebRTC-compatible formats.
+     * Automatically configures H.264 encoding for unsupported video codecs
+     * and Opus encoding for unsupported audio codecs.
+     *
+     * @param inputUrl - Media source URL (RTSP, file path, HTTP, etc.)
+     *
+     * @param options - Stream configuration options
+     *
+     * @returns Configured WebRTC stream instance
+     *
+     * @throws {Error} If no video stream found in input
+     *
+     * @throws {FFmpegError} If input cannot be opened
+     *
+     * @example
+     * ```typescript
+     * // Stream from RTSP camera
+     * const stream = await WebRTCStream.create('rtsp://camera.local/stream', {
+     *   mtu: 1200,
+     *   onVideoPacket: (rtp) => videoTrack.writeRtp(rtp),
+     *   onAudioPacket: (rtp) => audioTrack.writeRtp(rtp)
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream file with auto hardware acceleration
+     * const stream = await WebRTCStream.create('video.mp4', {
+     *   hardware: 'auto'
+     * });
+     * ```
+     */
+    static create(inputUrl: string, options?: WebRTCStreamOptions): Promise<WebRTCStream>;
+    /**
+     * Get detected codec information for SDP negotiation.
+     *
+     * Returns RTP codec parameters and FFmpeg codec IDs for video and audio.
+     * Use this information to configure WebRTC peer connections with matching codecs.
+     *
+     * @returns Codec configuration for video and audio streams
+     *
+     * @example
+     * ```typescript
+     * const stream = await WebRTCStream.create('input.mp4');
+     * const codecs = stream.getCodecs();
+     *
+     * console.log('Video codec:', codecs.video.mimeType);
+     * console.log('Audio codec:', codecs.audio?.mimeType);
+     * ```
+     */
+    getCodecs(): WebRTCCodecInfo;
+    /**
+     * 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.
+     * Flushes all buffers at the end of stream.
+     * This method blocks until streaming completes or {@link stop} is called.
+     *
+     * @returns Promise that resolves when streaming completes
+     *
+     * @throws {FFmpegError} If transcoding or muxing fails
+     *
+     * @example
+     * ```typescript
+     * const stream = await WebRTCStream.create('rtsp://camera.local/stream', {
+     *   onVideoPacket: (rtp) => sendRtp(rtp)
+     * });
+     *
+     * // Start streaming (blocks until complete or stopped)
+     * await stream.start();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Non-blocking start with background promise
+     * const stream = await WebRTCStream.create('input.mp4');
+     * const streamPromise = stream.start();
+     *
+     * // Later: stop streaming
+     * stream.stop();
+     * await streamPromise;
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stop streaming gracefully.
+     *
+     * Signals the streaming loop to exit after the current packet is processed.
+     * Does not immediately close resources - use {@link dispose} for cleanup.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * const stream = await WebRTCStream.create('input.mp4');
+     * const streamPromise = stream.start();
+     *
+     * // Stop after 10 seconds
+     * setTimeout(() => stream.stop(), 10000);
+     *
+     * await streamPromise; // Resolves when stopped
+     * stream.dispose();
+     * ```
+     */
+    stop(): void;
+    /**
+     * Clean up all resources and close the stream.
+     *
+     * Stops streaming if active and releases all FFmpeg resources including
+     * decoders, encoders, filters, outputs, and input. Should be called when
+     * done with the stream to prevent memory leaks.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * const stream = await WebRTCStream.create('input.mp4');
+     * await stream.start();
+     * stream.dispose();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using automatic cleanup
+     * {
+     *   await using stream = await WebRTCStream.create('input.mp4');
+     *   await stream.start();
+     * } // Automatically disposed
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Check if the given audio codec is compatible with WebRTC.
+     *
+     * @param codecId - The AVCodecID to check
+     *
+     * @returns True if the codec is WebRTC compatible, false otherwise
+     *
+     * @internal
+     */
+    private isAudioCodecSupported;
+    /**
+     * Check if the given video codec is compatible with WebRTC.
+     *
+     * @param codecId - The AVCodecID to check
+     *
+     * @returns True if the codec is WebRTC compatible, false otherwise
+     *
+     * @internal
+     */
+    private isVideoCodecSupported;
+    /**
+     * Get the audio codec configuration for WebRTC.
+     *
+     * @param codecId - The AVCodecID of the audio codec
+     *
+     * @returns An object containing MIME type, clock rate, and channels, or null if unsupported
+     *
+     * @internal
+     */
+    private getAudioCodecConfig;
+    /**
+     * Get the video codec configuration for WebRTC.
+     *
+     * @param codecId - The AVCodecID of the video codec
+     *
+     * @returns An object containing MIME type and clock rate, or null if unsupported
+     *
+     * @internal
+     */
+    private getVideoCodecConfig;
+    /**
+     * Flush video encoder pipeline.
+     *
+     * @param videoStreamIndex - Output video stream index
+     *
+     * @internal
+     */
+    private flushVideo;
+    /**
+     * Flush audio encoder pipeline.
+     *
+     * @param audioStreamIndex - Output audio stream index
+     *
+     * @param hasAudio - Whether audio stream exists
+     *
+     * @internal
+     */
+    private flushAudio;
+    /**
+     * Symbol.dispose implementation for automatic cleanup.
+     *
+     * @internal
+     */
+    [Symbol.dispose](): void;
+}
+/**
+ * Options for configuring WebRTC session with werift integration.
+ *
+ * Extends WebRTCStreamOptions but excludes RTP packet callbacks since
+ * they are automatically handled by the session's media tracks.
+ */
+export interface WebRTCSessionOptions extends Omit<WebRTCStreamOptions, 'onVideoPacket' | 'onAudioPacket'> {
+    /**
+     * ICE servers for NAT traversal and STUN/TURN configuration.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('input.mp4', {
+     *   iceServers: [
+     *     { urls: 'stun:stun.l.google.com:19302' },
+     *     { urls: 'turn:turn.example.com:3478' }
+     *   ]
+     * });
+     * ```
+     */
+    iceServers?: {
+        urls: string;
+    }[];
+}
+/**
+ * Complete WebRTC session management with werift integration.
+ *
+ * Provides end-to-end WebRTC streaming with automatic SDP negotiation,
+ * ICE candidate handling, and peer connection management.
+ * Built on top of {@link WebRTCStream} but handles all WebRTC protocol details.
+ * Integrates with werift library for RTCPeerConnection and media track handling.
+ * Ideal for building complete WebRTC streaming applications with minimal code.
+ *
+ * @example
+ * ```typescript
+ * import { WebRTCSession } from 'node-av/api';
+ *
+ * // Create session from media source
+ * const session = await WebRTCSession.create('rtsp://camera.local/stream', {
+ *   mtu: 1200,
+ *   hardware: 'auto',
+ *   iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+ * });
+ *
+ * // Setup ICE candidate handler
+ * session.onIceCandidate = (candidate) => {
+ *   sendToClient({ type: 'candidate', value: candidate });
+ * };
+ *
+ * // Process SDP offer from client
+ * const answer = await session.setOffer(clientOffer);
+ * sendToClient({ type: 'answer', value: answer });
+ *
+ * // Start streaming
+ * await session.start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Complete WebSocket signaling server
+ * import { WebSocket } from 'ws';
+ *
+ * ws.on('message', async (data) => {
+ *   const msg = JSON.parse(data);
+ *
+ *   if (msg.type === 'offer') {
+ *     const session = await WebRTCSession.create(msg.url, {
+ *       hardware: 'auto'
+ *     });
+ *
+ *     session.onIceCandidate = (candidate) => {
+ *       ws.send(JSON.stringify({ type: 'candidate', value: candidate }));
+ *     };
+ *
+ *     const answer = await session.setOffer(msg.value);
+ *     ws.send(JSON.stringify({ type: 'answer', value: answer }));
+ *
+ *     await session.start();
+ *   } else if (msg.type === 'candidate') {
+ *     session.addIceCandidate(msg.value);
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link WebRTCStream} For library-agnostic RTP streaming
+ * @see {@link MediaInput} For input media handling
+ * @see {@link HardwareContext} For GPU acceleration
+ */
+export declare class WebRTCSession implements Disposable {
+    private stream;
+    private pc;
+    private videoTrack;
+    private audioTrack;
+    private options;
+    /**
+     * Callback invoked when a new ICE candidate is discovered.
+     * Send this candidate to the remote peer via signaling channel.
+     *
+     * @param candidate - ICE candidate string to send to remote peer
+     *
+     * @example
+     * ```typescript
+     * session.onIceCandidate = (candidate) => {
+     *   ws.send(JSON.stringify({ type: 'candidate', value: candidate }));
+     * };
+     * ```
+     */
+    onIceCandidate: ((candidate: string) => void) | null;
+    /**
+     * @param options - Session configuration options
+     *
+     * Use {@link create} factory method
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create a WebRTC session from a media source.
+     *
+     * Opens the input media, creates internal streaming components, and prepares
+     * for WebRTC peer connection negotiation. Does not start streaming yet.
+     * Call {@link setOffer} to negotiate SDP and {@link start} to begin streaming.
+     *
+     * @param inputUrl - Media source URL (RTSP, file path, HTTP, etc.)
+     *
+     * @param options - Session configuration options
+     *
+     * @returns Configured WebRTC session instance
+     *
+     * @throws {Error} If no video stream found in input
+     *
+     * @throws {FFmpegError} If input cannot be opened
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('rtsp://camera.local/stream', {
+     *   mtu: 1200,
+     *   hardware: 'auto',
+     *   iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Session from file with hardware acceleration
+     * const session = await WebRTCSession.create('video.mp4', {
+     *   hardware: {
+     *     deviceType: AV_HWDEVICE_TYPE_CUDA
+     *   }
+     * });
+     * ```
+     */
+    static create(inputUrl: string, options?: WebRTCSessionOptions): Promise<WebRTCSession>;
+    /**
+     * Get detected codec information.
+     *
+     * Returns RTP codec parameters and FFmpeg codec IDs for video and audio.
+     * Useful for inspecting what codecs will be used in the WebRTC session.
+     *
+     * @returns Codec configuration for video and audio streams
+     *
+     * @throws {Error} If stream not initialized
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('input.mp4');
+     * const codecs = session.getCodecs();
+     *
+     * console.log('Video:', codecs.video.mimeType);
+     * console.log('Audio:', codecs.audio?.mimeType);
+     * ```
+     */
+    getCodecs(): WebRTCCodecInfo;
+    /**
+     * Process SDP offer from remote peer and generate SDP answer.
+     *
+     * Creates RTCPeerConnection with detected codecs, sets up media tracks,
+     * processes the remote SDP offer, and generates a local SDP answer.
+     * Also configures ICE candidate handling via {@link onIceCandidate} callback.
+     * Must be called before {@link start}.
+     *
+     * @param offerSdp - SDP offer string from remote WebRTC peer
+     *
+     * @returns SDP answer string to send back to remote peer
+     *
+     * @throws {Error} If stream not initialized
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('input.mp4');
+     *
+     * // Setup ICE candidate handler first
+     * session.onIceCandidate = (candidate) => {
+     *   sendToRemote({ type: 'candidate', value: candidate });
+     * };
+     *
+     * // Process offer and send answer
+     * const answer = await session.setOffer(remoteOffer);
+     * sendToRemote({ type: 'answer', value: answer });
+     * ```
+     */
+    setOffer(offerSdp: string): Promise<string>;
+    /**
+     * Add ICE candidate from remote peer.
+     *
+     * Processes ICE candidates received from the remote peer via signaling channel.
+     * Should be called whenever a new candidate message arrives from remote peer.
+     * Can be called multiple times as candidates are discovered.
+     *
+     * @param candidate - ICE candidate string from remote peer
+     *
+     * @throws {Error} If peer connection not initialized (call {@link setOffer} first)
+     *
+     * @example
+     * ```typescript
+     * // In signaling message handler
+     * if (msg.type === 'candidate') {
+     *   session.addIceCandidate(msg.value);
+     * }
+     * ```
+     */
+    addIceCandidate(candidate: string): void;
+    /**
+     * Start streaming media to WebRTC peer connection.
+     *
+     * Begins the media processing pipeline, reading packets from input,
+     * transcoding if necessary, and sending RTP packets to media tracks.
+     * Must call {@link setOffer} before starting.
+     * This method blocks until streaming completes or {@link stop} is called.
+     *
+     * @returns Promise that resolves when streaming completes
+     *
+     * @throws {Error} If stream not initialized
+     *
+     * @throws {FFmpegError} If transcoding or muxing fails
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('input.mp4');
+     * session.onIceCandidate = (c) => sendToRemote(c);
+     *
+     * const answer = await session.setOffer(remoteOffer);
+     * sendToRemote(answer);
+     *
+     * // Start streaming (blocks until complete)
+     * await session.start();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Non-blocking start
+     * const session = await WebRTCSession.create('input.mp4');
+     * const streamPromise = session.start();
+     *
+     * // Later: stop streaming
+     * session.stop();
+     * await streamPromise;
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stop streaming gracefully.
+     *
+     * Signals the streaming loop to exit after the current packet is processed.
+     * Does not immediately close resources - use {@link dispose} for cleanup.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('input.mp4');
+     * const streamPromise = session.start();
+     *
+     * // Stop after 10 seconds
+     * setTimeout(() => session.stop(), 10000);
+     *
+     * await streamPromise;
+     * session.dispose();
+     * ```
+     */
+    stop(): void;
+    /**
+     * Clean up all resources and close the session.
+     *
+     * Stops streaming if active, releases all FFmpeg resources, closes peer connection,
+     * and cleans up media tracks. Should be called when done with the session to prevent
+     * memory leaks. Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * const session = await WebRTCSession.create('input.mp4');
+     * await session.start();
+     * session.dispose();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using automatic cleanup
+     * {
+     *   await using session = await WebRTCSession.create('input.mp4');
+     *   await session.start();
+     * } // Automatically disposed
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Symbol.dispose implementation for automatic cleanup.
+     *
+     * @internal
+     */
+    [Symbol.dispose](): void;
+}