node-av 3.1.2 → 4.0.0

package/dist/api/{media-output.d.ts → muxer.d.ts}

@@ -1,18 +1,16 @@
-import { FormatContext } from '../lib/index.js';
+import { FormatContext } from '../lib/format-context.js';
+import { Packet } from '../lib/packet.js';
 import { Encoder } from './encoder.js';
-import type { IRational, OutputFormat, Packet, Stream } from '../lib/index.js';
+import type { OutputFormat, Stream } from '../lib/index.js';
 import type { IOOutputCallbacks, MediaOutputOptions } from './types.js';
-export interface StreamDescription {
-    initialized: boolean;
-    stream: Stream;
-    source: Encoder | Stream;
-    timeBase?: IRational;
-    sourceTimeBase?: IRational;
-    isStreamCopy: boolean;
-    bufferedPackets: Packet[];
+export interface AddStreamOptionsWithEncoder {
+    encoder?: Encoder;
+}
+export interface AddStreamOptionsWithInputStream {
+    inputStream?: Stream;
 }
 /**
- * High-level media output for writing and muxing media files.
+ * High-level muxer 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,
@@ -23,10 +21,10 @@ export interface StreamDescription {
  *
  * @example
  * ```typescript
- * import { MediaOutput } from 'node-av/api';
+ * import { Muxer } from 'node-av/api';
  *
  * // Create output file
- * await using output = await MediaOutput.open('output.mp4');
+ * await using output = await Muxer.open('output.mp4');
  *
  * // Add streams from encoders
  * const videoIdx = output.addStream(videoEncoder);
@@ -42,8 +40,8 @@ export interface StreamDescription {
  * @example
  * ```typescript
  * // Stream copy
- * await using input = await MediaInput.open('input.mp4');
- * await using output = await MediaOutput.open('output.mp4');
+ * await using input = await Demuxer.open('input.mp4');
+ * await using output = await Muxer.open('output.mp4');
  *
  * // Copy stream configuration
  * const videoIdx = output.addStream(input.video());
@@ -55,24 +53,32 @@ export interface StreamDescription {
  * }
  * ```
  *
- * @see {@link MediaInput} For reading media files
+ * @see {@link Demuxer} For reading media files
  * @see {@link Encoder} For encoding frames to packets
  * @see {@link FormatContext} For low-level API
  */
-export declare class MediaOutput implements AsyncDisposable, Disposable {
+export declare class Muxer implements AsyncDisposable, Disposable {
     private formatContext;
+    private options;
     private _streams;
     private ioContext?;
     private headerWritten;
+    private headerWritePromise?;
     private trailerWritten;
     private isClosed;
-    private headerWritePromise?;
+    private syncQueue?;
+    private sqPacket?;
+    private containerMetadataCopied;
+    private writeQueue?;
+    private writeWorkerPromise?;
     /**
+     * @param options - Media output options
+     *
      * @internal
      */
     private constructor();
     /**
-     * Open media output for writing.
+     * Open muxer for writing.
      *
      * Creates and configures output context for muxing.
      * Automatically creates directories for file output.
@@ -84,7 +90,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @param options - Output configuration options
      *
-     * @returns Opened media output instance
+     * @returns Opened muxer instance
      *
      * @throws {Error} If format required for custom I/O
      *
@@ -93,13 +99,13 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * @example
      * ```typescript
      * // Create file output
-     * await using output = await MediaOutput.open('output.mp4');
+     * await using output = await Muxer.open('output.mp4');
      * ```
      *
      * @example
      * ```typescript
      * // Create output with specific format
-     * await using output = await MediaOutput.open('output.ts', {
+     * await using output = await Muxer.open('output.ts', {
      *   format: 'mpegts'
      * });
      * ```
@@ -118,7 +124,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *   }
      * };
      *
-     * await using output = await MediaOutput.open(callbacks, {
+     * await using output = await Muxer.open(callbacks, {
      *   format: 'mp4',
      *   bufferSize: 8192
      * });
@@ -127,12 +133,12 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * @see {@link MediaOutputOptions} For configuration options
      * @see {@link IOOutputCallbacks} For custom I/O interface
      */
-    static open(target: string, options?: MediaOutputOptions): Promise<MediaOutput>;
+    static open(target: string, options?: MediaOutputOptions): Promise<Muxer>;
     static open(target: IOOutputCallbacks, options: MediaOutputOptions & {
         format: string;
-    }): Promise<MediaOutput>;
+    }): Promise<Muxer>;
     /**
-     * Open media output for writing synchronously.
+     * Open muxer for writing synchronously.
      * Synchronous version of open.
      *
      * Creates and configures output context for muxing.
@@ -145,7 +151,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @param options - Output configuration options
      *
-     * @returns Opened media output instance
+     * @returns Opened muxer instance
      *
      * @throws {Error} If format required for custom I/O
      *
@@ -154,23 +160,23 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * @example
      * ```typescript
      * // Create file output
-     * using output = MediaOutput.openSync('output.mp4');
+     * using output = Muxer.openSync('output.mp4');
      * ```
      *
      * @example
      * ```typescript
      * // Create output with specific format
-     * using output = MediaOutput.openSync('output.ts', {
+     * using output = Muxer.openSync('output.ts', {
      *   format: 'mpegts'
      * });
      * ```
      *
      * @see {@link open} For async version
      */
-    static openSync(target: string, options?: MediaOutputOptions): MediaOutput;
+    static openSync(target: string, options?: MediaOutputOptions): Muxer;
     static openSync(target: IOOutputCallbacks, options: MediaOutputOptions & {
         format: string;
-    }): MediaOutput;
+    }): Muxer;
     /**
      * Check if output is open.
      *
@@ -181,7 +187,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * }
      * ```
      */
