node-av 0.0.1

package/dist/api/media-output.d.ts

@@ -0,0 +1,274 @@
+/**
+ * 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 { FormatContext } from '../lib/index.js';
+import { Encoder } from './encoder.js';
+import type { IRational, Packet, Stream } from '../lib/index.js';
+import type { IOOutputCallbacks, MediaOutputOptions } from './types.js';
+interface StreamInfo {
+    stream: Stream;
+    timeBase: IRational;
+    isStreamCopy: boolean;
+    sourceTimeBase?: IRational;
+}
+/**
+ * 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 declare class MediaOutput implements AsyncDisposable {
+    private formatContext;
+    private streams;
+    private ioContext?;
+    private headerWritten;
+    private trailerWritten;
+    private closed;
+    /**
+     * Private constructor - use MediaOutput.open() instead.
+     *
+     * Initializes the output with a new FormatContext.
+     * The actual format setup happens in the static factory method.
+     */
+    private constructor();
+    /**
+     * 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 open(target: string | IOOutputCallbacks, options?: MediaOutputOptions): Promise<MediaOutput>;
+    /**
+     * 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: Encoder | Stream, options?: {
+        timeBase?: IRational;
+    }): number;
+    /**
+     * 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();
+     * }
+     * ```
+     */
+    writePacket(packet: Packet, streamIndex: number): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    writeHeader(): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    writeTrailer(): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Gets information about a specific stream.
+     */
+    getStreamInfo(streamIndex: number): StreamInfo | undefined;
+    /**
+     * Gets all stream indices.
+     */
+    getStreamIndices(): number[];
+    /**
+     * Checks if header has been written.
+     */
+    isHeaderWritten(): boolean;
+    /**
+     * Checks if trailer has been written.
+     */
+    isTrailerWritten(): boolean;
+    /**
+     * Gets the underlying format context.
+     *
+     * For advanced use cases requiring direct format context access.
+     */
+    getFormatContext(): 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
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export {};