mediaplayer/README.md

跨平台媒体播放器

一个基于 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）。

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。

运行

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 环境后启动 播放器；若环境未创建，请先执行：

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

快捷键

快捷键	功能
Space	播放 / 暂停
← / →	后退 / 前进 10 秒
Shift+← / Shift+→	后退 / 前进 60 秒
↑ / ↓	音量 +5 / -5
Ctrl+↑ / Ctrl+↓	快进步长 +5 / -5 秒（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 键仍可全屏。