node-av 3.0.5 → 3.1.0

package/README.md

@@ -397,6 +397,7 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 | Example | FFmpeg | Low-Level API | High-Level API |
 |---------|--------|---------------|----------------|
 | `browser-fmp4` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/browser/fmp4) |
+| `browser-webrtc` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/browser/webrtc) |
 | `api-dash` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-dash.ts) |
 | `api-encode-decode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-encode-decode.ts) |
 | `api-frame-extract` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-frame-extract.ts) |

package/dist/api/fmp4.d.ts

@@ -0,0 +1,325 @@
+import type { AVHWDeviceType } from '../constants/constants.js';
+/**
+ * Target codec strings for fMP4 streaming.
+ */
+export declare const FMP4_CODECS: {
+    readonly H264: "avc1.640029";
+    readonly H265: "hvc1.1.6.L153.B0";
+    readonly AV1: "av01.0.00M.08";
+    readonly AAC: "mp4a.40.2";
+    readonly FLAC: "flac";
+    readonly OPUS: "opus";
+};
+/**
+ * Options for configuring fMP4 streaming.
+ */
+export interface FMP4StreamOptions {
+    /**
+     * Callback invoked for each fMP4 chunk.
+     * Use this to send chunks to your client (WebSocket, HTTP, etc.).
+     *
+     * @param chunk - fMP4 data chunk
+     */
+    onChunk?: (chunk: Buffer) => void;
+    /**
+     * Supported codec strings from client.
+     * Comma-separated list (e.g., "avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2,flac,opus").
+     *
+     * @example "avc1.640029,mp4a.40.2"
+     */
+    supportedCodecs?: string;
+    /**
+     * Fragment duration in seconds.
+     * Smaller values reduce latency but increase overhead.
+     *
+     * @default 1
+     */
+    fragDuration?: number;
+    /**
+     * Hardware acceleration configuration for video transcoding.
+     *
+     * - `'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 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.
+ * Client sends supported codecs, server transcodes accordingly.
+ * Essential component for building adaptive streaming servers.
+ *
+ * @example
+ * ```typescript
+ * import { FMP4Stream } from 'node-av/api';
+ *
+ * // Client sends supported codecs
+ * const supportedCodecs = 'avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2,flac';
+ *
+ * // Create stream with codec negotiation
+ * const stream = await FMP4Stream.create('rtsp://camera.local/stream', {
+ *   supportedCodecs,
+ *   onChunk: (chunk) => ws.send(chunk)
+ * });
+ *
+ * // Start streaming (auto-transcodes if needed)
+ * await stream.start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream with hardware acceleration
+ * const stream = await FMP4Stream.create('input.mp4', {
+ *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+ *   hardware: 'auto',
+ *   fragDuration: 1,
+ *   onChunk: (chunk) => sendToClient(chunk)
+ * });
+ *
+ * await stream.start();
+ * stream.stop();
+ * stream.dispose();
+ * ```
+ *
+ * @see {@link MediaInput} For input media handling
+ * @see {@link MediaOutput} For fMP4 generation
+ * @see {@link HardwareContext} For GPU acceleration
+ */
+export declare class FMP4Stream implements Disposable {
+    private input;
+    private options;
+    private output;
+    private hardwareContext;
+    private videoDecoder;
+    private videoEncoder;
+    private audioDecoder;
+    private audioFilter;
+    private audioEncoder;
+    private streamActive;
+    private supportedCodecs;
+    /**
+     * @param input - Media input source
+     *
+     * @param options - Stream configuration options
+     *
+     * Use {@link create} factory method
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create a fMP4 stream from a media source.
+     *
+     * Opens the input media, detects video and audio codecs, and prepares
+     * transcoding pipelines based on client-supported codecs.
+     * Automatically transcodes to H.264 and AAC if necessary.
+     *
+     * @param inputUrl - Media source URL (RTSP, file path, HTTP, etc.)
+     *
+     * @param options - Stream configuration options with supported codecs
+     *
+     * @returns Configured fMP4 stream instance
+     *
+     * @throws {Error} If no video stream found in input
+     *
+     * @throws {FFmpegError} If input cannot be opened
+     *
+     * @example
+     * ```typescript
+     * // Stream from file with codec negotiation
+     * const stream = await FMP4Stream.create('video.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onChunk: (chunk) => ws.send(chunk)
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream from RTSP with auto hardware acceleration
+     * const stream = await FMP4Stream.create('rtsp://camera.local/stream', {
+     *   supportedCodecs: 'avc1.640029,hvc1.1.6.L153.B0,mp4a.40.2',
+     *   hardware: 'auto',
+     *   fragDuration: 0.5
+     * });
+     * ```
+     */
+    static create(inputUrl: string, options?: FMP4StreamOptions): Promise<FMP4Stream>;
+    /**
+     * Get the codec string that will be used by client.
+     *
+     * Returns the MIME type codec string based on input codecs and transcoding decisions.
+     * Call this after creating the stream to know what codec string to use for addSourceBuffer().
+     *
+     * @returns MIME type codec string (e.g., "avc1.640029,mp4a.40.2")
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     *
+     * const codecString = stream.getCodecString();
+     * console.log(codecString); // "avc1.640029,mp4a.40.2"
+     * // Use this for: sourceBuffer = mediaSource.addSourceBuffer(`video/mp4; codecs="${codecString}"`);
+     * ```
+     */
+    getCodecString(): string;
+    /**
+     * Get the resolution of the input video stream.
+     *
+     * @returns Object with width and height properties
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     *
+     * const resolution = stream.getResolution();
+     * console.log(`Width: ${resolution.width}, Height: ${resolution.height}`);
+     * ```
+     */
+    getResolution(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * 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.
+     * 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 FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onChunk: (chunk) => sendToClient(chunk)
+     * });
+     *
+     * // Start streaming (blocks until complete)
+     * await stream.start();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Non-blocking start with background promise
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     * 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 FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     * 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, output, and input. Should be called when
+     * done with the stream to prevent memory leaks.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     * await stream.start();
+     * stream.dispose();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using automatic cleanup
+     * {
+     *   await using stream = await FMP4Stream.create('input.mp4', {
+     *     supportedCodecs: 'avc1.640029,mp4a.40.2'
+     *   });
+     *   await stream.start();
+     * } // Automatically disposed
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Check if video codec is supported.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if H.264, H.265, or AV1 is in supported codecs
+     *
+     * @internal
+     */
+    private isVideoCodecSupported;
+    /**
+     * Check if audio codec is supported.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if AAC, FLAC, or Opus is in supported codecs
+     *
+     * @internal
+     */
+    private isAudioCodecSupported;
+    /**
+     * Flush video encoder pipeline.
+     *
+     * @param videoStreamIndex - Output video stream index
+     *
+     * @internal
+     */
+    private flushVideo;
+    /**
+     * Flush audio encoder pipeline.
+     *
+     * @param audioStreamIndex - Output audio stream index
+     *
+     * @internal
+     */
+    private flushAudio;
+    /**
+     * Symbol.dispose implementation for automatic cleanup.
+     *
+     * @internal
+     */
+    [Symbol.dispose](): void;
+}