# 跨平台媒体播放器

一个基于 Python 的图形化媒体播放器，可在 **Windows / Linux / macOS** 上运行。
支持音频与视频播放、播放列表、循环模式、变速播放，以及完整的键盘快捷键。
**无需安装任何第三方播放软件**：内置纯 Python 解码内核（PyAV + sounddevice），
pip 安装依赖后即可直接播放视频。

## 功能特性

- 播放 / 暂停 / 停止、上一首 / 下一首
- 前进 / 后退（步长可自定义）与进度条点击拖动定位
- 快进步长可在界面底部直接填写（1-600 秒），自动保存、下次启动自动加载
- 按句跳转：勾选后 `←` / `→` 自动播放上一句/下一句（基于音频静音自动识别
  句边界，无需联网，分析结果自动缓存）
- 音量调节、静音，0.5x - 2.0x 变速播放
- 三种循环模式：关 / 单曲循环 / 列表循环
- 播放列表管理（打开文件、打开文件夹、删除条目、双击播放）
- 自动记忆播放列表：退出后自动保存，下次启动自动恢复（含上次播放的曲目高亮）
- 播放列表右键菜单：播放选中 / 删除选中 / 清空全部（macOS 亦支持 Ctrl+点击）
- 视频内嵌到主窗口播放（纯 Python 内核；VLC 内核下 Windows / Linux 内嵌，
  macOS 使用独立视频窗口）
- 命令行直接传入文件或文件夹即可播放

## 安装

要求：Python 3.8 及以上（自带 tkinter）。

```bash
pip install -r requirements.txt
```

播放内核说明（按优先级自动选择）：

1. **VLC 内核**（`python-vlc`）：若电脑上安装了 VLC 播放器则优先使用，
   支持变速播放。
2. **纯 Python 内核**（PyAV + sounddevice）：无需安装任何软件，pip 装完
   依赖即可播放音视频，画面显示在主窗口内；不支持变速播放。
3. **pygame 内核**：以上依赖都缺失时的兜底，仅支持音频文件。

若想使用 VLC 内核，可自行安装 VLC：Windows 从
<https://www.videolan.org/vlc/> 下载；macOS 执行 `brew install --cask vlc`；
Linux（Debian/Ubuntu）执行 `sudo apt install vlc`。

## 运行

```bash
python media_player.py
python media_player.py 音乐/ 电影.mp4 song.mp3
```

也可以使用一键启动脚本（会自动激活名为 `mediaplayer` 的 conda 环境）：

- **Windows**：双击 `启动播放器_Windows.bat`
- **Linux**：双击 `启动播放器_Linux.sh`，或在终端执行 `bash 启动播放器_Linux.sh`
- **macOS**：终端执行 `conda activate mediaplayer && python media_player.py`

脚本会自动在 PATH 及常见安装目录中查找 conda，激活 `mediaplayer` 环境后启动
播放器；若环境未创建，请先执行：

```bash
conda create -n mediaplayer python=3.12
conda activate mediaplayer
pip install -r requirements.txt
```

## 快捷键

| 快捷键 | 功能 |
| --- | --- |
| `Space` | 播放 / 暂停 |
| `←` / `→` | 后退 / 前进（步长可自定义；勾选“按句跳转”后按句子跳转） |
| `Shift+←` / `Shift+→` | 后退 / 前进 60 秒 |
| `↑` / `↓` | 音量 +5 / -5 |
| `Ctrl+↑` / `Ctrl+↓` | 快进步长 +1 / -1 秒（macOS 亦支持 `Command+↑ / ↓`） |
| `M` | 静音 / 恢复 |
| `Ctrl+←` / `Ctrl+→` | 上一首 / 下一首（macOS 亦支持 `Command+← / →`） |
| `N` / `P` | 下一首 / 上一首 |
| `[` / `]` | 减速 / 加速（0.5x - 2.0x） |
| `L` | 切换循环模式（关 / 单曲 / 列表） |
| `F` | 视频全屏切换 |
| `Esc` | 退出全屏 |
| `Ctrl+O` | 打开文件（macOS 亦支持 `Command+O`） |
| `Ctrl+Shift+O` | 打开文件夹（macOS 亦支持 `Command+Shift+O`） |
| `Enter` | 播放列表中选中的曲目 |
| `Delete` | 从播放列表移除所选曲目 |
| `S` | 停止 |

播放列表的右键菜单支持：**播放选中曲目**、**删除选中曲目**、**清空播放列表**。
播放列表保存在用户主目录的 `.mediaplayer_playlist.json` 中，删除该文件即可
清除记忆。

界面底部的“快进步长”用于设置 `←` / `→` 每次跳转的秒数（`Shift+← / →` 固定为
60 秒），输入后按回车或点击其他位置即生效并自动保存（配置文件：用户主目录下的
`.mediaplayer_settings.json`）。

勾选“按句跳转”后，`←` / `→` 不再按固定秒数跳转，而是自动跳到上一句 / 下一句
的开头：程序会分析音频中的静音停顿来自动切分句子（适合听写、跟读等场景）。
静音阈值会根据每个文件的背景噪声自动调整，带环境噪音的录音也能正常分句。
分析在后台进行，首次播放某文件时状态栏会提示“正在分析句边界…”，完成后
自动缓存；无法识别（如纯音乐、无音频轨）时会提示并回退为普通步进跳转。
“按句跳转”的开关状态同样会自动保存。

## 常见问题

- **状态栏显示“纯 Python 解码内核”**：说明未检测到 VLC，程序正在使用内置的
  纯 Python 内核播放，无需额外安装任何软件，视频照常可用；仅变速（0.5x-2.0x）
  不可用。
- **状态栏显示“pygame 音频模式”**：说明连纯 Python 内核的依赖（av、
  sounddevice、numpy、Pillow）也未安装，程序回退为纯音频模式（视频不可用）。
  执行 `pip install -r requirements.txt` 后重启程序即可播放视频。
- **提示找不到内核**：说明既没有 `python-vlc` 也没有 `pygame`，请执行
  `pip install -r requirements.txt`；若已安装 `python-vlc` 仍提示，请确认 VLC 本体已安装。
- **Linux 缺少 tkinter**：`sudo apt install python3-tk`（Debian/Ubuntu）。
- **Linux 下视频没有嵌入主窗口**：多见于 Wayland 环境，程序会自动改用独立视频窗口。
- **macOS 视频显示在独立窗口**：这是平台限制，属正常行为，`F` 键仍可全屏。