FFmpeg庖丁解牛系列之option模块

关注

原创最新推荐文章于 2026-04-05 09:13:41 发布 3.2k 阅读 AI 写同款· GEO 优化 ›

Ollama内网离线部署大模型实战：从模型文件到私有化服务本文详细介绍了如何在内网离线环境下，利用Ollama部署私有化大模型服务。内容涵盖从获取GGUF格式模型文件、手动安装Ollama、编写核心Modelfile配置文件，到创建运行模型、性能调优及安全加固的全流程实战指南，旨在帮助企业安全、可控地构建内部AI能力。阅读详情

关于option模块

option是FFmpeg中另一个很基础的模块，相对于log模块，代码量上要复杂一些。主要代码实现在如下两个文件中：

libavutil/opt.c
libavutil/opt.h

关于AVOptions的介绍，直接参考log.h里的头文件注释吧：

AVOptions provide a generic system to declare options on arbitrary structs (“objects”). An option can have a help text, a type and a range of possible values. Options may then be enumerated, read and written to.

基于QQ浏览器自带的网络翻译软件（应该是腾讯翻译君），结果如下，翻译的还不错：

AVOptions提供了一个通用系统来声明任意结构中的选项(“对象”)。选项可以有帮助文本、类型和可能值的范围。然后可以枚举、读取和写入选项。实际上，是提供了一种通用方法，简便的对结构体成员变量进行赋值，并且不同的结构体是通用的。

简单使用的例子

