ffmpeg C++ API 修改元数据失败主因是封装格式限制：MP4/MKV支持完整metadata，AVI/FLV基本不支持；需匹配格式专用键名（如MP3用"TIT2"、MP4用"title"），并完整转封装而非就地修改。
ffmpeg\_avformat\_write\_header 失败通常是因为输入格式不支持写入
直接用 ffmpeg 命令行改元数据最稳，C++ 调 API 改则受限于封装格式。比如 MP4、MKV 支持写入 AVDictionary 元数据，但 AVI、FLV 几乎不支持——不是代码写得不对，是底层格式规范压根没留字段位置。
常见报错：Invalid data found when processing input 或 Operation not permitted，往往出现在调用 avformat_write_header 时。这时先检查 oc->oformat->flags & AVFMT_NOFILE 是否为 0，再确认 oc->oformat->flags & AVFMT_NOTIMESTAMPS 是否影响写入逻辑。
- 优先选 MP4（
"mp4"）或 MKV（"matroska"）作为输出格式，它们对metadata字段支持完整 - 不要试图复用输入上下文
ic直接写回原文件——必须新建AVFormatContext*并分配输出流 - 若源文件是 MP3，改完后需用
av_dict_set(&oc->metadata, "TIT2", ...)而非通用键名，因为 ID3v2 标签有专用键映射
av\_dict\_set 设置元数据时键名必须匹配封装格式规范
同一个“标题”在不同格式里对应不同键：MP4 用 "title"，MP3 用 "TIT2"，MKV 用 "TITLE"（全大写），AVI 则基本忽略所有 av_dict_set 设置——它只认 "title" 且仅在某些编解码器下生效。
FFmpeg 内部有张映射表（见 libavformat/utils.c 中的 ff_metadata_conv），但不会自动帮你转。你设了 av_dict_set(&oc->metadata, "title", "xxx", 0)，输出 MP4 没问题，输出 MP3 就静默失效。
立即学习“C++免费学习笔记（深入）”；
- 查格式支持的键名：运行
ffprobe -v quiet -show_entries format_tags= -of default file.mp4看原始键 - MP3 推荐用
"TIT2"（标题）、"TPE1"（艺术家）、"TDRC"（年份） - MP4/MKV 统一用小写英文键：
"title"、"artist"、"date" - 中文值要确保传入的是 UTF-8 编码字节流，别用本地编码（如 GBK）
重写文件必须完整拷贝音视频流，不能只改 header
元数据不是独立区块，尤其在 MP4 中，它和 moov box 紧密耦合。想“就地修改”，得解析整个 moov、更新字符串、重算偏移、再写回去——FFmpeg C API 不提供这种细粒度操作，libavformat 的写模式默认是流式追加，不支持随机改写。
所以实际做法只能是：打开输入 → 创建新输出 → 拷贝所有流（avcodec_parameters_copy）→ 设置新 metadata → 复制每个 packet（注意 pts/dts 时间基转换）→ 写完关闭。整个过程相当于“转封装+打标”，而非“编辑”。
- 别漏掉
av_packet_rescale_ts(&pkt, ist->time_base, ost->time_base)，否则时间戳错乱导致播放卡顿 - 若源流含 B-frame，
pkt.dts可能为AV_NOPTS_VALUE，此时应按文档建议用pkt.pts推导 - 输出前务必调用
avformat_write_header(oc, nullptr)，否则 metadata 不进文件头；写完记得av_write_trailer(oc)
命令行替代方案比手写 C++ 更可靠
除非你在嵌入式环境或已有重度定制 pipeline，否则真没必要用 C++ 调 FFmpeg API 改元数据。FFmpeg 自带工具链足够健壮：
ffmpeg -i in.mp4 -c copy -metadata title="新标题" -metadata artist="作者" out.mp4
这条命令零解码、零重编码，纯 copy 流 + 更新 moov，速度极快且兼容性远超手写 API 流程。遇到 ID3v2 还可加 -id3v2_version 3 控制版本。
手写 C++ 最容易卡在内存管理细节上：比如 av_dict_free 忘调导致重复 set、AVFormatContext 生命周期搞混引发 double-free、或者没设 AVFMT_FLAG_GENPTS 导致 packet 时间戳为空——这些问题在命令行里根本不存在。
真正需要 C++ 集成的场景，往往是批量处理 + 业务逻辑判断（比如根据文件哈希决定是否写某条 metadata），这时也建议把 ffmpeg 调用封装成子进程，而不是硬啃 libavformat 写法。
