node-av 1.3.0 → 2.1.0

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

@@ -242,8 +242,11 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -277,24 +280,6 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @see {@link Symbol.asyncDispose} For automatic cleanup
      */
     freeContext(): void;
-    /**
-     * Close an input format context.
-     *
-     * Closes input file and releases resources.
-     *
-     * Direct mapping to avformat_close_input().
-     *
-     * @returns Promise that resolves when closed
-     *
-     * @example
-     * ```typescript
-     * await ctx.closeInput();
-     * // Input closed and context freed
-     * ```
-     *
-     * @see {@link openInput} To open input
-     */
-    closeInput(): Promise<void>;
     /**
      * Open output file for writing.
      *
@@ -320,6 +305,30 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -338,6 +347,23 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -347,8 +373,11 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -366,6 +395,72 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
+     *
+     * Direct mapping to avformat_close_input().
+     *
+     * @returns Promise that resolves when closed
+     *
+     * @example
+     * ```typescript
+     * await ctx.closeInput();
+     * // Input closed and context freed
+     * ```
+     *
+     * @see {@link openInput} To open input
+     */
+    closeInput(): Promise<void>;
+    /**
+     * Close an input format context synchronously.
+     * Synchronous version of closeInput.
+     *
+     * Closes input file and releases resources.
+     *
+     * Direct mapping to avformat_close_input().
+     *
+     * @example
+     * ```typescript
+     * ctx.closeInputSync();
+     * // Input closed and context freed
+     * ```
+     *
+     * @see {@link closeInput} For async version
+     */
+    closeInputSync(): void;
     /**
      * Analyze streams to get stream info.
      *
@@ -375,6 +470,7 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -391,6 +487,33 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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 - Options dictionary (single, not array for sync version)
+     *
+     * @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.
      *
@@ -400,6 +523,7 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -427,6 +551,44 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -435,8 +597,11 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -454,6 +619,39 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -462,10 +660,15 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -495,6 +698,7 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -512,6 +716,31 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -521,6 +750,7 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -536,6 +766,30 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -545,6 +799,7 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -564,6 +819,36 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -587,6 +872,29 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * @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.
      *
@@ -596,11 +904,28 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      *
      * @example
      * ```typescript
-     * ctx.flush();
+     * 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
      */
-    flush(): void;
+    flushSync(): void;
     /**
      * Print format information.
      *
@@ -610,7 +935,9 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -631,8 +958,11 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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
@@ -655,10 +985,15 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * 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): {
@@ -673,6 +1008,7 @@ export declare class FormatContext extends OptionMember<NativeFormatContext> imp
      * Direct mapping to avformat_new_stream().
      *
      * @param c - Codec for the stream (optional)
+     *
      * @returns New stream instance
      *
      * @example