-    get isOutputOpen(): boolean;
+    get isOpen(): boolean;
     /**
      * Check if output is initialized.
      *
@@ -195,7 +201,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * }
      * ```
      */
-    get isOutputInitialized(): boolean;
+    get streamsInitialized(): boolean;
     /**
      * Get all streams in the media.
      *
@@ -206,7 +212,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * }
      * ```
      */
-    get streams(): Stream[] | null;
+    get streams(): Stream[];
     /**
      * Get format name.
      *
@@ -248,22 +254,67 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      */
     get mimeType(): string | null;
     /**
-     * Add a stream to the output.
+     * Add a stream to the output (encoder-only mode).
+     *
+     * Configures output stream from encoder. Stream is initialized lazily from first encoded frame.
+     * Use this when generating frames programmatically without an input stream.
+     *
+     * @param encoder - Encoder for encoding frames to packets
+     *
+     * @param options - Stream configuration options
+     *
+     * @param options.inputStream - Optional input stream for metadata/properties
+     *
+     * @param options.timeBase - Optional custom timebase for the stream
      *
-     * Configures output stream from encoder or input stream.
+     * @returns Stream index for packet writing
+     *
+     * @throws {Error} If called after packets have been written or output closed
+     *
+     * @example
+     * ```typescript
+     * // Encoder-only (e.g., frame generator)
+     * const encoder = await Encoder.create(FF_ENCODER_LIBX264);
+     * const streamIdx = output.addStream(encoder);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Encoder with input stream for metadata
+     * const streamIdx = output.addStream(encoder, {
+     *   inputStream: input.video()
+     * });
+     * ```
+     */
+    addStream(encoder: Encoder, options?: AddStreamOptionsWithInputStream): number;
+    /**
+     * Add a stream to the output (stream copy or transcoding mode).
+     *
+     * Configures output stream from input stream and optional encoder.
      * Must be called before writing any packets.
      * Returns stream index for packet writing.
      *
-     * Streams are initialized lazily - codec parameters are configured
-     * automatically when the first packet is written. This allows encoders
-     * to be initialized from frame properties.
+     * Automatically copies from input stream:
+     * - Codec parameters (stream copy mode)
+     * - Metadata
+     * - Disposition flags
+     * - Frame rates and aspect ratios
+     * - Duration hints
+     * - HDR/Dolby Vision side data (coded_side_data)
+     *
+     * When encoder is provided:
+     * - Stream is initialized lazily from first encoded frame
+     * - Metadata and disposition copied from input stream
+     * - Duration hint used for muxer
      *
      * Direct mapping to avformat_new_stream().
      *
-     * @param source - Encoder or stream to add
+     * @param stream - Input stream (source for properties/metadata)
      *
      * @param options - Stream configuration options
      *
+     * @param options.encoder - Optional encoder for transcoding
+     *
      * @param options.timeBase - Optional custom timebase for the stream
      *
      * @returns Stream index for packet writing
@@ -272,9 +323,17 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * // Add stream from encoder (lazy initialization)
-     * const videoIdx = output.addStream(videoEncoder);
-     * const audioIdx = output.addStream(audioEncoder);
+     * // Stream copy
+     * const videoIdx = output.addStream(input.video());
+     * const audioIdx = output.addStream(input.audio());
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With encoding
+     * const videoIdx = output.addStream(input.video(), {
+     *   encoder: videoEncoder
+     * });
      * ```
      *
      * @example
@@ -288,9 +347,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * @see {@link writePacket} For writing packets to streams
      * @see {@link Encoder} For transcoding source
      */
