Qt MinGW 32位工程接入FFmpeg 3.4：解码编码与避坑指南

简介面向32位Windows平台及MinGW32、Qt开发环境的多媒体开发包提供FFmpeg 3.4预编译头文件、导入库、动态库与示例源码适合在C/C项目中集成音视频编解码、格式转换、滤镜处理和流媒体功能的开发者。压缩包共170个文件以107个h头文件、21个c源码、6个dll动态库、6个lib导入库和6个a静态库为主辅以def、pc配置、ffpreset预设、makefile及readme等整体约2.62MB目录紧凑便于按模块查阅。包内示例覆盖AAC转码、封装、解封装等典型流程核心编解码、格式与滤镜库便于直接链接调用可帮助读者快速验证32位MinGWQt环境下的编译链接与基础音视频处理。已有229人学习下载适合需要搭建开发环境、对照示例查漏补缺的读者参考。1. 32 位 Qt 工程里的 FFmpeg 3.4一份能直接链接的 MinGW 编译包如果你手上维护着一个还在用 Qt mingw ffmpeg 32位 3.4 这套组合的老项目大概率遇到过这种局面源码里解码、转码、抽帧的逻辑都写好了卡在最后一步——找不到一份能和 MinGW 32 位编译器对上话的 FFmpeg 库。自己 configure 一遍要装 MSYS、挑依赖、关掉一堆 GPL 组件配完还不一定能过链接。这份 ffmpeg-3.4-mingw32 就是冲这个场景准备的头文件、MinGW 格式的导入库、运行期 DLL 一起打包解压进工程目录就能写-lavcodec -lavformat。它解决的不是FFmpeg 怎么用而是32 位 Qt 工程怎么把 FFmpeg 3.4 接上且不崩。适合两类人一是维护 Qt 5.x MinGW 32 位老项目的开发者二是需要在无网络、无包管理的环境里把音视频功能塞进桌面程序的人。代价也很明确——3.4 是一套老 API很多新写法在这里不存在下面按拆包、接入、编码、排查、验证的顺序走一遍。2. 拆包看结构头文件、导入库、DLL 三件套怎么配拿到压缩包先别急着往工程里拷先把目录结构和一个标准 MSVC 版本对照一遍。MinGW 和 MSVC 的库文件命名、ABI、运行时都不是一回事搞混了后面全是玄学错误。2.1 包里每个目录对应编译期的哪一步MinGW 32 位版本的 FFmpeg 预编译包结构基本是固定的三件套加一个可执行目录路径内容作用阶段include/libavcodec/、libavformat/、libavutil/、libswscale/、libswresample/、libavfilter/、libavdevice/、libpostproc/八个头文件目录编译期供#includelib/libavcodec.dll.a、libavformat.dll.a等导入库链接期告诉链接器去哪个 DLL 找符号bin/avcodec-57.dll、avformat-57.dll等运行库以及ffmpeg.exe、ffprobe.exe、ffplay.exe运行期bin/*.exe三个命令行工具调试和自检这里第一个要认清的点是lib/下的文件后缀。MinGW 用的是.dll.a动态链接的导入库或.a静态库而 MSVC 版本给的是.lib。.lib在 MinGW 的 ld 眼里就是一堆无法识别的二进制你把它加进LIBS只会得到file format not recognized。反过来也一样.dll.a交给 MSVC 的 link.exe 也用不了。所以判断一份 FFmpeg 包能不能给自己的工程用看lib/后缀比看版本号还快。第二个是 DLL 的命名规律avcodec-57.dll里的57是 libavcodec 的主版本号不是 FFmpeg 的版本号。3.4 这一代的对应关系是 libavcodec 57、libavformat 57、libavutil 55、libswscale 4、libswresample 2、libavfilter 6、libavdevice 57、libpostproc 54。后面排查运行时缺库靠的就是这串数字去对文件名。提示包里的ffprobe.exe是最省事的自检工具。解压后先跑一次ffprobe -version能打印出ffmpeg version 3.4和一行libavcodec 57.x.x说明这份包自身是完整的跑不起来说明缺 DLL 或者被 64 位系统上的路径问题绊住了。2.2 动态链接还是静态链接32 位 Qt 工程的取舍拿到包以后第一个决策是链接方式这个决定会影响后面所有部署动作。动态链接用.dll.a 运行时带 DLL是绝大多数 Qt 工程的选择。原因很实际exe 体积小编译快多个模块共用同一份运行库。代价是你必须把 7 个 DLL 一起放到 exe 同级目录或者PATH里漏一个就是启动即崩。而且windeployqt只认 Qt 自己的依赖FFmpeg 的 DLL 它一概不管这一步得自己写脚本处理。静态链接用.a适合做绿色单文件工具但 32 位下问题不少。FFmpeg 静态库的依赖顺序极其敏感-lavformat -lavcodec -lswscale -lswresample -lavutil这个顺序错了就是成片的undefined reference再叠加-lz -lm -lpthread -lws2_32 -lsecur32 -lbcrypt这些系统库稍微错一位链接器就罢工。另外静态链接会涉及授权边界问题具体能不能用要看这份包编译时开了哪些开关包内一般会带一个说明文件用之前翻一下。我一般建议桌面交付走动态链接工具型小程序再考虑静态。动态链接部署虽然多一步拷 DLL但这步可以脚本化比调静态库顺序省心得多。# 把运行时 DLL 一次性拷到构建输出目录缺哪个就报哪个 FF_DIR/path/to/ffmpeg-3.4-mingw32 OUT_DIRbuild/release for lib in avcodec avformat avutil swscale swresample avfilter avdevice postproc; do src$(ls $FF_DIR/bin/lib${lib}-*.dll 2/dev/null | head -n 1) if [ -n $src ]; then cp -f $src $OUT_DIR/ else echo missing dll: lib${lib}-*.dll fi done这段脚本用通配符匹配带版本号的 DLL 文件名避免每换一个小版本就要改脚本。head -n 1是防止目录里同时存在libavcodec-57.dll和libavcodec-57-debug.dll之类的变体时拷错——真碰到这种目录就该人工确认一下哪个是 release 版本了。拷完之后用ldd之类的工具在 Linux 上验证没用得在 Windows 上直接双击跑一次 exe或者用 Process Monitor 看加载路径。2.3 版本号对齐3.4 这一代的 ABI 边界32 位 MinGW 包最容易翻车的地方不在代码在版本混用。头文件来自 3.4、DLL 来自 4.2编译能过运行时随机崩溃这种问题查起来像黑匣子因为崩溃点往往在av_read_frame里而不是在你的代码里。判断是否同一批很简单在代码里打印版本宏和ffprobe -version的输出对一遍。extern C { #include libavcodec/avcodec.h #include libavformat/avformat.h #include libavutil/avutil.h } // 每个库都拆出主版本/次版本/微版本用于和 dll 实际版本比对 static void dumpVersions() { qDebug(avutil %d.%d.%d, LIBAVUTIL_VERSION_MAJOR, LIBAVUTIL_VERSION_MINOR, LIBAVUTIL_VERSION_MICRO); qDebug(avcodec %d.%d.%d, LIBAVCODEC_VERSION_MAJOR, LIBAVCODEC_VERSION_MINOR, LIBAVCODEC_VERSION_MICRO); qDebug(avformat %d.%d.%d, LIBAVFORMAT_VERSION_MAJOR, LIBAVFORMAT_VERSION_MINOR, LIBAVFORMAT_VERSION_MICRO); // 运行期实际加载到的版本和上面编译期宏对比 qDebug(runtime %s, av_version_info()); }编译期宏来自头文件av_version_info()返回的是当前加载到的 DLL 里的字符串。两者主版本号不一致说明头文件和 DLL 不是一批必须换。3.4 这一代的头文件宏在version.h里形如LIBAVCODEC_VERSION_MAJOR 57如果你看到 58、59 这些数字那就不是 3.4 的头文件了。还有一个隐性边界3.4 的AVCodecContext里还有大量可以直接读写的字段比如codec_id、width、height这些字段在 4.x 后期和 5.x 中被陆续废弃改成只能用av_opt_set或codecpar访问。反过来说如果你从网上抄了一段 5.x 的代码往 3.4 上贴一定会编译失败。抄代码前先确认版本这是 3.4 项目组最省时间的习惯。3. 接进 Qt MinGW 工程.pro 配置与一次完整解码目录结构清楚了接下来把它接进 qmake 工程。这一步的失败率最高因为错的地方不报错、只报一堆看不懂的链接错误。3.1 .pro 里怎么把头文件和库写对在工程目录下建一个3rdparty/ffmpeg/目录把include和lib整体拷进去然后在.pro里写# 头文件路径注意层级别写成 include/ 里那一堆 libav* 目录的父级 INCLUDEPATH $$PWD/3rdparty/ffmpeg/include # 库路径与依赖顺序被依赖的放后面GNU ld 是单遍扫描 LIBS -L$$PWD/3rdparty/ffmpeg/lib \ -lavformat \ -lavcodec \ -lswscale \ -lswresample \ -lavutil # 32 位 MinGW 下建议显式关掉自动导入的告警噪音 QMAKE_LFLAGS -Wl,--enable-auto-import三个细节值得单独说。第一是INCLUDEPATH指向的层级。包里的结构是include/libavcodec/avcodec.h所以INCLUDEPATH要指到include这一级代码里写#include libavcodec/avcodec.h。指到include/libavcodec就会变成#include avcodec.h能过编译但后续所有相对包含全乱。第二是库顺序。GNU ld 从左往右单遍扫描遇到未解析符号才去后面的库里找。libavformat依赖libavcodec和libavutil所以-lavformat必须放在前面-lavutil放最后。顺序反了不会报顺序错只会报一堆undefined reference to av_malloc很容易被误判成库没链上。第三是extern C。FFmpeg 是纯 C 库C 编译器会对函数名做名字修饰导致链接器在.dll.a里找不到av_register_all而只看到_Z16av_register_allv这种符号。所以所有 FFmpeg 头文件的包含必须包在extern C { }里或者写个统一的ffmpeg_headers.h集中处理。// ffmpeg_headers.h —— 全工程只在这里包含 FFmpeg 头文件 #ifndef FFMPEG_HEADERS_H #define FFMPEG_HEADERS_H extern C { #include libavformat/avformat.h #include libavcodec/avcodec.h #include libavutil/avutil.h #include libavutil/imgutils.h #include libswscale/swscale.h #include libswresample/swresample.h } #endif这样做的额外好处是哪天要整体升到 4.x只改一个文件里的包含关系不用全局搜索替换。3.2 打开输入与初始化解码器3.4 的 API 习惯3.4 的解码入口有两套 API老的avcodec_decode_video2和 3.1 引入的avcodec_send_packet/avcodec_receive_frame。新写的代码建议直接用后一套老代码混用会出问题——同一个AVCodecContext上两种方式交替调用状态机会乱。// 打开输入并准备解码器成功返回 true失败时 fmt/dec 均为 nullptr bool openInput(const QString path, AVFormatContext **outFmt, AVCodecContext **outDec, int *outStreamIndex) { *outFmt nullptr; *outDec nullptr; av_register_all(); // 3.4 还需要4.0 起被移除 avformat_network_init(); // 后面要读网络地址时再调本地文件可省 AVFormatContext *fmt nullptr; if (avformat_open_input(fmt, path.toUtf8().constData(), nullptr, nullptr) 0) { return false; // 文件不存在、格式不支持都会走到这里 } // 探测流信息失败一般说明文件损坏或只有头部没有数据 if (avformat_find_stream_info(fmt, nullptr) 0) { avformat_close_input(fmt); return false; } // 找第一条视频流不要假设它就是第 0 条 int vIdx av_find_best_stream(fmt, AVMEDIA_TYPE_VIDEO, -1, -1, nullptr, 0); if (vIdx 0) { avformat_close_input(fmt); return false; } AVCodecParameters *par fmt-streams[vIdx]-codecpar; AVCodec *codec avcodec_find_decoder(par-codec_id); if (!codec) { avformat_close_input(fmt); return false; } AVCodecContext *dec avcodec_alloc_context3(codec); if (!dec) { avformat_close_input(fmt); return false; } // 必须把 codecpar 的参数搬到解码上下文否则宽高、像素格式都是 0 if (avcodec_parameters_to_context(dec, par) 0 || avcodec_open2(dec, codec, nullptr) 0) { avcodec_free_context(dec); avformat_close_input(fmt); return false; } *outFmt fmt; *outDec dec; *outStreamIndex vIdx; return true; }几个参数含义值得展开。av_find_best_stream的第三个参数是期望的流索引传-1表示自动挑质量最好的一条第四个参数是关联流索引比如音频依赖视频一般传-1。用av_find_best_stream而不是遍历fmt-nb_streams判断codecpar-codec_type好处是它能处理多视频流的容器一个 MV 里塞多角度的情况并且对无索引文件更稳。avcodec_parameters_to_context这一步是 3.4 里最容易被漏掉的很多人直接avcodec_open2之后就发现dec-width 0。原因是 3.x 之后解码参数被抽到AVCodecParameters里AVCodecContext不再自动继承。注意av_register_all()在 3.4 里还在但已经是可省则省的状态。如果你的程序只用一个格式可以用avformat_register_all()之外的局部注册来减小初始化开销不过对桌面程序来说这点开销可以忽略不必过度优化。3.3 把 AVFrame 转成 QImage 并落到界面上拿到AVFrame只是拿到 YUV 数据Qt 界面要的是 RGB。这一步用sws_scale参数写错就是绿屏、花屏或者只有左半张图。// 从输入里解码出一帧并转成 QImage返回空图表示流结束或出错 QImage decodeOneFrame(AVFormatContext *fmt, AVCodecContext *dec, int streamIndex, SwsContext **swsPtr, int *w, int *h) { AVPacket *pkt av_packet_alloc(); AVFrame *frame av_frame_alloc(); QImage result; while (av_read_frame(fmt, pkt) 0) { if (pkt-stream_index ! streamIndex) { av_packet_unref(pkt); // 不是视频包必须立即释放 continue; } if (avcodec_send_packet(dec, pkt) 0) { if (avcodec_receive_frame(dec, frame) 0) { // 第一次拿到帧时才建转换上下文用帧里的真实参数 if (*swsPtr nullptr) { *swsPtr sws_getContext(frame-width, frame-height, (AVPixelFormat)frame-format, frame-width, frame-height, AV_PIX_FMT_RGB32, SWS_BILINEAR, nullptr, nullptr, nullptr); *w frame-width; *h frame-height; } if (*swsPtr) { result QImage(*w, *h, QImage::Format_RGB32); uint8_t *dst[4] { result.bits(), nullptr, nullptr, nullptr }; int dls[4] { result.bytesPerLine(), 0, 0, 0 }; // srcSliceH 用帧高不是 linesizedst 的步长用 QImage 的 bytesPerLine sws_scale(*swsPtr, frame-data, frame-linesize, 0, *h, dst, dls); } av_packet_unref(pkt); break; } } av_packet_unref(pkt); } av_frame_free(frame); av_packet_free(pkt); return result; }三个容易错的参数。sws_scale的第五个参数srcSliceH是要转换的行数也就是帧高很多人在这里填frame-linesize[0]结果是越界读或者只画出几条线。第七个参数dst数组的步长必须用QImage::bytesPerLine()因为 Qt 内部会按 4 字节对齐做行填充而width * 4在宽度不是 4 的倍数时和它不等。第三个是AV_PIX_FMT_RGB32和QImage::Format_RGB32的配对两者字节序一致写成AV_PIX_FMT_RGB24配Format_RGB32会得到偏色的图。SwsContext一定要缓存复用别每帧都sws_getContext再sws_freeContext。32 位进程地址空间紧张每帧新建一个上下文跑几百帧之后堆就碎了表现是解码到一半程序直接消失连崩溃日志都没有。4. 编码与封装从 QImage 生成 MP4 的完整链路解码是别人给你的数据你读懂编码是你的数据让别人能读难度不在代码量在时间戳和参数。3.4 的编码接口和现在差别不大但可用编码器的范围要提前确认。4.1 选编码器libx264 有没有先问一句预编译包最常见的一个惊喜是avcodec_find_encoder_by_name(libx264)返回nullptr。原因是 x264 是 GPL 组件很多预编译包为了授权干净直接没编进去只保留内置的mpeg4、mjpeg、h263这些。// 先试 libx264画质和体积最好不行退到内置 mpeg4 AVCodec *enc avcodec_find_encoder_by_name(libx264); if (!enc) { enc avcodec_find_encoder(AV_CODEC_ID_MPEG4); } if (!enc) { qWarning(no usable encoder in this build); return false; } qDebug(using encoder: %s, enc-name); // 想确认这份包到底带了哪些编码器遍历一遍最直观 AVCodec *c nullptr; while ((c av_codec_next(c)) ! nullptr) { if (av_codec_is_encoder(c) c-type AVMEDIA_TYPE_VIDEO) { qDebug(encoder available: %s, c-name); } }av_codec_next在 3.4 里还能用4.0 之后换成av_codec_iterate遍历一遍把可用编码器打出来比猜靠谱。如果列表里只有mpeg4、mjpeg、rawvideo这几个那就是没带 x264接受现实走AV_CODEC_ID_MPEG4或者自己重新编一份带--enable-libx264的。选回退方案时要注意画质和兼容性的差别。mpeg4在同样码率下细节明显不如 x264尤其是屏幕录制这类高对比内容块效应很明显好处是任何播放器都认。如果产物是内部预览、不做交付mpeg4 完全够用如果是给客户的文件建议还是想办法拿到带 x264 的构建。4.2 时基与时间戳pts 算错就是快进或卡死编码器上下文里的time_base是你喂给它的帧时间单位输出流的time_base是容器的时间单位两者通常不一样。写包之前必须做一次av_packet_rescale_ts否则播放器按流时基解释你给的 pts结果就是几倍速播放或者时间轴乱跳。// 创建编码器上下文并设置参数 AVCodecContext *encCtx avcodec_alloc_context3(enc); encCtx-width w ~1; // YUV420P 要求宽高为偶数奇数直接减一 encCtx-height h ~1; encCtx-pix_fmt AV_PIX_FMT_YUV420P; encCtx-time_base AVRational{1, fps}; // 帧率作为时间基每帧 pts 1 encCtx-gop_size fps * 2; // 两秒一个关键帧便于拖动 encCtx-max_b_frames 0; // 32 位老包上关掉 B 帧更稳 encCtx-bit_rate 2 * 1000 * 1000; // 2 Mbps屏幕内容可降到 800k encCtx-thread_count 2; // 32 位下别开太多线程栈空间吃紧 if (avcodec_open2(encCtx, enc, nullptr) 0) { qWarning(open encoder failed); return false; } // 输出流的时基设为编码器时基简化后面的换算 AVStream *st outFmt-streams[0]; st-time_base encCtx-time_base;参数怎么改取决于内容类型。帧率fps一般跟源一致屏幕录制 1525 就够高了纯浪费码率gop_size设成fps * 2是个折中关键帧太密体积大太稀拖动时等待久max_b_frames 0在 32 位老包上是血泪经验某些构建下 B 帧的帧重排序缓冲会额外占用内存长视频容易撞到地址空间上限thread_count同理默认值会按 CPU 核数开32 位进程每个线程栈默认 1MB开 8 个线程光栈就吃掉 8MB画质没提升多少。width ~1这个位运算就是向下取到偶数。YUV420P 的色度平面是亮度的一半宽高为奇数时色度平面尺寸无法整除编码器会直接返回-22。4.3 写封装av_interleaved_write_frame 的收尾封装阶段要做的事创建输出上下文、加一条流、写文件头、循环写包、flush、写文件尾。少任何一步产物要么打不开要么时长是 0。// 完整编码流程frames 是已经转成 YUV420P 的帧序列 bool encodeToMp4(const QString outPath, AVCodecContext *encCtx, const QVectorAVFrame * frames, int fps) { AVFormatContext *outFmt nullptr; // 按扩展名自动选封装器mp4 会选中 mp4/mov 系列 if (avformat_alloc_output_context2(outFmt, nullptr, nullptr, outPath.toUtf8().constData()) 0) { return false; } AVStream *st avformat_new_stream(outFmt, nullptr); if (!st) { avformat_free_context(outFmt); return false; } // 把编码器参数回填到流里缺这步播放器读不到编码格式 if (avcodec_parameters_from_context(st-codecpar, encCtx) 0) { avformat_free_context(outFmt); return false; } st-time_base encCtx-time_base; if (avio_open(outFmt-pb, outPath.toUtf8().constData(), AVIO_FLAG_WRITE) 0) { avformat_free_context(outFmt); return false; } if (avformat_write_header(outFmt, nullptr) 0) { avio_closep(outFmt-pb); avformat_free_context(outFmt); return false; } AVPacket *pkt av_packet_alloc(); int64_t pts 0; for (AVFrame *f : frames) { f-pts pts; if (avcodec_send_frame(encCtx, f) 0) { continue; } while (avcodec_receive_packet(encCtx, pkt) 0) { // 编码器时基 - 流时基这一步不做播放速度就是错的 av_packet_rescale_ts(pkt, encCtx-time_base, st-time_base); pkt-stream_index st-index; av_interleaved_write_frame(outFmt, pkt); av_packet_unref(pkt); } } // 冲刷编码器内部缓存的帧不 flush 会丢掉结尾一小段 avcodec_send_frame(encCtx, nullptr); while (avcodec_receive_packet(encCtx, pkt) 0) { av_packet_rescale_ts(pkt, encCtx-time_base, st-time_base); pkt-stream_index st-index; av_interleaved_write_frame(outFmt, pkt); av_packet_unref(pkt); } av_write_trailer(outFmt); // 不写 trailermp4 的 moov 盒子缺失文件打不开 av_packet_free(pkt); avio_closep(outFmt-pb); avformat_free_context(outFmt); return true; }av_packet_rescale_ts的四个参数顺序是包、源时基、目标时基。如果编码器和流时基设成一样像上面这样这步其实是恒等变换但代码里保留它是个好习惯——哪天改成st-time_base {1, 90000}这种标准 mp4 时基不改这里就会出错。av_write_trailer是最容易漏的一步。mp4 的索引信息moov box在文件尾不写 trailer 得到的是一个能拷走、但任何播放器都提示文件损坏的产物。有些封装器会把它写在头里AVFMT_NOFILE相关选项但默认行为是写尾部别赌。注意av_interleaved_write_frame而不是av_write_frame。前者会做音视频交错排序单视频轨看不出差别一旦加上音频轨用后者写出来的文件在某些播放器上音画不同步。5. 排查清单32 位 MinGW 环境下五个高频翻车点下面这五条按出现频率排基本覆盖了从编译到运行的完整链路。每条按现象 → 原因 → 解决写遇到问题可以直接对号入座。5.1 编译期 undefined reference toav_...现象.pro里LIBS看着没问题编译也过了链接阶段蹦出几十行undefined reference to av_register_all、avformat_open_input符号名看着完全对。原因三个可能按概率排。一是头文件没包extern CC 编译器把调用点修饰成了_Z16av_register_allv而库里是纯 C 的av_register_all二是LIBS顺序反了-lavutil写在了-lavformat前面三是-L路径指错链接器找到了一个同名的旧库或者根本是 MSVC 的.lib。解决先看错误行里的符号有没有_Z前缀有就是extern C问题把包含全收进一个头文件里统一处理。再看LIBS顺序保证-lavformat -lavcodec -lswscale -lswresample -lavutil这个被依赖者靠后的排列。最后在 qmake 生成的 Makefile 里搜-lavcodec确认它后面跟的-L路径确实是你拷进去的那份。5.2 运行时提示找不到 libavcodec-57.dll现象Qt Creator 里点运行窗口都没出来就退出了事件查看器里能看到应用程序无法正常启动 (0xc000007b)或者直接弹一个缺 DLL 的对话框。原因DLL 没跟 exe 放在一起或者放了一个位数不对的。0xc000007b这个错误码的经典含义就是32 位进程加载了 64 位 DLL反过来也一样。另一个可能是PATH里有另一份 FFmpeg 的同名 DLL版本号和头文件不匹配程序能启动但一调 API 就崩。解决把bin/下那 7 个 DLL 拷到 exe 同级目录先别依赖PATH。拷完用 Dependency Walker 之类的工具看一眼实际加载路径确认不是从系统目录里拖来的旧版本。如果项目同时有 32 位和 64 位构建建议在.pro里按contains(QT_ARCH, i386)分目录存放别共用一份。5.3 解码出来绿屏、花屏或者只有半张图现象sws_scale不报错QImage也有尺寸但显示出来上半部分是正常的、下半部分是绿的或者整张图颜色整体偏移。原因三个典型错误。sws_scale的srcSliceH参数填了frame-linesize[0]而不是帧高转换时用了AV_PIX_FMT_RGB24但QImage用了Format_RGB32每像素字节数对不上dst的步长用了width * 4而实际QImage::bytesPerLine()有 4 字节对齐填充。解决srcSliceH一律填帧高像素格式和QImage::Format严格配对AV_PIX_FMT_RGB32↔Format_RGB32AV_PIX_FMT_RGB24↔Format_RGB888dst步长永远用result.bytesPerLine()。还有一个隐蔽情况某些视频的AVFrame有 cropping 信息frame-crop_top之类显示区域比width/height小直接按width/height转会有黑边需要先av_frame_apply_cropping。5.4 avcodec_open2 返回 -22 或 -1现象解码器能创建参数看着也拷了avcodec_open2就是返回负数av_strerror出来是 Invalid argument 或者 Operation not permitted。原因-22一般是参数不合法常见于widthheight为 0、pix_fmt未设置、编码时宽高为奇数。-1更多是编解码器本身不可用比如你请求了libx264但包里没编进去或者硬件解码器在没有对应硬件的机器上被选中。解决打开之前把关键参数打一遍日志——width、height、pix_fmt、time_base、bit_rate缺哪个补哪个。编码路径下强制width ~1、height ~1。解码路径下确认用的是avcodec_find_decoder(par-codec_id)而不是硬编码某个解码器名。如果是硬件解码加一层软件解码回退别让一条路径封死。5.5 跑到一半进程直接消失没有崩溃日志现象处理一段 10 分钟的视频前 3 分钟正常之后程序无声无息地退出任务管理器里进程直接没了事件日志里也没有像样的堆栈。原因32 位进程的用户态地址空间上限是 2GB实际可用更少还要扣掉 DLL 映射和栈如果你把整段视频的所有帧都av_frame_alloc出来放在QVector里内存很快就到底。另一种情况是内存碎片频繁new/delete同尺寸的大块堆里全是空洞明明总空闲内存够就是申请不到连续块。解决改成流式处理解码一帧、转一帧、用完立刻av_frame_unref队列里最多保留几帧。如果业务确实需要缓存设一个上限比如 200 帧并做丢弃策略。另外养成习惯每个av_packet_allocav_frame_alloc都配一个对应的av_packet_freeav_frame_free别指望av_frame_unref会释放结构体本身。我在老项目里见过最隐蔽的一处泄漏是av_read_frame失败后直接break忘了av_packet_unref跑了两个小时才撑爆。6. 边界与验证3.4 能不能继续用怎么三分钟确认跑通判断一份 FFmpeg 3.4 包能不能进你的工程不用写完整业务跑一个二十行的自检程序就够。我的做法是新建一个空的 qmake 控制台工程链接这份库main里干三件事打印av_version_info()、打开一个测试文件、解出第一帧并打印宽高和像素格式。int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); av_register_all(); qDebug() ffmpeg: av_version_info(); // 期望看到 3.4.x AVFormatContext *fmt nullptr; if (avformat_open_input(fmt, test.mp4, nullptr, nullptr) 0) { qDebug() open failed; return 1; } avformat_find_stream_info(fmt, nullptr); qDebug() streams: fmt-nb_streams duration: fmt-duration; avformat_close_input(fmt); return 0; }三行输出分别验证了三件事版本号对得上说明头文件和 DLL 是一批nb_streams非零说明解复用链路通duration合理说明容器解析正常。这三步过了再往 Qt 界面里接。关于这套东西还能撑多久给一个务实的对照关注点FFmpeg 3.44.x / 5.x 差异初始化av_register_all()需要已移除无需调用解码入口avcodec_decode_video2仍可用已移除只能send/receive编码参数可直接写AVCodecContext字段逐步废弃走av_opt_set音频声道channels/channel_layout5.1 起改为ch_layout结构体32 位 Windows 构建社区预编译包常见越来越少主流转向 64 位结论不用绕新项目别选 3.4直接上 5.x 或 6.x已经在 3.4 上的老项目如果只是维护、没有硬性新特性需求继续用没问题但要把版本锁死——头文件、导入库、DLL 三样一起锁任何一个单独升级都等于给自己埋雷。最后一条血泪经验。我刚接第一个 32 位 Qt 音视频项目时图省事把库直接扔进系统PATH本机跑得好好的拿到客户机器上就起不来来回折腾了两天才发现是客户机上装了个旧版播放器PATH里躺着一份 54 版的avcodec.dll。从那以后我每次接入这种预编译包都强制走一遍拷贝到 exe 同级目录 自检程序跑通 断网跑一次这三步再动手写业务代码。这个习惯至少帮我省掉了十几次现场排查。希望帮到你。本文还有配套的精品资源点击获取