跳转至

QML-FFmpeg 项目介绍与技术架构

🔗 GitLab 仓库链接：Utilities/QML-FFmpeg

QML-FFmpeg 是一个高性能、多线程的视频播放器解决方案，基于 Qt Quick/QML、FFmpeg 和 SDL2 开发。项目致力于从传统的 OpenGL/FBO 离屏渲染平滑迁移至现代的 Qt Quick Scene Graph / RHI (Rendering Hardware Interface) 兼容 渲染路径，摆脱对特定图形底层的强绑定，提供跨平台的硬件加速播放能力。

🌟 核心特性

  1. RHI 兼容的 Scene Graph 渲染
  2. 摒弃了过时的 QQuickFramebufferObject，改用 Qt Quick Scene Graph 节点渲染视频帧，与 Qt6 的 RHI 渲染架构完美兼容。
  3. 多线程解耦流水线
  4. 采用多线程架构，将视频解复用（Demux）、视频解码（Decode）与音频播放（Audio Playback）完全解耦到独立线程中，保证界面的极速响应与播放的平滑顺畅。
  5. 以 SDL2 音频播放为主时钟（Master Clock）进行音视频同步（AV Sync），提供稳定的播放同步体验。
  6. 三级平滑硬件加速回退机制 (HWA Fallback)
  7. Stage 1 (零拷贝 GPU 渲染)：基于 Direct3D11 / VA-API 零拷贝渲染，直接映射 GPU 纹理。
  8. Stage 2 (GPU->CPU 拷贝渲染)：使用 av_hwframe_transfer_data() 将 NV12 等硬件解码帧拷贝回主存，经过高性能色彩空间转换后提交给 Scene Graph 绘制。已解决硬解帧池死锁与 avfilter 过滤问题。
  9. Stage 3 (纯 CPU 软件解码)：当硬件加速初始化或传输连续失败时，自动在 5 帧内无感重载并平滑降级为 CPU 软解（如 YUV420P），保障播放不中断。
  10. 双集成架构设计
  11. 既支持以独立应用程序直接内联编译播放器核心，也支持将其编译为独立的 QML 扩展插件 动态注入。
  12. 开箱即用部署与验证
  13. 内置 CMake 构建预设与自动化脚本，在 Windows 构建后自动拷贝所需的 FFmpeg/SDL2 DLL 库与测试视频；在 Linux (Ubuntu) 环境中同样具备高度的便携部署支持。

📁 模块架构

QML-FFmpeg (项目根目录)
 ├── QML-FFmpeg.pro         # 主子目录工程文件 (Qt Creator 直接打开)
 ├── docs/                  # 软硬件验证清单与技术设计方案
 ├── QMLVideoPlayer-OpenGL/  # 【独立应用模式】静态编译播放器核心与 QML HUD
 ├── VideoPlugin-OpenGL/    # 【QML 插件模块】编译为动态加载 of C++ 插件，内置着色器资源
 ├── Video-QML/             # 【插件测试外壳】动态导入 VideoPlugin 1.0 的纯 QML 测试应用
 └── ThirdParty/            # 【三方依赖库】包含 FFmpeg & SDL2 的预编译二进制 SDK (Git LFS)

📊 平台验证状态

根据上游 platform_hwa_checklist.md，目前项目的验证情况如下：

  • Windows (NVIDIA 物理机)：Stage 2 (GPU->CPU NV12) 拷贝渲染及 Stage 3 软解已全部通过验证，具备极佳的稳定性和故障容灾能力；D3D11 零拷贝处于待闭环状态。
  • Linux (Ubuntu 虚拟机)：由于无 GPU 直通，VA-API 硬解不可用，程序成功自动触发 Stage 3 纯软解回退，播放及控制界面运转正常。
  • ARM / 嵌入式平台：计划引入瑞芯微 MPP 及树莓派 V4L2 M2M 硬件解码，并实现 DRM / GLES 零拷贝渲染。

REF

[1]. about/index.md

[2]. platform_hwa_checklist.md