-    addStream(source: Encoder | Stream, options?: {
-        timeBase?: IRational;
-    }): number;
+    addStream(stream: Stream, options?: AddStreamOptionsWithEncoder): number;
     /**
      * Get output stream by index.
      *
@@ -303,7 +360,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * const output = await MediaOutput.open('output.mp4');
+     * const output = await Muxer.open('output.mp4');
      * const videoIdx = output.addStream(encoder);
      *
      * // Get the output stream to inspect codec parameters
@@ -330,7 +387,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * const output = await MediaOutput.open('output.mp4');
+     * const output = await Muxer.open('output.mp4');
      * output.addStream(videoEncoder);
      *
      * // Get first video stream
@@ -356,7 +413,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * const output = await MediaOutput.open('output.mp4');
+     * const output = await Muxer.open('output.mp4');
      * output.addStream(audioEncoder);
      *
      * // Get first audio stream
@@ -380,7 +437,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * const output = await MediaOutput.open('output.mp4');
+     * const output = await Muxer.open('output.mp4');
      * const format = output.outputFormat();
      * if (format) {
      *   console.log(`Output format: ${format.name}`);
@@ -399,10 +456,18 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * - Codec parameter configuration from encoder or input stream
      * - Header writing on first packet
      * - Timestamp rescaling between source and output timebases
+     * - Sync queue for proper interleaving
      *
      * For encoder sources, the encoder must have processed at least one frame
      * before packets can be written (encoder must be initialized).
      *
+     * Uses FFmpeg CLI's sync queue pattern: buffers packets per stream and writes
+     * them in DTS order using av_compare_ts for timebase-aware comparison.
+     *
+     * To signal EOF for a stream, pass null as the packet.
+     * This tells the muxer that no more packets will be sent for this stream.
+     * The trailer is written only when close() is called.
+     *
      * Direct mapping to avformat_write_header() (on first packet) and av_interleaved_write_frame().
      *
      * @param packet - Packet to write
@@ -436,7 +501,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @see {@link addStream} For adding streams
      */
-    writePacket(packet: Packet, streamIndex: number): Promise<void>;
+    writePacket(packet: Packet | null, streamIndex: number): Promise<void>;
     /**
      * Write a packet to the output synchronously.
      * Synchronous version of writePacket.
@@ -447,10 +512,18 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * - Codec parameter configuration from encoder or input stream
      * - Header writing on first packet
      * - Timestamp rescaling between source and output timebases
+     * - Sync queue for proper interleaving
      *
      * For encoder sources, the encoder must have processed at least one frame
      * before packets can be written (encoder must be initialized).
      *
+     * Uses FFmpeg CLI's sync queue pattern: buffers packets per stream and writes
+     * them in DTS order using av_compare_ts for timebase-aware comparison.
+     *
+     * To signal EOF for a stream, pass null as the packet.
+     * This tells the muxer that no more packets will be sent for this stream.
+     * The trailer is written only when close() is called.
+     *
      * Direct mapping to avformat_write_header() (on first packet) and av_interleaved_write_frame().
      *
      * @param packet - Packet to write
@@ -484,9 +557,9 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @see {@link writePacket} For async version
      */
