node-av-light 0.0.0-stage → 7.1.0-beta.1

package/dist/api/muxer.d.ts

@@ -0,0 +1,1311 @@
+import { Writable } from 'node:stream';
+import { FormatContext } from '../lib/format-context.js';
+import { Packet } from '../lib/packet.js';
+import { Encoder } from './encoder.js';
+import type { MuxerFormat, MuxerOptionsFor } from '../constants/index.js';
+import type { OutputFormat, Stream } from '../lib/index.js';
+import type { BitStreamFilterAPI } from './bitstream-filter.js';
+import type { Demuxer, RTPDemuxer } from './demuxer.js';
+import type { IOOutputCallbacks } from './io-stream.js';
+import type { ContextOptions } from './utilities/context-options.js';
+/**
+ * Observer for the packets a Muxer accepts for writing.
+ *
+ * @internal
+ */
+export interface MuxerPacketObserver {
+    /** A packet with payload was accepted; throwing fails the write like a muxing error. */
+    onPacket(streamIndex: number): void;
+    /**
+     * An accepted packet of this stream will not reach the output (dropped, or rejected by libavformat).
+     * A libavformat error for an earlier, buffered packet is reported against the packet submitted with it.
+     */
+    onPacketRejected(streamIndex: number): void;
+}
+/**
+ * Options for Muxer creation.
+ */
+export interface MuxerOptions<F extends MuxerFormat | (string & {}) = MuxerFormat | (string & {})> {
+    /**
+     * Input media for automatic metadata and property copying.
+     *
+     * When provided, Muxer will automatically copy:
+     * - Container-level metadata (title, artist, etc.)
+     * - Stream-level metadata
+     * - Disposition flags (DEFAULT, FORCED, etc.)
+     * - Duration hints for encoding
+     *
+     * This matches FFmpeg CLI behavior which copies metadata by default.
+     */
+    input?: Demuxer | RTPDemuxer;
+    /**
+     * Preferred output format.
+     *
+     * If not specified, format is guessed from file extension.
+     * Use this to override automatic format detection.
+     *
+     * Matches FFmpeg CLI's -f option.
+     *
+     * When given as a literal (e.g. `'mp4'`), `options` is strongly typed to that
+     * muxer's known options plus the generic AVFormatContext options.
+     */
+    format?: F;
+    /**
+     * Buffer size for I/O operations.
+     *
+     * This option controls the size of the internal buffer used for
+     * reading and writing data.
+     *
+     * @default 32768 (32 KB, matches FFmpeg CLI default)
+     */
+    bufferSize?: number;
+    /**
+     * Maximum packet size for I/O operations.
+     *
+     * This option controls the maximum size of individual packets
+     * for protocols that require specific packet sizes (e.g., RTP with MTU constraints).
+     *
+     * Matches FFmpeg's max_packet_size in AVIOContext.
+     *
+     * @default 1200
+     */
+    maxPacketSize?: number;
+    /**
+     * Exit immediately on first write error.
+     *
+     * When enabled, the muxer will terminate on the first write error.
+     * When disabled, errors are logged but processing continues.
+     * Timestamp discontinuities the muxer refuses to write (see
+     * {@link MuxerOptions.dtsBackwardThreshold} and
+     * {@link MuxerOptions.dtsForwardThreshold}) are thrown either way.
+     *
+     * @default true
+     */
+    exitOnError?: boolean;
+    /**
+     * Backward DTS jump in seconds above which writing a packet fails.
+     *
+     * Audio and video DTS must not decrease, so a packet behind the stream's last
+     * written DTS is clamped forward. After a large backward jump (a live source
+     * restarting its clock) every following packet is clamped to one tick past the
+     * previous one until the source catches up again, collapsing the timeline for
+     * as long as the jump. With a threshold set, such a packet is rejected with an
+     * error instead, so the owner can restart on a fresh timeline. Smaller jumps
+     * are still clamped. `0` disables the check.
+     *
+     * Independent of this option, MP4/MOV-family outputs always reject a DTS step
+     * or packet duration that their 32-bit sample durations cannot store (INT_MAX
+     * ticks or more), where movenc would otherwise collapse the step to one tick
+     * or abort the process. Without an edit list (fragmented output without
+     * `delay_moov`) they also reject the first packet of a stream that starts
+     * more than `max_interleave_delta` (10 s) after the others and ends before
+     * the output's start, which movenc cannot store either.
+     *
+     * @default 0
+     */
+    dtsBackwardThreshold?: number;
+    /**
+     * Forward DTS jump in seconds, beyond the real time that passed, above which
+     * writing a packet fails.
+     *
+     * For a source read in real time, timestamps advance with the clock: a gap
+     * in the stream comes with a matching wait for the packet after it. A packet
+     * whose DTS runs further ahead than the time that passed is a
+     * discontinuity (a live source restarting its clock behind a restreamer),
+     * and writing it would leave a sample spanning the jump. With a threshold
+     * set, such a packet is rejected with an error before it reaches the
+     * output, so the owner can restart on a fresh timeline. Real time is
+     * measured per audio/video stream from when its packets are passed to
+     * writePacket(), and a packet is compared with the stream's last 128 to 256
+     * packets, so frames a parser or encoder held back during a gap do not make
+     * the end of the gap look like a jump. A stream's first packet is not
+     * checked, and a packet without DTS is measured by its PTS. Use it only for
+     * sources read in real time: a file read faster than real time has its gaps
+     * without the wait. `0` disables the check.
+     *
+     * @default 0
+     */
+    dtsForwardThreshold?: number;
+    /**
+     * Maximum number of packets to buffer per stream in the sync queue.
+     *
+     * Matches FFmpeg CLI's -max_muxing_queue_size option.
+     * Limits memory usage when encoders are still initializing.
+     * Takes effect after muxingQueueDataThreshold is reached.
+     * If exceeded, an error is thrown.
+     *
+     * @default 128 (same as FFmpeg CLI)
+     */
+    maxMuxingQueueSize?: number;
+    /**
+     * Threshold in bytes after which maxMuxingQueueSize takes effect.
+     *
+     * Matches FFmpeg CLI's -muxing_queue_data_threshold option.
+     * Once this threshold is reached, maxMuxingQueueSize limit applies.
+     * This is an intelligent system: small streams (audio) can buffer many packets,
+     * large streams (video) are limited by packet count.
+     *
+     * @default 52428800 (50 MB, same as FFmpeg CLI)
+     */
+    muxingQueueDataThreshold?: number;
+    /**
+     * Maximum buffering duration in seconds for sync queue interleaving.
+     *
+     * Matches FFmpeg CLI's -shortest_buf_duration option.
+     * Controls how much buffering is allowed in the native sync queue
+     * for packet interleaving across multiple streams.
+     *
+     * @default 10 (same as FFmpeg CLI)
+     */
+    syncQueueBufferDuration?: number;
+    /**
+     * Start time offset in seconds for output timestamps.
+     *
+     * Matches FFmpeg CLI's -ss (output) option.
+     * Subtracts this offset from all packet timestamps.
+     * Use for trimming from start of stream.
+     *
+     * @default AV_NOPTS_VALUE (no offset)
+     */
+    startTime?: number;
+    /**
+     * Whether to copy initial non-keyframe packets in streamcopy mode.
+     *
+     * Matches FFmpeg CLI's -copyinkf option.
+     * If false (default), packets before first keyframe are skipped.
+     * If true, all packets from start are copied.
+     *
+     * @default false
+     */
+    copyInitialNonkeyframes?: boolean;
+    /**
+     * Copy or discard frames before start time.
+     *
+     * Matches FFmpeg CLI's -copypriorss option.
+     * Controls whether packets before the start time are copied:
+     * - -1 (default): Use FFmpeg's internal ts_copy_start calculation
+     * - 0: Discard packets before start time
+     * - 1: Copy all packets regardless of start time
+     *
+     * @default -1
+     */
+    copyPriorStart?: number;
+    /**
+     * Use synchronous packet queue for interleaving.
+     *
+     * When true and there are stream copy streams present, enables FFmpeg's
+     * sync queue for proper interleaving of packets based on timestamps.
+     *
+     * The sync queue is only activated when both conditions are met:
+     * - `useSyncQueue` is `true`
+     * - Output contains at least one stream copy stream
+     *
+     * This includes scenarios with:
+     * - Only stream copy streams (e.g., 1 streamcopy stream)
+     * - Mixed streams (e.g., 1 streamcopy + 1 encoded stream)
+     *
+     * For outputs with only encoded streams, the sync queue is not used.
+     *
+     * @default true
+     */
+    useSyncQueue?: boolean;
+    /**
+     * Use asynchronous write queue to prevent race conditions.
+     *
+     * When true and there are multiple streams (> 1), all write operations
+     * are serialized through an async queue, preventing concurrent access
+     * to AVFormatContext which can cause "Packet duration out of range"
+     * errors with parallel encoding.
+     *
+     * The async queue is only activated when both conditions are met:
+     * - `useAsyncWrite` is `true`
+     * - Output has more than one stream
+     *
+     * For single-stream outputs, writes are performed directly without
+     * queuing, regardless of this setting.
+     *
+     * @default true
+     */
+    useAsyncWrite?: boolean;
+    /**
+     * FFmpeg format options passed directly to the output.
+     *
+     * Key-value pairs of FFmpeg AVFormatContext / muxer-private options, applied
+     * before avformat_write_header(). When `format` is a known literal, these are
+     * typed to that muxer's options (autocomplete + value typing); arbitrary keys
+     * remain allowed so protocol/other options still pass.
+     */
+    options?: MuxerOptionsFor<F>;
+    /**
+     * Configure the underlying format context just before the header is written.
+     *
+     * Called with the output {@link FormatContext} once, after all streams have
+     * been initialized (their parameters, metadata, and disposition copied from
+     * the source) and immediately before `avformat_write_header`. Use it to set
+     * any container- or stream-level field with full type safety — for example
+     * per-stream metadata (language/title) or disposition that should not be
+     * overwritten by the source. Settings applied here take precedence because
+     * they run after the source values are copied.
+     *
+     * @example
+     * ```typescript
+     * import { Dictionary } from 'node-av';
+     *
+     * await Muxer.open('out.mp4', {
+     *   configure: (fmt) => {
+     *     fmt.streams[1].metadata = Dictionary.fromObject({ language: 'eng' });
+     *   },
+     * });
+     * ```
+     */
+    configure?: (context: FormatContext) => void;
+    /**
+     * Fields to set on the underlying format context.
+     *
+     * A typed, declarative bag for any writable {@link FormatContext} field. Applied
+     * once, after all streams are initialized (their parameters, metadata and
+     * disposition copied from the source) and immediately before
+     * `avformat_write_header`, so values here take precedence. The allowed keys are
+     * derived from the class, so every writable field is available and correctly
+     * typed. For per-stream or computed changes use {@link MuxerOptions.configure}.
+     *
+     * @example
+     * ```typescript
+     * await Muxer.open('out.mp4', {
+     *   context: {
+     *     startTime: 0n,
+     *   },
+     * });
+     * ```
+     */
+    context?: ContextOptions<FormatContext>;
+    /**
+     * AbortSignal for cancellation.
+     *
+     * When aborted, async methods throw AbortError.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * 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,
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { Muxer } from 'node-av/api';
+ *
+ * // Create output file
+ * await using output = await Muxer.open('output.mp4');
+ *
+ * // Add streams from encoders
+ * const videoIdx = output.addStream(videoEncoder);
+ * const audioIdx = output.addStream(audioEncoder);
+ *
+ * // Write packets - header written automatically on first packet
+ * await output.writePacket(packet, videoIdx);
+ *
+ * // Close - trailer written automatically
+ * // (automatic with await using)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Stream copy
+ * 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());
+ *
+ * // Process packets - header/trailer handled automatically
+ * for await (const packet of input.packets()) {
+ *   await output.writePacket(packet, videoIdx);
+ *   packet.free();
+ * }
+ * ```
+ *
+ * @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 Muxer implements AsyncDisposable, Disposable {
+    private formatContext;
+    private options;
+    private _streams;
+    private ioContext?;
+    private customIO;
+    private headerWritten;
+    private headerWritePromise?;
+    private trailerWritten;
+    private isClosed;
+    private syncQueue?;
+    private sqPacket?;
+    private containerMetadataCopied;
+    private writeQueue?;
+    private writeWorkerPromise?;
+    private writeWorkerError?;
+    private signal?;
+    private movSampleLimit;
+    private tsNonStrict;
+    private movZeroStart;
+    private interleaveDeltaUs;
+    private trailerDiscarded;
+    private forwardThresholdMs;
+    private clock;
+    private packetObserver?;
+    /**
+     * @param options - Media output options
+     *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Open muxer for writing.
+     *
+     * 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 muxer instance
+     *
+     * @throws {Error} If format required for custom I/O
+     *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
+     * @throws {FFmpegError} If allocation or opening fails
+     *
+     * @example
+     * ```typescript
+     * // Create file output
+     * await using output = await Muxer.open('output.mp4');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Create output with specific format
+     * await using output = await Muxer.open('output.ts', {
+     *   format: 'mpegts'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom I/O callbacks - async streaming to web destination
+     * const callbacks = {
+     *   write: async (buffer: Buffer) => {
+     *     await streamWriter.write(buffer);
+     *     return buffer.length;
+     *   }
+     * };
+     *
+     * await using output = await Muxer.open(callbacks, {
+     *   format: 'mp4',
+     *   bufferSize: 8192
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom I/O callbacks - synchronous buffering
+     * const chunks: Buffer[] = [];
+     * const callbacks = {
+     *   write: (buffer: Buffer) => {
+     *     chunks.push(Buffer.from(buffer));
+     *     return buffer.length;
+     *   }
+     * };
+     *
+     * await using output = await Muxer.open(callbacks, { format: 'mp4' });
+     * ```
+     *
+     * @see {@link MuxerOptions} For configuration options
+     * @see {@link IOOutputCallbacks} For custom I/O interface
+     */
+    static open<const F extends MuxerFormat | (string & {}) = MuxerFormat | (string & {})>(target: string, options?: MuxerOptions<F>): Promise<Muxer>;
+    static open<const F extends MuxerFormat | (string & {})>(target: IOOutputCallbacks, options: MuxerOptions<F> & {
+        format: F;
+    }): Promise<Muxer>;
+    static open<const F extends MuxerFormat | (string & {})>(target: Writable, options: MuxerOptions<F> & {
+        format: F;
+    }): Promise<Muxer>;
+    /**
+     * Open muxer 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 muxer instance
+     *
+     * @throws {Error} If format required for custom I/O
+     *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
+     * @throws {FFmpegError} If allocation or opening fails
+     *
+     * @example
+     * ```typescript
+     * // Create file output
+     * using output = Muxer.openSync('output.mp4');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Create output with specific format
+     * using output = Muxer.openSync('output.ts', {
+     *   format: 'mpegts'
+     * });
+     * ```
+     *
+     * @see {@link open} For async version
+     */
+    static openSync<const F extends MuxerFormat | (string & {}) = MuxerFormat | (string & {})>(target: string, options?: MuxerOptions<F>): Muxer;
+    static openSync<const F extends MuxerFormat | (string & {})>(target: IOOutputCallbacks, options: MuxerOptions<F> & {
+        format: F;
+    }): Muxer;
+    static openSync<const F extends MuxerFormat | (string & {})>(target: Writable, options: MuxerOptions<F> & {
+        format: F;
+    }): Muxer;
+    /**
+     * Check if output is open.
+     *
+     * @example
+     * ```typescript
+     * if (!output.isOutputOpen) {
+     *   console.log('Output is not open');
+     * }
+     * ```
+     */
+    get isOpen(): boolean;
+    /**
+     * Check if output is initialized.
+     *
+     * All streams have been initialized.
+     * This occurs after the first packet has been written to each stream.
+     *
+     * @example
+     * ```typescript
+     * if (!output.isOutputInitialized) {
+     *   console.log('Output is not initialized');
+     * }
+     * ```
+     */
+    get streamsInitialized(): boolean;
+    /**
+     * Get all streams in the media.
+     *
+     * @example
+     * ```typescript
+     * for (const stream of output.streams) {
+     *   console.log(`Stream ${stream.index}: ${stream.codecpar.codecType}`);
+     * }
+     * ```
+     */
+    get streams(): Stream[];
+    /**
+     * Get format name.
+     *
+     * Returns 'unknown' if output is closed or format is not available.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Format: ${output.formatName}`); // "mov,mp4,m4a,3gp,3g2,mj2"
+     * ```
+     */
+    get formatName(): string;
+    /**
+     * Get format long name.
+     *
+     * Returns 'Unknown Format' if output is closed or format is not available.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Format: ${output.formatLongName}`); // "QuickTime / MOV"
+     * ```
+     */
+    get formatLongName(): string;
+    /**
+     * Get MIME type of the output format.
+     *
+     * Returns format's native MIME type.
+     * Returns null if output is closed or format is not available.
+     *
+     * @example
+     * ```typescript
+     * console.log(mp4Output.mimeType); // "video/mp4"
+     * ```
+     */
+    get mimeType(): string | null;
+    /**
+     * 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
+     *
+     * @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?: {
+        inputStream?: Stream;
+        bsf?: BitStreamFilterAPI;
+    }): 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.
+     *
+     * 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 stream - Input stream (source for properties/metadata)
+     *
+     * @param options - Stream configuration options
+     *
+     * @param options.encoder - Optional encoder for transcoding
+     *
+     * @returns Stream index for packet writing
+     *
+     * @throws {Error} If called after packets have been written or output closed
+     *
+     * @example
+     * ```typescript
+     * // 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
+     * });
+     * ```
+     *
+     * @see {@link writePacket} For writing packets to streams
+     * @see {@link Encoder} For transcoding source
+     */
+    addStream(stream: Stream, options?: {
+        encoder?: Encoder;
+        bsf?: BitStreamFilterAPI;
+    }): number;
+    /**
+     * Get output stream by index.
+     *
+     * Returns the stream at the specified index.
+     * Use the stream index returned by addStream().
+     *
+     * @param index - Stream index (returned by addStream)
+     *
+     * @returns Stream or undefined if index is invalid
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('output.mp4');
+     * const videoIdx = output.addStream(encoder);
+     *
+     * // Get the output stream to inspect codec parameters
+     * const stream = output.getStream(videoIdx);
+     * if (stream) {
+     *   console.log(`Output codec: ${stream.codecpar.codecId}`);
+     * }
+     * ```
+     *
+     * @see {@link addStream} For adding streams
+     * @see {@link video} For getting video streams
+     * @see {@link audio} For getting audio streams
+     */
+    getStream(index: number): Stream | undefined;
+    /**
+     * Get video stream by index.
+     *
+     * Returns the nth video stream (0-based index).
+     * Returns undefined if stream doesn't exist.
+     *
+     * @param index - Video stream index (default: 0)
+     *
+     * @returns Video stream or undefined
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('output.mp4');
+     * output.addStream(videoEncoder);
+     *
+     * // Get first video stream
+     * const videoStream = output.video();
+     * if (videoStream) {
+     *   console.log(`Video output: ${videoStream.codecpar.width}x${videoStream.codecpar.height}`);
+     * }
+     * ```
+     *
+     * @see {@link audio} For audio streams
+     * @see {@link getStream} For direct stream access
+     */
+    video(index?: number): Stream | undefined;
+    /**
+     * Get audio stream by index.
+     *
+     * Returns the nth audio stream (0-based index).
+     * Returns undefined if stream doesn't exist.
+     *
+     * @param index - Audio stream index (default: 0)
+     *
+     * @returns Audio stream or undefined
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('output.mp4');
+     * output.addStream(audioEncoder);
+     *
+     * // Get first audio stream
+     * const audioStream = output.audio();
+     * if (audioStream) {
+     *   console.log(`Audio output: ${audioStream.codecpar.sampleRate}Hz`);
+     * }
+     * ```
+     *
+     * @see {@link video} For video streams
+     * @see {@link getStream} For direct stream access
+     */
+    audio(index?: number): Stream | undefined;
+    /**
+     * Get output format.
+     *
+     * Returns the output format used for muxing.
+     * May be null if format context not initialized.
+     *
+     * @returns Output format or null
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('output.mp4');
+     * const format = output.outputFormat();
+     * if (format) {
+     *   console.log(`Output format: ${format.name}`);
+     * }
+     * ```
+     *
+     * @see {@link OutputFormat} For format details
+     */
+    outputFormat(): OutputFormat | null;
+    /**
+     * Write a packet to the output.
+     *
+     * 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
+     * - 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 (or null to signal EOF for the stream)
+     *
+     * @param streamIndex - Target stream index
+     *
+     * @throws {Error} If stream invalid or encoder not initialized
+     *
+     * @throws {Error} On a timestamp discontinuity the output cannot take (see {@link MuxerOptions.dtsBackwardThreshold}).
+     * With the background write queue (more than one stream) it surfaces from a later writePacket() or close().
+     *
+     * @throws {FFmpegError} If write fails
+     *
+     * @example
+     * ```typescript
+     * // Write encoded packet - header written automatically on first packet
+     * const packet = await encoder.encode(frame);
+     * if (packet) {
+     *   await output.writePacket(packet, videoIdx);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream copy with packet processing
+     * for await (const packet of input.packets()) {
+     *   if (packet.streamIndex === inputVideoIdx) {
+     *     await output.writePacket(packet, outputVideoIdx);
+     *   }
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link addStream} For adding streams
+     */
+    writePacket(packet: Packet | null | undefined, streamIndex: number): Promise<void>;
+    /**
+     * Write a packet to the output synchronously.
+     * Synchronous version of writePacket.
+     *
+     * 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
+     * - 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 (or null/undefined to signal EOF)
+     *
+     * @param streamIndex - Target stream index
+     *
+     * @throws {Error} If stream invalid or encoder not initialized
+     *
+     * @throws {Error} On a timestamp discontinuity the output cannot take (see {@link MuxerOptions.dtsBackwardThreshold})
+     *
+     * @throws {FFmpegError} If write fails
+     *
+     * @example
+     * ```typescript
+     * // Write encoded packet - header written automatically on first packet
+     * const packet = encoder.encodeSync(frame);
+     * if (packet) {
+     *   output.writePacketSync(packet, videoIdx);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Stream copy with packet processing
+     * for (const packet of input.packetsSync()) {
+     *   if (packet.streamIndex === inputVideoIdx) {
+     *     output.writePacketSync(packet, outputVideoIdx);
+     *   }
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link writePacket} For async version
+     */
+    writePacketSync(packet: Packet | null | undefined, streamIndex: number): void;
+    /**
+     * Close muxer and free 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.
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('output.mp4');
+     * try {
+     *   // Use output - trailer written automatically on close
+     * } finally {
+     *   await output.close();
+     * }
+     * ```
+     *
+     * @throws {Error} If a background write failed and was not yet observed by the caller (resources are still released; a second close() is a no-op)
+     *
+     * @see {@link Symbol.asyncDispose} For automatic cleanup
+     */
+    close(): Promise<void>;
+    /**
+     * Close muxer and free resources synchronously.
+     * Synchronous version of close.
+     *
+     * 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
+     * const output = Muxer.openSync('output.mp4');
+     * try {
+     *   // Use output - trailer written automatically on close
+     * } finally {
+     *   output.closeSync();
+     * }
+     * ```
+     *
+     * @see {@link close} For async version
+     */
+    closeSync(): void;
+    /**
+     * Get underlying format context.
+     *
+     * Returns the internal format context for advanced operations.
+     *
+     * @returns Format context
+     *
+     * @internal
+     */
+    getFormatContext(): FormatContext;
+    /**
+     * Follow the packets this muxer accepts for writing.
+     *
+     * The observer hears about every packet with payload once it is accepted
+     * (before it waits in the pre-mux queue or reaches libavformat) and about
+     * every such packet that is dropped later, so together with the output it
+     * knows what the muxer holds. close() detaches it.
+     *
+     * @param observer - Observer, or undefined to detach
+     *
+     * @internal
+     */
+    setPacketObserver(observer: MuxerPacketObserver | undefined): void;
+    /**
+     * Replace the clock that stamps packet arrival times for the dtsForwardThreshold check.
+     *
+     * Lets tests drive real time deterministically. Set it before the first packet.
+     *
+     * @param clock - Monotonic time in ms
+     *
+     * @internal
+     */
+    setClock(clock: () => number): void;
+    /**
+     * Make close() skip the trailer.
+     *
+     * For owners that drop whatever the muxer still emits, such as FMP4Stream
+     * after a failed session: the trailer would only push libavformat's backlog
+     * into the void, and movenc asserts on some track states a failed session
+     * can leave behind. The backlog is freed with the format context instead.
+     *
+     * @internal
+     */
+    discardOnClose(): void;
+    /**
+     * Announce a packet the muxer has accepted to the packet observer.
+     *
+     * @param pkt - The muxer's clone of the packet
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @returns True when the observer now tracks the packet
+     *
+     * @throws {Error} If the observer fails the write (the clone is freed)
+     *
+     * @internal
+     */
+    private announcePacket;
+    /**
+     * Apply shared pre-header setup for writePacket and writePacketSync.
+     *
+     * Configures sync queues, dispositions and container metadata, then applies
+     * user-provided context options and the configure callback. Must run
+     * immediately before writing the header so both variants stay in sync.
+     *
+     * @internal
+     */
+    private prepareHeaderWrite;
+    /**
+     * Read the muxing setup libavformat settles while writing the header.
+     *
+     * movenc decides on edit lists only then: without one (fragmented output
+     * without delay_moov) it shifts the output to start at 0 and puts each
+     * track's first sample there, which {@link checkMovLateStart} guards.
+     *
+     * @internal
+     */
+    private readHeaderSetup;
+    /**
+     * 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;
+    /**
+     * Whether any stream still holds packets (or an EOF marker) in its pre-mux queue.
+     *
+     * @returns True if a pre-mux queue is not empty
+     *
+     * @internal
+     */
+    private hasPreMuxPackets;
+    /**
+     * 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
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @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
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @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
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @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
+     */
+    /**
+     * Apply the configured `startTime` offset to an encoded packet, per stream.
+     *
+     * `startTime` exists to strip a device's boot-relative timestamp base (e.g. the
+     * mach uptime avfoundation reports). But not every stream of an output carries
+     * that base (e.g. zero-based audio next to device video), so subtracting a large
+     * device startTime from such a stream would push its timestamps hugely negative and
+     * produce a broken/overflowed edit list that strict players (QuickTime) reject. The
+     * effective offset is therefore decided once on the stream's first packet and
+     * clamped to what the stream actually carries —
+     * `min(startTime, max(0, firstPts))`: boot-relative streams normalize to zero,
+     * already-zero-based streams are left untouched.
+     *
+     * @param packet - Cloned packet to adjust in place
+     *
+     * @param streamInfo - Per-stream muxing state
+     *
+     * @internal
+     */
+    private applyStartTimeOffset;
+    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. Rejects backward jumps beyond dtsBackwardThreshold
+     * 4. Fixes invalid DTS > PTS relationships
+     * 5. Enforces monotonic DTS (never decreasing), shrinking a clamped packet's duration to the clamped step
+     * 6. Rejects forward jumps that run ahead of real time beyond dtsForwardThreshold
+     * 7. Rejects DTS steps/durations a movenc output cannot store, and a late stream's first packet before its start
+     *
+     * The stream's last muxed DTS only advances when the packet is accepted and
+     * carries a DTS.
+     *
+     * @param pkt - Packet to fix
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @throws {Error} On a rejected timestamp discontinuity
+     *
+     * @internal
+     */
+    private muxFixupTs;
+    /**
+     * Reject a packet whose DTS lies further behind the stream's last muxed DTS
+     * than the configured dtsBackwardThreshold.
+     *
+     * Expects the DTS already rescaled to the output stream time base. No-op when
+     * the threshold is unset or 0.
+     *
+     * @param dts - Packet DTS in the output time base
+     *
+     * @param lastMuxDts - The stream's last muxed DTS
+     *
+     * @param timeBase - Output stream time base
+     *
+     * @param streamIndex - Stream index
+     *
+     * @throws {Error} If the backward jump exceeds the threshold
+     *
+     * @internal
+     */
+    private checkBackwardDts;
+    /**
+     * Reject a packet whose DTS runs further ahead of real time than the
+     * configured dtsForwardThreshold.
+     *
+     * Tracks per stream how real time and media time move apart (the offset) and
+     * compares the packet's offset with the lowest one of the stream's recent
+     * packets, see FORWARD_WINDOW_BUCKET. A gap in a live source leaves the
+     * offset level, since the wait comes with it; a jump lowers it by the size
+     * of the jump. The stream's first packet only sets the starting point.
+     *
+     * @param ts - Final packet DTS (PTS without DTS) in the output time base
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @returns The packet's offset, for {@link recordForwardDts} once the packet is accepted
+     *
+     * @throws {Error} If the DTS runs ahead of real time by more than the threshold
+     *
+     * @internal
+     */
+    private checkForwardDts;
+    /**
+     * Make an accepted packet the reference of the stream's next forward check.
+     *
+     * @param state - The stream's forward check state
+     *
+     * @param ts - The packet's DTS (PTS without DTS) in the output time base
+     *
+     * @param offset - The packet's offset from {@link checkForwardDts}
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @internal
+     */
+    private recordForwardDts;
+    /**
+     * Reject a packet whose DTS step or duration a movenc output cannot store.
+     *
+     * Runs after the monotonic clamp, on the DTS movenc will see. Steps are
+     * measured against the stream's last muxed DTS.
+     *
+     * @param dts - Final packet DTS, or its PTS for a packet without DTS
+     *
+     * @param duration - Final packet duration
+     *
+     * @param lastMuxDts - The stream's last muxed DTS
+     *
+     * @param timeBase - Output stream time base
+     *
+     * @param streamIndex - Stream index
+     *
+     * @throws {Error} If the step or duration reaches INT_MAX ticks
+     *
+     * @internal
+     */
+    private checkMovSampleDuration;
+    /**
+     * Reject a stream's first packet that ends before the output's start.
+     *
+     * Without an edit list movenc puts each track's first sample at the output's
+     * start, so a first packet that ends before it becomes a sample of negative
+     * duration, and movenc aborts the process (av_assert0 in
+     * get_cluster_duration) at the next fragment or the trailer unless a second
+     * sample reaches it first. libavformat sets that start from the lowest DTS
+     * it holds when it writes its first packet. It holds every packet until each
+     * stream has sent one or its queue spans max_interleave_delta, so only a
+     * stream that starts that much later than the others can land before it.
+     *
+     * @param ts - Packet DTS (PTS without DTS) in the output time base
+     *
+     * @param duration - Packet duration
+     *
+     * @param timeBase - Output stream time base
+     *
+     * @param streamIndex - Stream index
+     *
+     * @throws {Error} If the packet ends before a start libavformat may already have set
+     *
+     * @internal
+     */
+    private checkMovLateStart;
+    /**
+     * 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().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   await using output = await Muxer.open('output.mp4');
+     *   // Use output...
+     * } // Automatically closed
+     * ```
+     *
+     * @see {@link close} For manual cleanup
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Dispose of muxer synchronously.
+     *
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling closeSync().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using output = Muxer.openSync('output.mp4');
+     *   // Use output...
+     * } // Automatically closed
+     * ```
+     *
+     * @see {@link closeSync} For manual cleanup
+     */
+    [Symbol.dispose](): void;
+}