node-av 1.1.0 → 1.3.0

package/dist/lib/option.d.ts

@@ -1,501 +1,683 @@
-/**
- * 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 { 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/index.js';
 import type { OptionCapableObject } from './binding.js';
 import type { NativeOption } from './native-types.js';
 import type { ChannelLayout, IRational } from './types.js';
 /**
- * Low-level wrapper for a single AVOption.
+ * Option information descriptor.
+ *
+ * Describes a single option available on an FFmpeg object.
+ * Contains metadata about the option including name, type, default value,
+ * valid range, and documentation. Used to discover and validate options.
  *
- * 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().
+ * Direct mapping to FFmpeg's AVOption.
  *
  * @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}`);
+ * import { Option } from 'node-av';
+ *
+ * // Get option info
+ * const optInfo = Option.find(obj, 'bitrate');
+ * if (optInfo) {
+ *   console.log(`Option: ${optInfo.name}`);
+ *   console.log(`Help: ${optInfo.help}`);
+ *   console.log(`Type: ${optInfo.type}`);
+ *   console.log(`Default: ${optInfo.defaultValue}`);
+ *   console.log(`Range: ${optInfo.min} - ${optInfo.max}`);
  * }
  * ```
+ *
+ * @see [AVOption](https://ffmpeg.org/doxygen/trunk/structAVOption.html) - FFmpeg Doxygen
  */
 export declare class OptionInfo {
     private native;
-    /** @internal */
+    /**
+     * @param native - The native option instance
+     * @internal
+     */
     constructor(native: NativeOption);
     /**
      * Option name.
      *
-     * The key used to get/set this option.
+     * The name used to get/set this option.
+     *
+     * Direct mapping to AVOption->name.
      */
     get name(): string | null;
     /**
      * Option help text.
      *
-     * Human-readable description of the option.
+     * Human-readable description of the option's purpose.
+     *
+     * Direct mapping to AVOption->help.
      */
     get help(): string | null;
     /**
      * Option type.
      *
-     * Determines the data type and valid range of values.
+     * Data type of the option value (AV_OPT_TYPE_*).
+     *
+     * Direct mapping to AVOption->type.
      */
     get type(): AVOptionType;
     /**
      * Default value.
      *
-     * The value used if not explicitly set.
+     * The default value for this option.
      * Type depends on the option type.
+     *
+     * Direct mapping to AVOption->default_val.
      */
     get defaultValue(): unknown;
     /**
      * Minimum value.
      *
-     * For numeric types, the minimum allowed value.
+     * Minimum valid value for numeric options.
+     *
+     * Direct mapping to AVOption->min.
      */
     get min(): number;
     /**
      * Maximum value.
      *
-     * For numeric types, the maximum allowed value.
+     * Maximum valid value for numeric options.
+     *
+     * Direct mapping to AVOption->max.
      */
     get max(): number;
     /**
      * Option flags.
      *
-     * Bitfield of AV_OPT_FLAG_* values indicating option properties.
+     * Combination of AV_OPT_FLAG_* indicating option properties.
+     *
+     * Direct mapping to AVOption->flags.
      */
     get flags(): AVOptionFlag;
     /**
      * Option unit.
      *
-     * For options that are part of a named group.
+     * Unit string for grouping related options.
+     *
+     * Direct mapping to AVOption->unit.
      */
     get unit(): string | null;
     /**
-     * Get the native FFmpeg AVOption pointer.
+     * Get the underlying native Option object.
      *
-     * @internal For use by other wrapper classes
-     * @returns The underlying native option object
+     * @returns The native Option binding object
+     *
+     * @internal
      */
     getNative(): NativeOption;
 }
 /**
- * Low-level FFmpeg AVOption API.
+ * FFmpeg option management utilities.
  *
- * Provides static methods for accessing and modifying options on FFmpeg objects.
- * All methods work with native objects from the low-level API.
+ * Provides static methods for getting, setting, and querying options
+ * on FFmpeg objects that support the AVOption API. Handles type conversion
+ * and validation for various option types including strings, numbers,
+ * rationals, pixel formats, and more.
  *
- * Uses av_opt_* functions internally.
+ * Direct mapping to FFmpeg's AVOption API.
  *
  * @example
  * ```typescript
- * // Set codec bitrate
- * Option.setInt(codecContext, 'b', 2000000);
+ * import { Option, FFmpegError } from 'node-av';
+ * import { AV_OPT_SEARCH_CHILDREN, AV_PIX_FMT_YUV420P } from 'node-av/constants';
+ *
+ * // Set various option types
+ * let ret = Option.set(obj, 'preset', 'fast');
+ * FFmpegError.throwIfError(ret, 'set preset');
  *
- * // Get current bitrate
- * const bitrate = Option.getInt(codecContext, 'b');
+ * ret = Option.setInt(obj, 'bitrate', 2000000);
+ * FFmpegError.throwIfError(ret, 'set bitrate');
  *
- * // Iterate through all options
+ * ret = Option.setRational(obj, 'framerate', { num: 30, den: 1 });
+ * FFmpegError.throwIfError(ret, 'set framerate');
+ *
+ * // Get option values
+ * const preset = Option.get(obj, 'preset');
+ * const bitrate = Option.getInt(obj, 'bitrate');
+ * const framerate = Option.getRational(obj, 'framerate');
+ *
+ * // List all options
  * let opt = null;
- * while ((opt = Option.next(codecContext, opt))) {
+ * while ((opt = Option.next(obj, opt))) {
  *   console.log(`${opt.name}: ${opt.help}`);
  * }
  * ```
+ *
+ * @see [AVOption API](https://ffmpeg.org/doxygen/trunk/group__avoptions.html) - FFmpeg Doxygen
+ * @see {@link OptionMember} For inherited option support
  */
 export declare class Option {
-    private constructor();
     /**
-     * Iterate through options of an object.
+     * Iterate to next option.
      *
-     * Uses av_opt_next() internally.
+     * Iterates through available options on an object.
      *
-     * @param obj - Native object (CodecContext, FormatContext, FilterContext, etc.)
-     * @param prev - Previous option for iteration, or null to start
+     * Direct mapping to av_opt_next().
      *
-     * @returns Next option or null when done
+     * @param obj - Object with options
+     * @param prev - Previous option (null to get first)
+     * @returns Next option, or null if no more
      *
      * @example
      * ```typescript
      * let opt = null;
-     * while ((opt = Option.next(codecContext, opt))) {
-     *   console.log(`${opt.name}: ${opt.help}`);
+     * while ((opt = Option.next(obj, opt))) {
+     *   console.log(`Option: ${opt.name}`);
      * }
      * ```
      */
     static next(obj: OptionCapableObject, prev?: OptionInfo | null): OptionInfo | null;
     /**
-     * Find an option by name.
+     * Find option by name.
      *
-     * Uses av_opt_find() internally.
+     * Searches for an option with the specified name.
      *
-     * @param obj - Native object
-     * @param name - Option name to find
-     * @param searchFlags - Search flags (default: 0)
+     * Direct mapping to av_opt_find().
      *
-     * @returns Found option or null
+     * @param obj - Object to search
+     * @param name - Option name
+     * @param searchFlags - Search flags
+     * @returns Option info if found, null otherwise
      *
      * @example
      * ```typescript
-     * const opt = Option.find(codecContext, 'bitrate');
+     * const opt = Option.find(obj, 'bitrate');
      * if (opt) {
-     *   console.log(`Found option: ${opt.name}`);
+     *   console.log(`Found: ${opt.name}, Type: ${opt.type}`);
      * }
      * ```
      */
     static find(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): OptionInfo | null;
     /**
-     * Find an option by name with target object information.
+     * Find option with target info.
+     *
+     * Like find() but also indicates if option was found on different target.
      *
-     * Uses av_opt_find2() internally.
+     * Direct mapping to av_opt_find2().
      *
-     * @param obj - Native object
-     * @param name - Option name to find
-     * @param searchFlags - Search flags (default: 0)
+     * @param obj - Object to search
+     * @param name - Option name
+     * @param searchFlags - Search flags
+     * @returns Object with option and target info
      *
-     * @returns Object with option and whether target differs, or null
+     * @example
+     * ```typescript
+     * const result = Option.find2(obj, 'bitrate', AV_OPT_SEARCH_CHILDREN);
+     * if (result?.option) {
+     *   console.log(`Found on ${result.isDifferentTarget ? 'child' : 'object'}`);
+     * }
+     * ```
      */
     static find2(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): {
         option: OptionInfo | null;
         isDifferentTarget: boolean;
     } | null;
     /**
-     * Get option value as string.
+     * Get string option value.
      *
-     * Uses av_opt_get() internally.
-     * Converts any option type to its string representation.
+     * Direct mapping to av_opt_get().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Option value as string, or null
      *
-     * @returns Value string on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get codec preset option
+     * const preset = Option.get(codecContext, 'preset', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Codec preset:', preset); // 'medium', 'fast', etc.
+     * ```
      */
     static get(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): string | null;
     /**
-     * Get option value as integer.
+     * Get integer option value.
      *
-     * Uses av_opt_get_int() internally.
-     * Option must be of integer type.
+     * Direct mapping to av_opt_get_int().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Option value as integer, or null
      *
-     * @returns Integer value on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get codec GOP size
+     * const gopSize = Option.getInt(codecContext, 'g', AV_OPT_SEARCH_CHILDREN);
+     * console.log('GOP size:', gopSize); // 60, 120, etc.
+     * ```
      */
     static getInt(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): number | null;
     /**
-     * Get option value as double.
+     * Get double option value.
      *
-     * Uses av_opt_get_double() internally.
-     * Option must be of double/float type.
+     * Direct mapping to av_opt_get_double().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Option value as double, or null
      *
-     * @returns Double value on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get codec quality scale
+     * const crf = Option.getDouble(codecContext, 'crf', AV_OPT_SEARCH_CHILDREN);
+     * console.log('CRF value:', crf); // 23.0, 18.0, etc.
+     * ```
      */
     static getDouble(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): number | null;
     /**
-     * Get option value as rational.
+     * Get rational option value.
      *
-     * Uses av_opt_get_q() internally.
-     * Option must be of rational type.
+     * Direct mapping to av_opt_get_q().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Option value as rational, or null
      *
-     * @returns Rational object {num, den} on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get codec time base
+     * const timeBase = Option.getRational(codecContext, 'time_base', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Time base:', timeBase); // { num: 1, den: 30 }
+     * ```
      */
     static getRational(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): IRational | null;
     /**
-     * Get option value as pixel format.
+     * Get pixel format option value.
      *
-     * Uses av_opt_get_pixel_fmt() internally.
-     * Option must be of pixel format type.
+     * Direct mapping to av_opt_get_pixel_fmt().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Pixel format value, or null
      *
-     * @returns AVPixelFormat enum value on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get filter pixel format
+     * const pixFmt = Option.getPixelFormat(filterContext, 'pix_fmt', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Pixel format:', pixFmt); // AV_PIX_FMT_YUV420P, etc.
+     * ```
      */
     static getPixelFormat(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): AVPixelFormat | null;
     /**
-     * Get option value as sample format.
+     * Get sample format option value.
      *
-     * Uses av_opt_get_sample_fmt() internally.
-     * Option must be of sample format type.
+     * Direct mapping to av_opt_get_sample_fmt().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Sample format value, or null
      *
-     * @returns AVSampleFormat enum value on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get audio codec sample format
+     * const sampleFmt = Option.getSampleFormat(codecContext, 'sample_fmt', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Sample format:', sampleFmt); // AV_SAMPLE_FMT_FLTP, etc.
+     * ```
      */
     static getSampleFormat(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): AVSampleFormat | null;
     /**
-     * Get option value as image size.
+     * Get image size option value.
      *
-     * Uses av_opt_get_image_size() internally.
-     * Option must be of image size type.
+     * Direct mapping to av_opt_get_image_size().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Width and height, or null
      *
-     * @returns Size object {width, height} on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get filter output size
+     * const size = Option.getImageSize(filterContext, 'size', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Output size:', size); // { width: 1920, height: 1080 }
+     * ```
      */
     static getImageSize(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): {
         width: number;
         height: number;
     } | null;
     /**
-     * Get option value as channel layout.
+     * Get channel layout option value.
      *
-     * Uses av_opt_get_chlayout() internally.
-     * Option must be of channel layout type.
+     * Direct mapping to av_opt_get_chlayout().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Channel layout, or null
      *
-     * @returns ChannelLayout object on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get audio channel layout
+     * const layout = Option.getChannelLayout(codecContext, 'channel_layout', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Channel layout:', layout); // stereo, 5.1, etc.
+     * ```
      */
     static getChannelLayout(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): ChannelLayout | null;
     /**
-     * Get option value as dictionary.
+     * Get dictionary option value.
      *
-     * Uses av_opt_get_dict_val() internally.
-     * Option must be of dictionary type.
+     * Direct mapping to av_opt_get_dict_val().
      *
-     * @param obj - Native object
+     * @param obj - Object to query
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns Dictionary value, or null
      *
-     * @returns Dictionary object on success, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Get metadata dictionary
+     * const metadata = Option.getDict(formatContext, 'metadata', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Metadata:', metadata?.get('title'));
+     * ```
      */
     static getDict(obj: OptionCapableObject, name: string, searchFlags?: AVOptionSearchFlags): Dictionary | null;
     /**
-     * Set option value from string.
+     * Set string option value.
      *
-     * Uses av_opt_set() internally.
-     * Can be used for any option type - FFmpeg will parse the string.
+     * Direct mapping to av_opt_set().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - String value to set
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - String value
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set codec preset
+     * const ret = Option.set(codecContext, 'preset', 'fast', AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set preset');
+     * ```
      */
     static set(obj: OptionCapableObject, name: string, value: string, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as integer.
+     * Set integer option value.
      *
-     * Uses av_opt_set_int() internally.
-     * More efficient than set() for numeric options.
+     * Direct mapping to av_opt_set_int().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - Number or BigInt value to set
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Integer value
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set codec bitrate
+     * const ret = Option.setInt(codecContext, 'b', 2000000, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set bitrate');
+     * ```
      */
     static setInt(obj: OptionCapableObject, name: string, value: number | bigint, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as double.
+     * Set double option value.
      *
-     * Uses av_opt_set_double() internally.
-     * More efficient than set() for floating point options.
+     * Direct mapping to av_opt_set_double().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - Double value to set
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Double value
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set codec CRF value
+     * const ret = Option.setDouble(codecContext, 'crf', 23.0, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set CRF');
+     * ```
      */
     static setDouble(obj: OptionCapableObject, name: string, value: number, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as rational.
+     * Set rational option value.
      *
-     * Uses av_opt_set_q() internally.
-     * For framerates, aspect ratios, time bases, etc.
+     * Direct mapping to av_opt_set_q().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - Rational object {num, den} to set
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Rational value
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set codec frame rate
+     * const ret = Option.setRational(codecContext, 'framerate', { num: 30, den: 1 }, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set framerate');
+     * ```
      */
     static setRational(obj: OptionCapableObject, name: string, value: IRational, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as pixel format.
+     * Set pixel format option value.
      *
-     * Uses av_opt_set_pixel_fmt() internally.
-     * More type-safe than using set() with string names.
+     * Direct mapping to av_opt_set_pixel_fmt().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - AVPixelFormat enum value
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Pixel format
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set filter pixel format
+     * const ret = Option.setPixelFormat(filterContext, 'pix_fmt', AV_PIX_FMT_YUV420P, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set pixel format');
+     * ```
      */
     static setPixelFormat(obj: OptionCapableObject, name: string, value: AVPixelFormat, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as sample format.
+     * Set sample format option value.
      *
-     * Uses av_opt_set_sample_fmt() internally.
-     * More type-safe than using set() with string names.
+     * Direct mapping to av_opt_set_sample_fmt().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - AVSampleFormat enum value
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Sample format
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set audio codec sample format
+     * const ret = Option.setSampleFormat(codecContext, 'sample_fmt', AV_SAMPLE_FMT_FLTP, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set sample format');
+     * ```
      */
     static setSampleFormat(obj: OptionCapableObject, name: string, value: AVSampleFormat, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as image size.
+     * Set image size option value.
      *
-     * Uses av_opt_set_image_size() internally.
-     * Convenient for setting width and height together.
+     * Direct mapping to av_opt_set_image_size().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param width - Width in pixels
-     * @param height - Height in pixels
-     * @param searchFlags - Search flags (default: 0)
+     * @param width - Image width
+     * @param height - Image height
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set filter output size
+     * const ret = Option.setImageSize(filterContext, 'size', 1920, 1080, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set image size');
+     * ```
      */
     static setImageSize(obj: OptionCapableObject, name: string, width: number, height: number, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as channel layout.
+     * Set channel layout option value.
      *
-     * Uses av_opt_set_chlayout() internally.
-     * For audio channel configuration.
+     * Direct mapping to av_opt_set_chlayout().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - Channel layout mask (e.g., AV_CH_LAYOUT_STEREO)
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Channel layout
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set audio channel layout to stereo
+     * const ret = Option.setChannelLayout(codecContext, 'channel_layout', AV_CHANNEL_LAYOUT_STEREO, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set channel layout');
+     * ```
      */
     static setChannelLayout(obj: OptionCapableObject, name: string, value: number, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as dictionary.
+     * Set dictionary option value.
      *
-     * Uses av_opt_set_dict_val() internally.
-     * For options that accept key-value pairs.
+     * Direct mapping to av_opt_set_dict_val().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - Dictionary object
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Dictionary value
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set metadata dictionary
+     * const dict = new Dictionary();
+     * dict.set('title', 'My Video');
+     * const ret = Option.setDict(formatContext, 'metadata', dict, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set metadata');
+     * ```
      */
     static setDict(obj: OptionCapableObject, name: string, value: Dictionary, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set option value as binary data.
+     * Set binary option value.
      *
-     * Uses av_opt_set_bin() internally.
-     * For options that accept raw binary data.
+     * Direct mapping to av_opt_set_bin().
      *
-     * @param obj - Native object
+     * @param obj - Object to modify
      * @param name - Option name
-     * @param value - Binary data as Buffer
-     * @param searchFlags - Search flags (default: 0)
+     * @param value - Binary data
+     * @param searchFlags - Search flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Set binary extradata
+     * const extradata = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+     * const ret = Option.setBin(codecContext, 'extradata', extradata, AV_OPT_SEARCH_CHILDREN);
+     * FFmpegError.throwIfError(ret, 'Failed to set extradata');
+     * ```
      */
     static setBin(obj: OptionCapableObject, name: string, value: Buffer, searchFlags?: AVOptionSearchFlags): number;
     /**
-     * Set all options to their default values.
+     * Set defaults on object.
+     *
+     * Sets all options to their default values.
      *
-     * Uses av_opt_set_defaults() internally.
+     * Direct mapping to av_opt_set_defaults().
      *
-     * @param obj - Native object
+     * @param obj - Object to reset
+     *
+     * @example
+     * ```typescript
+     * // Reset all codec options to defaults
+     * Option.setDefaults(codecContext);
+     * ```
      */
     static setDefaults(obj: OptionCapableObject): void;
     /**
-     * Copy options from source to destination.
+     * Copy options between objects.
+     *
+     * Copies option values from source to destination.
      *
-     * Uses av_opt_copy() internally.
-     * Copies all option values from one object to another.
+     * Direct mapping to av_opt_copy().
      *
      * @param dest - Destination object
      * @param src - Source object
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Copy options from one codec context to another
+     * const ret = Option.copy(destCodecContext, srcCodecContext);
+     * FFmpegError.throwIfError(ret, 'Failed to copy options');
+     * ```
      */
     static copy(dest: OptionCapableObject, src: OptionCapableObject): number;
     /**
-     * Check if option is set to its default value.
+     * Check if option is set to default.
      *
-     * Uses av_opt_is_set_to_default_by_name() internally.
+     * Direct mapping to av_opt_is_set_to_default().
      *
-     * @param obj - Native object
+     * @param obj - Object to check
      * @param name - Option name
-     * @param searchFlags - Search flags (default: 0)
+     * @param searchFlags - Search flags
+     * @returns True if default, false if modified, null if not found
      *
-     * @returns true if set to default, false if not, null if option not found or on error
+     * @example
+     * ```typescript
+     * // Check if bitrate is at default value
+     * const isDefault = Option.isSetToDefault(codecContext, 'b', AV_OPT_SEARCH_CHILDREN);
+     * console.log('Bitrate is default:', isDefault);
+     * ```
      */
     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.
+     * Direct mapping to av_opt_serialize().
      *
-     * @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: ',')
+     * @param obj - Object to serialize
+     * @param optFlags - Option flags filter
+     * @param flags - Serialization flags
+     * @param keyValSep - Key-value separator
+     * @param pairsSep - Pairs separator
+     * @returns Serialized string, or null on error
      *
-     * @returns Serialized string on success, null on error or if no options to serialize
+     * @example
+     * ```typescript
+     * // Serialize codec options to string
+     * const serialized = Option.serialize(codecContext, 0, 0, '=', ':');
+     * console.log('Options:', serialized); // 'bitrate=2000000:preset=fast'
+     * ```
      */
     static serialize(obj: OptionCapableObject, optFlags?: number, flags?: number, keyValSep?: string, pairsSep?: string): string | null;
     /**
-     * Free options of an object.
+     * Free option resources.
+     *
+     * Direct mapping to av_opt_free().
      *
-     * Uses av_opt_free() internally.
+     * @param obj - Object to free options from
      *
-     * @param obj - Native object
+     * @example
+     * ```typescript
+     * // Free codec context options
+     * Option.free(codecContext);
+     * ```
      */
     static free(obj: OptionCapableObject): void;
     /**
-     * Show options to stderr for debugging.
+     * Show options for debugging.
      *
-     * Uses av_opt_show2() internally.
-     * Prints all available options to stderr.
+     * Direct mapping to av_opt_show2().
      *
-     * @param obj - Native object
-     * @param reqFlags - Required flags (default: 0)
-     * @param rejFlags - Rejected flags (default: 0)
+     * @param obj - Object to show options for
+     * @param reqFlags - Required flags
+     * @param rejFlags - Rejected flags
+     * @returns 0 on success, negative AVERROR on error
      *
-     * @returns 0 on success, negative AVERROR code on failure
+     * @example
+     * ```typescript
+     * // Show all codec options for debugging
+     * const ret = Option.show(codecContext, 0, 0);
+     * FFmpegError.throwIfError(ret, 'Failed to show options');
+     * ```
      */
     static show(obj: OptionCapableObject, reqFlags?: number, rejFlags?: number): number;
 }
@@ -513,10 +695,42 @@ export declare class Option {
  *
  * @example
  * ```typescript
+ * import { OptionMember, FFmpegError } from 'node-av';
+ * import { AV_OPT_TYPE_INT, AV_OPT_TYPE_STRING, AV_OPT_TYPE_RATIONAL } from 'node-av/constants';
+ *
  * class CodecContext extends OptionMember<NativeCodecContext> {
- *   // Inherits setOption, getOption, listOptions
+ *   constructor(native: NativeCodecContext) {
+ *     super(native);
+ *   }
+ * }
+ *
+ * // Use inherited methods
+ * const codec = new CodecContext(native);
+ *
+ * // Set options with automatic type handling
+ * let ret = codec.setOption('preset', 'fast');
+ * FFmpegError.throwIfError(ret, 'set preset');
+ *
+ * ret = codec.setOption('bitrate', 2000000, AV_OPT_TYPE_INT);
+ * FFmpegError.throwIfError(ret, 'set bitrate');
+ *
+ * ret = codec.setOption('framerate', { num: 30, den: 1 }, AV_OPT_TYPE_RATIONAL);
+ * FFmpegError.throwIfError(ret, 'set framerate');
+ *
+ * // Get typed options
+ * const preset = codec.getOption('preset');
+ * const bitrate = codec.getOption('bitrate', AV_OPT_TYPE_INT);
+ * const framerate = codec.getOption('framerate', AV_OPT_TYPE_RATIONAL);
+ *
+ * // List all available options
+ * const options = codec.listOptions();
+ * for (const opt of options) {
+ *   console.log(`${opt.name}: ${opt.help}`);
  * }
  * ```
+ *
+ * @see {@link Option} For static option methods
+ * @see {@link OptionInfo} For option metadata
  */
 export declare class OptionMember<T extends OptionCapableObject> {
     protected native: T;
@@ -574,6 +788,8 @@ export declare class OptionMember<T extends OptionCapableObject> {
      * Uses the AVOption API to enumerate all options.
      * Useful for discovering available settings and their types.
      *
+     * Direct mapping to av_opt_next() iteration.
+     *
      * @returns Array of option information objects
      *
      * @example
@@ -582,8 +798,11 @@ export declare class OptionMember<T extends OptionCapableObject> {
      * for (const opt of options) {
      *   console.log(`${opt.name}: ${opt.help}`);
      *   console.log(`  Type: ${opt.type}, Default: ${opt.defaultValue}`);
+     *   console.log(`  Range: ${opt.min} - ${opt.max}`);
      * }
      * ```
+     *
+     * @see {@link OptionInfo} For option metadata structure
      */
     listOptions(): OptionInfo[];
 }