# ffmpeg_player

**Repository Path**: uthelei/ffmpeg_player

## Basic Information

- **Project Name**: ffmpeg_player
- **Description**: No description available
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# FFmpeg Player

基于 Qt 5.15.2 Widgets + FFmpeg + QtMultimedia 的桌面音视频播放器。

## 项目简介

FFmpeg Player 是一个功能完善的本地媒体播放器，专为 Windows/Linux/macOS 桌面环境设计。播放器采用 Qt Widgets 作为 UI 框架，FFmpeg 作为解码引擎，结合 QtMultimedia 实现高质量音频输出，具备良好的跨平台兼容性和稳定性。

## 核心功能

### 媒体导入与播放
- 支持打开本地视频/音频文件
- 拖拽文件到窗口即可播放
- 自动记录最近播放列表
- 支持常见媒体格式（MP4、MKV、AVI、MOV、MP3 等）

### 播放控制
- 播放/暂停/停止操作
- 进度条拖动（Seek）功能
- 快进/快退调节
- 音量控制与静音切换
- 支持多种倍速播放（0.5x - 2.0x）
- 全屏模式与退出

### 播放列表
- 完整的播放列表管理
- 支持添加/移除/清空文件
- 多种播放模式（顺序播放、循环播放等）
- 列表去重功能

### 字幕支持
- 外挂 SRT 字幕加载
- 字幕显示/隐藏切换
- 字幕时间偏移调节
- 内嵌字幕流切换

### 实用功能
- 视频截图（支持自定义保存目录和格式）
- 记忆播放位置（下次打开自动续播）
- 完善的快捷键支持
- 设置中心（可配置截图、字幕、播放行为等）

## 技术架构

### 模块划分
- **PlayerCore**: 播放器核心状态机，对外提供统一 API
- **FFmpegPlayerBackend**: FFmpeg 解码后端，处理解复用、音视频解码
- **Clock**: 音频时钟实现，负责音画同步
- **SubtitleEngine**: 字幕解析引擎，支持 SRT 格式
- **HistoryStore / SettingsStore**: 数据持久化模块
- **MainWindow**: 主窗口 UI
- **VideoWidget**: 视频渲染与字幕绘制组件
- **PreferencesDialog**: 设置对话框

### 线程模型
- 主线程：UI 渲染与用户交互
- 解复用线程：读取媒体文件并分发数据包
- 音频线程：音频解码与输出
- 视频线程：视频解码与帧投递
- 字幕线程：字幕解析与同步

### 音画同步
- 采用音频时钟作为同步基准
- 基于 PTS 的帧调度策略
- 视频帧按需渲染，异步处理

## 环境要求

- **Qt**: 5.15.2 或更高版本
- **FFmpeg**: 4.x 或 5.x（项目内置兼容层）
- **C++**: 17 标准
- **CMake**: 3.16 或更高版本
- **操作系统**: Windows 10+/Linux/macOS 10.15+

## 编译构建

```bash
# 创建构建目录
mkdir build && cd build

# 配置项目
cmake .. -DCMAKE_BUILD_TYPE=Release

# 编译
cmake --build . -j$(nproc)

# 安装（可选）
cmake --install .
```

## 目录结构

```
ffmpeg_player/
├── CMakeLists.txt          # CMake 构建配置
├── LICENSE                  # 开源许可证
├── README.md               # 项目说明文档
├── PRD-xxx.md              # 产品需求文档
├── SDD-xxx.md              # 详细设计文档
└── src/
    ├── main.cpp            # 程序入口
    ├── player/
    │   ├── Clock.cpp/h     # 时钟模块
    │   ├── HistoryStore.*  # 历史记录存储
    │   ├── PlayerCore.*    # 播放器核心
    │   ├── PlayerTypes.h   # 类型定义
    │   ├── SettingsStore.* # 设置存储
    │   └── ffmpeg/
    │       ├── FFmpegCompat.h      # FFmpeg 兼容层
    │       ├── FFmpegPlayerBackend.*  # FFmpeg 后端实现
    │       └── PacketQueue.*       # 数据包队列
    ├── subtitle/
    │   ├── SubtitleEngine.* # 字幕引擎
    └── ui/
        ├── MainWindow.*      # 主窗口
        ├── PreferencesDialog.* # 设置对话框
        └── VideoWidget.*     # 视频渲染组件
```

## 使用说明

### 打开媒体文件
- 点击菜单 `File -> Open` 或使用快捷键 `Ctrl+O`
- 直接将文件拖入播放器窗口
- 从最近播放列表中选择

### 基本操作
| 操作 | 快捷键 |
|------|--------|
| 播放/暂停 | `Space` |
| 停止 | `S` |
| 快进 | `→` |
| 快退 | `←` |
| 全屏 | `F` |
| 截图 | `P` |
| 打开字幕 | `Ctrl+L` |

### 播放列表
- 右键点击播放列表可打开上下文菜单
- 支持移除选中项、清空列表、打开文件所在文件夹
- 双击列表项可直接播放

### 设置
- 通过 `Edit -> Preferences` 打开设置中心
- 可配置截图保存路径、格式、字幕字体大小
- 记忆播放与恢复播放列表选项

## 配置选项

在设置对话框中可调整以下选项：

| 选项 | 说明 | 默认值 |
|------|------|--------|
| 截图目录 | 保存截图的文件夹 | 当前工作目录 |
| 截图格式 | 截图文件格式 (png/jpg) | png |
| 字幕字号 | 字幕文字大小 | 16pt |
| 记忆播放 | 退出后记住播放位置 | 开启 |
| 恢复播放列表 | 启动时恢复上次列表 | 关闭 |
| 历史记录上限 | 最近播放列表最大项数 | 20 |

## 扩展与二次开发

项目采用模块化设计，便于扩展：

1. **后端扩展**: 可实现 `IPlayerBackend` 接口支持其他解码方案
2. **字幕格式**: 在 `SubtitleEngine` 中添加新格式解析器
3. **UI 主题**: 通过 Qt 样式表自定义界面风格

## 许可证

本项目采用 MIT License 开源协议。

## 贡献指南

欢迎提交 Issue 和 Pull Request。贡献前请确保：

- 代码遵循项目编码风格
- 新功能附带测试用例
- 文档同步更新

## 联系方式

- 项目地址: https://gitee.com/uthelei/ffmpeg_player
- 问题反馈: 请在 Gitee Issue 中提交