node-av-lgpl 0.0.0 → 7.1.0-beta.1

package/dist/lib/format-context.d.ts

@@ -0,0 +1,1335 @@
+import { Codec } from './codec.js';
+import { Dictionary } from './dictionary.js';
+import { InputFormat } from './input-format.js';
+import { OptionMember } from './option.js';
+import { OutputFormat } from './output-format.js';
+import { Stream } from './stream.js';
+import type { AVCodecID, AVFormatFlag, AVMediaType, AVSeekFlag } from '../constants/constants.js';
+import type { IOContext } from './io-context.js';
+import type { NativeFormatContext, NativeWrapper } from './native-types.js';
+import type { Packet } from './packet.js';
+/**
+ * RTSP stream information interface
+ */
+export interface RTSPStreamInfo {
+    streamIndex: number;
+    controlUrl: string;
+    transport: 'tcp' | 'udp' | 'udp_multicast' | 'unknown';
+    payloadType: number;
+    codecId: AVCodecID;
+    mediaType: 'video' | 'audio' | 'data' | 'subtitle' | 'unknown';
+    mimeType: string;
+    sampleRate?: number;
+    channels?: number;
+    direction: 'sendonly' | 'recvonly' | 'sendrecv' | 'inactive';
+    fmtp?: string;
+}
+/**
+ * Container format context for reading/writing multimedia files.
+ *
+ * Central structure for demuxing (reading) and muxing (writing) media files.
+ * Manages streams, packets, metadata, and format-specific operations.
+ * Supports both file-based and custom I/O through IOContext.
+ * Essential for all file-based media operations.
+ *
+ * Direct mapping to FFmpeg's AVFormatContext.
+ *
+ * @example
+ * ```typescript
+ * import { FormatContext, FFmpegError } from 'node-av';
+ * import { AVMEDIA_TYPE_VIDEO } from 'node-av/constants';
+ *
+ * // Open input file
+ * const ctx = new FormatContext();
+ * let ret = await ctx.openInput('input.mp4');
+ * FFmpegError.throwIfError(ret, 'openInput');
+ *
+ * ret = await ctx.findStreamInfo();
+ * FFmpegError.throwIfError(ret, 'findStreamInfo');
+ *
+ * // Find video stream
+ * const videoIndex = ctx.findBestStream(AVMEDIA_TYPE_VIDEO);
+ * if (videoIndex < 0) {
+ *   throw new Error('No video stream found');
+ * }
+ *
+ * // Read packets
+ * const packet = new Packet();
+ * packet.alloc();
+ * while ((ret = await ctx.readFrame(packet)) >= 0) {
+ *   if (packet.streamIndex === videoIndex) {
+ *     // Process video packet
+ *   }
+ *   packet.unref();
+ * }
+ *
+ * // Cleanup
+ * await ctx.closeInput();
+ * ```
+ *
+ * @see [AVFormatContext](https://ffmpeg.org/doxygen/trunk/structAVFormatContext.html) - FFmpeg Doxygen
+ * @see {@link InputFormat} For supported input formats
+ * @see {@link OutputFormat} For supported output formats
+ * @see {@link Stream} For stream management
+ */
+export declare class FormatContext extends OptionMember<NativeFormatContext> implements AsyncDisposable, NativeWrapper<NativeFormatContext> {
+    private _ioContext;
+    constructor();
+    /**
+     * URL or filename of the media.
+     *
+     * For input: the opened file path.
+     * For output: the target file path.
+     *
+     * Direct mapping to AVFormatContext->url.
+     */
+    get url(): string | null;
+    set url(value: string | null);
+    /**
+     * Start time of the stream.
+     *
+     * Position of the first frame in microseconds.
+     * AV_NOPTS_VALUE if unknown.
+     *
+     * Direct mapping to AVFormatContext->start_time.
+     */
+    get startTime(): bigint;
+    /**
+     * Duration of the stream.
+     *
+     * Total stream duration in microseconds.
+     * AV_NOPTS_VALUE if unknown.
+     *
+     * Direct mapping to AVFormatContext->duration.
+     */
+    get duration(): bigint;
+    /**
+     * Total stream bitrate.
+     *
+     * Bitrate in bits per second.
+     * 0 if unknown.
+     *
+     * Direct mapping to AVFormatContext->bit_rate.
+     */
+    get bitRate(): bigint;
+    /**
+     * Format-specific flags.
+     *
+     * Combination of AVFMT_FLAG_* values controlling
+     * format behavior (e.g., AVFMT_FLAG_GENPTS).
+     *
+     * Direct mapping to AVFormatContext->flags.
+     */
+    get flags(): AVFormatFlag;
+    set flags(value: AVFormatFlag);
+    /**
+     * Maximum bytes to probe for format detection.
+     *
+     * Larger values improve format detection accuracy
+     * but increase startup time.
+     *
+     * Direct mapping to AVFormatContext->probesize.
+     */
+    get probesize(): bigint;
+    set probesize(value: bigint);
+    /**
+     * Maximum duration to analyze streams.
+     *
+     * Time in microseconds to spend analyzing streams.
+     * Larger values improve stream detection accuracy.
+     *
+     * Direct mapping to AVFormatContext->max_analyze_duration.
+     */
+    get maxAnalyzeDuration(): bigint;
+    set maxAnalyzeDuration(value: bigint);
+    /**
+     * Maximum buffering duration for interleaving.
+     *
+     * Specifies the maximum difference between the timestamps of the
+     * first and the last packet in the muxing queue, above which libavformat
+     * will output a packet regardless of whether it has queued a packet for all
+     * the streams.
+     *
+     * Set to 0 for unlimited buffering
+     *
+     * Default: 10000000 (10 seconds in microseconds)
+     *
+     * Muxing only, set before avformat_write_header().
+     *
+     * Direct mapping to AVFormatContext->max_interleave_delta.
+     */
+    get maxInterleaveDelta(): bigint;
+    set maxInterleaveDelta(value: bigint);
+    /**
+     * Container metadata.
+     *
+     * Key-value pairs of metadata (title, author, etc.).
+     *
+     * Returns a copy of AVFormatContext->metadata - mutating the returned
+     * Dictionary does not affect the context. Assign it back to apply changes.
+     */
+    get metadata(): Dictionary | null;
+    set metadata(value: Dictionary | null);
+    /**
+     * Input format descriptor.
+     *
+     * Format used for demuxing. Null for output contexts.
+     *
+     * Direct mapping to AVFormatContext->iformat.
+     */
+    get iformat(): InputFormat | null;
+    /**
+     * Output format descriptor.
+     *
+     * Format used for muxing. Null for input contexts.
+     *
+     * Direct mapping to AVFormatContext->oformat.
+     */
+    get oformat(): OutputFormat | null;
+    set oformat(value: OutputFormat | null);
+    /**
+     * Custom I/O context.
+     *
+     * For custom I/O operations instead of file I/O.
+     * Assigning a callback-backed context also sets AVFMT_FLAG_CUSTOM_IO so libavformat never closes it.
+     * A context opened with open2() is closed once, by whichever comes first: its closep(), which
+     * also clears this pb like `avio_closep(&ctx->pb)` in C, or closing or freeing this output context.
+     * An IOContext can be the pb of one FormatContext at a time.
+     *
+     * Direct mapping to AVFormatContext->pb.
+     */
+    get pb(): IOContext | null;
+    set pb(value: IOContext | null);
+    /**
+     * Number of streams in the container.
+     *
+     * Direct mapping to AVFormatContext->nb_streams.
+     */
+    get nbStreams(): number;
+    /**
+     * Array of streams in the container.
+     *
+     * All audio, video, subtitle, and data streams.
+     *
+     * Direct mapping to AVFormatContext->streams.
+     */
+    get streams(): Stream[];
+    /**
+     * Strictness level for standards compliance.
+     *
+     * FF_COMPLIANCE_* value controlling how strictly
+     * to follow specifications.
+     *
+     * Direct mapping to AVFormatContext->strict_std_compliance.
+     */
+    get strictStdCompliance(): number;
+    set strictStdCompliance(value: number);
+    /**
+     * Maximum number of streams.
+     *
+     * Limit on stream count for security/resource reasons.
+     *
+     * Direct mapping to AVFormatContext->max_streams.
+     */
+    get maxStreams(): number;
+    set maxStreams(value: number);
+    /**
+     * Number of programs.
+     *
+     * For containers with multiple programs (e.g., MPEG-TS).
+     *
+     * Direct mapping to AVFormatContext->nb_programs.
+     */
+    get nbPrograms(): number;
+    /**
+     * Number of bytes read/written through I/O context.
+     *
+     * Direct mapping to avio_tell(AVFormatContext->pb).
+     */
+    get pbBytes(): bigint;
+    /**
+     * Format probe score.
+     *
+     * Confidence score from format detection (0-100).
+     * Higher values indicate more confident detection.
+     *
+     * Direct mapping to AVFormatContext->probe_score.
+     */
+    get probeScore(): number;
+    /**
+     * Allocate a format context.
+     *
+     * Allocates the context structure. Usually not needed
+     * as openInput/allocOutputContext2 handle this.
+     *
+     * Direct mapping to avformat_alloc_context().
+     *
+     * @example
+     * ```typescript
+     * const ctx = new FormatContext();
+     * ctx.allocContext();
+     * // Context is now allocated
+     * ```
+     */
+    allocContext(): void;
+    /**
+     * Allocate an output format context.
+     *
+     * Allocates and configures context for writing.
+     * Format is determined by parameters in priority order.
+     *
+     * Direct mapping to avformat_alloc_output_context2().
+     *
+     * @param oformat - Specific output format to use
+     *
+     * @param formatName - Format name (e.g., 'mp4', 'mkv')
+     *
+     * @param filename - Filename to guess format from extension
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *   - AVERROR_EINVAL: Invalid parameters
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ctx = new FormatContext();
+     * const ret = ctx.allocOutputContext2(null, 'mp4', 'output.mp4');
+     * FFmpegError.throwIfError(ret, 'allocOutputContext2');
+     * ```
+     *
+     * @see {@link openOutput} To open output file
+     * @see {@link writeHeader} To write file header
+     */
+    allocOutputContext2(oformat: OutputFormat | null, formatName: string | null, filename: string | null): number;
+    /**
+     * Free the format context.
+     *
+     * Releases all resources. The context becomes invalid.
+     *
+     * Direct mapping to avformat_free_context().
+     *
+     * @example
+     * ```typescript
+     * ctx.freeContext();
+     * // Context is now invalid
+     * ```
+     *
+     * @see {@link Symbol.asyncDispose} For automatic cleanup
+     */
+    freeContext(): void;
+    /**
+     * Open output file for writing.
+     *
+     * Opens the output file specified in url.
+     * Must call allocOutputContext2 first.
+     *
+     * Direct mapping to avio_open2().
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOENT: File not found
+     *   - AVERROR_EACCES: Permission denied
+     *   - AVERROR_EIO: I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await ctx.openOutput();
+     * FFmpegError.throwIfError(ret, 'openOutput');
+     * ```
+     *
+     * @see {@link allocOutputContext2} Must be called first
+     * @see {@link closeOutput} To close output
+     */
+    openOutput(): Promise<number>;
+    /**
+     * Open output file synchronously.
+     * Synchronous version of openOutput.
+     *
+     * Opens output file for writing.
+     * I/O context must be set before calling.
+     *
+     * Direct mapping to avio_open2().
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR(EIO): I/O error
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.openOutputSync();
+     * FFmpegError.throwIfError(ret, 'openOutputSync');
+     * ```
+     *
+     * @see {@link openOutput} For async version
+     */
+    openOutputSync(): number;
+    /**
+     * Close output file.
+     *
+     * Closes the output file and releases I/O resources.
+     *
+     * Direct mapping to avio_closep().
+     *
+     * @returns Promise that resolves when closed
+     *
+     * @example
+     * ```typescript
+     * await ctx.closeOutput();
+     * // Output file closed
+     * ```
+     *
+     * @see {@link openOutput} To open output
+     */
+    closeOutput(): Promise<void>;
+    /**
+     * Close output file synchronously.
+     * Synchronous version of closeOutput.
+     *
+     * Closes the output file and releases I/O resources.
+     *
+     * Direct mapping to avio_closep().
+     *
+     * @example
+     * ```typescript
+     * ctx.closeOutputSync();
+     * // Output file closed
+     * ```
+     *
+     * @see {@link closeOutput} For async version
+     */
+    closeOutputSync(): void;
+    /**
+     * Open input file for reading.
+     *
+     * Opens and probes the input file, detecting format automatically
+     * unless specified.
+     *
+     * Direct mapping to avformat_open_input().
+     *
+     * @param url - URL or file path to open
+     *
+     * @param fmt - Force specific input format (null for auto-detect)
+     *
+     * @param options - Format-specific options
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOENT: File not found
+     *   - AVERROR_INVALIDDATA: Invalid file format
+     *   - AVERROR_EIO: I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await ctx.openInput('input.mp4');
+     * FFmpegError.throwIfError(ret, 'openInput');
+     * ```
+     *
+     * @see {@link findStreamInfo} To analyze streams after opening
+     * @see {@link closeInput} To close input
+     */
+    openInput(url: string, fmt?: InputFormat | null, options?: Dictionary | null): Promise<number>;
+    /**
+     * Open an input file or URL synchronously.
+     * Synchronous version of openInput.
+     *
+     * Opens a media file or stream for reading.
+     * The format is auto-detected if not specified.
+     *
+     * Direct mapping to avformat_open_input().
+     *
+     * @param url - File path or URL to open
+     *
+     * @param fmt - Force specific format (null for auto-detect)
+     *
+     * @param options - Format-specific options
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid arguments
+     *   - AVERROR(EIO): I/O error
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.openInputSync('input.mp4');
+     * FFmpegError.throwIfError(ret, 'openInputSync');
+     * ```
+     *
+     * @see {@link openInput} For async version
+     */
+    openInputSync(url: string, fmt?: InputFormat | null, options?: Dictionary | null): number;
+    /**
+     * Close an input format context.
+     *
+     * Closes input file and releases resources.
+     * A pb with JS callbacks stops serving this input: a read, seek or open
+     * still waiting for one of its callbacks fails with AVERROR_EXIT, and its
+     * callbacks are not called again, so a stalled source cannot block the close.
+     *
+     * Direct mapping to avformat_close_input().
+     *
+     * @param detachPb - Forget a caller-owned pb (custom IOContext) once the
+     * reader thread has stopped, so it is not closed with the input. Setting
+     * `pb = null` yourself throws while an async reader is active.
+     *
+     * @returns Promise that resolves when closed
+     *
+     * @example
+     * ```typescript
+     * await ctx.closeInput();
+     * // Input closed and context freed
+     * ```
+     *
+     * @see {@link openInput} To open input
+     */
+    closeInput(detachPb?: boolean): Promise<void>;
+    /**
+     * Close an input format context synchronously.
+     * Synchronous version of closeInput.
+     *
+     * Closes input file and releases resources.
+     * A pb with JS callbacks stops serving this input (see closeInput).
+     *
+     * Direct mapping to avformat_close_input().
+     *
+     * @example
+     * ```typescript
+     * ctx.closeInputSync();
+     * // Input closed and context freed
+     * ```
+     *
+     * @see {@link closeInput} For async version
+     *
+     * @param detachPb - Forget a caller-owned pb once the reader stopped (see closeInput)
+     */
+    closeInputSync(detachPb?: boolean): void;
+    /**
+     * Analyze streams to get stream info.
+     *
+     * Reads packet headers to fill in stream information.
+     * Should be called after openInput for accurate stream data.
+     *
+     * Direct mapping to avformat_find_stream_info().
+     *
+     * @param options - Per-stream options array
+     *
+     * @returns >=0 on success, negative AVERROR on error:
+     *   - AVERROR_EOF: End of file reached
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await ctx.findStreamInfo();
+     * FFmpegError.throwIfError(ret, 'findStreamInfo');
+     * console.log(`Found ${ctx.nbStreams} streams`);
+     * ```
+     *
+     * @see {@link findStreamInfoSync} For synchronous version
+     * @see {@link openInput} Must be called first
+     */
+    findStreamInfo(options?: Dictionary[] | null): Promise<number>;
+    /**
+     * Analyze streams to get stream info synchronously.
+     * Synchronous version of findStreamInfo.
+     *
+     * Reads packet headers to fill in stream information.
+     * Should be called after openInputSync for accurate stream data.
+     *
+     * Direct mapping to avformat_find_stream_info().
+     *
+     * @param options - Per-stream options array
+     *
+     * @returns >=0 on success, negative AVERROR on error:
+     *   - AVERROR_EOF: End of file reached
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.findStreamInfoSync();
+     * FFmpegError.throwIfError(ret, 'findStreamInfoSync');
+     * console.log(`Found ${ctx.nbStreams} streams`);
+     * ```
+     *
+     * @see {@link findStreamInfo} For async version
+     */
+    findStreamInfoSync(options?: Dictionary[] | null): number;
+    /**
+     * Read next packet from the input.
+     *
+     * Reads and returns the next packet in the stream.
+     * Packet must be unreferenced after use.
+     *
+     * Direct mapping to av_read_frame().
+     *
+     * @param pkt - Packet to read into
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EOF: End of file
+     *   - AVERROR_EXIT: Aborted by interrupt() or closeInput()
+     *
+     * The first call starts the context's own reader thread, which is the only
+     * thread touching the input from then on: it blocks in av_read_frame(),
+     * retries EAGAIN itself and hands packets over through a bounded queue, so
+     * a waiting read never occupies a libuv threadpool thread. seekFrame(),
+     * seekFile(), sendRTSPPacket() and findStreamInfo() run on that thread
+     * between two reads; the sync variants throw while it is active.
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     * import { AVERROR_EOF } from 'node-av';
+     *
+     * const packet = new Packet();
+     * packet.alloc();
+     *
+     * let ret;
+     * while ((ret = await ctx.readFrame(packet)) >= 0) {
+     *   // Process packet
+     *   console.log(`Stream ${packet.streamIndex}, PTS: ${packet.pts}`);
+     *   packet.unref();
+     * }
+     *
+     * if (ret !== AVERROR_EOF) {
+     *   FFmpegError.throwIfError(ret, 'readFrame');
+     * }
+     * ```
+     *
+     * @see {@link seekFrame} To seek before reading
+     */
+    readFrame(pkt: Packet): Promise<number>;
+    /**
+     * Read next packet from the input synchronously.
+     * Synchronous version of readFrame.
+     *
+     * Reads and returns the next packet in the stream.
+     * Packet must be unreferenced after use.
+     *
+     * Direct mapping to av_read_frame().
+     *
+     * @param pkt - Packet to read into
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EOF: End of file
+     *   - AVERROR_EAGAIN: Temporarily unavailable
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     * import { AVERROR_EOF } from 'node-av';
+     *
+     * const packet = new Packet();
+     * packet.alloc();
+     *
+     * let ret;
+     * while ((ret = ctx.readFrameSync(packet)) >= 0) {
+     *   // Process packet
+     *   console.log(`Stream ${packet.streamIndex}, PTS: ${packet.pts}`);
+     *   packet.unref();
+     * }
+     *
+     * if (ret !== AVERROR_EOF) {
+     *   FFmpegError.throwIfError(ret, 'readFrameSync');
+     * }
+     * ```
+     *
+     * @see {@link readFrame} For async version
+     */
+    readFrameSync(pkt: Packet): number;
+    /**
+     * Seek to timestamp in stream.
+     *
+     * Seeks to the keyframe at or before the given timestamp.
+     *
+     * Direct mapping to av_seek_frame().
+     *
+     * @param streamIndex - Stream to seek in (-1 for default)
+     *
+     * @param timestamp - Target timestamp in stream time base
+     *
+     * @param flags - Seek flags (AVSEEK_FLAG_*)
+     *
+     * @returns >=0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR_EOF: Seek beyond file
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     * import { AVSEEK_FLAG_BACKWARD } from 'node-av/constants';
+     *
+     * // Seek to 10 seconds (assuming 1/1000 time base)
+     * const ret = await ctx.seekFrame(videoStreamIndex, 10000n, AVSEEK_FLAG_BACKWARD);
+     * FFmpegError.throwIfError(ret, 'seekFrame');
+     * ```
+     *
+     * @see {@link seekFile} For more precise seeking
+     */
+    seekFrame(streamIndex: number, timestamp: bigint, flags?: AVSeekFlag): Promise<number>;
+    /**
+     * Seek to timestamp in stream synchronously.
+     * Synchronous version of seekFrame.
+     *
+     * Seeks to closest keyframe at or before timestamp.
+     * Timestamp is in stream timebase units.
+     *
+     * Direct mapping to av_seek_frame().
+     *
+     * @param streamIndex - Stream to seek in (-1 for default)
+     *
+     * @param timestamp - Target timestamp in stream timebase
+     *
+     * @param flags - Seek flags (AVSEEK_FLAG_*)
+     *
+     * @returns >=0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid arguments
+     *   - AVERROR(EIO): I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     * import { AVSEEK_FLAG_BACKWARD } from 'node-av/constants';
+     *
+     * // Seek to 10 seconds
+     * const timestamp = 10n * 1000000n; // Assuming microsecond timebase
+     * const ret = ctx.seekFrameSync(-1, timestamp, AVSEEK_FLAG_BACKWARD);
+     * FFmpegError.throwIfError(ret, 'seekFrameSync');
+     * ```
+     *
+     * @see {@link seekFrame} For async version
+     */
+    seekFrameSync(streamIndex: number, timestamp: bigint, flags?: AVSeekFlag): number;
+    /**
+     * Seek to timestamp with bounds.
+     *
+     * More precise seeking with min/max timestamp bounds.
+     *
+     * Direct mapping to avformat_seek_file().
+     *
+     * @param streamIndex - Stream to seek in (-1 for default)
+     *
+     * @param minTs - Minimum acceptable timestamp
+     *
+     * @param ts - Target timestamp
+     *
+     * @param maxTs - Maximum acceptable timestamp
+     *
+     * @param flags - Seek flags
+     *
+     * @returns >=0 on success, negative AVERROR on error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Seek to 10s with 0.5s tolerance
+     * const target = 10000n;
+     * const ret = await ctx.seekFile(
+     *   -1,
+     *   target - 500n,
+     *   target,
+     *   target + 500n
+     * );
+     * FFmpegError.throwIfError(ret, 'seekFile');
+     * ```
+     *
+     * @see {@link seekFileSync} For synchronous version
+     * @see {@link seekFrame} For simpler seeking
+     */
+    seekFile(streamIndex: number, minTs: bigint, ts: bigint, maxTs: bigint, flags?: AVSeekFlag): Promise<number>;
+    /**
+     * Seek to timestamp with bounds synchronously.
+     * Synchronous version of seekFile.
+     *
+     * More precise seeking with min/max timestamp bounds.
+     *
+     * Direct mapping to avformat_seek_file().
+     *
+     * @param streamIndex - Stream to seek in (-1 for default)
+     *
+     * @param minTs - Minimum acceptable timestamp
+     *
+     * @param ts - Target timestamp
+     *
+     * @param maxTs - Maximum acceptable timestamp
+     *
+     * @param flags - Seek flags
+     *
+     * @returns >=0 on success, negative AVERROR on error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Seek to 10s with 0.5s tolerance
+     * const target = 10000n;
+     * const ret = ctx.seekFileSync(
+     *   -1,
+     *   target - 500n,
+     *   target,
+     *   target + 500n
+     * );
+     * FFmpegError.throwIfError(ret, 'seekFileSync');
+     * ```
+     *
+     * @see {@link seekFile} For async version
+     * @see {@link seekFrameSync} For simpler seeking
+     */
+    seekFileSync(streamIndex: number, minTs: bigint, ts: bigint, maxTs: bigint, flags?: AVSeekFlag): number;
+    /**
+     * Write file header.
+     *
+     * Writes the file header and initializes output.
+     * Must be called before writing packets.
+     *
+     * Direct mapping to avformat_write_header().
+     *
+     * @param options - Muxer-specific options
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR_EIO: I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await ctx.writeHeader();
+     * FFmpegError.throwIfError(ret, 'writeHeader');
+     * // Now ready to write packets
+     * ```
+     *
+     * @see {@link writeTrailer} To finalize file
+     * @see {@link writeFrame} To write packets
+     */
+    writeHeader(options?: Dictionary | null): Promise<number>;
+    /**
+     * Write file header synchronously.
+     * Synchronous version of writeHeader.
+     *
+     * Writes format header to output file.
+     * Must be called before writing packets.
+     *
+     * Direct mapping to avformat_write_header().
+     *
+     * @param options - Muxer-specific options
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.writeHeaderSync();
+     * FFmpegError.throwIfError(ret, 'writeHeaderSync');
+     * ```
+     *
+     * @see {@link writeHeader} For async version
+     */
+    writeHeaderSync(options?: Dictionary | null): number;
+    /**
+     * Write packet to output.
+     *
+     * Writes a packet directly without interleaving.
+     * Caller must handle correct interleaving.
+     *
+     * Direct mapping to av_write_frame().
+     *
+     * @param pkt - Packet to write (null to flush)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid packet
+     *   - AVERROR_EIO: I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await ctx.writeFrame(packet);
+     * FFmpegError.throwIfError(ret, 'writeFrame');
+     * ```
+     *
+     * @see {@link interleavedWriteFrame} For automatic interleaving
+     */
+    writeFrame(pkt: Packet | null): Promise<number>;
+    /**
+     * Write packet to output synchronously.
+     * Synchronous version of writeFrame.
+     *
+     * Writes a packet directly without interleaving.
+     * Caller must handle correct interleaving.
+     *
+     * Direct mapping to av_write_frame().
+     *
+     * @param pkt - Packet to write (null to flush)
+     *
+     * @returns 0 on success, negative AVERROR on error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.writeFrameSync(packet);
+     * FFmpegError.throwIfError(ret, 'writeFrameSync');
+     * ```
+     *
+     * @see {@link writeFrame} For async version
+     */
+    writeFrameSync(pkt: Packet | null): number;
+    /**
+     * Write packet with automatic interleaving.
+     *
+     * Writes packet with proper interleaving for muxing.
+     * Preferred method for writing packets.
+     *
+     * Direct mapping to av_interleaved_write_frame().
+     *
+     * @param pkt - Packet to write (null to flush)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid packet
+     *   - AVERROR_EIO: I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Write with proper interleaving
+     * const ret = await ctx.interleavedWriteFrame(packet);
+     * FFmpegError.throwIfError(ret, 'interleavedWriteFrame');
+     *
+     * // Flush buffered packets
+     * await ctx.interleavedWriteFrame(null);
+     * ```
+     *
+     * @see {@link writeFrame} For direct writing
+     */
+    interleavedWriteFrame(pkt: Packet | null): Promise<number>;
+    /**
+     * Write packet with automatic interleaving synchronously.
+     * Synchronous version of interleavedWriteFrame.
+     *
+     * Writes packet with proper interleaving for muxing.
+     * Preferred method for writing packets.
+     *
+     * Direct mapping to av_interleaved_write_frame().
+     *
+     * @param pkt - Packet to write (null to flush)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR(EIO): I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Write packet
+     * const ret = ctx.interleavedWriteFrameSync(packet);
+     * FFmpegError.throwIfError(ret, 'interleavedWriteFrameSync');
+     *
+     * // Flush interleaved packets
+     * ctx.interleavedWriteFrameSync(null);
+     * ```
+     *
+     * @see {@link interleavedWriteFrame} For async version
+     */
+    interleavedWriteFrameSync(pkt: Packet | null): number;
+    /**
+     * Write file trailer.
+     *
+     * Finalizes the output file, writing index and metadata.
+     * Must be called to properly close output files.
+     *
+     * Direct mapping to av_write_trailer().
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EIO: I/O error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await ctx.writeTrailer();
+     * FFmpegError.throwIfError(ret, 'writeTrailer');
+     * // File is now finalized
+     * ```
+     *
+     * @see {@link writeHeader} Must be called first
+     */
+    writeTrailer(): Promise<number>;
+    /**
+     * Write file trailer synchronously.
+     * Synchronous version of writeTrailer.
+     *
+     * Finalizes the output file, writing index and metadata.
+     * Must be called to properly close output files.
+     *
+     * Direct mapping to av_write_trailer().
+     *
+     * @returns 0 on success, negative AVERROR on error
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.writeTrailerSync();
+     * FFmpegError.throwIfError(ret, 'writeTrailerSync');
+     * // File is now finalized
+     * ```
+     *
+     * @see {@link writeTrailer} For async version
+     */
+    writeTrailerSync(): number;
+    /**
+     * Flush buffered data.
+     *
+     * Flushes any buffered packets in muxers.
+     *
+     * Direct mapping to avio_flush().
+     *
+     * @example
+     * ```typescript
+     * await ctx.flush();
+     * // Buffered data written to output
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush buffered data synchronously.
+     * Synchronous version of flush.
+     *
+     * Flushes any buffered packets in muxers.
+     *
+     * Direct mapping to avio_flush().
+     *
+     * @example
+     * ```typescript
+     * ctx.flushSync();
+     * // Buffered data written to output
+     * ```
+     *
+     * @see {@link flush} For async version
+     */
+    flushSync(): void;
+    /**
+     * Print format information.
+     *
+     * Dumps human-readable format info to stderr.
+     * Useful for debugging.
+     *
+     * Direct mapping to av_dump_format().
+     *
+     * @param index - Stream index to highlight (-1 for none)
+     *
+     * @param url - URL to display
+     *
+     * @param isOutput - True for output format, false for input
+     *
+     * @example
+     * ```typescript
+     * // Dump input format info
+     * ctx.dumpFormat(0, 'input.mp4', false);
+     *
+     * // Dump output format info
+     * ctx.dumpFormat(0, 'output.mp4', true);
+     * ```
+     */
+    dumpFormat(index: number, url: string, isOutput: boolean): void;
+    /**
+     * Find the best stream of a given type.
+     *
+     * Selects the most suitable stream (e.g., default audio/video).
+     *
+     * Direct mapping to av_find_best_stream().
+     *
+     * @param type - Media type to find (AVMEDIA_TYPE_*)
+     *
+     * @param wantedStreamNb - Preferred stream index (-1 for auto)
+     *
+     * @param relatedStream - Related stream for audio/video sync (-1 for none)
+     *
+     * @returns Stream index, or negative AVERROR if not found
+     *
+     * @example
+     * ```typescript
+     * import { AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO } from 'node-av/constants';
+     *
+     * const videoIndex = ctx.findBestStream(AVMEDIA_TYPE_VIDEO);
+     * if (videoIndex >= 0) {
+     *   console.log(`Best video stream: ${videoIndex}`);
+     * }
+     *
+     * const audioIndex = ctx.findBestStream(AVMEDIA_TYPE_AUDIO);
+     * if (audioIndex >= 0) {
+     *   console.log(`Best audio stream: ${audioIndex}`);
+     * }
+     * ```
+     */
+    findBestStream(type: AVMediaType, wantedStreamNb?: number, relatedStream?: number): number;
+    /**
+     * Find the best stream and its decoder.
+     *
+     * @param type - Media type to find
+     *
+     * @param wantedStreamNb - Preferred stream index
+     *
+     * @param relatedStream - Related stream index
+     *
+     * @param wantDecoder - True to also find decoder
+     *
+     * @param flags - Reserved flags
+     *
+     * @returns Object with stream index and decoder
+     */
+    findBestStream(type: AVMediaType, wantedStreamNb: number, relatedStream: number, wantDecoder: true, flags?: number): {
+        streamIndex: number;
+        decoder: Codec | null;
+    };
+    /**
+     * Add a new stream to output context.
+     *
+     * Creates a new stream for writing.
+     *
+     * Direct mapping to avformat_new_stream().
+     *
+     * @param c - Codec for the stream (optional)
+     *
+     * @returns New stream instance
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * const codec = Codec.findEncoder(AV_CODEC_ID_H264);
+     * const stream = ctx.newStream(codec);
+     * stream.id = ctx.nbStreams - 1;
+     * ```
+     *
+     * @see {@link Stream} For stream configuration
+     */
+    newStream(c?: Codec | null): Stream;
+    /**
+     * Set format flags.
+     *
+     * Sets one or more flags using bitwise OR. Allows setting multiple flags
+     * without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to set
+     *
+     * @example
+     * ```typescript
+     * import { AVFMT_FLAG_GENPTS, AVFMT_FLAG_IGNIDX } from 'node-av/constants';
+     *
+     * // Set multiple flags at once
+     * formatContext.setFlags(AVFMT_FLAG_GENPTS, AVFMT_FLAG_IGNIDX);
+     * ```
+     *
+     * @see {@link clearFlags} To unset flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    setFlags(...flags: AVFormatFlag[]): void;
+    /**
+     * Clear format flags.
+     *
+     * Clears one or more flags using bitwise AND NOT. Allows clearing multiple
+     * flags without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to clear
+     *
+     * @example
+     * ```typescript
+     * import { AVFMT_FLAG_IGNIDX } from 'node-av/constants';
+     *
+     * // Clear specific flag
+     * formatContext.clearFlags(AVFMT_FLAG_IGNIDX);
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    clearFlags(...flags: AVFormatFlag[]): void;
+    /**
+     * Check if format context has specific flags.
+     *
+     * Tests whether all specified flags are set using bitwise AND.
+     *
+     * @param flags - One or more flag values to check
+     *
+     * @returns true if all specified flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { AVFMT_FLAG_GENPTS } from 'node-av/constants';
+     *
+     * if (formatContext.hasFlags(AVFMT_FLAG_GENPTS)) {
+     *   console.log('GENPTS flag is set');
+     * }
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link clearFlags} To unset flags
+     * @see {@link flags} For direct flag access
+     */
+    hasFlags(...flags: AVFormatFlag[]): boolean;
+    /**
+     * Get RTSP stream information.
+     *
+     * Returns information about all RTSP streams including codec details.
+     * Only works with RTSP input contexts.
+     *
+     * @returns Array of stream information objects with codec details, or null if not RTSP
+     *
+     * @example
+     * ```typescript
+     * const ctx = new FormatContext();
+     * await ctx.openInput('rtsp://camera/stream?backchannel=1');
+     *
+     * const rtspStreams = ctx.getRTSPStreamInfo();
+     * if (rtspStreams) {
+     *   // Find sendonly stream (backchannel)
+     *   const backchannel = rtspStreams.find(s => s.direction === 'sendonly');
+     *   if (backchannel) {
+     *     console.log(`Transport: ${backchannel.transport}`);
+     *     console.log(`Codec ID: ${backchannel.codecId}`);
+     *     console.log(`MIME Type: ${backchannel.mimeType}`);
+     *     console.log(`Payload Type: ${backchannel.payloadType}`);
+     *     if (backchannel.sampleRate) {
+     *       console.log(`Audio: ${backchannel.sampleRate}Hz, ${backchannel.channels} channels`);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    getRTSPStreamInfo(): RTSPStreamInfo[] | null;
+    /**
+     * Interrupt any in-progress blocking I/O operation.
+     *
+     * Signals the interrupt callback so a blocking call (e.g. av_read_frame() on a
+     * quiet RTSP socket) returns immediately instead of waiting for data. The
+     * context is not freed and remains valid - this only aborts the pending
+     * operation, so a reader can drain and shut down before closing the input.
+     * An input pb with JS callbacks stops serving the input as on close: a call
+     * waiting for one of its callbacks fails with AVERROR_EXIT, and its callbacks
+     * are not called again.
+     *
+     * @example
+     * ```typescript
+     * ctx.interrupt(); // unblock a stalled readFrame()
+     * ```
+     *
+     * @see {@link closeInput} To close and free the input
+     */
+    interrupt(): void;
+    /**
+     * Send RTP packet to RTSP stream (supports both TCP and UDP)
+     *
+     * Automatically handles transport-specific packet formatting:
+     * - TCP: Sends with interleaved header ($channelId + length + RTP)
+     * - UDP: Sends raw RTP packet directly to UDP socket
+     *
+     * Used for backchannel/talkback audio streaming.
+     * Only works with RTSP input contexts.
+     *
+     * @param streamIndex - RTSP stream index
+     *
+     * @param rtpData - Raw RTP packet data (12-byte header + payload)
+     *
+     * @returns Promise resolving to number of bytes written on success, negative AVERROR on failure
+     *
+     * @example
+     * ```typescript
+     * // Get backchannel stream info
+     * const streams = ctx.getRTSPStreamInfo();
+     * const backchannel = streams.find(s => s.direction === 'sendonly');
+     *
+     * if (backchannel) {
+     *   // Send to camera (works with both TCP and UDP)
+     *   const ret = await ctx.sendRTSPPacket(backchannel.streamIndex, rtpPacket);
+     *   if (ret < 0) {
+     *     throw new Error(`Failed to send: ${ret}`);
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link sendRTSPPacketSync} For synchronous version
+     * @see {@link getRTSPStreamInfo} For getting stream info and transport type
+     */
+    sendRTSPPacket(streamIndex: number, rtpData: Buffer): Promise<number>;
+    /**
+     * Send RTP packet to RTSP stream (supports both TCP and UDP) synchronously.
+     * Synchronous version of sendRTSPPacket.
+     *
+     * Automatically handles transport-specific packet formatting:
+     * - TCP: Sends with interleaved header ($channelId + length + RTP)
+     * - UDP: Sends raw RTP packet directly to UDP socket
+     *
+     * Used for backchannel/talkback audio streaming.
+     * Only works with RTSP input contexts.
+     *
+     * @param streamIndex - RTSP stream index
+     *
+     * @param rtpData - Raw RTP packet data (12-byte header + payload)
+     *
+     * @returns Number of bytes written on success, negative AVERROR on failure
+     *
+     * @example
+     * ```typescript
+     * // Get backchannel stream info
+     * const streams = ctx.getRTSPStreamInfo();
+     * const backchannel = streams.find(s => s.direction === 'sendonly');
+     *
+     * if (backchannel) {
+     *   // Send to camera (works with both TCP and UDP)
+     *   const ret = ctx.sendRTSPPacketSync(backchannel.streamIndex, rtpPacket);
+     *   if (ret < 0) {
+     *     throw new Error(`Failed to send: ${ret}`);
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link sendRTSPPacket} For asynchronous version
+     * @see {@link getRTSPStreamInfo} For getting stream info and transport type
+     */
+    sendRTSPPacketSync(streamIndex: number, rtpData: Buffer): number;
+    /**
+     * Get the underlying native FormatContext object.
+     *
+     * @returns The native FormatContext binding object
+     *
+     * @internal
+     */
+    getNative(): NativeFormatContext;
+    /**
+     * Dispose of the format context.
+     *
+     * Implements the AsyncDisposable interface for automatic cleanup.
+     * Closes input/output and frees resources.
+     *
+     * @returns Promise that resolves when disposed
+     *
+     * @example
+     * ```typescript
+     * {
+     *   await using ctx = new FormatContext();
+     *   await ctx.openInput('input.mp4');
+     *   // Use context...
+     * } // Automatically closed and freed
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}