FFmpeg av_dict_set实战：AVDictionary键值对参数设置与内存管理

做 FFmpeg 开发的朋友，早晚都会碰到av_dict_set这个函数。它是 FFmpeg 里操作 AVDictionary（一套轻量级键值对字典）最核心的写入接口，无论是给编码器传 preset 参数、给 RTMP 协议设置超时时间，还是手动管理 filter 选项，你都得通过它把配置塞进那个AVDictionary **里。这个函数能解决什么问题呢？简单说，FFmpeg 大量模块的初始化参数都不走函数形参，而是统一收进一个键值对字典，再由底层模块自己识别处理，av_dict_set就是这个“传参通道”的关键入口。对做音视频编解码、流媒体推拉流、播放器开发的朋友来说，它是避不开的基础 API；对刚接触 FFmpeg 的新手，把它彻底搞懂，写起相关代码会顺手很多。

我最早真正重视这个函数，是在一个推流项目里排查“参数设置不生效”的问题。当时我对着结构体字段一个个赋值，结果编码器配置始终不对，最后才发现入口根本不在这里，而是要塞进 AVDictionary 再传给avcodec_open2。从那之后我就意识到，光知道函数签名没用，必须把它的内存规则、标志位语义和底层行为都摸清楚。这篇就把我实际用下来的经验完整整理一遍。

1. 先从需求谈起：av_dict_set 到底解决什么问题

1.1 没有字典的时候，参数传递有多痛苦

FFmpeg 的模块数量非常多，从解复用器、编解码器到协议层，每个模块的可用参数都不太一样。如果每加一个参数就改一次函数签名，那avcodec_open2这个函数可能会变成上百个参数的怪物，维护起来就是一场灾难。所以 FFmpeg 的设计者选了一条更灵活的路：用 AVDictionary 这种键值对容器来“打包传递”参数。调用方把参数名和参数值做成字符串键值对丢进去，底层模块拿到字典后自己解析、自己取用。这样一来，新增参数就不需要动接口了，添加一个字符串识别分支就行，兼容性也好很多。

av_dict_set就是往这个字典里写内容的入口。你可以理解为，AVDictionary 是一个“快递包裹”，av_dict_set是往包裹里塞东西的动作，av_dict_get是拆包裹时找东西的动作，而av_dict_free是拆完把包裹扔掉的收尾动作。在一套完整的 FFmpeg 调用链里，这四个动作基本都会出现，缺一个都容易出问题。

1.2 从调用习惯看设计意图

我刚开始用的时候有个疑惑：为什么很多函数的参数类型是AVDictionary **，而不是AVDictionary *？后来我发现这是 C 语言里“函数内修改指针本身”的经典套路。av_dict_set内部不仅要修改字典结构体的内容，在字典为空时还要为新字典分配内存，并把新的指针写回调用方。如果你只传AVDictionary *，那函数里再怎么改，外面的指针还是 NULL，后续操作就会崩。

这个设计也解释了为什么很多 FFmpeg 初始化函数，比如avcodec_open2、avformat_open_input，最后一个参数都是AVDictionary **。它们内部会调用av_dict_set或其他字典操作函数来处理你传入的选项，同时也允许底层代码往同一个字典里补充信息。所以你在外面先av_dict_set准备好选项，再把字典指针的地址传进去，这个模式是整个 FFmpeg 选项机制的通用用法。

2. 函数签名与参数拆解：每个参数背后都有讲究

2.1 函数原型与返回值

av_dict_set的完整原型定义在libavutil/dict.h中：

int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags);

函数返回 0 表示成功，返回负数AVERROR(EINVAL)等值时表示参数无效或内存分配失败。实际开发里，我见过不少人不检查返回值，这其实有风险，虽然多数时候它不会失败，但 key 或 pm 传错时它一定会报错。稳妥的做法是写成下面这种形式：

