# ffmpeg-video

**Repository Path**: hackerc5/ffmpeg-video

## Basic Information

- **Project Name**: ffmpeg-video
- **Description**: 基于PyQt5+ MPV Player + FFmpeg 的可视化媒体浏览标记剪辑工具，可流畅播放H265视频
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 媒体浏览器 — Media Viewer


```
python -m PyInstaller build.spec --noconfirm --clean
```

基于 **Qt (PyQt5) + MPV Player + FFmpeg** 的可视化媒体浏览工具。

## 功能概览

| 功能 | 说明 |
|------|------|
| 左侧目录树 | 显示电脑磁盘目录树，点击即加载该目录下的媒体文件 |
| 右侧预览区 | 一次预览一个文件，支持图片和视频 |
| 播放控制 | 上一个 / 播放暂停 / 停止 / 下一个 / 删除当前文件 |
| 进度条 | 视频播放进度条，可任意拖动拖拽 |
| 键盘快捷键 | ← 上一个、→ 下一个、空格 播放/暂停、Delete 删除 |

## 支持的文件格式

- **图片**: jpg, jpeg, png, gif (含动画), bmp, webp, svg, tiff, ico
- **视频**: mp4, avi, mkv, mov, webm, flv, wmv, m4v, mpg, mpeg, ts, 3gp, vob

## 视频后端

本工具支持三种视频后端，自动选择最佳可用方案：

| 后端 | 来源 | 格式支持 | 安装要求 |
|------|------|----------|----------|
| **MPV libmpv** (最佳) | python-mpv + libmpv | 最全面 (MKV/FLV/WebM 等) | 需 mpv-2.dll |
| **MPV Subprocess** (推荐) | mpv.exe --wid + IPC | 最全面 (MKV/FLV/WebM 等) | 需 mpv.exe |
| **QMediaPlayer** (后备) | PyQt5 + Windows Media Foundation | 常见格式 (MP4/AVI/WMV) | 无需额外安装 |

启动时会自动检测可用后端：
1. 优先使用 **MPV libmpv**（如果系统中能找到 `mpv-2.dll`）
2. 否则使用 **MPV Subprocess**（如果系统中能找到 `mpv.exe`，如 `C:\Program Files\mpv\mpv.exe`）
3. 最后回退到 **QMediaPlayer**（PyQt5 自带，开箱即用）
4. 状态栏会显示当前使用的后端

## 环境要求

- **Python** 3.8 或更高版本
- **PyQt5** (含 QtMultimedia, 通常与 PyQt5 一起安装)
- **python-mpv** (可选，用于启用 MPV libmpv 后端)
- **MPV Player** (可选，用于获得最佳视频格式支持，支持 mpv.exe 模式)

## 安装步骤

### 方式一：直接运行（开箱即用）

```bash
# 安装 Python 依赖（PyQt5 自带 QtMultimedia，无需安装 MPV 即可播放视频）
pip install PyQt5
python main.py
```

✅ 这一步完成后图片浏览和常见视频格式（MP4/AVI/WMV）即可使用。

### 方式二：完整功能（推荐）

```bash
# 1. 安装 MPV 以获得最佳视频支持
winget install mpv

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3. 运行
python main.py
```

✅ 安装 MPV 后，工具会自动切换到 MPV 后端（优先尝试 libmpv，若不存在则自动使用 mpv.exe 子进程模式），支持 MKV/FLV/WebM 等更多格式。

## 运行

### 方式 A: 双击运行
双击 `run.bat` 文件，会自动检查依赖并启动。

### 方式 B: 命令行运行
```bash
python main.py
```

## 使用说明

1. 启动后，左侧显示磁盘目录树
2. 展开并点击任意目录，右侧自动加载该目录下的图片和视频
3. 使用底部控制栏进行导航和播放控制
4. 拖动进度条可跳转到视频任意位置
5. 按 Delete 键或点击"删除"按钮可删除当前文件（会弹出确认对话框）

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `←` | 上一个文件 |
| `→` | 下一个文件 |
| `空格` | 播放 / 暂停 |
| `Delete` | 删除当前文件 |

## 技术架构

```
┌─────────────────────────────────────────────────┐
│                  MediaViewerApp                  │
│                   (QMainWindow)                  │
├──────────────┬──────────────────────────────────┤
│              │                                    │
│ DirectoryTree│         PreviewPanel               │
│   Panel      │     ┌──────────────────┐           │
│ (QTreeView)  │     │  QStackedWidget   │           │
│              │     │  ┌─ Image Label   │           │
│  磁盘目录树   │     │  └─ Video Player  │           │
│              │     │    ├─ MPV libmpv │           │
│              │     │    ├─ MPV Subproc │           │
│              │     │    └─ QMediaPlayer│          │
│              │     └──────────────────┘           │
│              │     ┌──────────────────┐           │
│              │     │   控制栏          │           │
│              │     │  ◄  ▶  ■  ►  ═══  删除 │      │
│              │     └──────────────────┘           │
└──────────────┴──────────────────────────────────┘

技术栈:
  - PyQt5: UI 框架 (目录树、按钮、进度条等)
  - MPV (libmpv / mpv.exe): 视频播放引擎, 基于 FFmpeg, 格式支持最全面
  - QMediaPlayer: 视频后备引擎 (PyQt5 内置, Windows Media Foundation)
  - FFmpeg: 媒体解码 (MPV 内部使用, 也是整个工具的视频处理基础)
```

## 常见问题

### Q: 启动后提示 "无视频后端" 或 "视频播放不可用"
可能未安装 PyQt5 或 QtMultimedia 不可用。请尝试：
```bash
pip install PyQt5 --upgrade
```

### Q: 启动后使用 QMediaPlayer 后端，如何切换到 MPV
安装 MPV 后重启本程序即可自动切换：
```bash
winget install mpv
```
程序会同时检测 `mpv-2.dll` 和 `mpv.exe`。如果只有 `mpv.exe`（如 `C:\Program Files\mpv\mpv.exe`），会自动使用 mpv.exe 子进程模式，同样支持所有 MPV 格式。

### Q: 已安装 MPV 但程序仍使用 QMediaPlayer
请检查 MPV 是否安装到了以下常见位置之一，或是否加入了系统 PATH：
- `C:\Program Files\mpv\mpv.exe`
- `C:\Program Files (x86)\mpv\mpv.exe`
- 通过 Scoop/WinGet 安装的路径
- 系统 PATH 中的 `mpv.exe`

如果 MPV 在其他位置，可以将其路径加入系统 PATH，或把 `mpv.exe` 复制到本程序目录。

### Q: 某些视频格式无法播放（QMediaPlayer 后端）
QMediaPlayer 基于 Windows Media Foundation，对 MKV/FLV/WebM 等格式支持有限。
请安装 MPV 以获得完整格式支持。

### Q: 视频播放没有声音
检查系统音量设置。QMediaPlayer/MPV 默认使用系统音频输出。

### Q: 删除文件后可以恢复吗
删除操作使用 `os.remove` 直接删除文件，不可恢复。删除前会弹出确认对话框，请谨慎操作。

## 项目结构

```
ffmpeg-video/
├── main.py           # 主程序 (全部代码)
├── requirements.txt  # Python 依赖
├── run.bat           # Windows 一键运行脚本
└── README.md         # 说明文档
```