node-av 1.3.0 → 2.0.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();
@@ -63,7 +65,8 @@ export declare class MediaOutput implements AsyncDisposable {
     private ioContext?;
     private headerWritten;
     private trailerWritten;
-    private closed;
+    private isClosed;
+    private headerWritePromise?;
     /**
      * @internal
      */
@@ -127,21 +130,25 @@ export declare class MediaOutput implements AsyncDisposable {
      * 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 +171,26 @@ 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
      *
-     * Direct mapping to av_interleaved_write_frame().
+     * 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() (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 +210,13 @@ 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.
-     *
-     * Writes format header with stream configuration.
-     * Must be called after adding all streams and before writing packets.
-     * Finalizes stream parameters and initializes muxer.
-     *
-     * Direct mapping to avformat_write_header().
-     *
-     * @throws {Error} If already written or output closed
-     *
-     * @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
-     * ```
-     *
-     * @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();
-     * ```
-     *
-     * @see {@link writeHeader} Must be called first
-     * @see {@link close} For cleanup after trailer
-     */
-    writeTrailer(): Promise<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 +224,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();
      * }
@@ -271,61 +233,6 @@ export declare class MediaOutput implements AsyncDisposable {
      * @see {@link Symbol.asyncDispose} For automatic cleanup
      */
     close(): Promise<void>;
-    /**
-     * Get stream information.
-     *
-     * Returns internal stream info for the specified index.
-     *
-     * @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
-     *
-     * @example
-     * ```typescript
-     * if (!output.isHeaderWritten()) {
-     *   await output.writeHeader();
-     * }
-     * ```
-     */
-    isHeaderWritten(): boolean;
-    /**
-     * Check if trailer has been written.
-     *
-     * @returns true if trailer written
-     *
-     * @example
-     * ```typescript
-     * if (!output.isTrailerWritten()) {
-     *   await output.writeTrailer();
-     * }
-     * ```
-     */
-    isTrailerWritten(): boolean;
     /**
      * Get underlying format context.
      *