node-av 0.0.1

package/dist/lib/native-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=native-types.js.map

package/dist/lib/native-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-types.js","sourceRoot":"","sources":["../../src/lib/native-types.ts"],"names":[],"mappings":""}

package/dist/lib/option.d.ts

@@ -0,0 +1,589 @@
+/**
+ * Option - FFmpeg AVOption System Bindings
+ *
+ * Provides low-level access to FFmpeg's AVOption API for getting and setting
+ * options on various FFmpeg objects (CodecContext, FormatContext, FilterContext, etc).
+ *
+ * The AVOption API is FFmpeg's unified system for runtime configuration,
+ * allowing type-safe access to object properties with validation.
+ *
+ * @module lib/option
+ */
+import { Dictionary } from './dictionary.js';
+import type { OptionCapableObject } from './binding.js';
+import type { AVOptionFlag, AVOptionSearchFlags, AVOptionType, AVOptionTypeBinary, AVOptionTypeBinaryIntArray, AVOptionTypeBool, AVOptionTypeChLayout, AVOptionTypeColor, AVOptionTypeConst, AVOptionTypeDict, AVOptionTypeDouble, AVOptionTypeDuration, AVOptionTypeFlags, AVOptionTypeFloat, AVOptionTypeImageSize, AVOptionTypeInt, AVOptionTypeInt64, AVOptionTypePixelFmt, AVOptionTypeRational, AVOptionTypeSampleFmt, AVOptionTypeString, AVOptionTypeUint, AVOptionTypeUint64, AVOptionTypeVideoRate, AVPixelFormat, AVSampleFormat } from './constants.js';
+import type { NativeOption } from './native-types.js';
+import type { ChannelLayout, IRational } from './types.js';
+/**
+ * Low-level wrapper for a single AVOption.
+ *
+ * Provides metadata about an option including its name, type, range, and default value.
+ * Options are not created directly but retrieved through Option.next() or Option.find().
+ *
+ * @example
+ * ```typescript
+ * const opt = Option.find(codecContext, 'bitrate');
+ * if (opt) {
+ *   console.log(`Option ${opt.name}: ${opt.help}`);
+ *   console.log(`Type: ${opt.type}, Default: ${opt.defaultValue}`);
+ * }
+ * ```
+ */
+export declare class OptionInfo {
+    private native;
+    /** @internal */
+    constructor(native: NativeOption);
+    /**
+     * Option name.
+     *
+     * The key used to get/set this option.
+     */
+    get name(): string | null;
+    /**
+     * Option help text.
+     *
+     * Human-readable description of the option.
+     */
+    get help(): string | null;
+    /**
+     * Option type.
+     *
+     * Determines the data type and valid range of values.
+     */
+    get type(): AVOptionType;
+    /**
+     * Default value.
+     *
+     * The value used if not explicitly set.
+     * Type depends on the option type.
+     */
+    get defaultValue(): unknown;
+    /**
+     * Minimum value.
+     *
+     * For numeric types, the minimum allowed value.
+     */
+    get min(): number;
+    /**
+     * Maximum value.
+     *
+     * For numeric types, the maximum allowed value.
+     */
+    get max(): number;
+    /**
+     * Option flags.
+     *
+     * Bitfield of AV_OPT_FLAG_* values indicating option properties.
+     */
+    get flags(): AVOptionFlag;
+    /**
+     * Option unit.
+     *
+     * For options that are part of a named group.
+     */
+    get unit(): string | null;
+    /**
+     * Get the native FFmpeg AVOption pointer.
+     *
+     * @internal For use by other wrapper classes
+     * @returns The underlying native option object
+     */
+    getNative(): NativeOption;
+}
+/**
+ * Low-level FFmpeg AVOption API.
+ *
+ * Provides static methods for accessing and modifying options on FFmpeg objects.
+ * All methods work with native objects from the low-level API.
+ *
+ * Uses av_opt_* functions internally.
+ *
+ * @example
+ * ```typescript
+ * // Set codec bitrate
+ * Option.setInt(codecContext, 'b', 2000000);
+ *
+ * // Get current bitrate
+ * const bitrate = Option.getInt(codecContext, 'b');
+ *
+ * // Iterate through all options
+ * let opt = null;
+ * while ((opt = Option.next(codecContext, opt))) {
+ *   console.log(`${opt.name}: ${opt.help}`);
+ * }
+ * ```
+ */
+export declare class Option {
+    private constructor();
+    /**
+     * Iterate through options of an object.
+     *
+     * Uses av_opt_next() internally.
+     *
+     * @param obj - Native object (CodecContext, FormatContext, FilterContext, etc.)
+     * @param prev - Previous option for iteration, or null to start
+     *
+     * @returns Next option or null when done
+     *
+     * @example
+     * ```typescript
+     * let opt = null;
+     * while ((opt = Option.next(codecContext, opt))) {
+     *   console.log(`${opt.name}: ${opt.help}`);
+     * }
+     * ```
+     */
+    static next(obj: OptionCapableObject, prev?: OptionInfo | null): OptionInfo | null;
+    /**
+     * Find an option by name.
+     *
+     * Uses av_opt_find() internally.
+     *
+     * @param obj - Native object
+     * @param name - Option name to find
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Found option or null
+     *
+     * @example
+     * ```typescript
+     * const opt = Option.find(codecContext, 'bitrate');
+     * if (opt) {
+     *   console.log(`Found option: ${opt.name}`);
+     * }
+     * ```
+     */
+    static find(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): OptionInfo | null;
+    /**
+     * Find an option by name with target object information.
+     *
+     * Uses av_opt_find2() internally.
+     *
+     * @param obj - Native object
+     * @param name - Option name to find
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Object with option and whether target differs, or null
+     */
+    static find2(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): {
+        option: OptionInfo | null;
+        isDifferentTarget: boolean;
+    } | null;
+    /**
+     * Get option value as string.
+     *
+     * Uses av_opt_get() internally.
+     * Converts any option type to its string representation.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Value string on success, null if option not found or on error
+     */
+    static get(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): string | null;
+    /**
+     * Get option value as integer.
+     *
+     * Uses av_opt_get_int() internally.
+     * Option must be of integer type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Integer value on success, null if option not found or on error
+     */
+    static getInt(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): number | null;
+    /**
+     * Get option value as double.
+     *
+     * Uses av_opt_get_double() internally.
+     * Option must be of double/float type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Double value on success, null if option not found or on error
+     */
+    static getDouble(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): number | null;
+    /**
+     * Get option value as rational.
+     *
+     * Uses av_opt_get_q() internally.
+     * Option must be of rational type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Rational object {num, den} on success, null if option not found or on error
+     */
+    static getRational(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): IRational | null;
+    /**
+     * Get option value as pixel format.
+     *
+     * Uses av_opt_get_pixel_fmt() internally.
+     * Option must be of pixel format type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns AVPixelFormat enum value on success, null if option not found or on error
+     */
+    static getPixelFormat(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): AVPixelFormat | null;
+    /**
+     * Get option value as sample format.
+     *
+     * Uses av_opt_get_sample_fmt() internally.
+     * Option must be of sample format type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns AVSampleFormat enum value on success, null if option not found or on error
+     */
+    static getSampleFormat(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): AVSampleFormat | null;
+    /**
+     * Get option value as image size.
+     *
+     * Uses av_opt_get_image_size() internally.
+     * Option must be of image size type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Size object {width, height} on success, null if option not found or on error
+     */
+    static getImageSize(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Get option value as channel layout.
+     *
+     * Uses av_opt_get_chlayout() internally.
+     * Option must be of channel layout type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns ChannelLayout object on success, null if option not found or on error
+     */
+    static getChannelLayout(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): ChannelLayout | null;
+    /**
+     * Get option value as dictionary.
+     *
+     * Uses av_opt_get_dict_val() internally.
+     * Option must be of dictionary type.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns Dictionary object on success, null if option not found or on error
+     */
+    static getDict(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): Dictionary | null;
+    /**
+     * Set option value from string.
+     *
+     * Uses av_opt_set() internally.
+     * Can be used for any option type - FFmpeg will parse the string.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - String value to set
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static set(obj: OptionCapableObject, name: string, value: string, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as integer.
+     *
+     * Uses av_opt_set_int() internally.
+     * More efficient than set() for numeric options.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - Number or BigInt value to set
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setInt(obj: OptionCapableObject, name: string, value: number | bigint, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as double.
+     *
+     * Uses av_opt_set_double() internally.
+     * More efficient than set() for floating point options.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - Double value to set
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setDouble(obj: OptionCapableObject, name: string, value: number, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as rational.
+     *
+     * Uses av_opt_set_q() internally.
+     * For framerates, aspect ratios, time bases, etc.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - Rational object {num, den} to set
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setRational(obj: OptionCapableObject, name: string, value: IRational, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as pixel format.
+     *
+     * Uses av_opt_set_pixel_fmt() internally.
+     * More type-safe than using set() with string names.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - AVPixelFormat enum value
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setPixelFormat(obj: OptionCapableObject, name: string, value: AVPixelFormat, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as sample format.
+     *
+     * Uses av_opt_set_sample_fmt() internally.
+     * More type-safe than using set() with string names.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - AVSampleFormat enum value
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setSampleFormat(obj: OptionCapableObject, name: string, value: AVSampleFormat, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as image size.
+     *
+     * Uses av_opt_set_image_size() internally.
+     * Convenient for setting width and height together.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param width - Width in pixels
+     * @param height - Height in pixels
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setImageSize(obj: OptionCapableObject, name: string, width: number, height: number, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as channel layout.
+     *
+     * Uses av_opt_set_chlayout() internally.
+     * For audio channel configuration.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - Channel layout mask (e.g., AV_CH_LAYOUT_STEREO)
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setChannelLayout(obj: OptionCapableObject, name: string, value: number, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as dictionary.
+     *
+     * Uses av_opt_set_dict_val() internally.
+     * For options that accept key-value pairs.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - Dictionary object
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setDict(obj: OptionCapableObject, name: string, value: Dictionary, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set option value as binary data.
+     *
+     * Uses av_opt_set_bin() internally.
+     * For options that accept raw binary data.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param value - Binary data as Buffer
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static setBin(obj: OptionCapableObject, name: string, value: Buffer, searchFlags?: AVOptionSearchFlags): number;
+    /**
+     * Set all options to their default values.
+     *
+     * Uses av_opt_set_defaults() internally.
+     *
+     * @param obj - Native object
+     */
+    static setDefaults(obj: OptionCapableObject): void;
+    /**
+     * Copy options from source to destination.
+     *
+     * Uses av_opt_copy() internally.
+     * Copies all option values from one object to another.
+     *
+     * @param dest - Destination object
+     * @param src - Source object
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static copy(dest: OptionCapableObject, src: OptionCapableObject): number;
+    /**
+     * Check if option is set to its default value.
+     *
+     * Uses av_opt_is_set_to_default_by_name() internally.
+     *
+     * @param obj - Native object
+     * @param name - Option name
+     * @param searchFlags - Search flags (default: 0)
+     *
+     * @returns true if set to default, false if not, null if option not found or on error
+     */
+    static isSetToDefault(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): boolean | null;
+    /**
+     * Serialize options to string.
+     *
+     * Uses av_opt_serialize() internally.
+     * Converts all non-default options to a string representation.
+     *
+     * @param obj - Native object
+     * @param optFlags - Option flags to include (default: 0)
+     * @param flags - Serialization flags (default: 0)
+     * @param keyValSep - Key-value separator (default: '=')
+     * @param pairsSep - Pairs separator (default: ',')
+     *
+     * @returns Serialized string on success, null on error or if no options to serialize
+     */
+    static serialize(obj: OptionCapableObject, optFlags?: number, flags?: number, keyValSep?: string, pairsSep?: string): string | null;
+    /**
+     * Free options of an object.
+     *
+     * Uses av_opt_free() internally.
+     *
+     * @param obj - Native object
+     */
+    static free(obj: OptionCapableObject): void;
+    /**
+     * Show options to stderr for debugging.
+     *
+     * Uses av_opt_show2() internally.
+     * Prints all available options to stderr.
+     *
+     * @param obj - Native object
+     * @param reqFlags - Required flags (default: 0)
+     * @param rejFlags - Rejected flags (default: 0)
+     *
+     * @returns 0 on success, negative AVERROR code on failure
+     */
+    static show(obj: OptionCapableObject, reqFlags?: number, rejFlags?: number): number;
+}
+/**
+ * Base class for FFmpeg objects that support AVOptions.
+ *
+ * Provides a common interface for getting, setting, and listing options
+ * on FFmpeg objects that have an AVClass structure. This includes codecs,
+ * formats, filters, and various processing contexts.
+ *
+ * Classes that support AVOptions should extend this class to inherit
+ * the option management functionality.
+ *
+ * @template T - The native FFmpeg object type that supports AVOptions
+ *
+ * @example
+ * ```typescript
+ * class CodecContext extends OptionMember<NativeCodecContext> {
+ *   // Inherits setOption, getOption, listOptions
+ * }
+ * ```
+ */
+export declare class OptionMember<T extends OptionCapableObject> {
+    protected native: T;
+    constructor(native: T);
+    setOption(name: string, value: string, type?: AVOptionTypeString, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: string, type: AVOptionTypeColor, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeInt, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: bigint, type: AVOptionTypeInt64, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeUint, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: bigint, type: AVOptionTypeUint64, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeFlags, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: boolean, type: AVOptionTypeBool, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeDuration, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeConst, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeDouble, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number, type: AVOptionTypeFloat, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: IRational, type: AVOptionTypeRational, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: IRational, type: AVOptionTypeVideoRate, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: AVPixelFormat, type: AVOptionTypePixelFmt, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: AVSampleFormat, type: AVOptionTypeSampleFmt, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: {
+        width: number;
+        height: number;
+    }, type: AVOptionTypeImageSize, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number | bigint, type: AVOptionTypeChLayout, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: Buffer, type: AVOptionTypeBinary, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: number[], type: AVOptionTypeBinaryIntArray, searchFlags?: AVOptionSearchFlags): number;
+    setOption(name: string, value: Dictionary, type: AVOptionTypeDict, searchFlags?: AVOptionSearchFlags): number;
+    getOption(name: string, type?: AVOptionTypeString, searchFlags?: AVOptionSearchFlags): string | null;
+    getOption(name: string, type: AVOptionTypeColor, searchFlags?: AVOptionSearchFlags): string | null;
+    getOption(name: string, type: AVOptionTypeInt, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeInt64, searchFlags?: AVOptionSearchFlags): bigint | null;
+    getOption(name: string, type: AVOptionTypeUint, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeUint64, searchFlags?: AVOptionSearchFlags): bigint | null;
+    getOption(name: string, type: AVOptionTypeFlags, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeBool, searchFlags?: AVOptionSearchFlags): boolean | null;
+    getOption(name: string, type: AVOptionTypeDuration, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeConst, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeDouble, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeFloat, searchFlags?: AVOptionSearchFlags): number | null;
+    getOption(name: string, type: AVOptionTypeRational, searchFlags?: AVOptionSearchFlags): IRational | null;
+    getOption(name: string, type: AVOptionTypeVideoRate, searchFlags?: AVOptionSearchFlags): IRational | null;
+    getOption(name: string, type: AVOptionTypePixelFmt, searchFlags?: AVOptionSearchFlags): AVPixelFormat | null;
+    getOption(name: string, type: AVOptionTypeSampleFmt, searchFlags?: AVOptionSearchFlags): AVSampleFormat | null;
+    getOption(name: string, type: AVOptionTypeImageSize, searchFlags?: AVOptionSearchFlags): {
+        width: number;
+        height: number;
+    } | null;
+    getOption(name: string, type: AVOptionTypeChLayout, searchFlags?: AVOptionSearchFlags): ChannelLayout | null;
+    getOption(name: string, type: AVOptionTypeDict, searchFlags?: AVOptionSearchFlags): Dictionary | null;
+    getOption(name: string, type: AVOptionTypeBinary, searchFlags?: AVOptionSearchFlags): string | null;
+    /**
+     * List all available options for this object.
+     *
+     * Uses the AVOption API to enumerate all options.
+     * Useful for discovering available settings and their types.
+     *
+     * @returns Array of option information objects
+     *
+     * @example
+     * ```typescript
+     * const options = obj.listOptions();
+     * for (const opt of options) {
+     *   console.log(`${opt.name}: ${opt.help}`);
+     *   console.log(`  Type: ${opt.type}, Default: ${opt.defaultValue}`);
+     * }
+     * ```
+     */
+    listOptions(): OptionInfo[];
+}