node-av 1.3.0 → 2.1.0

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

@@ -3,15 +3,20 @@ import { Encoder } from './encoder.js';
 import type { IRational, Packet, Stream } from '../lib/index.js';
 import type { IOOutputCallbacks, MediaOutputOptions } from './types.js';
 export interface StreamDescription {
+    initialized: boolean;
     stream: Stream;
-    timeBase: IRational;
-    isStreamCopy: boolean;
+    source: Encoder | Stream;
+    timeBase?: IRational;
     sourceTimeBase?: IRational;
+    isStreamCopy: boolean;
+    bufferedPackets: Packet[];
 }
 /**
  * High-level media output for writing and muxing media files.
  *
  * Provides simplified access to media muxing and file writing operations.
+ * Automatically manages header and trailer writing - header is written on first packet,
+ * trailer is written on close. Supports lazy initialization for both encoders and streams.
  * Handles stream configuration, packet writing, and format management.
  * Supports files, URLs, and custom I/O with automatic cleanup.
  * Essential component for media encoding pipelines and transcoding.
@@ -27,14 +32,11 @@ export interface StreamDescription {
  * const videoIdx = output.addStream(videoEncoder);
  * const audioIdx = output.addStream(audioEncoder);
  *
- * // Write header
- * await output.writeHeader();
- *
- * // Write packets
+ * // Write packets - header written automatically on first packet
  * await output.writePacket(packet, videoIdx);
  *
- * // Write trailer and close
- * await output.writeTrailer();
+ * // Close - trailer written automatically
+ * // (automatic with await using)
  * ```
  *
  * @example
@@ -45,8 +47,8 @@ export interface StreamDescription {
  *
  * // Copy stream configuration
  * const videoIdx = output.addStream(input.video());
- * await output.writeHeader();
  *
+ * // Process packets - header/trailer handled automatically
  * for await (const packet of input.packets()) {
  *   await output.writePacket(packet, videoIdx);
  *   packet.free();
@@ -57,13 +59,14 @@ export interface StreamDescription {
  * @see {@link Encoder} For encoding frames to packets
  * @see {@link FormatContext} For low-level API
  */