AVDictionary *dict = NULL; int ret = av_dict_set(&dict, "preset", "medium", 0); if (ret < 0) { // 处理错误，比如打印日志后跳过该参数 }

有一点要注意，av_dict_set的value参数是可以传 NULL 的。传 NULL 表示删除这个 key，而不是写入空字符串。这个行为很多人容易搞混，以为传 NULL 是写一个空值，结果参数被删掉了，排查好久才找到原因。

2.2 pm 的双重指针为什么不能省略

pm是指向AVDictionary *的指针。标准用法是这样的：

AVDictionary *dict = NULL; av_dict_set(&dict, "key", "value", 0);

如果dict还是 NULL，av_dict_set内部会分配一个新的 AVDictionary，然后把它赋给*pm。如果dict已经存在对应的 key，它会复用已有的结构并更新内容。这个“自动分配”的行为让调用方省去了手动初始化的麻烦。但也正因为如此，你不能再把dict重新赋值为 NULL，否则前面设置的参数全丢了，而且如果后面还有av_dict_free(&dict)，就会处理刚分配的新对象，逻辑上容易乱。

我见过一个典型错误：有人先把一个局部AVDictionary *tmp传给avcodec_open2，函数内部可能修改了tmp，但调用方还拿着旧指针去av_dict_free，导致内存泄漏。正确做法是让同一个指针变量贯穿整个生命周期。

2.3 key 和 value 的生命周期规则

默认情况下，av_dict_set内部会拷贝一份 key 和 value 字符串，所以函数返回后，你在外部是否释放原字符串都不影响字典里的内容。这一点非常方便，你完全可以用栈上的 char 数组来传参：

char key_buf[32]; snprintf(key_buf, sizeof(key_buf), "timeout_%d", index); av_dict_set(&dict, key_buf, "3000000", 0);

函数结束后，key_buf内容就算被后续代码覆盖，字典里存的值也依然正确，因为内部已经 strdup 过了。反过来，如果你传了AV_DICT_DONT_STRDUP_KEY或AV_DICT_DONT_STRDUP_VAL标志，那就代表你明确告诉它“这个内存由我管理，你别复制，直接引用”，这时外部字符串必须在字典生命周期结束前一直存活，而且不能在中途修改。这个标志通常用于性能敏感的代码路径，普通业务代码里建议不要用，容易踩内存坑。

2.4 flags 标志位逐个解读

flags是av_dict_set最有意思的地方，也是文档描述最少、最容易踩坑的部分。常见的 flags 取值一共有 7 个，它们定义在libavutil/dict.h里：

我实际使用中遇到最多的是AV_DICT_DONT_OVERWRITE和AV_DICT_APPEND，其他几个在特殊场景里才会用到。

AV_DICT_DONT_OVERWRITE的意思是：如果字典里已经有这个 key，那么本次写入不生效。这个标志的典型用途是“用户传了参数就尊重用户参数，没传就用默认值”。比如你在封装一个通用配置接口，希望调用方传入的选项优先级最高，那就可以先写入默认值，再调用一次带AV_DICT_DONT_OVERWRITE的写入覆盖用户选项。因为用户选项先写在前面，默认值写入时发现 key 存在就不覆盖，优先级自然就对上了。

AV_DICT_APPEND则允许同一个 key 存在多个 value，后面追加的值会跟在已有值后面，而不是替换。这个标志在做 filter 图拼接、多路输出参数合并时很有用。不过你要注意，追加模式下，用av_dict_get默认只会返回第一个匹配项，要遍历同一 key 的多个值，需要配合AV_DICT_IGNORE_SUFFIX或使用av_dict_iterate手动遍历。

AV_DICT_MULTIKEY是在新版 FFmpeg 中引入的，它允许同一个 key 存储多个完全独立的值。它和AV_DICT_APPEND的差别在于：AV_DICT_APPEND是把多个值合并成一个“列表字符串”存在同一个条目里，而AV_DICT_MULTIKEY是真正建立多个不同的条目。做协议层或者复杂滤镜开发时可能会用到，普通场景不需要。

3. 实操案例：从参数设置到编码器配置的完整闭环

3.1 案例一：给 H.264 编码器传参

最常见的场景是打开编码器前设置编码参数。比如我们要设置 H.264 编码器的 preset、profile 和码率控制模式，可以这样组织代码：

AVFormatContext *fmt_ctx = NULL; AVCodecContext *enc_ctx = NULL; AVDictionary *dict = NULL; // 先塞入基础参数 av_dict_set(&dict, "preset", "slow", 0); av_dict_set(&dict, "profile", "high", 0); av_dict_set(&dict, "crf", "23", 0); av_dict_set(&dict, "x264-params", "keyint=250:min-keyint=25", 0); // 打开编码器 AVCodec *codec = avcodec_find_encoder_by_name("libx264"); if (!codec) { // 处理找不到编码器的情况 } enc_ctx = avcodec_alloc_context3(codec); if (!enc_ctx) { // 处理分配失败 } enc_ctx->width = 1920; enc_ctx->height = 1080; enc_ctx->time_base = (AVRational){1, 25}; enc_ctx->pix_fmt = AV_PIX_FMT_YUV420P; int ret = avcodec_open2(enc_ctx, codec, &dict); if (ret < 0) { char errbuf[AV_ERROR_MAX_STRING_SIZE]; av_strerror(ret, errbuf, sizeof(errbuf)); // 打印错误日志 } av_dict_free(&dict);

这里要注意几个细节。首先，preset、profile、crf这些参数并不是 AVCodecContext 的成员变量，而是 libx264 编码器通过选项系统暴露出来的私有参数，所以必须通过av_dict_set传进去，avcodec_open2才会把它们解析到编码器内部。其次，avcodec_open2内部会对字典进行消费，但不会帮你释放，所以用完必须自己av_dict_free。

还有个常见的坑是：有些人把dict传到avcodec_open2之后，又想在后面复用同一个dict继续设置其他参数。这个做法很危险，因为avcodec_open2内部可能会修改这个字典，甚至释放部分条目。如果你想复用，建议先av_dict_copy一份备份。

3.2 案例二：设置协议层选项

除了编码器，av_dict_set在协议层也大量使用。比如用 FFmpeg 打开 RTMP 流时，想设置超时时间、buffer 大小或者自定义的 RTMP 参数，都靠它：

AVDictionary *options = NULL; av_dict_set(&options, "rtmp_transport", "tcp", 0); av_dict_set(&options, "timeout", "3000000", 0); // 单位是微秒 av_dict_set(&options, "buffer_size", "65536", 0); av_dict_set(&options, "tcp_nodelay", "1", 0); AVFormatContext *ifmt_ctx = NULL; int ret = avformat_open_input(&ifmt_ctx, rtmp_url, NULL, &options); if (ret < 0) { // 处理失败 } av_dict_free(&options);

avformat_open_input的最后一个参数也是AVDictionary **，它会从这个字典里取出协议层需要的选项。这里有个非常实用的技巧：打开输入之后，你可以遍历这个字典，看看哪些选项没被消费掉。正常情况下，如果某个 key 没有对应模块认领，它就会留在字典里。这个特性对排查“参数为什么没生效”极有帮助。

排查的方法很简单，就是在avformat_open_input结束后遍历字典，凡是还能遍历出来的 key，基本都是没被识别或者没被用上的参数：

const AVDictionaryEntry *entry = NULL; while ((entry = av_dict_iterate(options, entry))) { av_log(NULL, AV_LOG_WARNING, "unused option: %s=%s\n", entry->key, entry->value); }

这样你就能很清楚地看到哪些参数是白传了。我踩过的一个典型坑是：把本应该传给 muxer 的参数错误地传给了 demuxer，结果参数一直“没生效”，用这个方法一眼就发现了。

3.3 案例三：命令行参数批量解析

av_dict_set还有一个非常有用的搭档av_dict_parse_string，它可以把形如"key1=value1:key2=value2"的字符串一次性解析进字典。这在处理外部配置、命令行参数时特别方便：

AVDictionary *dict = NULL; const char *config = "preset=fast:crf=20:profile=main"; int ret = av_dict_parse_string(&dict, config, "=", ":", 0); if (ret < 0) { // 解析失败 } // 之后可以继续用 av_dict_set 覆盖或补充单个参数 av_dict_set(&dict, "preset", "medium", 0);

av_dict_parse_string的关键是分隔符参数。第二个参数是键值之间的分隔符，第三个参数是条目之间的分隔符。中间那个形如"key1=value1"的格式很直观，但要注意如果 value 本身包含分隔符，需要做转义处理，否则解析会错乱。

说实话，我更喜欢先把配置解析进临时字典，再通过av_dict_set做二次修正，因为这样可以保证用户配置和默认配置的合并逻辑清晰。

3.4 配套 API 的组合使用

AVDictionary 的完整操作远不止av_dict_set一个函数，实际项目里通常要搭配其他几个 API 一起用：

// 拷贝整个字典，常用于在多个上下文中复用同一套配置 AVDictionary *dst = NULL; av_dict_copy(&dst, src_dict, 0); // 查询某个 key 的值 const AVDictionaryEntry *entry = av_dict_get(dst, "preset", NULL, 0); if (entry) { printf("preset = %s\n", entry->value); } // 获取字典条目数量 int count = av_dict_count(dst); // 遍历所有条目 const AVDictionaryEntry *e = NULL; while ((e = av_dict_iterate(dst, e))) { printf("%s = %s\n", e->key, e->value); } // 释放整个字典 av_dict_free(&dst);

av_dict_get的第三个参数是“上一个匹配的条目”，配合AV_DICT_IGNORE_SUFFIX可以实现一种类似前缀匹配的效果。举个例子，如果你 key 存的是foo.a和foo.b，你可以设置key = "foo."外加AV_DICT_IGNORE_SUFFIX，就能匹配到foo.开头的第一个条目。这个机制在 FFmpeg 内部使用很多，像是区分不同码流、不同轨道的选项时，靠的就是这个。外部项目里如果选项命名有统一前缀，也可以这么玩。

av_dict_iterate是较新版本提供的遍历 API，老的代码里也有人用av_dict_get配合 NULL 为最后一个参数来遍历，但那个写法有隐患，官方推荐优先用av_dict_iterate。我实际用下来，av_dict_iterate的语义更清晰，遍历过程中也不要修改字典，否则行为未定义。

4. 常见问题与排查技巧实录

4.1 内存泄漏：最容易被忽视的坑

AVDictionary 的内存管理说简单也简单，说麻烦也麻烦。核心规则只有一个：只要你还引用了这个字典的指针，用完就必须av_dict_free。我在代码 review 里见过不少av_dict_set用得很溜、但忘了av_dict_free的情况。尤其是avcodec_open2和avformat_open_input这种函数，很多人以为它们内部会把字典“接管”或“释放”，结果实际并没有。

要确认到底谁负责释放，最简单的方法是查 API 文档。就我测试过的行为来说，avcodec_open2和avformat_open_input都不会释放你传入的字典，需要调用方自己释放。但要注意，某些内部逻辑可能会修改字典内容，所以你释放前最好先备份需要的数据。真出了内存泄漏，用 valgrind 或 AddressSanitizer 一查，看到av_dict_set内部av_strdup分配的块没有被释放，基本就能定位。

这里有个我的习惯：在设置完参数交给 FFmpeg 后，如果确认不再需要这个字典，立刻av_dict_free(&dict)并把指针置 NULL，防止后面误用悬空指针。如果后续还要复用，就保留到最后一个使用点再释放。

4.2 参数被静默覆盖：排查思路

很多人第一次用av_dict_set会踩同一个坑：同一个 key 设置两次，第二次把第一次覆盖了。这是默认行为，因为 AVDictionary 的语义就是“一个 key 对应一个 value”，除非你显式传入AV_DICT_MULTIKEY或使用追加逻辑。

这个默认行为本身没问题，但如果你是从配置系统里读入键值对，后来又在代码里手动av_dict_set相同 key，就会出现“配置被硬编码覆盖”的诡异现象。我的排查思路是：在写入后立刻打印字典内容，确认每一步的状态。比如：

void dump_dict(AVDictionary *d) { const AVDictionaryEntry *e = NULL; while ((e = av_dict_iterate(d, e))) { fprintf(stderr, "[dict] %s = %s\n", e->key, e->value); } }

每调用一次av_dict_set就 dump 一次，很快就能看到哪个 key 在哪一步被改掉了。这个方法听着简陋，但真的比瞎猜高效得多。

4.3 遍历字典时修改内容：非常危险

AVDictionary 不是一个线程安全的容器，而且遍历中修改内容会导致未定义行为。具体点说，如果在av_dict_iterate的循环里调用av_dict_set，轻则漏掉新插入的条目，重则触发内存崩溃。因为在遍历过程中，内部数组可能被扩容、搬移或重新分配，迭代器的位置就失效了。

如果你确实需要“边遍历边修改”，我建议分两步走：先在遍历中收集需要修改的 key，保存到临时列表；遍历结束后，再统一调用av_dict_set做修改。这样既安全又清晰。

还有个容易被忽略的细节：av_dict_set传入的pm在字典为 NULL 时会自动分配，但如果这个函数被多线程并发调用，且共享同一个字典，就会产生竞争条件。FFmpeg 官方文档明确说 AVDictionary 不是线程安全的，必须用锁保护。

4.4 使用时机错误：为什么设置了却不生效

在 FFmpeg 里，很多选项只在特定阶段生效。比如编码器参数必须在avcodec_open2之前通过字典传进去，打开之后你再怎么av_dict_set都没用。协议层的选项必须在avformat_open_input或avformat_write_header之前传，一旦连接建立，再改就晚了。

我用一个案例说明：有次我想在推流过程中动态修改b（码率），代码里不停地av_dict_set(&fmt_ctx->metadata, ...)，结果码率纹丝不动，就是因为改错了对象。编码参数是要通过编码器 AVCodecContext 的相关 API 在运行中调整的，不是往字典里塞一个字符串就完事。

所以遇到“设置了不生效”，先别怀疑函数本身，先确认三个问题：

• 你设置的 key 名称对不对？FFmpeg 的 key 拼写错误时通常不会报错，而是安静地留在字典里等待被忽略。
• 你是否在正确的生命周期阶段设置？
• 你传的字典是否真的传到了底层模块？比如avformat_open_input是不是用了&options而不是options。

4.5 常见坑速查表

5. 经验汇总：几个提升效率的细节

如果要用一句话总结我使用av_dict_set的核心经验，那就是：先想清楚这个参数到底归哪个模块管，再决定往哪本字典里塞。FFmpeg 的选项系统是分层的，有 AVFormatContext 级别的，有 AVCodecContext 级别的，还有协议层和滤镜层的，每一层都有一个字典入口。传错层级，函数本身不报错，但参数就是“没进对门”。

再说一个实用的小技巧。当你要给一个 key 设置多个候选值时，可以先用av_dict_set写入默认值，再用带AV_DICT_DONT_OVERWRITE的调用写入用户配置，这样用户配置永远不会被默认值覆盖：

av_dict_set(&dict, "crf", "23", 0); // 默认值 av_dict_set(&dict, "crf", user_crf, AV_DICT_DONT_OVERWRITE); // 用户值优先

这个模式比先把键删掉再写新值要安全得多，也更简洁。类似的，如果你在拼接一个长字符串值，可以用多次追加的方式先把片段写入一个临时字典，再用av_dict_get读出合并结果。不过我一般不会这么干，直接操作字符串更直观。

最后再分享一个小技巧：给av_dict_set传参前，养成打印一下 key 和 value 的习惯。不要觉得日志啰嗦，实际排查“参数不生效”问题时，这几行日志能帮你省下一整天时间。我在这上面栽过跟头之后，现在所有涉及 AVDictionary 的代码都会做一个 dump 函数，用来确认参数进入 FFmpeg 前后的状态。这个习惯看着不起眼，但真的能让 FFmpeg 的开发体验顺滑不少。