node-av 3.1.3 → 4.0.0

package/dist/api/fmp4-stream.js

@@ -0,0 +1,539 @@
+import { AV_CODEC_ID_AAC, AV_CODEC_ID_AV1, AV_CODEC_ID_FLAC, AV_CODEC_ID_H264, AV_CODEC_ID_HEVC, AV_CODEC_ID_OPUS, AV_HWDEVICE_TYPE_NONE, AV_SAMPLE_FMT_FLTP, } from '../constants/constants.js';
+import { FF_ENCODER_AAC, FF_ENCODER_LIBX264 } from '../constants/encoders.js';
+import { Codec } from '../lib/codec.js';
+import { avGetCodecString } from '../lib/utilities.js';
+import { Decoder } from './decoder.js';
+import { Demuxer } from './demuxer.js';
+import { Encoder } from './encoder.js';
+import { FilterPreset } from './filter-presets.js';
+import { FilterAPI } from './filter.js';
+import { HardwareContext } from './hardware.js';
+import { Muxer } from './muxer.js';
+import { pipeline } from './pipeline.js';
+/**
+ * Target codec strings for fMP4 streaming.
+ */
+export const FMP4_CODECS = {
+    H264: 'avc1.640029',
+    H265: 'hvc1.1.6.L153.B0',
+    AV1: 'av01.0.00M.08',
+    AAC: 'mp4a.40.2',
+    FLAC: 'flac',
+    OPUS: 'opus',
+};
+/**
+ * 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 = FMP4Stream.create('rtsp://camera.local/stream', {
+ *   supportedCodecs,
+ *   onData: (data) => ws.send(data.data)
+ * });
+ *
+ * // Start streaming (auto-transcodes if needed)
+ * await stream.start();
+ *
+ * // Stop when done
+ * await stream.stop();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream with hardware acceleration
+ * const stream = FMP4Stream.create('input.mp4', {
+ *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+ *   hardware: 'auto',
+ *   fragDuration: 1,
+ *   onData: (data) => sendToClient(data.data)
+ * });
+ *
+ * await stream.start();
+ * await stream.stop();
+ * ```
+ */
+export class FMP4Stream {
+    options;
+    inputUrl;
+    inputOptions;
+    input;
+    output;
+    hardwareContext;
+    videoDecoder;
+    videoEncoder;
+    audioDecoder;
+    audioFilter;
+    audioEncoder;
+    pipeline;
+    supportedCodecs;
+    incompleteBoxBuffer = null;
+    /**
+     * @param inputUrl - Media input URL
+     *
+     * @param options - Stream configuration options
+     *
+     * Use {@link create} factory method
+     *
+     * @internal
+     */
+    constructor(inputUrl, options) {
+        this.inputUrl = inputUrl;
+        this.inputOptions = {
+            ...options.inputOptions,
+            options: {
+                flags: 'low_delay',
+                fflags: 'nobuffer',
+                // analyzeduration: 0,
+                // probesize: 32,
+                timeout: 5000000,
+                rtsp_transport: inputUrl.toLowerCase().startsWith('rtsp') ? 'tcp' : undefined,
+                ...options.inputOptions?.options,
+            },
+        };
+        this.options = {
+            onData: options.onData ?? (() => { }),
+            onClose: options.onClose ?? (() => { }),
+            supportedCodecs: options.supportedCodecs ?? '',
+            fragDuration: options.fragDuration ?? 1,
+            hardware: options.hardware ?? { deviceType: AV_HWDEVICE_TYPE_NONE },
+            inputOptions: options.inputOptions,
+            bufferSize: options.bufferSize ?? 2 * 1024 * 1024,
+            boxMode: options.boxMode ?? false,
+            movFlags: options.movFlags ?? '+frag_keyframe+separate_moof+default_base_moof+empty_moov',
+        };
+        // Parse supported codecs
+        this.supportedCodecs = new Set(this.options.supportedCodecs
+            .split(',')
+            .map((c) => c.trim())
+            .filter(Boolean));
+    }
+    /**
+     * Create a fMP4 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 inputUrl - Media source URL (RTSP, file path, HTTP, etc.)
+     *
+     * @param options - Stream configuration options with supported codecs
+     *
+     * @returns Configured fMP4 stream instance
+     *
+     * @example
+     * ```typescript
+     * // Stream from file with codec negotiation
+     * const stream = FMP4Stream.create('video.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onData: (data) => ws.send(data.data)
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream from RTSP with auto hardware acceleration
+     * const stream = 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, options = {}) {
+        return new FMP4Stream(inputUrl, options);
+    }
+    /**
+     * 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 = FMP4Stream.create('input.mp4', {
+     * const input = stream.getInput();
+     * console.log('Bitrate:', input?.bitRate);
+     * ```
+     */
+    getInput() {
+        return this.input;
+    }
+    /**
+     * 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 start() is called to know what codec string to use for addSourceBuffer().
+     *
+     * @returns MIME type codec string (e.g., "avc1.640029,mp4a.40.2")
+     *
+     * @throws {Error} If called before start() is called
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     *
+     * await stream.start(); // Must start first
+     * const codecString = stream.getCodecString();
+     * console.log(codecString); // "avc1.640029,mp4a.40.2"
+     * // Use this for: sourceBuffer = mediaSource.addSourceBuffer(`video/mp4; codecs="${codecString}"`);
+     * ```
+     */
+    getCodecString() {
+        if (!this.input) {
+            throw new Error('Input not opened. Call start() first to open the input.');
+        }
+        const videoStream = this.input.video();
+        const audioStream = this.input.audio();
+        const videoCodecId = videoStream?.codecpar.codecId;
+        const audioCodecId = audioStream?.codecpar.codecId;
+        // Determine video codec string
+        let videoCodec = null;
+        if (videoCodecId) {
+            const needsVideoTranscode = !this.isVideoCodecSupported(videoCodecId);
+            if (needsVideoTranscode) {
+                // Transcoding to H.264
+                videoCodec = FMP4_CODECS.H264;
+            }
+            else if (videoCodecId === AV_CODEC_ID_H264) {
+                // H.264 - use RFC 6381 codec string from input
+                const codecString = avGetCodecString(videoStream.codecpar);
+                videoCodec = codecString ?? FMP4_CODECS.H264;
+            }
+            else if (videoCodecId === AV_CODEC_ID_HEVC) {
+                // H.265 - use RFC 6381 codec string from input
+                const codecString = avGetCodecString(videoStream.codecpar);
+                videoCodec = codecString ?? FMP4_CODECS.H265;
+            }
+            else if (videoCodecId === AV_CODEC_ID_AV1) {
+                // AV1 - use RFC 6381 codec string from input
+                const codecString = avGetCodecString(videoStream.codecpar);
+                videoCodec = codecString ?? FMP4_CODECS.AV1;
+            }
+            else {
+                // Fallback to H.264 (should not happen as we transcode unsupported codecs)
+                videoCodec = FMP4_CODECS.H264;
+            }
+        }
+        // Determine audio codec string
+        let audioCodec = null;
+        if (audioCodecId) {
+            const needsAudioTranscode = !this.isAudioCodecSupported(audioCodecId);
+            if (needsAudioTranscode) {
+                // Transcoding to AAC
+                audioCodec = FMP4_CODECS.AAC;
+            }
+            else if (audioCodecId === AV_CODEC_ID_AAC) {
+                // AAC - use fixed codec string
+                audioCodec = FMP4_CODECS.AAC;
+            }
+            else if (audioCodecId === AV_CODEC_ID_FLAC) {
+                // FLAC
+                audioCodec = FMP4_CODECS.FLAC;
+            }
+            else if (audioCodecId === AV_CODEC_ID_OPUS) {
+                // Opus
+                audioCodec = FMP4_CODECS.OPUS;
+            }
+            else {
+                // Fallback to AAC (should not happen as we transcode unsupported codecs)
+                audioCodec = FMP4_CODECS.AAC;
+            }
+        }
+        // Combine video and audio codec strings
+        return [videoCodec, audioCodec].filter(Boolean).join(',');
+    }
+    /**
+     * 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 returns immediately after starting the pipeline.
+     *
+     * @returns Promise that resolves when pipeline is started
+     *
+     * @throws {FFmpegError} If setup fails
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2',
+     *   onData: (data) => sendToClient(data.data)
+     * });
+     *
+     * // Start streaming (returns immediately)
+     * await stream.start();
+     *
+     * // Later: stop streaming
+     * await stream.stop();
+     * ```
+     */
+    async start() {
+        if (this.pipeline) {
+            return;
+        }
+        // Open input if not already open
+        this.input ??= await Demuxer.open(this.inputUrl, this.inputOptions);
+        const videoStream = this.input.video();
+        const audioStream = this.input.audio();
+        // Check if video needs transcoding
+        const needsVideoTranscode = videoStream && !this.isVideoCodecSupported(videoStream.codecpar.codecId);
+        if (needsVideoTranscode) {
+            // Check if we need hardware acceleration
+            if (this.options.hardware === 'auto') {
+                this.hardwareContext = HardwareContext.auto();
+            }
+            else if (this.options.hardware.deviceType !== AV_HWDEVICE_TYPE_NONE) {
+                this.hardwareContext = HardwareContext.create(this.options.hardware.deviceType, this.options.hardware.device, this.options.hardware.options);
+            }
+            // Transcode to H.264
+            this.videoDecoder = await Decoder.create(videoStream, {
+                hardware: this.hardwareContext,
+                exitOnError: false,
+            });
+            const encoderCodec = this.hardwareContext?.getEncoderCodec('h264') ?? Codec.findEncoderByName(FF_ENCODER_LIBX264);
+            const encoderOptions = {};
+            if (encoderCodec.name === FF_ENCODER_LIBX264 || encoderCodec.name === FF_ENCODER_LIBX264) {
+                encoderOptions.preset = 'ultrafast';
+                encoderOptions.tune = 'zerolatency';
+            }
+            this.videoEncoder = await Encoder.create(encoderCodec, {
+                decoder: this.videoDecoder,
+                options: encoderOptions,
+            });
+        }
+        // Check if audio needs transcoding
+        const needsAudioTranscode = audioStream && !this.isAudioCodecSupported(audioStream.codecpar.codecId);
+        if (needsAudioTranscode) {
+            // Transcode to AAC
+            this.audioDecoder = await Decoder.create(audioStream, {
+                exitOnError: false,
+            });
+            const targetSampleRate = 44100;
+            const filterChain = FilterPreset.chain().aformat(AV_SAMPLE_FMT_FLTP, targetSampleRate, 'stereo').build();
+            this.audioFilter = FilterAPI.create(filterChain);
+            this.audioEncoder = await Encoder.create(FF_ENCODER_AAC, {
+                decoder: this.audioDecoder,
+                filter: this.audioFilter,
+            });
+        }
+        // Setup output with callback
+        const cb = {
+            write: (buffer) => {
+                if (this.options.boxMode) {
+                    // Box mode: buffer until we have complete boxes
+                    this.processBoxMode(buffer);
+                }
+                else {
+                    // Chunk mode: send raw data immediately
+                    this.options.onData(buffer, {
+                        isComplete: false,
+                        boxes: [],
+                    });
+                }
+                return buffer.length;
+            },
+        };
+        this.output = await Muxer.open(cb, {
+            input: this.input,
+            format: 'mp4',
+            bufferSize: this.options.bufferSize,
+            exitOnError: false,
+            options: {
+                movflags: this.options.movFlags,
+                frag_duration: this.options.fragDuration,
+            },
+        });
+        this.runPipeline()
+            .then(() => {
+            // Pipeline completed successfully
+            this.options.onClose?.();
+        })
+            .catch(async (error) => {
+            await this.stop();
+            this.options.onClose?.(error);
+        });
+    }
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const stream = await FMP4Stream.create('input.mp4', {
+     *   supportedCodecs: 'avc1.640029,mp4a.40.2'
+     * });
+     * await stream.start();
+     *
+     * // Stop after 10 seconds
+     * setTimeout(async () => await stream.stop(), 10000);
+     * ```
+     */
+    async stop() {
+        // Stop pipeline if running and wait for completion
+        if (this.pipeline && !this.pipeline.isStopped()) {
+            this.pipeline.stop();
+            await this.pipeline.completion;
+            this.pipeline = undefined;
+        }
+        // Close all resources
+        await this.input?.close();
+        this.input = undefined;
+        this.videoDecoder?.close();
+        this.videoDecoder = undefined;
+        this.videoEncoder?.close();
+        this.videoEncoder = undefined;
+        this.audioDecoder?.close();
+        this.audioDecoder = undefined;
+        this.audioFilter?.close();
+        this.audioFilter = undefined;
+        this.audioEncoder?.close();
+        this.audioEncoder = undefined;
+        this.hardwareContext?.dispose();
+        this.hardwareContext = undefined;
+        await this.output?.close();
+        this.output = undefined;
+    }
+    /**
+     * Run the streaming pipeline until completion or stopped.
+     *
+     * @internal
+     */
+    async runPipeline() {
+        if (!this.input || !this.output) {
+            return;
+        }
+        const hasVideo = this.input?.video() !== undefined;
+        const hasAudio = this.input?.audio() !== undefined;
+        if (hasAudio && hasVideo) {
+            this.pipeline = pipeline(this.input, {
+                video: [this.videoDecoder, this.videoEncoder],
+                audio: [this.audioDecoder, this.audioFilter, this.audioEncoder],
+            }, this.output);
+        }
+        else if (hasVideo) {
+            this.pipeline = pipeline(this.input, {
+                video: [this.videoDecoder, this.videoEncoder],
+            }, this.output);
+        }
+        else if (hasAudio) {
+            this.pipeline = pipeline(this.input, {
+                audio: [this.audioDecoder, this.audioFilter, this.audioEncoder],
+            }, this.output);
+        }
+        else {
+            throw new Error('No audio or video streams found in input');
+        }
+        await this.pipeline.completion;
+        this.pipeline = undefined;
+    }
+    /**
+     * Check if video codec is supported.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if H.264, H.265, or AV1 is in supported codecs
+     *
+     * @internal
+     */
+    isVideoCodecSupported(codecId) {
+        if (codecId === AV_CODEC_ID_H264 && (this.supportedCodecs.has(FMP4_CODECS.H264) || this.supportedCodecs.has('avc1'))) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_HEVC && (this.supportedCodecs.has(FMP4_CODECS.H265) || this.supportedCodecs.has('hvc1') || this.supportedCodecs.has('hev1'))) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_AV1 && (this.supportedCodecs.has(FMP4_CODECS.AV1) || this.supportedCodecs.has('av01'))) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if audio codec is supported.
+     *
+     * @param codecId - Codec ID
+     *
+     * @returns True if AAC, FLAC, or Opus is in supported codecs
+     *
+     * @internal
+     */
+    isAudioCodecSupported(codecId) {
+        if (codecId === AV_CODEC_ID_AAC && this.supportedCodecs.has(FMP4_CODECS.AAC)) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_FLAC && this.supportedCodecs.has(FMP4_CODECS.FLAC)) {
+            return true;
+        }
+        if (codecId === AV_CODEC_ID_OPUS && this.supportedCodecs.has(FMP4_CODECS.OPUS)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Process buffer in box mode - buffers until complete boxes are available.
+     *
+     * @param chunk - Incoming data chunk from FFmpeg
+     *
+     * @internal
+     */
+    processBoxMode(chunk) {
+        // If we have an incomplete box from previous chunk, append to it
+        if (this.incompleteBoxBuffer) {
+            chunk = Buffer.concat([this.incompleteBoxBuffer, chunk]);
+            this.incompleteBoxBuffer = null;
+        }
+        let offset = 0;
+        const boxes = [];
+        while (offset + 8 <= chunk.length) {
+            // Read box header
+            const boxSize = chunk.readUInt32BE(offset);
+            const boxType = chunk.toString('ascii', offset + 4, offset + 8);
+            // Check if we have the complete box
+            if (offset + boxSize > chunk.length) {
+                // Box is incomplete - save for next chunk
+                this.incompleteBoxBuffer = chunk.subarray(offset);
+                break;
+            }
+            // We have the complete box - parse it
+            const box = {
+                type: boxType,
+                size: boxSize,
+                data: chunk.subarray(offset + 8, offset + boxSize),
+                offset: offset,
+            };
+            boxes.push(box);
+            // Move to next box
+            offset += boxSize;
+            // Safety check: invalid box size
+            if (boxSize < 8) {
+                break;
+            }
+        }
+        // If we have complete boxes, send them to the callback
+        if (boxes.length > 0) {
+            this.options.onData(chunk.subarray(0, offset), {
+                isComplete: true,
+                boxes,
+            });
+        }
+    }
+}
+//# sourceMappingURL=fmp4-stream.js.map

package/dist/api/fmp4-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmp4-stream.js","sourceRoot":"","sources":["../../src/api/fmp4-stream.ts"],"names":[],"mappings":"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"}

package/dist/api/hardware.d.ts

@@ -1,5 +1,7 @@
-import { Codec, HardwareDeviceContext } from '../lib/index.js';
-import type { AVCodecID, AVHWDeviceType, AVPixelFormat, FFDecoderCodec, FFEncoderCodec } from '../constants/index.js';
+import { Codec } from '../lib/codec.js';
+import { HardwareDeviceContext } from '../lib/hardware-device-context.js';
+import { Stream } from '../lib/stream.js';
+import type { AVCodecID, AVHWDeviceType, AVPixelFormat, FFDecoderCodec, FFEncoderCodec, FFHWDeviceType } from '../constants/index.js';
 import type { BaseCodecName, HardwareOptions } from './types.js';
 /**
  * High-level hardware acceleration management.
@@ -120,7 +122,57 @@ export declare class HardwareContext implements Disposable {
      * @see {@link auto} For automatic detection
      * @see {@link HardwareDeviceContext} For low-level API
      */
-    static create(deviceType: AVHWDeviceType, device?: string, options?: Record<string, string>): HardwareContext | null;
+    static create(deviceType: AVHWDeviceType | FFHWDeviceType, device?: string, options?: Record<string, string>): HardwareContext | null;
+    /**
+     * Create a derived hardware device context.
+     *
+     * Creates a new hardware context derived from an existing one.
+     * Allows creating contexts on different device types that can share
+     * memory or resources with the source device. Useful for cross-device
+     * pipelines (e.g., VAAPI → OpenCL, CUDA → Vulkan).
+     *
+     * Direct mapping to av_hwdevice_ctx_create_derived().
+     *
+     * @param source - Source hardware context to derive from
+     *
+     * @param targetType - Target device type to create
+     *
+     * @returns New hardware context or null if derivation fails
+     *
+     * @example
+     * ```typescript
+     * import { AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_OPENCL } from 'node-av/constants';
+     *
+     * // Create VAAPI device for decoding
+     * const vaapi = HardwareContext.create(AV_HWDEVICE_TYPE_VAAPI);
+     *
+     * // Derive OpenCL device for filtering (shares memory with VAAPI)
+     * const opencl = HardwareContext.derive(vaapi, AV_HWDEVICE_TYPE_OPENCL);
+     *
+     * if (opencl) {
+     *   // Decode with VAAPI
+     *   const decoder = await Decoder.create(stream, { hardware: vaapi });
+     *
+     *   // Filter with OpenCL (overrides frame's VAAPI context)
+     *   const filter = FilterAPI.create('program_opencl=...', { hardware: opencl });
+     *
+     *   for await (const frame of decoder.frames()) {
+     *     // frame has VAAPI context, but filter uses OpenCL
+     *     const filtered = await filter.apply(frame);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // CUDA → Vulkan derivation
+     * const cuda = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
+     * const vulkan = HardwareContext.derive(cuda, AV_HWDEVICE_TYPE_VULKAN);
+     * ```
+     *
+     * @see {@link create} For creating independent device
+     */
+    static derive(source: HardwareContext, targetType: AVHWDeviceType | FFHWDeviceType): HardwareContext | null;
     /**
      * List all available hardware device types.
      *
@@ -175,7 +227,7 @@ export declare class HardwareContext implements Disposable {
      * // Output: "cuda" or "videotoolbox" etc.
      * ```
      */
-    get deviceTypeName(): string;
+    get deviceTypeName(): FFHWDeviceType;
     /**
      * Get the device pixel format.
      *
@@ -257,7 +309,7 @@ export declare class HardwareContext implements Disposable {
      * Returns null if no hardware encoder is available for the codec.
      * Automatically tests encoder viability before returning.
      *
-     * @param codec - Generic codec name (e.g., 'h264', 'hevc', 'av1') or AVCodecID
+     * @param codecOrStream - Generic codec name (e.g., 'h264', 'hevc', 'av1'), AVCodecID or Stream
      *
      * @param validate - Whether to validate encoder by testing (default: false)
      *
@@ -283,7 +335,7 @@ export declare class HardwareContext implements Disposable {
      *
      * @see {@link Encoder.create} For using the codec
      */
-    getEncoderCodec(codec: BaseCodecName | AVCodecID, validate?: boolean): Codec | null;
+    getEncoderCodec(codecOrStream: BaseCodecName | AVCodecID | Stream, validate?: boolean): Codec | null;
     /**
      * Get the appropriate decoder codec for a given base codec name.
      *