下面的结构体是带option使能的，

 typedef struct test_struct {
     const AVClass *class;
     int      int_opt;
     char    *str_opt;
     uint8_t *bin_opt;
     int      bin_len;
 } test_struct;


 static const AVOption test_options[] = {
   { "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
     AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
   { "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
     AV_OPT_TYPE_STRING },
   { "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
     AV_OPT_TYPE_BINARY },
   { NULL },
 };


 static const AVClass test_class = {
     .class_name = "test class",
     .item_name  = av_default_item_name,
     .option     = test_options,
     .version    = LIBAVUTIL_VERSION_INT,
 };

继续分析注释里的讲解，

Next, when allocating your struct, you must ensure that the AVClass
pointer is set to the correct value. Then, av_opt_set_defaults() can
be called to initialize defaults. After that the struct is ready to be
used with the AVOptions API. When cleaning up, you may use the
av_opt_free() function to automatically free all the allocated string
and binary options.

接下来，在分配结构体时，必须确保AVClass指针设置为正确的值。然后，可以调用av_opt_set_defaults()来初始化默认值。之后，该结构体就做好了通过AVOptions API使用的准备工作了。
当准备清理时，您可以使用av_opt_free()函数自动释放所有分配的字符串和二进制选项。下面是具体的使用例子，分别介绍了在分配结构体和释放结构体时，需要额外进行的options操作。

  test_struct *alloc_test_struct(void)
  {
      test_struct *ret = av_mallocz(sizeof(*ret));
      ret->class = &test_class;
      av_opt_set_defaults(ret);
      return ret;
  }
  void free_test_struct(test_struct **foo)
  {
      av_opt_free(*foo);
      av_freep(foo);
  }

嵌套的option使用

还是先来看注释说明，

It may happen that an AVOptions-enabled struct contains another
AVOptions-enabled struct as a member (e.g. AVCodecContext in
libavcodec exports generic options, while its priv_data field exports
codec-specific options). In such a case, it is possible to set up the
parent struct to export a child’s options. To do that, simply
implement AVClass.child_next() and AVClass.child_class_next() in the
parent struct’s AVClass.

还有的情况是，一个启用了AVOptions的结构体作为另一个启用了AVOptions的结构体的成员(例如，AVCodecContext中的libavcodec输出通用选项，而它的priv_data字段则输出编解码器特定选项)。在这样的情况下，可以设置父结构以导出子选项。要做到这一点，只需在父结构体的AVClass中实现AVClass.child_next()和AVClass.child_class_next() 即可。假设上面的test_struct现在还包含一个child_struct结构体字段，如下：

    typedef struct child_struct {
        AVClass *class;
        int flags_opt;
    } child_struct;
    static const AVOption child_opts[] = {
        { "test_flags", "This is a test option of flags type.",
          offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
        { NULL },
    };
    static const AVClass child_class = {
        .class_name = "child class",
        .item_name  = av_default_item_name,
        .option     = child_opts,
        .version    = LIBAVUTIL_VERSION_INT,
    };

    void *child_next(void *obj, void *prev)
    {
        test_struct *t = obj;
        if (!prev && t->child_struct)
            return t->child_struct;
        return NULL;
    }
    const AVClass child_class_next(const AVClass *prev)
    {
        return prev ? NULL : &child_class;
    }

Putting child_next() and child_class_next() as defined above into
test_class will now make child_struct’s options accessible through
test_struct (again, proper setup as described above needs to be done on
child_struct right after it is created).

将child_next()和child_class_next() 两个函数实现作为test_class 的成员函数，将使子结构的选项可以通过test_class 来获得(当然，如前所述，也需要在child_struct 创建时做正确的设置)，类似如下：

static const AVClass test_class = {
     .class_name = "test class",
     .item_name  = av_default_item_name,
     .option     = test_options,
     .version    = LIBAVUTIL_VERSION_INT,                    
     .child_class_next = child_class_next,
     .child_next = child_next,
 };

From the above example it might not be clear why both child_next()
and child_class_next() are needed. The distinction is that child_next()
iterates over actually existing objects, while child_class_next()
iterates over all possible child classes. E.g. if an AVCodecContext
was initialized to use a codec which has private options, then its
child_next() will return AVCodecContext.priv_data and finish
iterating. OTOH child_class_next() on AVCodecContext.av_class will
iterate over all available codecs with private options.

上述例子可能不是很清晰，为什么需要两个函数child_next()
和child_class_next()实现而不是一个就可以呢？区别在于child_next()迭代实际存在的对象，而child_class_next()遍历所有可能的子类。例如，如果AVCodecContext初始化用于带private选项的编解码器，那么，child_next()将返回AVCodecContext.priv_data并完成迭代。另一方面，AVCodecContext.av_class的child_class_next()将遍历带private选项的所有可用编解码器。
简单的说，一个是遍历类，一个是搜索到对象立即停止。

命名常量option

It is possible to create named constants for options. Simply set the unit
field of the option the constants should apply to a string and
create the constants themselves as options of type AV_OPT_TYPE_CONST
with their unit field set to the same string.
Their default_val field should contain the value of the named
constant.

创建命名常量的option非常简单，只要设置结构体AVOption中的unit成员变量以常量字符串，并且设置option类型AVOptionType的值为AV_OPT_TYPE_CONST即可，在使用这些命名常量的option中，同样需要设置unit成员变量为相同的字符串，那么这些使用命名常量的option的默认值则包括了这些命名常量，包括的命名常量可以有多个。
继续前述例子，下面的例子为child_opts的test_flags添加了命名常量flag1，将下述内容放置到child_opts 数组即可，它们的unit成员变量都赋值了test_unit 的字符串，并且flag1的option类型是AV_OPT_TYPE_CONST 的。

{ "test_flags", "This is a test option of flags type.", offsetof(child_struct, flags_opt), 
    AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
{ "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0,
     "test_unit" },

主要结构体

typedef struct AVOption {
    const char *name; /*选项名*/
    const char *help;/*帮助文本*/
    int offset;/*相对于context结构体的偏移，对于命名常量则为0*/
    enum AVOptionType type;/**选项类型**/
    /*默认值，联合体，只能是一种类型*/
    union {
        int64_t i64;
        double dbl;
        const char *str;
        /* TODO those are unused now */
        AVRational q;
    } default_val;
    double min; /*最小值*/
    double max;/*最大值*/
    int flags;/*标记*/
    const char *unit;/*option归属者的名称，命名常量和非命名常量共享，可以是NULL*/
} AVOption;

其中flags可取如下宏定义：

#define AV_OPT_FLAG_ENCODING_PARAM  1   /*编码参数*/
#define AV_OPT_FLAG_DECODING_PARAM  2   /*解码参数*/
#define AV_OPT_FLAG_METADATA        4   /*meta数据*/
#define AV_OPT_FLAG_AUDIO_PARAM     8   /*音频参数*/
#define AV_OPT_FLAG_VIDEO_PARAM     16  /*视频参数*/
#define AV_OPT_FLAG_SUBTITLE_PARAM  32  /*字幕参数*/
#define AV_OPT_FLAG_EXPORT          64  /*导出型参数，不大了解？*/
#define AV_OPT_FLAG_READONLY        128 /*只读参数*/
#define AV_OPT_FLAG_FILTERING_PARAM (1<<16) /*过滤参数？用于avfilter吗？*/

下面是AVOptionRange结构体定义，顾名思义，这个结构体表示一个option的某种值的范围，虽然现在还不知道具体怎么用，但是我们先看看定义：

typedef struct AVOptionRange {
    const char *str;/*字符串信息*/
    double value_min, value_max;/*最小值和最大值，如果是字符串则表示最小和最大长度，如果表示视频尺寸则是最小和最大像素，或是宽度和高度*/
    double component_min, component_max;/*最小和最大组件范围，对于字符串则表示Unicode编码的字符值范围，对于ASCII限定于0-127*/
    int is_range;/*范围标记，1表示是一个范围，0表示就是单一的值，即最大值和最小值一样*/
} AVOptionRange;

下面是结构体AVOptionRanges的定义，表示一个AVOptionRange的列表/数组（Array of option ranges），也就是多个component范围的集合，当然实际使用中大部分option类型都只有一个component，但也有些option类型包括多个AVOptionRange，比如对于图像AV_OPT_TYPE_IMAGE_SIZE类型，一个component范围是像素数，一个component范围是宽度，一个component范围是高度，那么这三个component AVOptionRange就组成了AVOptionRanges 结构体。这里一定要记住，AVOptionRange是关于option类型的一个结构体：

typedef struct AVOptionRanges {
    AVOptionRange **range;/*范围值数组*/
    int nb_ranges;/*每个component的range数量*/
    int nb_components;/*component数量*/
} AVOptionRanges;

使用方法例子，也是抄的opt.h里的注释部分，很明了，两级for循环：

int range_index, component_index;
AVOptionRanges *ranges;
AVOptionRange *range[3]; //may require more than 3 in the future.
av_opt_query_ranges(&ranges, obj, key, AV_OPT_MULTI_COMPONENT_RANGE);
for (range_index = 0; range_index < ranges->nb_ranges; range_index++) {
     for (component_index = 0; component_index < ranges->nb_components; component_index++)
         range[component_index] = ranges->range[ranges->nb_ranges * component_index + range_index];
     //do something with range here.
 }
av_opt_freep_ranges(&ranges);

接口和API函数

int av_opt_show2(void *obj, void *av_log_obj, int req_flags, int rej_flags);

通过av_log显示对象相关的option值。obj表示AVClass类型的指针，av_log_obj表示待显示的对象指针，req_flags表示需要显示的内容flags标记，rej_flags则是相反的，拒绝显示的内容flags标记。

void av_opt_set_defaults(void *s);

设置所有的option字段为默认值，s表示支持option使能的结构体，注意它的第一个成员变量必须是AVClass类型，类似AVFormatContext这种类型。

void av_opt_set_defaults2(void *s, int mask, int flags);

功能类似前一函数，只是加了mask掩码条件，需满足条件(opt->flags & mask) == flags 。

int av_set_options_string(void *ctx, const char *opts, const char *key_val_sep, 
                const char *pairs_sep);

顾名思义，此函数是设置options字符串的意思，设置到哪呢？就是参数ctx代表的上下文，要求这个上下文必须是AVClass类型的结构体，也就是说结构体的第一个成员变量是类型AVClass啦，例如AVFormatContext这种。当然了，有了AVClass就可以找到AVOption成员变量了。参数opts字符串是什么？是一个key/value键值对的字符串，包括了多个key/value值；那么参数key_val_seq和pairs_sep又是什么意思呢？key_val_seq是键值对key/value 间的分隔符，pairs_seq则是不同的键值对之间的分隔符。比如：“x=1:y=2:z=3”，“=”是key_val_seq，“：”是pairs_sep 。

int av_opt_set_from_string(void *ctx, const char *opts,const char *const *shorthand,
                const char *key_val_sep, const char *pairs_sep);

功能与上一个函数类似，但是加了shorthand参数，注释的意思是，如果opts里的key/value对里，某些对里没有key，则从shorthand数组里按顺序挨个找，shorthand数组里存储的是option的name，option name必须是如下范围：a-z A-Z 0-9 - . / _ ，shorthand notation速记符号的意思。

void av_opt_free(void *obj);

释放option，同样的，obj必须是AVClass类型的context对象。

int av_opt_flag_is_set(void *obj, const char *field_name, const char *flag_name);

此函数判断是否设置了某个option值，也就是某个field_name是否设置了flag_name，这种情形在命名常量里用的比较多，前面我们也讲到了命名常量的定义。前述命名常量的例子里test_flags和flag1其实就是field_name和flag_name的关系，实际可能有多个命名常量（如flag2，flag3）可以为test_flags使用，但同一时间只能设置一个flag值。

int av_opt_set_dict(void *obj, struct AVDictionary **options);

通过字典AVDictionary参数来设置option，而不是前述的字符串方式，obj必须是AVClass类型的context对象。

int av_opt_set_dict2(void *obj, struct AVDictionary **options, int search_flags);

也是通过字典方式来设置option，但是带有搜索标记flag，flag在FFmpeg3.2.4里取如下宏定义：

#define AV_OPT_SEARCH_CHILDREN   (1 << 0)/*搜索子对象*/
#define AV_OPT_SEARCH_FAKE_OBJ   (1 << 1)/*搜索对象是伪造的，因为我们要求option的context必须是AVClass类型的，为了免去这些对象的分配，用double指针来替代AVClass指针，具体怎么用？不是很清楚*/

int av_opt_get_key_value(const char **ropts,
                         const char *key_val_sep, const char *pairs_sep,
                         unsigned flags,
                         char **rkey, char **rval);

从ropts里读取key和value值，flags值可取AV_OPT_FLAG_IMPLICIT_KEY，即接受没有key的value，key_val_sep和pairs_sep还是如前所述的分隔符。

int av_opt_eval_flags (void *obj, const AVOption *o, const char *val, int        *flags_out);
int av_opt_eval_int   (void *obj, const AVOption *o, const char *val, int        *int_out);
int av_opt_eval_int64 (void *obj, const AVOption *o, const char *val, int64_t    *int64_out);
int av_opt_eval_float (void *obj, const AVOption *o, const char *val, float      *float_out);
int av_opt_eval_double(void *obj, const AVOption *o, const char *val, double     *double_out);
int av_opt_eval_q     (void *obj, const AVOption *o, const char *val, AVRational *q_out);

这组函数的作用和av_opt_set()类似，但是结果是通过最后一个参数返回，而不是直接写入对象。？？具体用途不是很清楚。

const AVOption *av_opt_find(void *obj, const char *name, const char *unit,
                            int opt_flags, int search_flags);

查找一个对象的option，同样的，obj必须是AVClass类型的context对象，如果是命名常量，还必须用到unit字段以标明命名常量所属，opt_flags指定搜索的类型，如前述宏定义AV_OPT_FLAG_ 开头的宏定义，search_flags则如前所述指定搜索的方式。

const AVOption *av_opt_find2(void *obj, const char *name, const char *unit,
                             int opt_flags, int search_flags, void **target_obj);

功能类似av_opt_find()，除了最后一个参数返回搜索到的option所属的对象，target_obj和obj可能不是一个，因为如果搜索参数search_flags里带了AV_OPT_SEARCH_CHILDREN标记的话，有可能搜到的是子对象。如果搜索参数search_flags带AV_OPT_SEARCH_FAKE_OBJ标记，则忽略此参数的返回值。

const AVOption *av_opt_next(const void *obj, const AVOption *prev);

遍历obj对象的所有AVOption值，prev是上一个遍历的对象，可以为NULL，此时返回第一个option值。

void *av_opt_child_next(void *obj, void *prev);

遍历obj对象的子对象的所有AVOption值。

const AVClass *av_opt_child_class_next(const AVClass *parent, const AVClass *prev);

遍历parent类的子类，prev是上一个遍历的对象，可以为NULL，此时返回第一个子类。

int av_opt_set         (void *obj, const char *name, const char *val, int search_flags);
int av_opt_set_int     (void *obj, const char *name, int64_t     val, int search_flags);
int av_opt_set_double  (void *obj, const char *name, double      val, int search_flags);
int av_opt_set_q       (void *obj, const char *name, AVRational  val, int search_flags);
int av_opt_set_bin     (void *obj, const char *name, const uint8_t *val, int size, int search_flags);
int av_opt_set_image_size(void *obj, const char *name, int w, int h, int search_flags);
int av_opt_set_pixel_fmt (void *obj, const char *name, enum AVPixelFormat fmt, int search_flags);
int av_opt_set_sample_fmt(void *obj, const char *name, enum AVSampleFormat fmt, int search_flags);
int av_opt_set_video_rate(void *obj, const char *name, AVRational val, int search_flags);
int av_opt_set_channel_layout(void *obj, const char *name, int64_t ch_layout, int search_flags);

这组函数设置对象obj的option值，设置的字段名是name，需设置的值是val；search_flags是传递给底层函数av_opt_find2使用的，所以功能类似前述。如果设置了AV_OPT_SEARCH_CHILDREN的flags，则option值会设置到obj的子对象里。

int av_opt_set_dict_val(void *obj, const char *name, const AVDictionary *val, int search_flags);

重新设置新的AVDictionary到obj对象，val内存需要由函数调用者释放。

int av_opt_get         (void *obj, const char *name, int search_flags, uint8_t   **out_val);
int av_opt_get_int     (void *obj, const char *name, int search_flags, int64_t    *out_val);
int av_opt_get_double  (void *obj, const char *name, int search_flags, double     *out_val);
int av_opt_get_q       (void *obj, const char *name, int search_flags, AVRational *out_val);
int av_opt_get_image_size(void *obj, const char *name, int search_flags, int *w_out, int *h_out);
int av_opt_get_pixel_fmt (void *obj, const char *name, int search_flags, enum AVPixelFormat *out_fmt);
int av_opt_get_sample_fmt(void *obj, const char *name, int search_flags, enum AVSampleFormat *out_fmt);
int av_opt_get_video_rate(void *obj, const char *name, int search_flags, AVRational *out_val);
int av_opt_get_channel_layout(void *obj, const char *name, int search_flags, int64_t *ch_layout);

这组函数获取obj对象的name字段的option值，并返回到out_val里。需要注意返回的字符串需要调用者释放内存。

int av_opt_get_dict_val(void *obj, const char *name, int search_flags, AVDictionary **out_val);

功能类似，返回AVDictionary类型的值。

void *av_opt_ptr(const AVClass *avclass, void *obj, const char *name);

获取一个对象option中name字段的地址指针，通过函数返回。

void av_opt_freep_ranges(AVOptionRanges **ranges);

释放AVOptionRanges的所有内存。

int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags);

获取obj对象里option中，name为key值的所有AVOptionRange集合。注意返回的结果必须通过av_opt_freep_ranges()函数释放内存。

int av_opt_copy(void *dest, const void *src);

拷贝src对象的option到dest对象中。

int av_opt_query_ranges_default(AVOptionRanges **, void *obj, const char *key, int flags);

与前一函数av_opt_query_ranges的区别在于，如果AVClass对象中，注册了下述成员，

int (*query_ranges)(struct AVOptionRanges **, void *obj, const char *key, int flags);

那么av_opt_query_ranges()会使用注册的这个函数进行搜索，而av_opt_query_ranges_default()则使用默认的函数进行搜索。此功能在version (52.12)之后方可使用。

int av_opt_is_set_to_default(void *obj, const AVOption *o);

检查AVOption o是否正确的设置到了对象obj里，需要注意的是，o必须属于obj对象。此函数不能用于子对象选项的检查。

int av_opt_is_set_to_default_by_name(void *obj, const char *name, int search_flags);

此函数是对前一函数的补充，增加了search_flags，所以可以结果AV_OPT_SEARCH_*相关的搜索属性，可以搜索子对象了。

#define AV_OPT_SERIALIZE_SKIP_DEFAULTS              0x00000001  
#define AV_OPT_SERIALIZE_OPT_FLAGS_EXACT            0x00000002  

int av_opt_serialize(void *obj, int opt_flags, int flags, char **buffer,
                     const char key_val_sep, const char pairs_sep);

将obj对象的option进行序列化处理（组装成key/value对字符串的方式），返回结果存放在buffer中，buffer需要由调用者释放内存。opt_flags接受AV_OPT_FLAG_IMPLICIT_KEY类型的选项，即允许不带key的value存在。宏定义AV_OPT_SERIALIZE_SKIP_DEFAULTS表示在序列化过程中忽略默认的option值，只取修改过的option；宏定义AV_OPT_SERIALIZE_OPT_FLAGS_EXACT则表示只抽取匹配opt_flags所定义的option值。

总结

上述内容我们仅仅分析了怎么使用AVOption模块，并未深入去分析其实现原理和代码，粗略看了一下，还是挺复杂的。从整个FFmpeg功能上来说，我们现阶段了解这个模块的使用即可，后续如果需要具体了解模块实现再深入分析。
虽然对AVOption的主要定义和接口进行了描述，但是有些注释还不是很清晰，待后续遇到问题时再逐步修订。

收录于