node-av 1.1.0 → 1.3.0

package/dist/lib/option.js

@@ -1,43 +1,48 @@
-/**
- * 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 { AV_OPT_SEARCH_CHILDREN, AV_OPT_TYPE_BINARY, AV_OPT_TYPE_BINARY_INT_ARRAY, AV_OPT_TYPE_BOOL, AV_OPT_TYPE_CHLAYOUT, AV_OPT_TYPE_COLOR, AV_OPT_TYPE_CONST, AV_OPT_TYPE_DICT, AV_OPT_TYPE_DOUBLE, AV_OPT_TYPE_DURATION, AV_OPT_TYPE_FLAGS, AV_OPT_TYPE_FLOAT, AV_OPT_TYPE_IMAGE_SIZE, AV_OPT_TYPE_INT, AV_OPT_TYPE_INT64, AV_OPT_TYPE_PIXEL_FMT, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_SAMPLE_FMT, AV_OPT_TYPE_STRING, AV_OPT_TYPE_UINT, AV_OPT_TYPE_UINT64, AV_OPT_TYPE_VIDEO_RATE, AVFLAG_NONE, } from '../constants/constants.js';
 import { bindings } from './binding.js';
 import { Dictionary } from './dictionary.js';
 import { Rational } from './rational.js';
 /**
- * Low-level wrapper for a single AVOption.
+ * Option information descriptor.
  *
- * 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().
+ * 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.
+ *
+ * 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 class OptionInfo {
     native;
-    /** @internal */
+    /**
+     * @param native - The native option instance
+     * @internal
+     */
     constructor(native) {
         this.native = native;
     }
     /**
      * 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() {
         return this.native.name;
@@ -45,7 +50,9 @@ export class OptionInfo {
     /**
      * Option help text.
      *
-     * Human-readable description of the option.
+     * Human-readable description of the option's purpose.
+     *
+     * Direct mapping to AVOption->help.
      */
     get help() {
         return this.native.help;
@@ -53,7 +60,9 @@ export class OptionInfo {
     /**
      * 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() {
         return this.native.type;
@@ -61,8 +70,10 @@ export class OptionInfo {
     /**
      * 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() {
         return this.native.defaultValue;
@@ -70,7 +81,9 @@ export class OptionInfo {
     /**
      * Minimum value.
      *
-     * For numeric types, the minimum allowed value.
+     * Minimum valid value for numeric options.
+     *
+     * Direct mapping to AVOption->min.
      */
     get min() {
         return this.native.min;
@@ -78,7 +91,9 @@ export class OptionInfo {
     /**
      * Maximum value.
      *
-     * For numeric types, the maximum allowed value.
+     * Maximum valid value for numeric options.
+     *
+     * Direct mapping to AVOption->max.
      */
     get max() {
         return this.native.max;
@@ -86,7 +101,9 @@ export class OptionInfo {
     /**
      * 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() {
         return this.native.flags;
@@ -94,65 +111,81 @@ export class OptionInfo {
     /**
      * Option unit.
      *
-     * For options that are part of a named group.
+     * Unit string for grouping related options.
+     *
+     * Direct mapping to AVOption->unit.
      */
     get unit() {
         return this.native.unit;
     }
     /**
-     * Get the native FFmpeg AVOption pointer.
+     * Get the underlying native Option object.
+     *
+     * @returns The native Option binding object
      *
-     * @internal For use by other wrapper classes
-     * @returns The underlying native option object
+     * @internal
      */
     getNative() {
         return this.native;
     }
 }
 /**
- * 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');
+ *
+ * ret = Option.setInt(obj, 'bitrate', 2000000);
+ * FFmpegError.throwIfError(ret, 'set bitrate');
  *
- * // Get current bitrate
- * const bitrate = Option.getInt(codecContext, 'b');
+ * ret = Option.setRational(obj, 'framerate', { num: 30, den: 1 });
+ * FFmpegError.throwIfError(ret, 'set framerate');
  *
- * // Iterate through all options
+ * // 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 class Option {
-    // Private constructor - static class only
-    constructor() {
-        throw new Error('Option is a static class and cannot be instantiated');
-    }
-    // Static Methods - Iteration
     /**
-     * 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}`);
      * }
      * ```
      */
@@ -161,21 +194,22 @@ export class Option {
         return result ? new OptionInfo(result) : 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}`);
      * }
      * ```
      */
@@ -184,15 +218,24 @@ export class Option {
         return result ? new OptionInfo(result) : 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, name, searchFlags = AVFLAG_NONE) {
         const result = bindings.Option.find2(obj, name, searchFlags);
@@ -204,336 +247,455 @@ export class Option {
         };
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.get(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getInt(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getDouble(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getRational(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getPixelFormat(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getSampleFormat(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getImageSize(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.getChannelLayout(obj, name, searchFlags);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         const native = bindings.Option.getDict(obj, name, searchFlags);
         return native ? Dictionary.fromNative(native) : 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.set(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setInt(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setDouble(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setRational(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setPixelFormat(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setSampleFormat(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, width, height, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setImageSize(obj, name, width, height, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setChannelLayout(obj, name, value, searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setDict(obj, name, value.getNative(), searchFlags);
     }
     /**
-     * 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, name, value, searchFlags = AVFLAG_NONE) {
         return bindings.Option.setBin(obj, name, value, searchFlags);
     }
     /**
-     * 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) {
         bindings.Option.setDefaults(obj);
     }
     /**
-     * Copy options from source to destination.
+     * Copy options between objects.
      *
-     * Uses av_opt_copy() internally.
-     * Copies all option values from one object to another.
+     * Copies option values from source to destination.
+     *
+     * 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, src) {
         return bindings.Option.copy(dest, src);
     }
     /**
-     * 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, name, searchFlags = AVFLAG_NONE) {
         return bindings.Option.isSetToDefault(obj, name, searchFlags);
@@ -541,41 +703,57 @@ export class Option {
     /**
      * 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, optFlags = 0, flags = 0, keyValSep = '=', pairsSep = ',') {
         return bindings.Option.serialize(obj, optFlags, flags, keyValSep, pairsSep);
     }
     /**
-     * Free options of an object.
+     * Free option resources.
      *
-     * Uses av_opt_free() internally.
+     * Direct mapping to av_opt_free().
      *
-     * @param obj - Native object
+     * @param obj - Object to free options from
+     *
+     * @example
+     * ```typescript
+     * // Free codec context options
+     * Option.free(codecContext);
+     * ```
      */
     static free(obj) {
         bindings.Option.free(obj);
     }
     /**
-     * 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, reqFlags = 0, rejFlags = 0) {
         return bindings.Option.show(obj, reqFlags, rejFlags);
@@ -595,10 +773,42 @@ export 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 class OptionMember {
     native;
@@ -611,25 +821,42 @@ export class OptionMember {
      * Uses the AVOption API to set options.
      * Available options depend on the specific object type.
      *
+     * Direct mapping to av_opt_set* functions.
+     *
      * @param name - Option name
      * @param value - Option value
      * @param type - Option type (defaults to AV_OPT_TYPE_STRING)
      * @param searchFlags - Search flags (default: AV_OPT_SEARCH_CHILDREN)
-     * @returns 0 on success, negative AVERROR code on failure
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOENT: Option not found
+     *   - AVERROR_ERANGE: Value out of range
+     *   - AVERROR_EINVAL: Invalid value
      *
      * @example
      * ```typescript
+     * import { FFmpegError } from 'node-av';
+     * import { AV_OPT_TYPE_STRING, AV_OPT_TYPE_INT64, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_PIXEL_FMT } from 'node-av/constants';
+     *
      * // String options (default)
-     * ret = obj.setOption('preset', 'fast');
+     * let ret = obj.setOption('preset', 'fast');
+     * FFmpegError.throwIfError(ret, 'set preset');
+     *
      * ret = obj.setOption('codec', 'h264', AV_OPT_TYPE_STRING);
+     * FFmpegError.throwIfError(ret, 'set codec');
      *
      * // Integer options
      * ret = obj.setOption('bitrate', 2000000, AV_OPT_TYPE_INT64);
+     * FFmpegError.throwIfError(ret, 'set bitrate');
+     *
      * ret = obj.setOption('threads', 4, AV_OPT_TYPE_INT);
+     * FFmpegError.throwIfError(ret, 'set threads');
      *
      * // Complex types with proper types
      * ret = obj.setOption('framerate', {num: 30, den: 1}, AV_OPT_TYPE_RATIONAL);
+     * FFmpegError.throwIfError(ret, 'set framerate');
+     *
      * ret = obj.setOption('pix_fmt', AV_PIX_FMT_YUV420P, AV_OPT_TYPE_PIXEL_FMT);
+     * FFmpegError.throwIfError(ret, 'set pixel format');
      * ```
      */
     setOption(name, value, type = AV_OPT_TYPE_STRING, searchFlags = AV_OPT_SEARCH_CHILDREN) {
@@ -758,13 +985,17 @@ export class OptionMember {
      *
      * Uses the AVOption API to retrieve options.
      *
+     * Direct mapping to av_opt_get* functions.
+     *
      * @param name - Option name
      * @param type - Option type (defaults to AV_OPT_TYPE_STRING)
      * @param searchFlags - Search flags (default: AV_OPT_SEARCH_CHILDREN)
-     * @returns Option value (type depends on type parameter)
+     * @returns Option value (type depends on type parameter), or null if not found
      *
      * @example
      * ```typescript
+     * import { AV_OPT_TYPE_STRING, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_PIXEL_FMT, AV_OPT_TYPE_INT64 } from 'node-av/constants';
+     *
      * // String options (default)
      * const preset = obj.getOption('preset');
      * const codec = obj.getOption('codec', AV_OPT_TYPE_STRING);
@@ -772,7 +1003,7 @@ export class OptionMember {
      * // Typed options
      * const framerate = obj.getOption('framerate', AV_OPT_TYPE_RATIONAL); // Returns {num, den}
      * const pixFmt = obj.getOption('pix_fmt', AV_OPT_TYPE_PIXEL_FMT); // Returns AVPixelFormat
-     * const bitrate = obj.getOption('bitrate', AV_OPT_TYPE_INT64); // Returns number
+     * const bitrate = obj.getOption('bitrate', AV_OPT_TYPE_INT64); // Returns bigint
      * ```
      */
     getOption(name, type = AV_OPT_TYPE_STRING, searchFlags = AV_OPT_SEARCH_CHILDREN) {
@@ -830,6 +1061,8 @@ export class OptionMember {
      * 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
@@ -838,8 +1071,11 @@ export class OptionMember {
      * 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() {
         const options = [];