调试 RTSP 拉流问题时我经常在代码里写这样一行av_dict_set(opts, rtsp_transport, tcp, 0)然后期望 FFmpeg 乖乖走 TCP。但有一次它没有生效抓包发现还是 UDP。排查到最后问题不在网络而是另一个地方先设置了一个大小写不同的同义键而 AVDictionary 默认不区分大小写后设置的被静默忽略了。这大概是我入坑 FFmpeg 以来踩得最深的一类坑。av_dict_set是 libavutil 提供的字典操作接口也是给 FFmpeg 各模块传递参数的核心入口之一。无论你是刚开始写 FFmpeg 调用代码还是已经维护了好几年的播放、转码、推流服务只要绕不开avformat_open_input、avcodec_open2就一定绕不开av_dict_set。这篇文章我打算把这几年跟这个函数打交道的经验一次讲透函数原型、每个参数背后的细节、六种 flags 的真实行为、底层数据结构为什么会是“数组”、怎么跟配套函数配合以及我实际踩过的高频坑。每一节都会给出能直接抄走的代码示例。1. 从一个排查记录说起为什么 FFmpeg 需要 AVDictionary先说个背景。FFmpeg 里有大量可配置项比如打开网络流时要不要走 TCP、超时时间多长、解码时要不要用低延迟模式、编码器用哪个 preset、CRF 设置多少。这些选项分散在多个模块里有的属于协议层有的属于解封装器demuxer有的属于封装器muxer还有的属于编码器私有的 AVOption。如果给每个参数都单独设计一个 setter 函数比如avformat_set_rtsp_transport()、avformat_set_timeout()那 API 会膨胀到没法维护。FFmpeg 的解法是统一用键值对字符串来表达这些参数由各模块自己去查表、解析、校验。承载这些键值对的核心容器就是AVDictionary。AVDictionary *opts NULL; // 注意初始化为 NULL av_dict_set(opts, rtsp_transport, tcp, 0); av_dict_set(opts, timeout, 3000000, 0); av_dict_set(opts, max_delay, 500000, 0); AVFormatContext *fmt_ctx NULL; int ret avformat_open_input(fmt_ctx, url, NULL, opts); // 用完必须释放 av_dict_free(opts);为什么全部用字符串原因很务实用户输入天然就是字符串。命令行里-rtsp_transport tcp传进来的是字符串配置文件里写的也是字符串用字符串做中间格式可以省掉一层类型转换。整数、浮点、布尔值在进入具体模块之前都以字符串形式存在模块内部按需调用strtol、strtod或av_opt机制再做转换。这样统一、简单、无歧义。AVDictionary 还有一个重要用途保存媒体文件的元数据metadata。AVFormatContext-metadata就是一个AVDictionary *。读取标题、艺术家、专辑信息时本质上也是在做键值对操作。所以av_dict_set并不只是给“传参”用的元数据的修改、合并同样走这套 API。2. av_dict_set 函数原型与每个参数的隐藏语义先看完整原型#include libavutil/dict.h int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags);参数只有四个但每个都有不少门道。2.1 pm 为什么必须是二级指针pm是指向AVDictionary *的指针。函数内部可能要做三件事字典为空时分配一块新的字典内存、字典已有条目时扩容、字典被清空时释放整块内存。这些操作都会改变AVDictionary *变量本身的值所以必须传二级指针才能把变化带回调用端。很多新手会写错成AVDictionary *opts NULL; av_dict_set(opts, k, v, 0); // 错误传的是经值传递的一级指针这样函数内部即使分配了内存调用端opts仍然是 NULL后续传给avformat_open_input时等于什么都没配置而且没有指针可以去释放直接内存泄漏。正确的初始化姿势是AVDictionary *opts NULL; av_dict_set(opts, k, v, 0);2.2 value 为 NULL 时是删除语义把一个键的 value 传 NULL表示从字典里删除这个键av_dict_set(opts, key, NULL, 0); // 删除 key 对应的条目这个特性有实际用途。比如代码里先有一个公共默认配置项某个特殊场景下需要把其中一项去掉就可以用av_dict_set(opts, key, NULL, 0)精确删除。注意如果 key 本来就不存在这个调用不会报错也不会做任何事。与此对应key 传 NULL 属于未定义行为。内部会走av_strdup(NULL)或者av_strcasecmp等逻辑轻则空指针崩溃重则掩盖问题。永远不要传 NULL key。2.3 返回值一定要检查函数返回 0 表示成功返回负值表示出错常见的是AVERROR(ENOMEM)内存分配失败。绝大多数情况下av_dict_set都会成功所以很多老代码直接忽略返回值。但高并发转码服务里内存压力大时确实可能返回负值这时候参数没设置成功后面表现出的症状是“某个选项不生效”。排查这种问题非常费劲所以我建议从一开始就检查int ret av_dict_set(opts, crf, 23, 0); if (ret 0) { fprintf(stderr, 设置 crf 失败: %s\n, av_err2str(ret)); goto fail; }av_err2str宏会把 AVERROR 转成可读字符串调试时很好用。2.4 AVDictionary 结构体本身是不透明的早期版本的 FFmpeg 在头文件里直接暴露了 AVDictionary 结构体字段很多代码习惯直接访问dict-count、dict-elems。新版本为了 ABI 兼容已经把它改成不透明类型具体定义隐藏在dict.c里。外部代码只能通过 API 函数操作字典av_dict_set插入或删除av_dict_get查询av_dict_count获取条目数量av_dict_copy复制av_dict_free释放如果你的代码还在用-count编译器会直接报 incomplete type 错误迁移到av_dict_count即可。3. flags 六种取值拆解源码行为与典型用法flags是av_dict_set最复杂的参数一不留神就踩坑。先看完整定义#define AV_DICT_MATCH_CASE 1 #define AV_DICT_IGNORE_SUFFIX 2 #define AV_DICT_DONT_STRDUP_KEY 4 #define AV_DICT_DONT_STRDUP_VAL 8 #define AV_DICT_DONT_OVERWRITE 16 #define AV_DICT_APPEND 32 #define AV_DICT_MULTIKEY 64这些标志可以按位或组合比如AV_DICT_DONT_OVERWRITE | AV_DICT_MATCH_CASE。3.1 AV_DICT_MATCH_CASE默认不区分大小写这是最容易踩的坑。av_dict_set和av_dict_get在默认情况下查找、匹配 key 时不区分大小写内部用的是av_strcasecmp。所以av_dict_set(opts, Key, 1, 0); av_dict_set(opts, key, 2, 0); // 会覆盖上面那条默认大小写不敏感文章开头那个 RTSP 拉流诡异问题就是这么来的某段公共代码设置了RTSP_TRANSPORT后面我的代码设置了rtsp_transport后者按匹配规则被当成同一个 key但因为某种顺序问题被覆盖或者没有生效。如果你希望 key 严格区分大小写加上AV_DICT_MATCH_CASE。但要注意FFmpeg 内部的 AVOption 查找大多走av_opt_find它的匹配规则和字典 API 不是同一套所以这个标志更多影响的是字典自身的存取行为。3.2 AV_DICT_DONT_STRDUP_KEY 和 AV_DICT_DONT_STRDUP_VAL接管内存所有权默认情况下av_dict_set内部会用av_strdup复制一份 key 和 value。调用者的字符串即使马上被释放也不影响字典内容。但如果你的字符串生命周期足够长又不想多一次拷贝和内存分配可以加这两个标志让函数“接管”传入的指针不再复制字符串。这里的“接管”意味着字典释放时会用av_free释放这些字符串。所以传入的指针必须是av_malloc 系列函数分配的内存不能用标准库的strdup或malloc。否则av_dict_free调用av_free时会按 FFmpeg 的内存管理头去解析轻则崩溃重则内存损坏。正确用法是配合av_strdup或av_asprintfchar *key av_strdup(my_key); char *val av_strdup(my_value); int ret av_dict_set(opts, key, val, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL); if (ret 0) { // 失败时函数内部会处理指针不需要再手动 free // 但要注意如果前面 av_strdup 成功而 set 失败set 内部已释放 goto fail; } // 成功后不能再 free key/val所有权转移给了字典这里有个细节如果av_dict_set返回失败它内部会释放掉已经拷贝或者要接管的字符串调用者不应该再对 key/value 调用av_free。因为函数内部对copy_key、copy_value做了统一清理。实际编码时我只有在循环设置大量参数、且内存敏感的场景下才用 DONT_STRDUP普通场景没必要。3.3 AV_DICT_DONT_OVERWRITE已有键时静默跳过这个标志表示“如果这个 key 已经存在不要覆盖”。典型用途是给用户提供的参数设置默认值但用户显式配置过的键要保留// 先应用用户配置 av_dict_set(opts, crf, user_crf, 0); // 再用默认值但只对尚未设置的 key 生效 av_dict_set(opts, crf, 28, AV_DICT_DONT_OVERWRITE); // 不会覆盖 av_dict_set(opts, preset, medium, AV_DICT_DONT_OVERWRITE);如果 key 不存在行为与普通 set 完全一样会新增条目。3.4 AV_DICT_APPEND新值不是覆盖而是拼接AV_DICT_APPEND的效果是把新值 append 到旧值后面中间以逗号分隔av_dict_set(opts, a, 1, 0); av_dict_set(opts, a, 2, AV_DICT_APPEND); // 最终 a 1,2这个设计最初是为了兼容某些元数据标签允许重复出现的场景。比如 ID3 标签中可能有多个 author每个 author 单独写进一个 AVDictionary 条目会破坏键唯一性假设于是选择用逗号拼接。实际开发中AV_DICT_APPEND更适合用于继承父作用域参数、追加额外值的场景。不过要注意拼接时用的是英文逗号如果值本身包含逗号解析时容易混淆下游拿到时再拆分要格外小心。3.5 AV_DICT_MULTIKEY允许同一个 key 出现多次默认字典强制键唯一重复设置就是覆盖。加了AV_DICT_MULTIKEY后字典里可以同时存在多个相同 key 的条目av_dict_set(opts, tag, a, 0); av_dict_set(opts, tag, b, AV_DICT_MULTIKEY); // 现在有两个 tag 条目查询时av_dict_get只会返回第一个匹配项要遍历同 key 的所有条目需要配合 prev 参数手动迭代。这个标志用得非常少一般只有在处理格式不规范的输入元数据时才会碰到。3.6 AV_DICT_IGNORE_SUFFIX匹配时忽略 key 的后缀这个标志跟 AVOption 的流指示语法有关。FFmpeg 的命令行或av_opt支持类似key:stream_spec的写法后缀部分用于限定流范围。当av_opt_find拿到一个带后缀的 key 再回调字典查找时AV_DICT_IGNORE_SUFFIX可以让基础 key 匹配到带后缀的条目。它的行为是匹配 entry-key 时如果 entry-key 的开头部分与目标 key 相同后面还有额外字符则视为匹配成功。比如 entry key 是sc_threshold:0查找sc_threshold并带上AV_DICT_IGNORE_SUFFIX可以命中。这个标志主要面向 libavutil 内部实现普通业务代码很少直接使用。下表汇总六个标志的核心行为标志行为典型场景AV_DICT_MATCH_CASE匹配时区分大小写需要严格区分大小写的配置项AV_DICT_IGNORE_SUFFIX匹配时忽略后缀AVOption 流限定查询AV_DICT_DONT_STRDUP_KEY不复制 key接管所有权性能敏感预分配字符串AV_DICT_DONT_STRDUP_VAL不复制 value接管所有权性能敏感预分配字符串AV_DICT_DONT_OVERWRITE不覆盖已存在的键默认值填充AV_DICT_APPEND值以逗号拼接追加多值元数据AV_DICT_MULTIKEY允许重复键处理特殊元数据4. 底层数据结构数组实现的“假哈希表”很多看过 FFmpeg 源码的人都有一个疑惑AVDictionary 名字里带 dict实现却是数组。它内部维护一个AVDictionaryEntry数组条目按插入顺序排列查找时做线性扫描。简化后的结构概念如下typedef struct AVDictionaryEntry { char *key; char *value; } AVDictionaryEntry; typedef struct AVDictionary { int count; // 当前条目数 AVDictionaryEntry *elems; // 动态数组 } AVDictionary;av_dict_set内部大致逻辑是如果没有AV_DICT_MULTIKEY先在线性数组里找有没有同 key 条目找到了且没设AV_DICT_DONT_OVERWRITE就释放旧 value替换新 value找不到就av_realloc扩容数组把新条目追加到末尾value 为 NULL则删除该条目并把后续元素前移插入和查询的平均时间复杂度都是 O(n)。对于动辄上千个条目的哈希表场景这不可接受但 AVDictionary 的典型规模通常是几个到几十个 key线性查找的 cache 友好性反而比哈希表更好。没有哈希冲突、没有扩容 rehash 的成本实现也简洁对 FFmpeg 这种追求“够用就好”的库来说这是刻意的取舍。不过这也带来一个实际影响大规模字典的查找性能不会很好。当元数据条目达到几百甚至上千时每次av_dict_get都做全量扫描会明显拖慢处理速度。所以我在处理超大 metadata 时会先评估必要时转到自己的哈希表里。另外字典的数组是动态增长的av_dict_set频繁调用时会有 realloc 和 memcpy。虽然单次开销很小但在初始化阶段一次性设置几十个参数性能差异可以忽略真正追求极致时可以用av_dict_copy或预分配手段减少分配次数。5. 配套函数串联真正会用 av_dict_set 的姿势av_dict_set只是字典操作族的一员实际开发中几乎总是和下面几个函数配套使用。5.1 av_dict_set_int整数参数省一次转换#include libavutil/dict.h #include stdint.h int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags);内部就是把 int64 拼成字符串再调av_dict_set。适合设置 bitrate、buffer size 这类数值项av_dict_set_int(opts, b, 2000000, 0); // 2 Mbps av_dict_set_int(opts, maxrate, 2500000, 0);好处是省去手写snprintf代码更干净。5.2 av_dict_get 与遍历迭代查询单个条目AVDictionaryEntry *e av_dict_get(opts, crf, NULL, 0); if (e) { printf(crf %s\n, e-value); }prev参数是遍历用的。当key为 NULL 时av_dict_get返回下一个条目实现全量遍历AVDictionaryEntry *e NULL; while ((e av_dict_get(opts, NULL, e, 0))) { printf(%s %s\n, e-key, e-value); }当key不为 NULL、prev也不为 NULL 时会从prev往后继续寻找同 key 的条目配合AV_DICT_MULTIKEY使用可以收集所有重复键。5.3 av_dict_parse_string一行字符串灌入字典新版本推荐使用av_dict_parse_string2int av_dict_parse_string2(AVDictionary **pm, const char *str, const char *key_val_sep, const char *pairs_sep, int flags);比如把fflagsnobuffer:flagslow_delay解析成两个条目AVDictionary *opts NULL; int ret av_dict_parse_string2(opts, fflagsnobuffer:flagslow_delay, , :, 0); if (ret 0) { fprintf(stderr, 解析参数失败: %s\n, av_err2str(ret)); } av_dict_free(opts);老版本的av_dict_parse_string对空格、转义的处理比较粗糙新版本更健壮。如果你维护的代码还在用旧接口建议升级。5.4 av_dict_copy 与 av_dict_free 的搭档关系av_dict_copy复制整个字典常用于继承全局配置AVDictionary *global_opts NULL; AVDictionary *local_opts NULL; av_dict_set(global_opts, timeout, 3000000, 0); av_dict_copy(local_opts, global_opts, 0); av_dict_set(local_opts, rtsp_transport, tcp, 0); // 用完分别释放 av_dict_free(local_opts); av_dict_free(global_opts);av_dict_free会释放字典里所有 key、value 字符串以及数组本身最后把传入指针置为 NULL。这设计得很省心不用手动再把它置空。av_dict_get_string可以做反向序列化把字典导出为字符串。调试时打印整个字典非常好用char *dump NULL; av_dict_get_string(opts, dump, , :); if (dump) { printf(opts: %s\n, dump); av_free(dump); // 注意这里要用 av_free }6. 实战场景从输入到编码器的参数传递讲完 API 细节来几段可以直接抄的实战代码。6.1 输入侧RTSP 传输与低延迟配置AVDictionary *opts NULL; AVFormatContext *fmt_ctx NULL; av_dict_set(opts, rtsp_transport, tcp, 0); av_dict_set(opts, timeout, 3000000, 0); av_dict_set(opts, max_delay, 0, 0); av_dict_set(opts, fflags, nobuffer,low_delay, 0); av_dict_set(opts, flags, low_delay, 0); int ret avformat_open_input(fmt_ctx, rtsp://192.168.1.10/live, NULL, opts); if (ret 0) { fprintf(stderr, 打开输入失败: %s\n, av_err2str(ret)); av_dict_free(opts); return ret; } // 手动检查 opts 中是否还有未消费的 key if (opts) { AVDictionaryEntry *e NULL; while ((e av_dict_get(opts, NULL, e, 0))) { fprintf(stderr, 警告: 未识别的选项 %s%s\n, e-key, e-value); } av_dict_free(opts); }注意flags、fflags都是AVFormatContext的 AVOption。nobuffer和low_delay之间可以逗号分隔也可以多次设置效果相同。max_delay0可以把缓冲区压到最小适合直播场景代价是网络抖动容忍度变低。6.2 输出侧muxer 参数传递同样走 opts只是对应的 AVClass 变成了 muxerAVDictionary *opts NULL; av_dict_set(opts, hls_time, 4, 0); av_dict_set(opts, hls_list_size, 0, 0); av_dict_set_int(opts, muxdelay, 0, 0); ret avformat_write_header(out_ctx, opts); if (ret 0) { fprintf(stderr, 写封装头失败: %s\n, av_err2str(ret)); av_dict_free(opts); return ret; } if (opts) { AVDictionaryEntry *e NULL; while ((e av_dict_get(opts, NULL, e, 0))) { fprintf(stderr, 警告: muxer 未识别的选项 %s%s\n, e-key, e-value); } av_dict_free(opts); }avformat_write_header接受一个AVDictionary **options参数会把其中能被当前 muxer 消费的选项取走剩下的留在字典里。打印剩余项是排查“参数为什么没生效”最有效的手段。6.3 编码器侧avcodec_open2 的 optionsAVDictionary *opts NULL; av_dict_set(opts, preset, slow, 0); av_dict_set(opts, tune, film, 0); av_dict_set(opts, crf, 20, 0); av_dict_set(opts, profile, high, 0); av_dict_set(opts, level, 4.1, 0); ret avcodec_open2(codec_ctx, codec, opts); if (ret 0) { fprintf(stderr, 打开编码器失败: %s\n, av_err2str(ret)); av_dict_free(opts); return ret; } // 剩下未识别的 option 说明拼写错了或者编码器不支持 if (opts) { AVDictionaryEntry *e NULL; while ((e av_dict_get(opts, NULL, e, 0))) { fprintf(stderr, 警告: 编码器未识别的选项 %s%s\n, e-key, e-value); } av_dict_free(opts); }x264、x265 这类第三方编码器支持大量私有参数全都能通过这个入口传递。如果拼错一个参数名编码器不会报错只是静默忽略或打印警告。养成“打开编码器后检查残留 opts”的习惯能省下大量调试时间。6.4 结合 av_opt_set_dict2 的通用方案av_opt_set_dict2可以把 AVDictionary 批量应用到任意带 AVClass 的对象上int apply_opts(void *obj, AVDictionary **opts) { // AV_OPT_SEARCH_CHILDREN 表示同时搜索子对象比如 codec 私有选项 return av_opt_set_dict2(obj, opts, AV_OPT_SEARCH_CHILDREN); }很多封装层就用这个函数统一处理参数不再区分参数属于容器还是编码器。avcodec_open2内部本质上也做了类似的事所以没必要重复调用。7. 高频踩坑清单这些坑我基本都踩过最后把我踩过的坑集中列一遍每条都是真金白银换来的经验。7.1 DONT_STRDUP 的内存所有权陷阱再次强调AV_DICT_DONT_STRDUP_KEY/VAL意味着字典接管内存释放用av_free。如果你按惯性思维用strdup分配了字符串后面av_dict_free几乎必然崩溃。实在搞不清楚所有权就别用这两个标志默认的复制行为多花一次 malloc 的代价完全可以接受。7.2 大小写不敏感引发的覆盖问题默认不区分大小写这个设计容易让人以为“写错了也能匹配”实际上它掩盖了很多拼写错误。比如某个选项官方写法是b_frame_strategy你写了大写字母查表时可能匹配到一个相近的键行为完全不符合预期。排查此类问题时先检查字典里的实际键名。7.3 opts 未消费完不等于报错avformat_open_input或avcodec_open2后opts中残留项并不代表函数失败。有些选项确实是给上层逻辑用的需要你自己从中取出。设计良好的代码应当显式区分“未知选项警告”和“业务选项读取”两种残留情况避免误报。7.4 AV_DICT_APPEND 的逗号拼接AV_DICT_APPEND用逗号拼接多值如果值本身来自用户输入且包含逗号下游拆分时会出错。我一般只在值域明确不含逗号的场景使用比如拼接多个协议名、多个 preset 名。7.5 线程安全与生命周期AVDictionary 不是线程安全的。多个线程同时读写同一个字典需要外部加锁或者每个线程独立维护一个字典再合并。另外av_dict_set内部会持有传入字符串的指针DONT_STRDUP 场景并发设置同一个 key 时可能触发 ABA 问题。7.6 删除 key 的误用av_dict_set(opts, key, NULL, 0)是删除操作不是“设置空值”。如果你想表达“这个 key 存在但值为空”需要给它一个空字符串。这两个在语义上差别很大下游判断e-value[0] \0和e NULL的逻辑完全不同。7.7 忘记初始化为 NULL这个错误最常见也最致命。AVDictionary *opts; av_dict_set(opts, ...)如果忘了初始化成 NULL内部判断m时读到的是栈上垃圾值轻则写入非法指针重则直接段错误。定义变量时就写上 NULL成本几乎为零能省去大量排查时间。8. 我日常用 av_dict_set 的一些习惯代码层面我现在基本固定这套写法字典变量一律初始化为 NULL所有av_dict_set返回值都检查调用avformat_open_input、avcodec_open2、avformat_write_header之后统一打印残留选项每个字典都保证成对出现av_dict_free。参数管理上我会把所有默认配置组织成静态数组循环灌入字典再用AV_DICT_DONT_OVERWRITE给用户参数兜底。这样新增配置项只需要改数组不用改流程逻辑。static const struct { const char *key; const char *value; } default_opts[] { { preset, medium }, { crf, 23 }, { profile, high }, }; for (size_t i 0; i sizeof(default_opts) / sizeof(default_opts[0]); i) { int ret av_dict_set(opts, default_opts[i].key, default_opts[i].value, AV_DICT_DONT_OVERWRITE); if (ret 0) { av_dict_free(opts); return ret; } }最后还有个小技巧调试时我习惯在关键节点用av_dict_get_string把整个 opts 序列化到日志里。别看它不起眼很多“参数没生效”的问题打印一眼就能发现 key 拼错了、前后多了空格、或者被别的层覆盖了。掌握av_dict_set等于掌握了 FFmpeg 参数体系的钥匙剩下的只是在实际项目里多踩几个坑、多积累几个 pattern 而已。