# XPlayer

**Repository Path**: lj16888/xplayer

## Basic Information

- **Project Name**: XPlayer
- **Description**: 基于ffmpeg + QT + OpenGL的视频播放器
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 4
- **Created**: 2024-02-21
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ffmpeg, Opengl, Qt

## README

# XPlayer

#### 介绍
基于 FFmpeg 3.4 + Qt 5.15 + OpenGL 的视频播放器。

支持本地视频文件播放，使用 FFmpeg 进行解复用和解码，Qt 5 的 QAudioOutput 进行音频输出，QOpenGLWidget + GLSL 着色器实现 YUV→RGB 硬件加速渲染。

#### 软件架构

```
XPlay2/                    # 源代码目录
├── main.cpp               # 程序入口
├── XPlay2.cpp/h           # 主窗口
├── XPlay2.ui              # Qt Designer 界面
├── XDemux.cpp/h           # 解复用模块 (avformat)
├── XDecodec.cpp/h         # 解码模块 (avcodec Send/Recv)
├── XReSample.cpp/h        # 音频重采样模块 (swresample)
├── XAudioPlay.cpp/h       # 音频输出单例 (QAudioOutput)
├── XAudioThread.cpp/h     # 音频解码播放线程
├── XVideoThread.cpp/h     # 视频解码渲染线程
├── XVideoWidget.cpp/h     # OpenGL 视频渲染控件
├── XDemuxThread.cpp/h     # 解复用主控线程
├── IVideoCall.cpp/h       # 视频渲染回调接口
├── 002.mp4                # 测试视频文件
include/                   # FFmpeg 3.4 头文件
lib/win32, lib/win64/      # FFmpeg 导入库
bin/win32, bin/win64/      # FFmpeg DLL 运行时库
CMakeLists.txt             # CMake 构建配置
```

#### 构建教程 (Windows)

##### 前置条件

| 依赖 | 版本 | 说明 |
|------|------|------|
| Visual Studio 2022 | 17.x | 安装时勾选「使用 C++ 的桌面开发」工作负载 |
| CMake | ≥ 3.16 | 可通过 `winget install CMake` 或官网下载 |
| Qt 5.15.x | 5.15.2+ | 推荐 msvc2019_64 或 msvc2022_64 版本 |
| FFmpeg 3.4 | 3.4.x | **已捆绑在项目中**，无需额外安装 |

##### 快速构建

```bash
# 1. 打开「Developer Command Prompt for VS 2022」
#    或任何已配置好 MSVC 环境的终端

# 2. 进入项目目录
cd E:\pro\xplayer

# 3. CMake 配置（关键：指定 Qt5_DIR 指向你的 Qt 安装路径）
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build ^
      -DQt5_DIR="D:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5"

cmake -G "Visual Studio 17 2022" -A x64 -S . -B build -DQt5_DIR="D:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5"

# 4. 编译
cmake --build build --config Debug

# 5. 运行
cd build/bin/Debug && XPlay2.exe
```

> **注意**：`-DQt5_DIR` 参数必须根据你本机的 Qt 安装路径修改。
> 常见路径示例：
> - `D:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5`
> - `C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5`
> - `C:/Qt/Qt5.15.2/5.15.2/msvc2019_64/lib/cmake/Qt5`

##### 如果 CMake 找不到 Qt5

方法一：通过 `-DQt5_DIR` 显式指定（推荐）：
```bash
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build ^
      -DQt5_DIR="D:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5"
```

方法二：设置环境变量 `CMAKE_PREFIX_PATH`：
```bash
set CMAKE_PREFIX_PATH=D:/Qt/5.15.2/msvc2019_64
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build
```

方法三：将 Qt 的 `bin` 目录加入 PATH：
```bash
set PATH=D:/Qt/5.15.2/msvc2019_64/bin;%PATH%
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build
```

##### 清理重建

```bash
# 删除构建目录重新配置
rmdir /s /q build
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build ^
      -DQt5_DIR="D:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5"
cmake --build build --config Debug
```

#### 使用说明

1. 编译成功后运行 `XPlay2.exe`
2. 程序会自动加载同目录下的 `002.mp4` 测试视频
3. 视频通过 OpenGL 硬件加速渲染，音频通过 QAudioOutput 输出

#### 已知问题

详见 [`XPlay2/ANALYSIS_AND_LEARNING_ROADMAP.md`](XPlay2/ANALYSIS_AND_LEARNING_ROADMAP.md)

| 问题 | 位置 | 说明 |
|------|------|------|
| PTS 重复赋值 | [`XDemux.cpp:126-127`](XPlay2/XDemux.cpp:126) | 同一表达式赋值两次，第二行应为 `pkt->dts = ...` |
| 参数生命周期混乱 | [`XDecodec.cpp:33`](XPlay2/XDecodec.cpp:33) | Open() 内部释放了传入的 AVCodecParameters |
| 忙等待 CPU 空转 | 所有线程 run() | 使用 msleep(1) 轮询，应改为条件变量 |
| 无音视频同步 | 音频/视频线程独立运行 | 视频无 PTS 等待，直接渲染 |
| 中文注释乱码 | 所有 .cpp/.h | GBK 编码文件被 MSVC 以 UTF-8 编译 |

#### 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request