-    writePacketSync(packet: Packet, streamIndex: number): void;
+    writePacketSync(packet: Packet | null, streamIndex: number): void;
     /**
-     * Close media output and free resources.
+     * Close muxer and free resources.
      *
      * Automatically writes trailer if header was written.
      * Closes the output file and releases all resources.
@@ -495,7 +568,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * const output = await MediaOutput.open('output.mp4');
+     * const output = await Muxer.open('output.mp4');
      * try {
      *   // Use output - trailer written automatically on close
      * } finally {
@@ -507,7 +580,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      */
     close(): Promise<void>;
     /**
-     * Close media output and free resources synchronously.
+     * Close muxer and free resources synchronously.
      * Synchronous version of close.
      *
      * Automatically writes trailer if header was written.
@@ -517,7 +590,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      *
      * @example
      * ```typescript
-     * const output = MediaOutput.openSync('output.mp4');
+     * const output = Muxer.openSync('output.mp4');
      * try {
      *   // Use output - trailer written automatically on close
      * } finally {
@@ -539,7 +612,148 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      */
     getFormatContext(): FormatContext;
     /**
-     * Dispose of media output.
+     * Setup sync queues based on stream configuration.
+     *
+     * Called before writing header.
+     * Muxing sync queue is created only if nb_interleaved > nb_av_enc
+     * (i.e., when there are streamcopy streams).
+     *
+     * All streams are added as non-limiting (FFmpeg default without -shortest),
+     * which means no timestamp-based synchronization - frames are output immediately.
+     *
+     * @internal
+     */
+    private setupSyncQueues;
+    /**
+     * Flush all PreMuxQueues in DTS-sorted order.
+     *
+     * Implements FFmpeg's PreMuxQueue flush algorithm from mux_task_start().
+     * Repeatedly finds the stream with the earliest DTS packet and sends it:
+     * - WITH SyncQueue: Sends to SyncQueue for interleaving
+     * - WITHOUT SyncQueue: Writes directly to muxer
+     * NULL packets (EOF markers) and packets with AV_NOPTS_VALUE have priority (sent first).
+     *
+     * @internal
+     */
+    private flushPreMuxQueues;
+    /**
+     * Flush all PreMuxQueues in DTS-sorted order (synchronous version).
+     *
+     * Implements FFmpeg's PreMuxQueue flush algorithm from mux_task_start().
+     * Repeatedly finds the stream with the earliest DTS packet and sends it:
+     * - WITH SyncQueue: Sends to SyncQueue for interleaving
+     * - WITHOUT SyncQueue: Writes directly to muxer
+     * NULL packets (EOF markers) and packets with AV_NOPTS_VALUE have priority (sent first).
+     *
+     * @internal
+     */
+    private flushPreMuxQueuesSync;
+    /**
+     * Write a packet to the output.
+     *
+     * @param pkt - Packet to write
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @internal
+     */
+    private write;
+    /**
+     * Internal write implementation.
+     * Called either directly or through the write worker.
+     *
+     * @param pkt - Packet to write
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @internal
+     */
+    private writeInternal;
+    /**
+     * Start background worker for async write queue.
+     * Processes write jobs sequentially to prevent race conditions.
+     *
+     * @internal
+     */
+    private startWriteWorker;
+    /**
+     * Write a packet to the output synchronously.
+     * Synchronous version of write.
+     *
+     * @param pkt - Packet to write
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @internal
+     */
+    private writeSync;
+    /**
+     * Streamcopy packet filtering and timestamp offset.
+     *
+     * Applies streamcopy-specific logic before muxing:
+     * 1. Recording time limit check
+     * 2. Skip non-keyframe packets at start (unless copyInitialNonkeyframes)
+     * 3. Skip packets before ts_copy_start (unless copyPriorStart)
+     * 4. Skip packets before startTime
+     * 5. Apply start_time timestamp offset
+     *
+     * @param pkt - Packet to process
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @returns true if packet should be written, false if packet should be skipped
+     *
+     * @throws {Error} If recording time limit reached
+     *
+     * @internal
+     */
+    private ofStreamcopy;
+    /**
+     * Fix packet timestamps before muxing.
+     *
+     * Performs timestamp corrections:
+     * 1. Rescales timestamps to output timebase (av_rescale_delta for audio streamcopy)
+     * 2. Sets pkt.timeBase to output stream timebase
+     * 3. Fixes invalid DTS > PTS relationships
+     * 4. Enforces monotonic DTS (never decreasing)
+     *
+     * @param pkt - Packet to fix
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @internal
+     */
+    private muxFixupTs;
+    /**
+     * Copy container metadata from input to output.
+     *
+     * Automatically copies global metadata from input Demuxer to output format context.
+     * Only copies once (on first call). Removes duration/creation_time metadata.
+     *
+     * @internal
+     */
+    private copyContainerMetadata;
+    /**
+     * Auto-set DEFAULT disposition for first stream of each type.
+     *
+     * FFmpeg automatically sets DEFAULT flag for the first stream of each type
+     * if no stream of that type has DEFAULT set yet.
+     *
+     * @internal
+     */
+    private updateDefaultDisposition;
+    /**
+     * Dispose of muxer.
      *
      * Implements AsyncDisposable interface for automatic cleanup.
      * Equivalent to calling close().
@@ -547,7 +761,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * @example
      * ```typescript
      * {
-     *   await using output = await MediaOutput.open('output.mp4');
+     *   await using output = await Muxer.open('output.mp4');
      *   // Use output...
      * } // Automatically closed
      * ```
@@ -556,7 +770,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      */
     [Symbol.asyncDispose](): Promise<void>;
     /**
-     * Dispose of media output synchronously.
+     * Dispose of muxer synchronously.
      *
      * Implements Disposable interface for automatic cleanup.
      * Equivalent to calling closeSync().
@@ -564,7 +778,7 @@ export declare class MediaOutput implements AsyncDisposable, Disposable {
      * @example
      * ```typescript
      * {
-     *   using output = MediaOutput.openSync('output.mp4');
+     *   using output = Muxer.openSync('output.mp4');
      *   // Use output...
      * } // Automatically closed
      * ```