# Python 视频播放器

**Repository Path**: deepin20/python-video-player

## Basic Information

- **Project Name**: Python 视频播放器
- **Description**: Python 视频播放器（python-video-player）：基于 **OpenCV + Tkinter** 的轻量桌面视频播放器。
开发者helloworldp仓库地址：https://gitee.com/helloworldpxy/python-video-player
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# python-video-player

基于 **OpenCV + Tkinter** 的轻量桌面视频播放器（v1.1）。

helloworldp仓库地址：https://gitee.com/helloworldpxy/python-video-player

![icon](assets/icons/icon_256.png)

## 功能特性

- 🎬 基础播放：播放 / 暂停 / 停止 / 逐帧驱动，进度条任意拖动，←/→ 快进快退 5 秒
- 🔊 音频支持：基于 [ffpyplayer](https://pypi.org/project/ffpyplayer/)（可选依赖），未安装时自动降级为静音画面播放，音量调节 / 静音
- 📃 播放列表：多选添加、去重、双击切换、自动连播、上一/下一个（到头回绕）、单曲循环
- 🖥 画面适配：默认等比缩放铺满画布（**小视频自动放大**），可一键切回原始尺寸
- ⏩ 倍速播放：0.5x ~ 2.0x 下拉选择
- 🌙 暗色主题界面：自绘进度条、时间显示（`mm:ss / mm:ss`）、扁平化控件
- 🖼 软件图标：深蓝渐变播放三角（assets 下多尺寸 PNG，缺失时运行时自动生成）
- ⌨️ 完整快捷键、F11 全屏、窗口置顶、右键菜单

## 快速开始

### 方式一：一键脚本（UOS / Debian 推荐）

```bash
./run.sh
```

脚本会自动：创建虚拟环境 → 安装依赖（清华镜像）→ 检查系统库 → 启动。

### 方式二：手动运行

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt            # 必需：opencv-python、Pillow
pip install -r requirements-audio.txt      # 可选：音频支持
python python-video-player.py              # 或 python -m pvp
```

### 方式三：Debian 包安装（UOS / Deepin / Debian）

```bash
# 安装：源码装到 /opt/python-video-player，附桌面入口、图标、man 手册
sudo apt install ./dist/python-video-player_1.1.1-1_all.deb

# 从应用菜单启动，或命令行（支持直接打开视频文件）：
python-video-player
python-video-player 视频1.mp4 视频2.mp4

# 卸载
sudo apt remove python-video-player
```

依赖由 apt 自动处理（`python3-tk` / `python3-opencv` / `python3-pil`）。
可选音频：`python3 -m pip install --user ffpyplayer`（未装则静音播放）。
启动器会遍历系统所有 `python3` / `python3.x` 解释器，**优先选择"画面
依赖 + ffpyplayer"都齐全的**；多 Python 共存（pyenv/conda）也不会装错环境。
包质量已用 lintian 校验：仅剩"安装于 /opt"提示（按设计布局）与
`python3-*` 依赖名误报。

## 构建 deb 包

```bash
./tools/build_deb.sh
```

- 产物：`dist/python-video-player_<版本>-1_all.deb`（architecture: all）
- 布局：源码 → `/opt/python-video-player`；启动器 → `/usr/bin/python-video-player`
  （自动探测系统依赖，缺失时回退 `/opt` 内自建 venv）；桌面入口 + hicolor
  全尺寸图标 + 英文 man 手册 + Debian changelog + copyright
- 校验：`lintian dist/*.deb`

## 快捷键

| 按键 | 功能 |
|---|---|
| `Space` | 播放 / 暂停 |
| `←` / `→` | 后退 / 前进 5 秒 |
| `F11` / `Esc` | 全屏 / 退出全屏 |
| `Ctrl+O` | 打开文件（可多选） |
| `+` / `-` | 音量 ±5% |
| `M` | 静音开关 |
| `N` / `P` | 下一个 / 上一个 |
| `L` | 单曲循环 |
| `F` | 画面适配窗口开关（放大 ↔ 原始尺寸） |
| `Delete` | 从列表移除当前项 |

右键菜单：画布右键（打开/播放/停止/循环/适配/全屏/关于），列表右键（播放/移除/添加/清空）。

## 项目结构

```
python-video-player/
├── python-video-player.py    # 启动入口（薄封装）
├── python-video-player.desktop # 桌面启动器模板（复制到 ~/.local/share/applications）
├── run.sh                    # 一键启动脚本（venv + 依赖 + 启动）
├── requirements.txt          # 必需依赖
├── requirements-audio.txt    # 可选音频依赖
├── pyproject.toml            # 打包元数据（可 pip install . 获得 pvp 命令）
├── pvp/                      # 核心包（模块化）
│   ├── config.py             # 常量 / 暗色主题配色 / 文件类型
│   ├── utils.py              # 画面适配计算、时间格式化（纯函数）
│   ├── audio.py              # ffpyplayer 薄封装（异常全吞，不影响画面）
│   ├── icons.py              # 图标绘制与加载
│   ├── widgets.py            # 主题 + 自绘 SeekBar 进度条
│   ├── player.py             # VideoPlayer 主窗口
│   └── app.py                # main() 入口
├── tests/                    # 单元测试（unittest）
│   ├── test_basic.py         # 纯函数测试（无显示环境可跑）
│   └── test_gui.py           # GUI 集成测试（需显示环境，自动跳过）
├── tools/
│   ├── run_tests.sh          # 一键跑测试（静态自检 + unittest）
│   ├── static_check.py       # AST 静态自检（self. 引用完整性）
│   ├── make_icons.py         # 重新生成 assets/icons 多尺寸图标
│   ├── make_demo_video.py    # 生成演示视频 assets/demo/demo.mp4
│   └── build_deb.sh          # 构建 Debian 包（源码 -> /opt + /usr/bin 启动器）
└── assets/
    ├── icons/                # 图标 PNG（16~256）+ SVG 源
    └── demo/demo.mp4         # 演示视频（音画同步测试用）
```

## 运行测试

```bash
./tools/run_tests.sh
# 或
python -m unittest discover -s tests -v
```

- 静态自检：AST 检查所有类的 `self.` 属性/方法引用均有定义（无显示环境也有效）
- 纯函数测试在任何环境通过；GUI 集成测试在检测到图形显示（`$DISPLAY`）时自动执行，
  无显示环境（CI/无头服务器）自动跳过。

## 体验演示视频

```bash
python tools/make_demo_video.py    # 生成 assets/demo/demo.mp4（20 秒，含音轨）
```

彩色动画画面 + 琶音音轨，可用来快速验证播放、音画同步、进度条、倍速、音量。

## 加入桌面启动器（可选）

编辑 `python-video-player.desktop` 里的 `Exec`/`Icon` 为实际安装路径，然后：

```bash
cp python-video-player.desktop ~/.local/share/applications/
```

## 常见问题

**启动报 `libGL.so.1` 错误？**
OpenCV 需要系统库：`sudo apt install libgl1 libglib2.0-0`

**没有声音？**
安装可选音频依赖：`pip install -r requirements-audio.txt`。
安装失败也不影响使用（自动静音播放），状态栏会有提示。
Linux 源码编译需要：`sudo apt install libsdl2-dev libavcodec-dev libavformat-dev libswscale-dev pkg-config`

**deb 安装后状态栏提示"音频未启用 / 缺少 ffpyplayer"，明明已经 pip install 过？**
终端里的 `pip` 可能对应另一个 Python（pyenv / conda / 不同版本），
包装进了别的环境，而播放器用的是启动器选定的解释器。修复：
复制状态栏显示的精确命令执行（它指向播放器正在用的解释器），例如：

    /usr/bin/python3 -m pip install --user ffpyplayer

执行后重启播放器即可。也可以在"关于"对话框查看当前解释器路径确认。
若命令执行后仍提示"音频加载失败"，多为缺 ffmpeg 运行库，先
`sudo apt install libavcodec58 libavformat58 libswscale5`（或对应发行版包名）。

**视频画面太小/太大？**
按 `F` 或画布右键切换"画面适配窗口"：开启时小视频等比放大铺满画布，关闭时按原始尺寸显示。

**重新生成图标？**
修改 `pvp/icons.py` 后运行 `python tools/make_icons.py`。

## 许可证

GPL-3.0，见 [LICENSE](LICENSE)。