node-av 0.0.1

package/dist/api/media-output.js

@@ -0,0 +1,486 @@
+/**
+ * MediaOutput - Unified Output Handler for FFmpeg
+ *
+ * Provides a high-level interface for writing media to various destinations.
+ * Supports files, streams, and custom IO with automatic format configuration.
+ *
+ * Central entry point for all media output operations.
+ * Manages FormatContext lifecycle and provides stream management.
+ *
+ * @module api/media-output
+ */
+import { AVFMT_FLAG_CUSTOM_IO, AVFMT_NOFILE, AVIO_FLAG_WRITE, FFmpegError, FormatContext, IOContext, Rational } from '../lib/index.js';
+import { Encoder } from './encoder.js';
+/**
+ * MediaOutput - High-level media output handler.
+ *
+ * Creates and manages media containers for writing encoded streams.
+ * Automatically handles format setup and stream configuration.
+ *
+ * Manages the FormatContext and provides convenient methods for
+ * adding streams, writing packets, and finalizing output.
+ *
+ * @example
+ * ```typescript
+ * import { MediaOutput, Encoder } from 'node-av/api';
+ *
+ * // Open output file
+ * const output = await MediaOutput.open('output.mp4');
+ *
+ * // Add encoder stream
+ * const encoder = await Encoder.create('libx264', {
+ *   width: 1920,
+ *   height: 1080,
+ *   pixelFormat: AV_PIX_FMT_YUV420P
+ * });
+ * const streamIdx = output.addStream(encoder);
+ *
+ * // Write header, packets, trailer
+ * await output.writeHeader();
+ * await output.writePacket(packet, streamIdx);
+ * await output.writeTrailer();
+ * await output.close();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream copy without re-encoding
+ * const input = await MediaInput.open('input.mp4');
+ * const output = await MediaOutput.open('output.mkv');
+ *
+ * const videoStream = input.video();
+ * const streamIdx = output.addStream(videoStream);
+ *
+ * await output.writeHeader();
+ * for await (const packet of input.packets()) {
+ *   if (packet.streamIndex === videoStream.index) {
+ *     await output.writePacket(packet, streamIdx);
+ *   }
+ * }
+ * await output.writeTrailer();
+ * ```
+ */
+export class MediaOutput {
+    formatContext;
+    streams = new Map();
+    ioContext;
+    headerWritten = false;
+    trailerWritten = false;
+    closed = false;
+    /**
+     * Private constructor - use MediaOutput.open() instead.
+     *
+     * Initializes the output with a new FormatContext.
+     * The actual format setup happens in the static factory method.
+     */
+    constructor() {
+        this.formatContext = new FormatContext();
+    }
+    /**
+     * Opens a media output for writing with custom IO callbacks or stream URL or file output
+     *
+     * Creates a FormatContext and prepares the output for writing.
+     * Automatically detects format from filename/URL if not specified.
+     *
+     * If io callbacks is used, it creates a FormatContext with custom IO handling.
+     * Format must be explicitly specified for custom IO.
+     *
+     * Uses avformat_alloc_output_context2() and avio_alloc_context() internally.
+     *
+     * @param target - File path or stream URL or custom IO callbacks
+     * @param options - Optional configuration
+     *
+     * @returns Promise resolving to MediaOutput instance
+     *
+     * @throws {Error} If format not specified or context allocation fails
+     *
+     * @example
+     * ```typescript
+     * const callbacks = {
+     *   write: (buffer) => myStream.write(buffer),
+     *   seek: (offset, whence) => offset
+     * };
+     * const output = await MediaOutput.open(callbacks, { format: 'mp4' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const output = await MediaOutput.open('output.mp4');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const output = await MediaOutput.open('rtmp://server/live/streamkey', { format: 'flv' });
+     * ```
+     */
+    static async open(target, options) {
+        const output = new MediaOutput();
+        try {
+            if (typeof target === 'string') {
+                // File or stream URL
+                const ret = output.formatContext.allocOutputContext2(null, options?.format ?? null, target === '' ? null : target);
+                FFmpegError.throwIfError(ret, 'Failed to allocate output context');
+                // Check if we need to open IO
+                const oformat = output.formatContext.oformat;
+                if (target && oformat && !(oformat.flags & AVFMT_NOFILE)) {
+                    // For file-based formats, we need to open the file using avio_open2
+                    // FFmpeg will manage the AVIOContext internally
+                    output.ioContext = new IOContext();
+                    const openRet = await output.ioContext.open2(target, AVIO_FLAG_WRITE);
+                    FFmpegError.throwIfError(openRet, `Failed to open output file: ${target}`);
+                    output.formatContext.pb = output.ioContext;
+                }
+            }
+            else {
+                // Custom IO with callbacks - format is required
+                if (!options?.format) {
+                    throw new Error('Format must be specified for custom IO');
+                }
+                const ret = output.formatContext.allocOutputContext2(null, options.format, null);
+                FFmpegError.throwIfError(ret, 'Failed to allocate output context');
+                // Setup custom IO with callbacks
+                output.ioContext = new IOContext();
+                output.ioContext.allocContextWithCallbacks(options.bufferSize ?? 4096, 1, target.read, target.write, target.seek);
+                output.ioContext.maxPacketSize = options.bufferSize ?? 4096;
+                output.formatContext.pb = output.ioContext;
+                output.formatContext.flags = AVFMT_FLAG_CUSTOM_IO;
+            }
+            return output;
+        }
+        catch (error) {
+            // Cleanup on error
+            if (output.ioContext) {
+                try {
+                    if (output.formatContext.flags & AVFMT_FLAG_CUSTOM_IO) {
+                        // Clear the pb reference first
+                        output.formatContext.pb = null;
+                        // For custom IO with callbacks, free the context
+                        output.ioContext.freeContext();
+                    }
+                    else {
+                        // For file-based IO, close the file handle
+                        await output.ioContext.closep();
+                    }
+                }
+                catch {
+                    // Ignore errors
+                }
+            }
+            if (output.formatContext) {
+                try {
+                    output.formatContext.freeContext();
+                }
+                catch {
+                    // Ignore errors
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Adds a stream to the output container.
+     *
+     * Creates a new stream in the output format context.
+     * Copies codec parameters from encoder or input stream.
+     *
+     * Uses avformat_new_stream() and avcodec_parameters_copy() internally.
+     *
+     * @param source - Encoder for transcoding or Stream for copying
+     * @param options - Optional stream configuration
+     * @param options.timeBase - Custom output timebase for the stream.
+     *                           If not specified, uses the source's timebase.
+     *                           When set, packets will be automatically rescaled
+     *                           from source timebase to this output timebase.
+     *
+     * @returns Stream index for packet writing
+     *
+     * @throws {Error} If called after header is written or output is closed
+     *
+     * @example
+     * ```typescript
+     * // Add encoder stream (transcoding) - uses encoder's timebase
+     * const encoder = await Encoder.create('libx264', { width: 1920, height: 1080 });
+     * const streamIdx = output.addStream(encoder);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Add stream for direct copy - uses input stream's timebase
+     * const inputStream = input.video();
+     * const streamIdx = output.addStream(inputStream);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom output timebase (e.g., for format requirements)
+     * const streamIdx = output.addStream(encoder, {
+     *   timeBase: { num: 1, den: 90000 }  // MPEG-TS standard
+     * });
+     * // Packets from encoder will be automatically rescaled to 1/90000
+     * ```
+     */
+    addStream(source, options) {
+        if (this.closed) {
+            throw new Error('MediaOutput is closed');
+        }
+        if (this.headerWritten) {
+            throw new Error('Cannot add streams after header is written');
+        }
+        const stream = this.formatContext.newStream(null);
+        if (!stream) {
+            throw new Error('Failed to create new stream');
+        }
+        let isStreamCopy = false;
+        let sourceTimeBase;
+        if (source instanceof Encoder) {
+            // Transcoding with encoder
+            const codecContext = source.getCodecContext();
+            if (!codecContext) {
+                throw new Error('Failed to get codec context from encoder');
+            }
+            const ret = stream.codecpar.fromContext(codecContext);
+            FFmpegError.throwIfError(ret, 'Failed to copy codec parameters from encoder');
+            // Store the encoder's timebase as source (we'll need it for rescaling)
+            sourceTimeBase = codecContext.timeBase;
+            // Output stream uses encoder's timebase (or custom if specified)
+            stream.timeBase = options?.timeBase ? new Rational(options.timeBase.num, options.timeBase.den) : codecContext.timeBase;
+        }
+        else {
+            // Stream copy
+            const ret = source.codecpar.copy(stream.codecpar);
+            FFmpegError.throwIfError(ret, 'Failed to copy codec parameters');
+            // Store the input stream's timebase as source (we'll need it for rescaling)
+            sourceTimeBase = source.timeBase;
+            // Output stream uses input stream's timebase (or custom if specified)
+            stream.timeBase = options?.timeBase ? new Rational(options.timeBase.num, options.timeBase.den) : source.timeBase;
+            stream.codecpar.codecTag = 0; // Important for format compatibility
+            isStreamCopy = true;
+        }
+        this.streams.set(stream.index, {
+            stream,
+            timeBase: stream.timeBase,
+            isStreamCopy,
+            sourceTimeBase,
+        });
+        return stream.index;
+    }
+    /**
+     * Writes a packet to the output container.
+     *
+     * Writes an encoded packet to the specified stream.
+     * Automatically sets the stream index on the packet.
+     *
+     * Uses av_interleaved_write_frame() internally.
+     *
+     * @param packet - Packet to write
+     * @param streamIndex - Target stream index
+     *
+     * @throws {Error} If header not written, trailer already written, or invalid stream
+     *
+     * @example
+     * ```typescript
+     * const encoded = await encoder.encode(frame);
+     * if (encoded) {
+     *   await output.writePacket(encoded, streamIdx);
+     *   encoded.free();
+     * }
+     * ```
+     */
+    async writePacket(packet, streamIndex) {
+        if (this.closed) {
+            throw new Error('MediaOutput is closed');
+        }
+        if (!this.headerWritten) {
+            throw new Error('Header must be written before packets');
+        }
+        if (this.trailerWritten) {
+            throw new Error('Cannot write packets after trailer');
+        }
+        const streamInfo = this.streams.get(streamIndex);
+        if (!streamInfo) {
+            throw new Error(`Invalid stream index: ${streamIndex}`);
+        }
+        // Set stream index
+        packet.streamIndex = streamIndex;
+        // Rescale packet timestamps if source and output timebases differ
+        // Note: The stream's timebase may have been changed by writeHeader (e.g., MP4 uses 1/time_scale)
+        if (streamInfo.sourceTimeBase) {
+            const outputStream = this.formatContext.streams?.[streamIndex];
+            if (outputStream) {
+                // Only rescale if timebases actually differ
+                const srcTb = streamInfo.sourceTimeBase;
+                const dstTb = outputStream.timeBase;
+                if (srcTb.num !== dstTb.num || srcTb.den !== dstTb.den) {
+                    packet.rescaleTs(streamInfo.sourceTimeBase, outputStream.timeBase);
+                }
+            }
+        }
+        // Write the packet
+        const ret = await this.formatContext.interleavedWriteFrame(packet);
+        FFmpegError.throwIfError(ret, 'Failed to write packet');
+    }
+    /**
+     * Writes the output file header.
+     *
+     * Writes the container header with stream information.
+     * Must be called before writing any packets.
+     *
+     * Uses avformat_write_header() internally.
+     *
+     * @param options - Optional header options (format-specific)
+     *
+     * @throws {Error} If header already written or output is closed
+     *
+     * @example
+     * ```typescript
+     * await output.writeHeader();
+     * ```
+     */
+    async writeHeader() {
+        if (this.closed) {
+            throw new Error('MediaOutput is closed');
+        }
+        if (this.headerWritten) {
+            throw new Error('Header already written');
+        }
+        const ret = await this.formatContext.writeHeader();
+        FFmpegError.throwIfError(ret, 'Failed to write header');
+        this.headerWritten = true;
+    }
+    /**
+     * Writes the output file trailer.
+     *
+     * Finalizes the output file with necessary metadata.
+     * Should be called after all packets have been written.
+     *
+     * Uses av_write_trailer() internally.
+     *
+     * @throws {Error} If header not written, trailer already written, or output is closed
+     *
+     * @example
+     * ```typescript
+     * await output.writeTrailer();
+     * ```
+     */
+    async writeTrailer() {
+        if (this.closed) {
+            throw new Error('MediaOutput is closed');
+        }
+        if (!this.headerWritten) {
+            throw new Error('Cannot write trailer without header');
+        }
+        if (this.trailerWritten) {
+            throw new Error('Trailer already written');
+        }
+        const ret = await this.formatContext.writeTrailer();
+        FFmpegError.throwIfError(ret, 'Failed to write trailer');
+        this.trailerWritten = true;
+    }
+    /**
+     * Closes the output and releases all resources.
+     *
+     * Writes trailer if needed, closes IO context, and frees format context.
+     * Safe to call multiple times.
+     *
+     * Uses av_write_trailer(), avio_closep(), and avformat_free_context() internally.
+     *
+     * @example
+     * ```typescript
+     * await output.close();
+     * ```
+     */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        // Try to write trailer if header was written but trailer wasn't
+        try {
+            if (this.headerWritten && !this.trailerWritten) {
+                await this.formatContext.writeTrailer();
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        // Clear pb reference first to prevent use-after-free
+        if (this.ioContext) {
+            this.formatContext.pb = null;
+        }
+        // For file-based IO, close the file handle via closep
+        // For custom IO, the context will be freed below
+        if (this.ioContext && !(this.formatContext.flags & AVFMT_FLAG_CUSTOM_IO)) {
+            try {
+                await this.ioContext.closep();
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        // Free format context
+        if (this.formatContext) {
+            try {
+                this.formatContext.freeContext();
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+        // Now free custom IO context if present
+        if (this.ioContext && this.formatContext.flags & AVFMT_FLAG_CUSTOM_IO) {
+            try {
+                this.ioContext.freeContext();
+            }
+            catch {
+                // Ignore errors
+            }
+        }
+    }
+    /**
+     * Gets information about a specific stream.
+     */
+    getStreamInfo(streamIndex) {
+        return this.streams.get(streamIndex);
+    }
+    /**
+     * Gets all stream indices.
+     */
+    getStreamIndices() {
+        return Array.from(this.streams.keys());
+    }
+    /**
+     * Checks if header has been written.
+     */
+    isHeaderWritten() {
+        return this.headerWritten;
+    }
+    /**
+     * Checks if trailer has been written.
+     */
+    isTrailerWritten() {
+        return this.trailerWritten;
+    }
+    /**
+     * Gets the underlying format context.
+     *
+     * For advanced use cases requiring direct format context access.
+     */
+    getFormatContext() {
+        return this.formatContext;
+    }
+    /**
+     * AsyncDisposable implementation for using statement.
+     *
+     * Enables automatic resource cleanup with await using syntax.
+     *
+     * @example
+     * ```typescript
+     * await using output = await MediaOutput.open('output.mp4');
+     * // Output automatically closes when scope ends
+     * ```
+     */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}
+//# sourceMappingURL=media-output.js.map

package/dist/api/media-output.js.map

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

package/dist/api/pipeline.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Pipeline - Stream-based media processing pipeline
+ *
+ * Provides a Node.js-style pipeline function for chaining media processing components.
+ * Automatically handles type conversions, buffering, and flushing.
+ *
+ * Supports two modes:
+ * 1. Simple: Single stream with variable parameters
+ * 2. Named: Multiple streams with named routing with variable parameters
+ *
+ * @module api/pipeline
+ */
+import type { Frame, Packet } from '../lib/index.js';
+import type { BitStreamFilterAPI } from './bitstream-filter.js';
+import type { Decoder } from './decoder.js';
+import type { Encoder } from './encoder.js';
+import type { FilterAPI } from './filter.js';
+import type { MediaInput } from './media-input.js';
+import type { MediaOutput } from './media-output.js';
+type StreamName = 'video' | 'audio';
+type NamedInputs<K extends StreamName = StreamName> = Pick<Record<StreamName, MediaInput>, K>;
+type NamedStages<K extends StreamName = StreamName> = Pick<Record<StreamName, (Decoder | FilterAPI | FilterAPI[] | Encoder | BitStreamFilterAPI | BitStreamFilterAPI[])[] | 'passthrough'>, K>;
+type NamedOutputs<K extends StreamName = StreamName> = Pick<Record<StreamName, MediaOutput>, K>;
+/**
+ * Pipeline control interface for managing pipeline execution
+ */
+export interface PipelineControl {
+    /**
+     * Stop the pipeline gracefully
+     */
+    stop(): void;
+    /**
+     * Check if the pipeline has been stopped
+     */
+    isStopped(): boolean;
+    /**
+     * Promise that resolves when the pipeline completes
+     */
+    readonly completion: Promise<void>;
+}
+/**
+ * Full transcoding pipeline: input → decoder → encoder → output
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, encoder: Encoder, output: MediaOutput): PipelineControl;
+/**
+ * Full transcoding pipeline with filter: input → decoder → filter → encoder → output
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[], encoder: Encoder, output: MediaOutput): PipelineControl;
+/**
+ * Transcoding with bitstream filter: input → decoder → encoder → bsf → output
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, encoder: Encoder, bsf: BitStreamFilterAPI | BitStreamFilterAPI[], output: MediaOutput): PipelineControl;
+/**
+ * Full pipeline with filter and bsf: input → decoder → filter → encoder → bsf → output
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[], encoder: Encoder, bsf: BitStreamFilterAPI | BitStreamFilterAPI[], output: MediaOutput): PipelineControl;
+/**
+ * Decode + multiple filters + encode: input → decoder → filter1 → filter2 → encoder → output
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, filter1: FilterAPI, filter2: FilterAPI, encoder: Encoder, output: MediaOutput): PipelineControl;
+/**
+ * Stream copy pipeline: input → output (copies all streams)
+ */
+export declare function pipeline(source: MediaInput, output: MediaOutput): PipelineControl;
+/**
+ * Stream copy with bitstream filter: input → bsf → output
+ */
+export declare function pipeline(source: MediaInput, bsf: BitStreamFilterAPI | BitStreamFilterAPI[], output: MediaOutput): PipelineControl;
+/**
+ * Filter + encode + output: frames → filter → encoder → output
+ */
+export declare function pipeline(source: AsyncIterable<Frame>, filter: FilterAPI | FilterAPI[], encoder: Encoder, output: MediaOutput): PipelineControl;
+/**
+ * Encode + output: frames → encoder → output
+ */
+export declare function pipeline(source: AsyncIterable<Frame>, encoder: Encoder, output: MediaOutput): PipelineControl;
+/**
+ * Partial pipeline: input → decoder (returns frames)
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder): AsyncGenerator<Frame>;
+/**
+ * Partial pipeline: input → decoder → filter (returns frames)
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[]): AsyncGenerator<Frame>;
+/**
+ * Partial pipeline: input → decoder → filter → encoder (returns packets)
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, filter: FilterAPI | FilterAPI[], encoder: Encoder): AsyncGenerator<Packet>;
+/**
+ * Partial pipeline: input → decoder → encoder (returns packets)
+ */
+export declare function pipeline(source: MediaInput, decoder: Decoder, encoder: Encoder): AsyncGenerator<Packet>;
+/**
+ * Partial pipeline: frames → filter (returns frames)
+ */
+export declare function pipeline(source: AsyncIterable<Frame>, filter: FilterAPI | FilterAPI[]): AsyncGenerator<Frame>;
+/**
+ * Partial pipeline: frames → encoder (returns packets)
+ */
+export declare function pipeline(source: AsyncIterable<Frame>, encoder: Encoder): AsyncGenerator<Packet>;
+/**
+ * Partial pipeline: frames → filter → encoder (returns packets)
+ */
+export declare function pipeline(source: AsyncIterable<Frame>, filter: FilterAPI | FilterAPI[], encoder: Encoder): AsyncGenerator<Packet>;
+/**
+ * Named pipeline with single output - all streams go to the same output
+ */
+export declare function pipeline<K extends StreamName>(inputs: NamedInputs<K>, stages: NamedStages<K>, output: MediaOutput): PipelineControl;
+/**
+ * Named pipeline with multiple outputs - each stream has its own output
+ */
+export declare function pipeline<K extends StreamName>(inputs: NamedInputs<K>, stages: NamedStages<K>, outputs: NamedOutputs<K>): PipelineControl;
+/**
+ * Partial named pipeline (returns generators for further processing)
+ */
+export declare function pipeline<K extends StreamName, T extends Packet | Frame = Packet | Frame>(inputs: NamedInputs<K>, stages: NamedStages<K>): Record<K, AsyncGenerator<T>>;
+export {};