简介一份基于Qt框架的视频播放器完整源码对应示例工程samp15_5VideoPlayer适合正在学习Qt多媒体编程或自行设计播放器的开发者阅读。压缩包共计51个文件、大小623KB以cpp、h、ui、qrc等工程源码为主辅以bmp、ico、gif界面素材以及Debug/Release目录下的编译产物结构清晰便于对照工程配置理解Qt Creator项目的组织方式。已有431人学习使用。源码围绕QMediaPlayer与QVideoWidget展开覆盖媒体加载、播放暂停/停止、进度控制、播放列表管理以及信号与槽的事件通信。通过阅读mainwindow与自定义视频控件代码还可了解界面布局、资源引用和事件处理等实用技巧对后续开发跨平台多媒体应用或扩展播放器功能有直接参考价值。1. 拆开 QT 视频播放器源码.zip它到底能替你解决什么问题拿到这个 QT视频播放器源码.zip先别急着双击 .pro 编译——你要先弄清楚它在什么 Qt 版本、什么编译器下能一遍过。这个源码包是一个基于 Qt Widgets QMediaPlayer 的桌面视频播放器完整工程解压后主窗口、控制栏、播放列表、信号槽连接都在里面核心播放能力交给 QMediaPlayer界面用 QVideoWidget 显示。它能播本地文件也能播 m3u8 这类网络流地址。适合两类人刚学 Qt 想找一份能编译、能改的播放器工程照着写的新手以及要在内部工具里快速塞一个视频预览模块、又不想从零搭这套播放逻辑的工程师。这篇笔记把编译、播放逻辑和五个最常见的坑都拆开讲你照着整理一遍就具备把它接进自己项目的能力了。2. 解压之后看到什么模块划分与多媒体选型逻辑2.1 文件结构每个文件是干什么的我拿到源码第一件事不是双击运行而是先做目录清点。这个源码包解压后主体代码基本是这个布局QTPlayer/ ├── QTPlayer.pro # qmake 工程文件 ├── main.cpp # 程序入口 ├── playerwindow.h/cpp # 主窗口控制栏、进度条、音量、播放列表 ├── playerwindow.ui # 界面布局 ├── playlistwidget.h/cpp # 播放列表控件 ├── videowidget.h/cpp # 视频显示控件基于 QVideoWidget 扩展 └── resources/ └── icons.qrc # 图标资源每个文件在工程里的角色是这样的文件职责谁依赖它QTPlayer.pro声明 Qt 模块、源文件、C 标准、图标编译系统main.cpp创建 QApplication设置高分屏属性加载主窗口Qt 框架playerwindow.h/cpp持有 QMediaPlayer、QMediaPlaylist 和全部控制栏控件播放核心playerwindow.ui界面布局按钮、滑块、标签的位置Qt Designerplaylistwidget.h/cpp维护 QList 双击列表项切歌playerwindowvideowidget.h/cpp继承 QVideoWidget预留 paintEvent 扩展点playerwindowresources/icons.qrc把播放、暂停、停止图标编进二进制资源编译系统playerwindow 是整个播放器的枢纽QMediaPlayer 负责解码和音频输出QMediaPlaylist 负责管理媒体列表QVideoWidget 负责视频上屏控制栏按钮通过信号槽把用户操作转成 QMediaPlayer 的调用。这个分层方式很常规但也有个隐藏优点如果你以后要把界面换成 QML播放核心可以原封不动搬走只换一层皮。2.2 为什么用 QMediaPlayer而不是 QtAV 或 FFmpeg做播放器源码主流路线有三条Qt 官方 QMediaPlayer、QtAV基于 FFmpeg 的封装库、自己集成 FFmpeg 写解码和显示。这个源码选的是官方方案理由很务实QMediaPlayer 在不同系统上底层解码器不同。Windows 上走 WMFWindows Media FoundationLinux 上走 GStreamermacOS 上走 AVFoundation。也就是说解码能力不全在源码里而是吃系统组件。好处是工程体积小、API 稳定、信号槽和 Qt 事件循环天然配合坏处是某些冷门格式能不能播取决于用户系统里有没有对应的解码插件。典型例子在 Ubuntu 上搭建 Qt 开发环境时只装 qtmultimedia5-dev 不够还得装 gstreamer1.0-plugins-good 才能正常放 mp4。这不是源码的锅是 QMediaPlayer 的架构决定的。对比之下QtAV 内部集成 FFmpeg支持的封装格式和编码格式要广得多但代价是工程维护活跃度不稳定官方编译包也少基本得自己跑一遍依赖。而直接调 FFmpeg 自绘最可控但要自己写音频输出、音视频同步、时钟基准这个工作量够单独开一个项目了。还有一类网常见的 v8 系播放器走的是嵌入式浏览器内核的渲染管线和 Qt Widgets 桌面控件不是一个技术栈做内部工具集成时我一般不考虑。这个源码选 QMediaPlayer 是合理的。它没用 mvvm 那套框架但 playerwindow 把界面层和播放逻辑分得还算开你后续想往 MVVM 方向重构底子不差。选型这件事别上来就追求解码能力最强先问你自己的需求里有没有冷门容器格式没有就用官方方案把精力留给后面的坑。2.3 工程文件里的门道.pro 的关键几行打开 QTPlayer.pro前几行决定了编译能不能过QT core gui widgets multimedia multimediawidgets TARGET QTPlayer TEMPLATE app CONFIG c17 DEFINES QT_DEPRECATED_WARNINGS SOURCES \ main.cpp \ playerwindow.cpp \ playlistwidget.cpp \ videowidget.cpp HEADERS \ playerwindow.h \ playlistwidget.h \ videowidget.h FORMS \ playerwindow.ui RESOURCES \ resources/icons.qrc win32: RC_ICONS resources/player.ico逐行看几个容易踩的地方。QT multimediawidgets是必须的很多播放器源码卡在编译期报 unknown module multimediawidgets就是因为只加了 multimedia没加 multimediawidgets而 QVideoWidget 在 multimediawidgets 模块里。CONFIG c17在 Qt 5.15 下没毛病但如果你的 kit 里编译器是老 MinGW可能要降回 c11。RC_ICONS只在 Windows 生效作用是把图标写进生成的可执行文件Linux/macOS 下这行会被忽略。如果你打算把这套源码用 CMake 组织对应的 find_package 也要写全find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core Gui Widgets Multimedia MultimediaWidgets) find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Gui Widgets Multimedia MultimediaWidgets)CMake 里缺了这个 Components 列表里的MultimediaWidgets编译到 QVideoWidget 那行照样报错而且错误信息往往不直接说缺模块而是说找不到某个 Qt 头文件很容易误导你去查 include 路径。资源和图标部分qrc 文件编译时会把图标二进制嵌入到可执行文件里所以部署时不用在程序目录外单独放 icons 文件夹这个设计对分发非常友好。3. 把源码跑起来环境匹配与编译排错3.1 版本选型Qt 5.15.2 MSVC2019 还是 MinGW读一个播放器源码先看它依赖的 Qt 版本。这个源码按常见目录结构看是 Qt 5.15.2 的工程走的是 msvc2019_64 那套 include 路径习惯。Qt 5.15.2 是离线安装包时代一个非常主流的版本之后 Qt 官方把开源发行版改成在线安装器想要老版本得从镜像站拿 install 脚本自己去拉。编译器的选择直接影响你后面能不能省时间记住一个原则Qt 的 mkspec 和编译器必须配套。MSVC 编译的 Qt 库不能拿去给 MinGW 的工程链接反过来也一样。两套工具链的 ABI 不兼容混用大概率会报一大堆unresolved external symbol或unknown type name的诡异错误。组合适用场景注意点Qt 5.15.2 MSVC2019 64bitWindows 10/11 主流的组合需要先装 Visual Studio 2019 或 2022 并装好 MSVC 组件Qt 5.15.2 MinGW 8.1 64bit不想装 VS只用 Qt CreatorMinGW 位数和 Qt 安装包的位数必须一致Qt 5.15.2 Linux/GStreamerUbuntu 等发行版缺 gstreamer 插件会导致有声音没画面用 VS2022 配 Qt 5.15.2 的人也不少做法是装 Qt VS Tools 扩展然后在扩展设置里指向 Qt 的安装目录。注意调试器要选 CDB对应 MSVC而不是 GDB不然断点打不进去排查 qt 崩溃时很难定位。3.2 从打开到跑通的四个动作在 Qt Creator 里的操作链路是这样的菜单 File → Open File or Project选中解压目录下的 QTPlayer.pro。Qt Creator 弹 Configure Project 对话框勾选 Desktop Qt 5.15.2 MSVC2019 64bit 这个 kit。点左下角绿色的运行按钮它会先编译再启动。如果编译报错先看是不是第 2 章说的模块缺失问题。命令行党也可以不依赖 Creator直接手动编mkdir build cd build qmake ../QTPlayer.pro -spec win32-msvc nmake这段命令里-spec win32-msvc明确告诉 qmake 用 MSVC 的 mkspec如果你在 Qt 的 MSVC 命令行环境里跑也可以不指定 spec。这里最关键的坑是qmake必须来自你打算用的那套 Qt 目录比如D:\Qt\5.15.2\msvc2019_64\bin\qmake.exe不能拿系统 Path 里混着的旧版本去冒泡否则生成 Makefile 里全是错误路径。编译通过之后部署时别忘了 windeployqt。命令行这样用windeployqt build\release\QTPlayer.exe它会自动把 Qt 的 DLL、插件目录、qrc 资源生成的东西复制到 exe 旁边。很多新手把 exe 拷到别的电脑上发现双击没反应十有八九是没跑这一步依赖的 Qt 运行库没带上。3.3 那个 dependent 路径找不到的经典报错检索数据里出现过的这个报错长这样:-1: error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets\qwidget.h does not exist.现象是编译任何文件都失败而且错误指向的是 Qt 安装目录里某个头文件。原因往往有三个按概率从高到低一是工程文件被移动过。源码从别人电脑里拷出来之后目录结构变了但 .pro 或 .pri 里用了类似INCLUDEPATH ../../..这种相对路径而相对层级是按原来那台机器的路径深度写的换到你的机器上就指错位置了。二是 .user 文件带过来的残留配置。Qt Creator 打开工程后会在旁边生成工程名.pro.user文件记录 kit 路径、构建目录、环境变量。如果这份源码的 .user 文件指向的是原作者机器上的 Qt 路径就会和当前环境对不上。三是 qmake 的 mkspec 里 cache 路径过期这种情况多见于频繁切换 kit 的环境。解决思路按优先级来。先打开 .pro搜索INCLUDEPATH、LIBS里有没有写死绝对路径的一律改成以$$PWD开头的相对路径然后删除工程目录下的.user文件和 build 目录重新用 Qt Creator 打开配置一次最后在 Tools → Options → Kits → Qt Versions 里确认当前用的 Qt 路径确实存在且与你选择的 kit 匹配。提示我自己的习惯是强制用 out-of-source 构建也就是 build 目录放在工程目录之外。这样 qmake 生成中间文件时不会污染源码目录换机器、换路径时路径问题少一半。4. 播放器核心逻辑拆解信号槽、进度条与控制栏4.1 播放、暂停与停止的信号槽链路播放器核心逻辑在 playerwindow 的构造函数里完成最关键的三行是player new QMediaPlayer(this); playlist new QMediaPlaylist(this); videoWidget new VideoWidget(this); player-setPlaylist(playlist); player-setVideoOutput(videoWidget); // 没有这行只有声音没有画面QMediaPlayer 是状态机式的对象它有stateChanged、positionChanged、durationChanged、error这几个信号控制栏按钮只需要把用户动作翻译成对 player 的调用即可。暂停和恢复的逻辑通常在同一个槽函数里void PlayerWindow::togglePlay() { if (player-state() QMediaPlayer::PlayingState) { player-pause(); } else { player-play(); } }这个函数的逻辑很直白处于播放态就暂停否则就恢复播放。按钮的图标最好也在这个槽函数里同步切换用stateChanged信号去驱动而不是在点击时直接改这样点击之外的状态变化比如播放完自动停止也能把图标更新回来。另外一定要连error信号这是排查黑匣子问题的救星connect(player, QOverloadQMediaPlayer::Error::of(QMediaPlayer::error), this, PlayerWindow::onPlayerError);QMediaPlayer::Error枚举值包含ResourceError、FormatError等拿到具体错误码再查系统解码器比对着黑屏瞎猜靠谱得多。音频输出其实不需要额外设置QMediaPlayer 会走系统默认音频设备但如果你要做多路输出控制setAudioOutput在 Qt 5.15 里已经可以指定 QAudioOutput 了。4.2 进度条与音量滑块驱动方式别写错进度条是播放器最容易翻车的地方。常见的错误想法是用 QTimer 定时轮询position()再 setValue结果就是进度条每秒跳好几下、卡顿、和视频画面不同步。正确做法是用positionChanged信号驱动频率已经足够了connect(player, QMediaPlayer::durationChanged, this, [this](qint64 d) { slider-setRange(0, int(d)); }); connect(player, QMediaPlayer::positionChanged, this, [this](qint64 pos) { if (!slider-isSliderDown()) { // 用户正在拖动时不刷新 slider-setValue(int(pos)); } }); connect(slider, QSlider::sliderMoved, player, QMediaPlayer::setPosition);positionChanged的触发间隔大概 100ms 左右对进度条来说足够平滑。isSliderDown()判断是防止“拖动时被信号回写”的关键不然滑块会一边拖一边被 positionChanged 拉回去这就是进度条拖动时“打架”的直接原因。sliderMoved负责把用户拖拽的目标位置传给 QMediaPlayer注意sliderMoved和valueChanged的区别前者只在用户交互时触发后者在代码 setValue 时也会触发。如果用 valueChanged 去 setPosition会形成“设值 → seek → 位置变化 → 再设值”的循环。时间标签的格式化可以单独写个函数QString PlayerWindow::formatTime(qint64 ms) { qint64 sec ms / 1000; return QString(%1:%2) .arg(sec / 60, 2, 10, QLatin1Char(0)) .arg(sec % 60, 2, 10, QLatin1Char(0)); }音量滑块更简单范围设 0 到 100直接连setVolume。唯一要注意的是 QSlider 的默认方向是水平的如果你用垂直滑块记得setOrientation(Qt::Vertical)否则外观会不对。4.3 播放列表与网络流的接入点播放列表这一块源码里常见的实现是让 PlaylistWidget 内部持有一个 QMediaPlaylist同时维护一个 QListWidget 做显示。void PlaylistWidget::addFiles(const QStringList paths) { for (const QString path : paths) { QUrl url QUrl::fromLocalFile(QFileInfo(path).absoluteFilePath()); playlist-addMedia(url); QListWidgetItem *item new QListWidgetItem(QFileInfo(path).fileName()); addItem(item); } }QUrl::fromLocalFile不是可选项是必须项。直接把C:/Movies/test.mp4这类字符串塞给addMediaQt 会把它当成一个协议不明的 URL播放直接失败。QFileInfo(path).fileName()用来取纯文件名避免列表里显示一长串路径。双击切换和删除当前项的逻辑也在这里:connect(this, QListWidget::itemDoubleClicked, this, [this](QListWidgetItem *item) { int row row(item); playlist-setCurrentIndex(row); player-play(); });网络流的接法和本地文件不同不是fromLocalFile而是直接构造 URLQUrl streamUrl(http://example.com/live/index.m3u8); playlist-addMedia(streamUrl);QMediaPlayer 能不能播 m3u8取决于底层 WMF 或 GStreamer 的解封装器有没有相关插件。Windows 上一般可以某些精简版系统或特殊网络环境里可能会报错这是一层你控制不了的系统差异源码本身写的逻辑没有错。5. 避坑排查五个你多半会遇到的编译与运行现场5.1 dependent 路径找不到编译期现象编译一开始就报dependent ...\qt\5.15.2\msvc2019_64\include\qtwidgets\qwidget.h does not exist每个文件都失败。原因工程被移动过.pro 里的相对路径层级还是原作者机器上的深度或者 .user 文件带了过期的 Qt 路径配置。这是源码包类项目最典型的问题编辑器路径残留直接把整个编译挡住。解决删掉工程目录下的.user文件搜索 .pro 里的INCLUDEPATH把写死的绝对路径改成$$PWD开头的相对路径然后清空 build 目录重新 qmake。改完之后我会强制 out-of-source 构建以后换目录再没出过这个问题。5.2 播放黑屏但有声音运行期现象视频文件能正常出声进度条也在走但视频区域是灰的画面死活不出来。原因最常见的是setVideoOutput(videoWidget)没有被调用或者调用顺序不对。其次是个别显卡驱动下 QVideoWidget 的 overlay 渲染失败那属于玄学范畴重装显卡驱动能解决但概率很低。解决先在代码里 grepsetVideoOutput八成是自己在初始化时漏了。给 videoWidget 设一个最小尺寸比如setMinimumSize(320, 180)防止窗口还没布局完时尺寸为 0。最后试试在窗口显示后手动resize一下强制触发重新渲染。5.3 中文路径或中文文件名播放失败现象英文路径的文件全正常换成“测试视频.mp4”就没画面有的机器上甚至会 qt 崩溃闪退。原因直接拿原始字符串拼 URL 时中文编码在 Windows 的本地代码页下被搞乱了。QUrl::fromLocalFile本身能处理中文但如果你在代码里写了QUrl(file:/// path)这种手拼方式路径里的中文或空格都会出问题。解决全部统一走QUrl::fromLocalFile(QFileInfo(path).absoluteFilePath())不要手拼file:///前缀。另外检查文件是否真的存在用QFileInfo::exists()做个前置校验把排查范围缩小到编码之外。5.4 进度条拖不动一松手就回弹现象按住滑块拖动时滑块抖得厉害或者拖不动松手后进度条跳回原来的位置。原因positionChanged信号在拖动期间也在触发如果代码里没有isSliderDown()判断setValue 会反复覆盖拉动的目标位置或者根本没用sliderMoved只用了sliderReleased导致拖动过程中没有实时 seek。这也是播放器源码里最容易改坏的一处改了就像进度条在抽筋。解决按第 4 章 4.2 的写法slider 的刷新加isSliderDown()保护拖拽信号连sliderMoved松手后由 positionChanged 自然对齐。这样拖动过程中不会被回写松手后 seek 到目标位置一切正常。5.5 高 DPI 下界面错位个别机器闪退现象Windows 高分屏125%、150% 缩放上按钮挤在一起播放区域错位有的机器启动直接崩。原因Qt 5 默认不做高分屏缩放需要应用主动声明。如果 main.cpp 里没有在创建 QApplication 之前设置Qt::AA_EnableHighDpiScalingQt 就会按物理像素布局界面在高 DPI 下乱掉。解决main.cpp 的 main 函数第一行加QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);注意顺序必须在QApplication构造之前。如果你以后迁移到 Qt 6这两行是反效果因为 Qt 6 默认就开了别再重复设置否则会得到两倍缩放的界面。6. 进阶封装把播放器抽成可复用的 PlayerWidget6.1 给它加上截图能力Qt 5 的 QMediaPlayer 没有内置截图接口最稳的实现是直接抓 QVideoWidget 的显示内容bool PlayerWindow::saveSnapshot(const QString dir) { if (!videoWidget) return false; QPixmap frame videoWidget-grab(); QString name QDateTime::currentDateTime().toString(yyyyMMdd_hhmmss) .png; return frame.save(dir / name); }grab 是 QWidget 自带的方法会把当前控件可见内容渲染成 QPixmap性能足够应付单张截图。如果你要连续抓帧做检测就得动底层 QAbstractVideoSurface 拿 QVideoFrame那会牵扯到播放线程的内存管理新手不建议直接改。6.2 把它接进自己项目的三个衔接点播放器能不能复用到别的工程就看三个对象player、playlist、videoWidget。抽模块时只保留这三个和它们的信号连接把 playerwindow 的界面部分整个丢掉。这样你的工程只需要 player_widget 和 videowidget 两个类不依赖原来的 main.cpp。如果你要跟图像算法联动比如 qt 调用 halcon 做实时识别把检测结果画在视频帧上重点在 videowidget 的 paintEvent 里做叠加绘制不要阻塞播放线程。halcon 在独立线程里跑结果通过信号抛回主线程在 paintEvent 里用 QPainter 画矩形和文字播放器本身不动。如果你下一步打算上 qt vue3 这类混合方案这个播放器可以通过 QQuickWidget 嵌进 QML 界面把播放状态用信号转发给 QML内部逻辑和界面分层都还够用。6.3 补一条 m3u8 直播流的常用配置playlist-setPlaybackMode(QMediaPlaylist::Loop); player-setMedia(QUrl(http://example.com/live/index.m3u8)); player-setVolume(80); player-play();Loop模式用于直播流的循环重连点播场景用CurrentItemOnce更合适。m3u8 能不能播仍然取决于系统解码器Windows 上一般没问题Linux 上记得装 gstreamer 的 hls 插件。从那以后我每次拿到播放器源码都先花十分钟把 .pro 的模块依赖、编译器 kit、系统解码器插件这三件事列清楚再动手编译省下的都是玄学报错的时间。希望帮到你。本文还有配套的精品资源点击获取