-export declare class MediaOutput implements AsyncDisposable {
+export declare class MediaOutput implements AsyncDisposable, Disposable {
     private formatContext;
     private streams;
     private ioContext?;
     private headerWritten;
     private trailerWritten;
-    private closed;
+    private isClosed;
+    private headerWritePromise?;
     /**
      * @internal
      */
@@ -78,7 +81,9 @@ export declare class MediaOutput implements AsyncDisposable {
      * Direct mapping to avformat_alloc_output_context2() and avio_open2().
      *
      * @param target - File path, URL, or I/O callbacks
+     *
      * @param options - Output configuration options
+     *
      * @returns Opened media output instance
      *
      * @throws {Error} If format required for custom I/O
@@ -123,25 +128,69 @@ export declare class MediaOutput implements AsyncDisposable {
      * @see {@link IOOutputCallbacks} For custom I/O interface
      */
     static open(target: string | IOOutputCallbacks, options?: MediaOutputOptions): Promise<MediaOutput>;
+    /**
+     * Open media output for writing synchronously.
+     * Synchronous version of open.
+     *
+     * Creates and configures output context for muxing.
+     * Automatically creates directories for file output.
+     * Supports files, URLs, and custom I/O callbacks.
+     *
+     * Direct mapping to avformat_alloc_output_context2() and avio_open2().
+     *
+     * @param target - File path, URL, or I/O callbacks
+     *
+     * @param options - Output configuration options
+     *
+     * @returns Opened media output instance
+     *
+     * @throws {Error} If format required for custom I/O
+     *
+     * @throws {FFmpegError} If allocation or opening fails
+     *
+     * @example
+     * ```typescript
+     * // Create file output
+     * using output = MediaOutput.openSync('output.mp4');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Create output with specific format
+     * using output = MediaOutput.openSync('output.ts', {
+     *   format: 'mpegts'
+     * });
+     * ```
+     *
+     * @see {@link open} For async version
+     */
+    static openSync(target: string | IOOutputCallbacks, options?: MediaOutputOptions): MediaOutput;
     /**
      * Add a stream to the output.
      *
      * Configures output stream from encoder or input stream.
-     * Must be called before writeHeader().
+     * Must be called before writing any packets.
      * Returns stream index for packet writing.
      *
-     * Direct mapping to avformat_new_stream() and avcodec_parameters_copy().
+     * Streams are initialized lazily - codec parameters are configured
+     * automatically when the first packet is written. This allows encoders
+     * to be initialized from frame properties.
+     *
+     * Direct mapping to avformat_new_stream().
      *
      * @param source - Encoder or stream to add
+     *
      * @param options - Stream configuration options
+     *
      * @param options.timeBase - Optional custom timebase for the stream
+     *
      * @returns Stream index for packet writing
      *
-     * @throws {Error} If called after header written or output closed
+     * @throws {Error} If called after packets have been written or output closed
      *
      * @example
      * ```typescript
-     * // Add stream from encoder
+     * // Add stream from encoder (lazy initialization)
      * const videoIdx = output.addStream(videoEncoder);
      * const audioIdx = output.addStream(audioEncoder);
      * ```
@@ -164,20 +213,28 @@ export declare class MediaOutput implements AsyncDisposable {
      * Write a packet to the output.
      *
      * Writes muxed packet to the specified stream.
-     * Automatically handles timestamp rescaling.
-     * Must be called after writeHeader() and before writeTrailer().
+     * Automatically handles:
+     * - Stream initialization on first packet (lazy initialization)
+     * - Codec parameter configuration from encoder or input stream
+     * - Header writing on first packet
+     * - Timestamp rescaling between source and output timebases
+     *
+     * For encoder sources, the encoder must have processed at least one frame
+     * before packets can be written (encoder must be initialized).
      *
-     * Direct mapping to av_interleaved_write_frame().
+     * Direct mapping to avformat_write_header() (on first packet) and av_interleaved_write_frame().
      *
      * @param packet - Packet to write
+     *
      * @param streamIndex - Target stream index
-     * @throws {Error} If stream invalid or called at wrong time
+     *
+     * @throws {Error} If stream invalid or encoder not initialized
      *
      * @throws {FFmpegError} If write fails
      *
      * @example
      * ```typescript
-     * // Write encoded packet
+     * // Write encoded packet - header written automatically on first packet
      * const packet = await encoder.encode(frame);
      * if (packet) {
      *   await output.writePacket(packet, videoIdx);
@@ -197,64 +254,61 @@ export declare class MediaOutput implements AsyncDisposable {
      * ```
      *
      * @see {@link addStream} For adding streams
-     * @see {@link writeHeader} Must be called first
      */
     writePacket(packet: Packet, streamIndex: number): Promise<void>;
     /**
-     * Write file header.
+     * Write a packet to the output synchronously.
+     * Synchronous version of writePacket.
      *
-     * Writes format header with stream configuration.
-     * Must be called after adding all streams and before writing packets.
-     * Finalizes stream parameters and initializes muxer.
+     * Writes muxed packet to the specified stream.
+     * Automatically handles:
+     * - Stream initialization on first packet (lazy initialization)
+     * - Codec parameter configuration from encoder or input stream
+     * - Header writing on first packet
+     * - Timestamp rescaling between source and output timebases
+     *
+     * For encoder sources, the encoder must have processed at least one frame
+     * before packets can be written (encoder must be initialized).
      *
-     * Direct mapping to avformat_write_header().
+     * Direct mapping to avformat_write_header() (on first packet) and av_interleaved_write_frame().
      *
-     * @throws {Error} If already written or output closed
+     * @param packet - Packet to write
+     *
+     * @param streamIndex - Target stream index
+     *
+     * @throws {Error} If stream invalid or encoder not initialized
      *
      * @throws {FFmpegError} If write fails
      *
      * @example
      * ```typescript
-     * // Standard workflow
-     * const output = await MediaOutput.open('output.mp4');
-     * output.addStream(encoder);
-     * await output.writeHeader();
-     * // Now ready to write packets
+     * // Write encoded packet - header written automatically on first packet
+     * const packet = encoder.encodeSync(frame);
+     * if (packet) {
+     *   output.writePacketSync(packet, videoIdx);
+     *   packet.free();
+     * }
      * ```
      *
-     * @see {@link addStream} Must add streams first
-     * @see {@link writePacket} Can write packets after
-     * @see {@link writeTrailer} Must call at end
-     */
-    writeHeader(): Promise<void>;
-    /**
-     * Write file trailer.
-     *
-     * Writes format trailer and finalizes the file.
-     * Must be called after all packets are written.
-     * Flushes any buffered data and updates file headers.
-     *
-     * Direct mapping to av_write_trailer().
-     *
-     * @throws {Error} If header not written or already written
-     *
-     * @throws {FFmpegError} If write fails
-     *
      * @example
      * ```typescript
-     * // Finalize output
-     * await output.writeTrailer();
-     * await output.close();
+     * // Stream copy with packet processing
+     * for (const packet of input.packetsSync()) {
+     *   if (packet.streamIndex === inputVideoIdx) {
+     *     output.writePacketSync(packet, outputVideoIdx);
+     *   }
+     *   packet.free();
+     * }
      * ```
      *
-     * @see {@link writeHeader} Must be called first
-     * @see {@link close} For cleanup after trailer
+     * @see {@link writePacket} For async version
      */
-    writeTrailer(): Promise<void>;
+    writePacketSync(packet: Packet, streamIndex: number): void;
     /**
      * Close media output and free resources.
      *
-     * Writes trailer if needed and releases all resources.
+     * Automatically writes trailer if header was written.
+     * Closes the output file and releases all resources.
      * Safe to call multiple times.
      * Automatically called by Symbol.asyncDispose.
      *
@@ -262,7 +316,7 @@ export declare class MediaOutput implements AsyncDisposable {
      * ```typescript
      * const output = await MediaOutput.open('output.mp4');
      * try {
-     *   // Use output
+     *   // Use output - trailer written automatically on close
      * } finally {
      *   await output.close();
      * }
@@ -272,60 +326,27 @@ export declare class MediaOutput implements AsyncDisposable {
      */
     close(): Promise<void>;
     /**
-     * Get stream information.
-     *
-     * Returns internal stream info for the specified index.
+     * Close media output and free resources synchronously.
+     * Synchronous version of close.
      *
-     * @param streamIndex - Stream index
-     * @returns Stream info or undefined
-     *
-     * @example
-     * ```typescript
-     * const info = output.getStreamInfo(0);
-     * console.log(`Stream 0 timebase: ${info?.timeBase.num}/${info?.timeBase.den}`);
-     * ```
-     */
-    getStreamInfo(streamIndex: number): StreamDescription | undefined;
-    /**
-     * Get all stream indices.
-     *
-     * Returns array of all added stream indices.
-     *
-     * @returns Array of stream indices
-     *
-     * @example
-     * ```typescript
-     * const indices = output.getStreamIndices();
-     * console.log(`Output has ${indices.length} streams`);
-     * ```
-     */
-    getStreamIndices(): number[];
-    /**
-     * Check if header has been written.
-     *
-     * @returns true if header written
+     * Automatically writes trailer if header was written.
+     * Closes the output file and releases all resources.
+     * Safe to call multiple times.
+     * Automatically called by Symbol.dispose.
      *
      * @example
      * ```typescript
-     * if (!output.isHeaderWritten()) {
-     *   await output.writeHeader();
+     * const output = MediaOutput.openSync('output.mp4');
+     * try {
+     *   // Use output - trailer written automatically on close
+     * } finally {
+     *   output.closeSync();
      * }
      * ```
-     */
-    isHeaderWritten(): boolean;
-    /**
-     * Check if trailer has been written.
-     *
-     * @returns true if trailer written
      *
-     * @example
-     * ```typescript
-     * if (!output.isTrailerWritten()) {
-     *   await output.writeTrailer();
-     * }
-     * ```
+     * @see {@link close} For async version
      */
-    isTrailerWritten(): boolean;
+    closeSync(): void;
     /**
      * Get underlying format context.
      *
@@ -353,4 +374,21 @@ export declare class MediaOutput implements AsyncDisposable {
      * @see {@link close} For manual cleanup
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Dispose of media output synchronously.
+     *
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling closeSync().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using output = MediaOutput.openSync('output.mp4');
+     *   // Use output...
+     * } // Automatically closed
+     * ```
+     *
+     * @see {@link closeSync} For manual cleanup
+     */
+    [Symbol.dispose](): void;
 }