# 全能媒体播放器

**Repository Path**: deepin20/media_player

## Basic Information

- **Project Name**: 全能媒体播放器
- **Description**: 全能媒体播放器 - 基于 python-vlc + PyQt5，深度适配 UOS/Deepin
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎬 全能媒体播放器

> 基于 `python-vlc` + `PyQt5` 的全能媒体播放器，专为**统信 UOS / Deepin 25** 深度适配，提供完整的字幕支持、音频均衡器、视频滤镜等高级功能。

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
[![PyQt5](https://img.shields.io/badge/PyQt5-5.11%2B-green)](https://pypi.org/project/PyQt5/)
[![VLC](https://img.shields.io/badge/VLC-3.0%2B-orange)](https://www.videolan.org/vlc/)
[![License](https://img.shields.io/badge/License-GPLv3-red)](https://www.gnu.org/licenses/gpl-3.0.html)

---

## ✨ 功能亮点

### 🎞️ 播放核心
- **本地文件支持**：MP3/WAV/FLAC/M4A/MP4/AVI/MKV/MOV/WMV 等常见格式
- **网络流播放**：支持 HTTP/HTTPS/RTSP/RTMP 直链，可定制缓存大小
- **智能播放列表**：添加/清空/双击播放，支持**顺序、循环、单曲循环、随机**四种模式
- **进度拖拽**：实时显示当前/总时长，平滑跳转
- **音量控制**：可视化滑块，图标随音量变化

### 📝 强大的字幕系统
- **自动加载**：播放本地视频时自动加载同名字幕（支持 `.srt` / `.ass` / `.ssa` / `.idx` / `.sub`）
- **手动加载**：通过菜单选择任意字幕文件
- **内嵌轨道切换**：动态枚举并切换 MKV/MP4 等容器内的字幕流
- **延迟调整**：±500ms 步进，一键重置，解决音画不同步
- **样式定制**：字体、字号（10%~100%）、颜色、编码（UTF-8/GBK/GB18030/BIG5 等）全面可调

### 🎛️ 音视频增强
- **10 段音频均衡器**：60Hz~16kHz 精细调节，支持前置放大，内置**古典、摇滚、流行、舞曲**等 14 种预设
- **实时视频滤镜**：亮度、对比度、饱和度、色调（0~360°）、锐度可调，一键重置

### 🖥️ 交互与界面
- **深/浅色主题适配**：跟随 UOS 系统主题自动切换
- **跑马灯叠加**：自定义滚动文本，可用于提示或水印
- **全屏模式**：双击视频或按 `ESC` 进入/退出，全屏时自动隐藏控制栏，退出后恢复布局
- **全局快捷键**：`Ctrl+O` 打开文件，`Ctrl+U` 打开 URL，`Ctrl+S` 截图

### 🛠️ 实用工具
- **截图**：一键保存当前画面为 PNG（自动命名时间戳）
- **录制**（实验性）：支持开始/停止录制（依赖 VLC 录制 API，部分版本可能不可用）
- **设置持久化**：窗口尺寸、缓存、字幕样式等自动保存

---

## 📦 系统要求

| 组件 | 版本要求 |
|------|----------|
| **操作系统** | Deepin 25 / UOS 20+（亦支持其他 Linux） |
| **Python** | 3.8 或更高 |
| **PyQt5** | 5.11 或更高 |
| **python-vlc** | 3.0 或更高 |
| **VLC** | 3.0 或更高（必须安装） |
| **PulseAudio**（音频） | 通常系统自带 |

---

## 🚀 安装与运行

### 方式一：通过 .deb 包一键安装（推荐）

1. 下载 `media-player_1.0.0_all.deb` 包。
2. 在终端中执行：
   ```bash
   sudo dpkg -i media-player_1.0.0_all.deb
   sudo apt install -f      # 自动补全依赖
   ```
3. 安装后，可在**应用菜单**中找到“全能媒体播放器”，或直接在终端运行 `media-player`。

### 方式二：从源码运行

1. 克隆或下载本项目。
2. 确保系统已安装 Python 3、PyQt5、python-vlc、VLC：
   ```bash
   sudo apt update
   sudo apt install python3-pyqt5 python3-vlc vlc
   ```
3. 进入项目根目录，执行：
   ```bash
   python3 -m media_player
   ```
   或使用提供的启动脚本：
   ```bash
   ./run_player.sh
   ```

### 方式三：PyInstaller 打包（可选）

如果你希望生成一个独立的可执行文件，可使用 PyInstaller（需自行处理 VLC 库依赖）。

---

## 🎮 使用指南

### 播放操作
- **添加文件**：点击“添加文件”按钮，或从菜单 `文件 → 打开文件`（`Ctrl+O`）。
- **添加网络流**：点击“添加 URL”，输入直链（如 `http://example.com/video.mp4`）。
- **播放控制**：播放/暂停/停止/上一曲/下一曲，播放模式切换。
- **进度跳转**：拖拽进度条，实时更新。

### 字幕使用
- **自动加载**：将字幕文件放在视频同一目录，文件名相同（扩展名不同）即可自动加载。
- **手动加载**：菜单 `字幕 → 加载字幕文件...`。
- **切换轨道**：菜单 `字幕 → 字幕轨道` 选择内嵌字幕。
- **延迟调整**：菜单 `字幕 → 延迟调整`，或使用 `+500ms` / `-500ms` 调整。
- **样式设置**：菜单 `字幕 → 字幕样式设置...`，自定义字体/颜色/大小/编码。

### 均衡器与滤镜
- **均衡器**：菜单 `音频 → 均衡器`，可手动调节或选择预设。
- **视频滤镜**：菜单 `视频 → 视频滤镜`，调节亮度/对比度/饱和度等。

### 全屏与截图
- **全屏**：双击视频画面，或按 `ESC`（全屏模式下再次按 `ESC` 退出）。
- **截图**：菜单 `播放 → 截图`，或快捷键 `Ctrl+S`。

---

## ⚙️ 高级配置

### 修改缓存大小
- 菜单 `设置 → 播放器设置`，在“常规”选项卡中调整“网络缓存”（100~5000 毫秒）。

### 自定义启动参数
- 编辑 `/usr/bin/media-player` 或 `run_player.sh`，可调整 VLC 输出模块（如 `--vout=x11` 改为 `--vout=gl`）。

### 配置文件位置
- 用户配置文件保存在 `~/.config/MediaPlayer/Settings.conf`（由 QSettings 管理）。

---

## 🐛 常见问题

**Q：视频无法显示，只有声音？**  
A：请确保使用 X11 显示服务器（Deepin 默认 X11），并运行启动脚本（已自动设置 `QT_QPA_PLATFORM=xcb`）。如果使用 Wayland，需切换至 X11。

**Q：字幕乱码？**  
A：在“字幕样式设置”中尝试切换编码（如 GBK 或 UTF-8），也可手动指定字体（建议安装 `Noto Sans CJK SC`）。

**Q：录制功能无效？**  
A：`player.record()` 在部分 VLC 版本中不可用，目前为实验性功能，建议使用外部录屏工具。

**Q：打开网络流一直缓冲？**  
A：可在“设置”中增加网络缓存值，或检查网络连接是否稳定。

**Q：如何更新？**  
A：重新安装新的 `.deb` 包即可（会自动覆盖旧文件）。

---

## 📁 目录结构（安装后）

```
/opt/media-player/
├── media_player/          # 可修改的 Python 源码
│   ├── core/
│   ├── ui/
│   ├── resources/
│   ├── utils/
│   ├── __init__.py
│   └── __main__.py
├── run.sh                 # 备用启动脚本
/usr/bin/media-player      # 全局启动器（符号链接）
/usr/share/applications/media-player.desktop
```

---

## 📄 许可证

本项目使用 **GPLv3** 许可证，详情请见 [LICENSE](LICENSE) 文件。  
使用 PyQt5（GPLv3）和 VLC（LGPLv2.1），遵循其相应许可条款。

---

## 🤝 贡献

欢迎提交 Issue 或 Pull Request。如果你希望增加新功能，请先开 Issue 讨论。

---

## 📞 联系方式

- 作者：Your Name
- 邮箱：you@example.com
- 项目主页：[GitHub](https://github.com/yourname/media-player)

---

**Enjoy your media experience! 🎧🎬**