The AVOption system in FFmpeg provides a unified interface for configuring codec, format, and filter parameters. When working with encoders, this structure defines how user-facing settnigs map to internal context fields and how named constants are associated with specific parameters.

Core Structure Definition

Each configurable parameter is represented by an AVOption entry containing metadata, type information, and value constraints:

typedef struct AVOption {
    const char *name;       // Identifier used in CLI or API calls
    const char *help;       // Brief description of the parameter
    int offset;             // Byte offset within the context struct (0 for constants)
    enum AVOptionType type; // Data type (INT, STRING, CONST, etc.)
    union {
        int64_t i64;
        double dbl;
        const char *str;
        AVRational q;
    } default_val;          // Fallback value for scalar types
    double min;             // Lower bound for numeric options
    double max;             // Upper bound for numeric options
    int flags;              // Usage context (ENCODING, DECODING, VIDEO, AUDIO, etc.)
    const char *unit;       // Logical group linking parameters to their constants
} AVOption;

The flags field utilizes bitwise masks to indicate where an option applies. Common masks include AV_OPT_FLAG_ENCODING_PARAM, AV_OPT_FLAG_VIDEO_PARAM, and AV_OPT_FLAG_READONLY. These determine whether the setting is mutable during runtime, restricted to specific media types, or meant solely for exporting itnernal state.

Parameter vs. Constant Classification

Options generally fall into two distinct categories based on their role in the configuration pipeline:

1. Configurable Parameters: These hold actual values that modify encoder behavior. They specify a valid memory offset pointing to a field in the private context structure, define a concrete type (e.g., AV_OPT_TYPE_INT), and often include min/max boundaries.
2. Named Constants: These act as predefined values for configurable parameters. They are marked with AV_OPT_TYPE_CONST, always have an offset of 0, and store their actual numeric value inside default_val.i64.

The linkage between a parameter and its allowed constants is established through the unit field. A parameter declares a unit string, and any constant sharing that exact string becomes a valid assignment for that parameter.

Practical Configuration Example

The following array demonstrates how a hypothetical video encoder defines a rate control mode alongside its associated constants:

#define OPT_OFFSET(x) offsetof(EncoderContext, x)

static const AVOption encoder_opts[] = {
    { "rc_mode", "Rate control strategy selection", OPT_OFFSET(rate_ctrl), AV_OPT_TYPE_INT, { .i64 = -1 }, -1, 2, AV_OPT_FLAG_ENCODING_PARAM | AV_OPT_FLAG_VIDEO_PARAM, "rc_strategy" },
    { "auto",    "Let the encoder decide",          0, AV_OPT_TYPE_CONST, { .i64 = RC_AUTO },    0, 0, AV_OPT_FLAG_ENCODING_PARAM | AV_OPT_FLAG_VIDEO_PARAM, "rc_strategy" },
    { "cqp",     "Constant quantization parameter", 0, AV_OPT_TYPE_CONST, { .i64 = RC_CQP },     0, 0, AV_OPT_FLAG_ENCODING_PARAM | AV_OPT_FLAG_VIDEO_PARAM, "rc_strategy" },
    { "vbr",     "Variable bitrate targeting",      0, AV_OPT_TYPE_CONST, { .i64 = RC_VBR },     0, 0, AV_OPT_FLAG_ENCODING_PARAM | AV_OPT_FLAG_VIDEO_PARAM, "rc_strategy" },
    { "log_file","Path for encoding statistics",    OPT_OFFSET(stats_path), AV_OPT_TYPE_STRING, { .str = NULL }, 0, 0, AV_OPT_FLAG_ENCODING_PARAM | AV_OPT_FLAG_VIDEO_PARAM, NULL },
    { NULL }
};

In this configuration:

• rc_mode is the primary adjustable field. Its unit is set to "rc_strategy", signaling that it expects values from constants belonging to that group.
• auto, cqp, and vbr are constants. Their offset is 0, their type is AV_OPT_TYPE_CONST, and they share the "rc_strategy" unit. When a user passes -rc_mode vbr, the options parser resolves the string to the constant's i64 value (RC_VBR) and writes it to the memory location specified by OPT_OFFSET(rate_ctrl).
• log_file operates independently. Since it accepts arbitrary string input rather than a predefined set of constants, its unit remains NULL.

The options parsing mechanism automatically validates assignments, ensuring that only constants matching the target parameter's unit are applied, while standalone parameters bypass unit validation entirely.