简介Qt 配合 FFmpeg 实现跨平台视频播放器是不少客户端开发者的常见需求。这份资源面向已有 Qt 基础、想在项目中接入 FFmpeg 以兼容更多音视频格式的开发人员通过一个可运行的播放器工程演示了完整集成思路从 FFmpeg 库的编译链接到继承 QAbstractMediaService 自定义解码服务再到界面层播放、暂停、快进、进度跳转、音量控制与异常反馈的实现。压缩包共 270 个文件、34.26MB以 180 个头文件、22 个 lib 与 18 个 dll 动态库、16 个 a/def 静态导入库为主体构成 FFmpeg 链接与调用基础4 个 cpp 与 1 个 ui 文件对应播放器主逻辑和界面设计qrc 资源、ico 图标、mp4 示例视频及 pro 工程文件让读者可以直接用 Qt Creator 打开工程对照学习。这份资料还覆盖了 avcodec_find_decoder、avcodec_open2、AVFormatContext 打开文件、AVStream 获取流、YUV/RGB 渲染到 QVideoWidget 等关键调用点并给出元数据显示与错误处理框架方便二次开发。目前已有 1070 人学习适合希望深度掌握 Qt 与 FFmpeg 媒体管道、并快速落地到实际项目的读者。 我最早接触 Qt 和 FFmpeg是想给项目里加一个简单又好用的视频播放模块。Qt 自带的 QMediaPlayer 说实话够用但碰到一些非常规格式、或者想对解码后的帧做实时处理时就会明显感觉使不上劲。后来花了几个晚上用 FFmpeg 的库直接对接 Qt把解码、显示、音频输出、同步这些环节一个一个打通总算是完完整整跑起来了。这篇文章就把这个过程中最有参考价值的东西整理出来包含架构选型、工程配置、代码骨架、同步思路和踩坑记录给正准备用 Qt FFmpeg 做播放器的朋友一份可以少走弯路的参考。1. 播放器方案选型与整体架构设计我之前也纠结过一个问题既然 Qt 已经提供了 QMediaPlayer为什么还要绕一圈去调 FFmpeg这个问题的答案直接决定了整个项目的技术路线。1.1 QMediaPlayer 与 FFmpeg 方案的边界QMediaPlayer 的优势是接入简单几行代码就能拖动一个窗口播放本地视频。但它有一个绕不开的短板解码能力受限于 Qt Multimedia 后端的实现。在 Windows 上依赖系统自带的 DirectShow 或 WMF在 Linux 上依赖 GStreamer一旦遇到系统没安装对应解码器或格式较冷门的文件就直接罢工。而且 QMediaPlayer 不给你访问原始帧数据的机会想做滤镜、截图、逐帧分析、定制渲染基本没门。FFmpeg 是一个纯粹的编解码库自带 libavcodec、libavformat、libswscale、libswresample 等模块支持的封装格式和编码格式覆盖面非常广。它不管界面的事把解码出来的原始数据交给你剩下怎么显示、怎么播放、怎么同步完全由自己掌控。这既是优势也是成本界面、线程、音频输出、同步逻辑全都要自己搭。1.2 整体模块划分我最终的播放器架构分成了四个核心模块解封装与解码模块基于 FFmpeg 的 libavformat 读取容器格式通过 libavcodec 解码出原始视频帧和音频采样。视频显示模块把解码出的 YUV 帧转换为 RGB 图像交给 Qt 的 QLabel 或 QOpenGLWidget 渲染。音频输出模块把 PCM 数据喂给 Qt 的 QAudioSink实现出声。同步控制模块以音频时钟为参考控制视频帧的显示节奏实现音画同步。这几个模块放在独立的解码线程中避免阻塞 UI 线程。UI 线程只负责接收 QImage 并显示音频数据则通过队列传递给音频输出接口。这样拆分的最大好处是职责清晰后续想加暂停、定位、截图功能时只需要在对应模块上扩展。提示如果对实时性要求不高只是想在 Qt 里放一个能用的视频窗口QMediaPlayer 确实更省事。但如果你想深入理解播放器原理或者对格式兼容性、帧处理有更高要求FFmpeg 方案是非常值得投入时间的选择。2. 开发环境准备与工程构建在动手写代码之前先把环境搭好。这部分看起来琐碎但很多新手会在这里卡住特别是链接库那一堆依赖关系。2.1 版本选型与下载我使用的是 Qt 5.15.2 和 FFmpeg 4.4后来也试过 FFmpeg 6.x接口基本兼容。Qt 5.15.2 是 LTS 版本稳定资料多适合开发桌面应用。FFmpeg 4.4 也是 LTS 分支API 变动相对小网上能查到的资料大部分都适用于这个版本。如果是在 Windows 上开发FFmpeg 官方不直接提供 Windows 编译版本一般去 gyan.dev 或 BtbN 的 GitHub Releases 下载已编译好的 shared 版本。shared 版本里面包含 dll、lib 和头文件适合做二次开发。Qt 的话官方安装包在国内下载可能会慢一些可以走 Qt 的国内镜像站比如清华 TUNA 的镜像源。装的时候注意勾选 Qt 5.15.2 对应的 MSVC 编译器版本别只装 Qt 库却忘了装编译器工具链。2.2 CMake 工程配置整个项目用 CMake 构建比 qmake 更灵活也更符合现代 C 项目的习惯。核心配置是这样的cmake_minimum_required(VERSION 3.16) project(QtFfmpegPlayer) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) find_package(Qt5 COMPONENTS Widgets Multimedia REQUIRED) set(FFMPEG_ROOT D:/libs/ffmpeg-4.4) set(FFMPEG_INCLUDE_DIR ${FFMPEG_ROOT}/include) set(FFMPEG_LIB_DIR ${FFMPEG_ROOT}/lib) add_executable(QtFfmpegPlayer main.cpp MainWindow.ui PlayerCore.h PlayerCore.cpp ) target_include_directories(QtFfmpegPlayer PRIVATE ${FFMPEG_INCLUDE_DIR}) target_link_directories(QtFfmpegPlayer PRIVATE ${FFMPEG_LIB_DIR}) target_link_libraries(QtFfmpegPlayer PRIVATE Qt5::Widgets Qt5::Multimedia avformat avcodec avutil swscale swresample )有几个点需要特别强调。第一FFmpeg 的头文件和库目录一定要正确指定否则编译时会报找不到头文件。第二链接顺序有讲究。在 MSVC 环境下avformat 依赖 avcodec 和 avutilavcodec 依赖 avutilswscale 和 swresample 也依赖 avutil所以通常把 avutil 放在最后让链接器能正确解析符号依赖。如果你在链接时遇到一堆 unresolved external symbol多半就是顺序问题。第三Debug 和 Release 版本的库不能混用。Qt 的 debug 库后缀是 dFFmpeg 的库如果只有 release 版本那整个项目也统一用 release 构建否则会碰到运行时崩溃或解码异常的问题。2.3 动态库运行时配置编译通过只是第一步。程序运行时由于 FFmpeg 是动态链接的必须让系统能找到对应的 dll 文件。两个做法直接把 FFmpeg 的 bin 目录下的所有 dll 复制到 exe 所在目录。这是最简单也最粗暴的方法发布时也用得上。在 Qt Creator 里把 FFmpeg 的 bin 目录路径加入到 PATH 环境变量或者构建环境的 PATH 设置中方便开发调试。网上经常看到有人运行时提示找不到 avformat-*.dll或者代码能编译但一运行就崩溃一部分原因就是 dll 没跟着跑起来。另有一个高频报错是 Windows 下提示 no qt platform plugin could be initialized这个多半是 Qt 的 platforms 插件目录没有随程序正确发布导致的后面在常见问题里我会再详细说。注意FFmpeg 在 Windows 下的 Debug 构建版本并不好找多数预编译包只提供 release 版本。如果项目必须用 Debug 模式调试建议在 CMake 里做一次判断Debug 模式也链接 release 库并确保全局使用同样的运行时库设置以免出现运行时崩溃。3. FFmpeg 解封装与解码流程实现环境没问题之后就开始写核心逻辑了。解封装和解码是播放器的前半段就是把视频文件中压缩的数据还原成原始的图像和声音。3.1 打开媒体文件与查找流信息第一步是打开文件拿到格式上下文并从容器中探测出视频流、音频流和对应的解码器。extern C { #include libavformat/avformat.h #include libavcodec/avcodec.h #include libswscale/swscale.h #include libswresample/swresample.h #include libavutil/imgutils.h } bool PlayerCore::openFile(const QString filePath) { // 1. 打开输入文件 if (avformat_open_input(m_formatCtx, filePath.toStdString().c_str(), nullptr, nullptr) ! 0) { return false; } // 2. 读取媒体信息找到视频流和音频流 if (avformat_find_stream_info(m_formatCtx, nullptr) 0) { return false; } // 3. 查找最佳视频流 m_videoStreamIndex av_find_best_stream(m_formatCtx, AVMEDIA_TYPE_VIDEO, -1, -1, nullptr, 0); m_audioStreamIndex av_find_best_stream(m_formatCtx, AVMEDIA_TYPE_AUDIO, -1, -1, nullptr, 0); if (m_videoStreamIndex 0) { // 既有视频也有音频才算是完整的播放器需求 return false; } m_videoStream m_formatCtx-streams[m_videoStreamIndex]; // 4. 打开视频解码器 const AVCodec* videoDecoder avcodec_find_decoder(m_videoStream-codecpar-codec_id); m_videoCodecCtx avcodec_alloc_context3(videoDecoder); avcodec_parameters_to_context(m_videoCodecCtx, m_videoStream-codecpar); if (avcodec_open2(m_videoCodecCtx, videoDecoder, nullptr) 0) { return false; } // 5. 音频解码器按同样步骤打开 // ... return true; }av_find_best_stream 这个函数很好用它会自动选择最合适的流省去自己遍历 streams 数组去判断编码类型的麻烦。注意旧版本的 FFmpeg 用的是 codec新版本用 codecpar如果你看的老博客用的是旧的赋值方式编译时会报字段不存在的错误。3.2 读取数据包与解码打开解码器之后就进入主循环循环读取压缩数据包把包交给解码器解码器输出原始帧然后再把帧做后续处理。AVPacket* packet av_packet_alloc(); AVFrame* frame av_frame_alloc(); while (av_read_frame(m_formatCtx, packet) 0) { if (packet-stream_index m_videoStreamIndex) { // 发送给视频解码器 if (avcodec_send_packet(m_videoCodecCtx, packet) 0) { while (avcodec_receive_frame(m_videoCodecCtx, frame) 0) { // 拿到一个解码后的视频帧 processVideoFrame(frame); } } } else if (m_audioStreamIndex 0 packet-stream_index m_audioStreamIndex) { // 音频包走同样的流程解码后交给音频输出 if (avcodec_send_packet(m_audioCodecCtx, packet) 0) { while (avcodec_receive_frame(m_audioCodecCtx, frame) 0) { processAudioFrame(frame); } } } av_packet_unref(packet); }这里有一个关键的编码方式设计FFmpeg 新一代的 API 是 send/receive 模式即发送一个压缩包进去解码器可能输出 0 个、1 个或多个原始帧。必须用 while 循环把解码器内部缓冲的所有帧都取出来不能只取一次。3.3 视频转格式YUV 到 RGBFFmpeg 解码出来的视频帧一般是 YUV420P 格式但 Qt 的 QImage 显示最方便的是 RGB32 格式。这个转换用 FFmpeg 自带的 swscale 模块完成效率很高。void PlayerCore::processVideoFrame(AVFrame* frame) { // 第一次处理时初始化格式转换上下文 if (m_swsCtx nullptr) { m_swsCtx sws_getContext( frame-width, frame-height, AV_PIX_FMT_YUV420P, frame-width, frame-height, AV_PIX_FMT_RGB32, SWS_BILINEAR, nullptr, nullptr, nullptr); m_rgbBuffer.resize(av_image_get_buffer_size(AV_PIX_FMT_RGB32, frame-width, frame-height, 1)); } uint8_t* rgbData[1] { m_rgbBuffer.data() }; int rgbLineSize[1] { frame-width * 4 }; sws_scale(m_swsCtx, frame-data, frame-linesize, 0, frame-height, rgbData, rgbLineSize); QImage image(rgbData[0], frame-width, frame-height, rgbLineSize[0], QImage::Format_RGB32); // 通过信号把图片发给 UI 线程 emit frameReady(image.copy()); }QImage 默认是浅拷贝只保存像素指针不复制数据所以这里必须调用 copy() 做一次深拷贝否则传给 UI 线程后原始缓冲区被复用图像内容就乱了。这是我最早写播放器时踩过的一个坑图像花屏闪烁找了好久才发现是这个原因。4. 音频输出与音视频同步视频图像能一帧一帧出来之后接下来要解决两个问题声音怎么放出来以及画面和声音怎么对上。4.1 Qt 的音频输出接口实现我用了 Qt Multimedia 里的 QAudioOutput 来播放 PCM 数据。这个类会把 QByteArray 或 QIODevice 里的数据写入音频设备底层是跨平台的省去自己调 Windows/ALSA/CoreAudio 的麻烦。初始化代码// 假设声道数是 2采样率 44100采用 16 位有符号整数 QAudioFormat fmt; fmt.setSampleRate(44100); fmt.setChannelCount(2); fmt.setSampleFormat(QAudioFormat::UInt8); // 注意这里 m_audioOutput new QAudioOutput(fmt); m_audioIO m_audioOutput-start();编码细节需要说明一下不同平台和不同 FFmpeg 解码出的音频格式并不一样很多音频文件解码出来是 AV_SAMPLE_FMT_FLTP即浮点 planar 格式而 QAudioOutput 最通用的是有符号 16 位交错格式。因此你需要用 swresample 做一次音频重采样把解码出的 AVFrame 转成目标格式后再塞给音频输出。如果不做转换轻则无声重则杂音剧烈。音频重采样示例// 初始化转换器 SwrContext* swr swr_alloc_set_opts(nullptr, outChannelLayout, AV_SAMPLE_FMT_S16, outSampleRate, inChannelLayout, (AVSampleFormat)frame-format, (int)frame-sample_rate, 0, nullptr); swr_init(swr); // 转换数据 uint8_t* outBuffer nullptr; int outSamples swr_get_out_samples(swr, frame-nb_samples); av_samples_alloc(outBuffer, nullptr, outChannels, outSamples, AV_SAMPLE_FMT_S16, 0); int converted swr_convert(swr, outBuffer, outSamples, (const uint8_t**)frame-extended_data, frame-nb_samples); // 然后 m_audioIO-write((const char*)outBuffer, converted * outChannels * 2);4.2 音视频同步的常用策略播放器最难的部分不是解码而是同步。我采用的是最经典、也最实用的方案以音频时钟为主时钟视频向音频对齐。具体思路是这样的维护一个全局的音频时钟即当前正在播放的音频已经播到了第几秒。视频帧在显示之前比较自己的 PTS展示时间戳和音频时钟的差值。如果视频领先音频超过一定阈值就等待比如休眠几十毫秒再判断。如果视频落后音频就放弃显示这一帧直接跳过让画面快点追上声音。计算视频帧 PTS 秒数的方式double pts frame-pts * av_q2d(m_videoStream-time_base);音频时钟的获取我用的方案是记录音频输出启动时的 QAudioOutput 的 processedUSecs 减去已写入的数据累计时间。更简单一点可以用一个计数器累加每次写入音频设备的样本数再除以采样率得到当前播放位置。当然启动和暂停的时候这个时钟会复杂一点但基本的播放下累加写入样本数的方式已经够用。有了时钟后视频显示逻辑可以简化成伪代码double audioClock getAudioClock(); double videoPts getVideoPts(frame); if (videoPts audioClock) { // 画面快了等一下 double delayMs (videoPts - audioClock) * 1000; QThread::msleep(qMin((int)delayMs, 100)); // 最多睡100ms避免卡死UI } else if (audioClock - videoPts 0.1) { // 画面落后太多跳过这帧 av_frame_unref(frame); continue; }同步算法的具体阈值可以根据实际体验调整。阈值太小会觉得卡顿太大会觉得不同步。我最后用的是声音领先的画面超前 30ms 内不丢帧画面落后 50ms 内强制显示的策略试了几轮视频下来体感正常。4.3 暂停与跳转的同步处理如果停了播放又原地开始音频和视频的时间基准就不一致了。最简单的处理方式是暂停时记住当前的音频时钟偏移量恢复时将偏移量加到所有帧的 PTS 比较逻辑上。跳转时则调用 av_seek_frame 或者 avformat_seek_file 进行关键帧定位跳转后清空解码器内部缓冲同时重置音频时钟。跳转一次之后如果直接读到非关键帧解码器无法立即输出完整画面这是正常现象。FFmpeg 在 seek 后会自动往关键帧跳不过视频可能会有几十毫秒到几百毫秒的黑屏或花屏过渡这符合正常的播放器行为。5. 工程构建中的高频报错与排查记录最后把这几个月的实践中碰到最多的坑总结一下。这些报错在论坛和问答平台里几乎天天能看到很多人卡住很久我把原因和解决办法直接列出来。5.1 高频问题排查表报错现象可能原因解决办法运行时提示 no qt platform plugin could be initialized程序目录缺少 platforms/qwindows.dll用 windeployqt 部署插件目录或在开发环境检查 PATH 是否包含 Qt 的 plugins 目录编译时报 avformat.h 找不到FFmpeg 头文件路径未指定检查 CMake 的 include_directories 路径确认是 include 目录而不是 bin 目录链接报 unresolved external symbol库链接顺序不对或库版本与编译器不匹配FFmpeg 库放在依赖库之前确认库用的编译器架构和当前一致程序运行后立刻崩溃FFmpeg 是 release 库但工程是 debug 模式统一用 release 模式编译或换用带 debug 符号的库有图像没声音音频格式未转换或采样率不匹配检查 QAudioFormat 参数用 swresample 把 PCM 转成 S16 交错格式画面播放速度过快缺少同步逻辑帧直接全速显示引入音频时钟显示前判断 PTS 差值等待或丢帧视频出现花屏、闪烁QImage 浅拷贝导致缓冲区被覆盖信号发出前调用 QImage::copy() 深拷贝视频结束后 UI 卡死解码循环和 UI 线程直接交互保证解码、读取、处理都在子线程只通过信号和 UI 通信5.2 发布部署的注意事项程序开发完要发布到其他机器时需要把 Qt 的运行库和 FFmpeg 的 dll 打包完整。Qt 官方提供的 windeployqt 工具可以自动分析 exe 依赖并拷贝对应的 Qt 插件和运行库但 FFmpeg 的 dll 必须手动一起复制进去。我用 windeployqt 部署完又手动把 FFmpeg 的 bin 目录下所有 dll 放到 exe 同一目录下测试了几台没有 Qt 环境的新电脑都能正常运行。有次我在项目里还遇到过一个比较隐蔽的问题在 Windows 上 FFmpeg 如果打开了硬件解码比如 cuda、dxva2发布时需要额外带上对应依赖而且目标机器还得有对应显卡驱动否则会运行报错。我没有在通用版本里启用硬件解码只在特定需求的版本中做了条件编译。5.3 调试技巧与性能优化开发过程中有一些很有效的排查手段用 av_err2str 函数把 FFmpeg 返回的错误码转换成字符串错误信息可以快速判断是文件打开失败、流未找到还是解码器内出现异常。视频转 RGB 时SWS_BILINEAR 是通用选择如果需要更高性能可以试试 SWS_FAST_BILINEAR质量差一点点但速度快不少。如果做实时预览或处理高分辨率视频建议用 QOpenGLWidget 配合着色器直接做 YUV 到 RGB 的转换比 sws_scale 再交给 QImage 要快得多。解码线程是纯计算密集型任务在 Qt 的信号槽中传递 QImage 虽然方便但频繁的拷贝会影响性能。我后续优化时把视频帧队列改为使用无锁队列直接传递 QImage把 UI 刷新通过定时器定时从队列取图这样能显著减少 UI 线程的压力。从整体体验来看Qt FFmpeg 这个组合除了开发初期搭建环境需要一点耐心之外后面基本是一马平川非常自由几乎所有音视频层的需求都能自己掌控。你完全可以基于这套架构继续扩展比如加字幕、做帧截图、加滤镜、支持网络流播放这也是我当初选择 FFmpeg 而不是其他方案的原因所在。本文还有配套的精品资源点击获取