# 千千静听

**Repository Path**: deepin20/ttplayer

## Basic Information

- **Project Name**: 千千静听
- **Description**: 千千静听音乐播放器：基于 PyQt5 和 VLC 的本地音乐播放器，支持歌词、均衡器、频谱等。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 千千静听音乐播放器

基于 PyQt5 和 VLC 的本地音乐播放器，还原经典千千静听风格，支持歌词显示、均衡器、频谱动画等多种功能。

![播放器截图](screenshot.png) <!-- 如有截图可替换 -->

---

## ✨ 功能特性

- 🎵 **本地音乐播放**：支持 MP3、FLAC、WAV、M4A、OGG 等常见格式
- 📃 **歌词显示**：
  - 自动加载同目录下的 `.lrc` 歌词文件
  - 支持从 LRCLIB 网络 API 获取同步歌词（需提供歌手和歌名）
  - 歌词窗口可独立拖拽，当前行高亮并自动滚动
- 🎚️ **均衡器**：10 段图形均衡器，内置摇滚、流行、古典三种预设
- 📊 **频谱动画**：模拟频谱柱状图，随音量变化
- 🔁 **播放模式**：顺序播放、列表循环、单曲循环、随机播放
- 📂 **播放列表管理**：添加/删除歌曲、扫描文件夹、清空列表
- 🎨 **千千静听风格界面**：无边框窗口，自定义标题栏，沉浸式体验

---

## 📦 安装方法

### 方法一：使用预构建的 Debian 包（推荐 UOS/Deepin 用户）

在项目根目录执行以下命令构建并安装：

```bash
# 安装构建依赖
sudo apt install build-essential debhelper dh-python python3-all python3-setuptools python3-pyqt5 python3-vlc python3-requests vlc

# 由于系统源缺少 python3-pyqtgraph，需通过 pip 安装
sudo pip3 install pyqtgraph --break-system-packages

# 构建 .deb 包
dpkg-buildpackage -us -uc -d

# 安装生成的 .deb
sudo dpkg -i ../ttplayer_1.0.0-1_all.deb
```

安装完成后，可在系统菜单中找到“千千静听”，或直接在终端输入 `ttplayer` 启动。

### 方法二：使用 pip 安装（开发模式）

```bash
# 克隆或解压项目源码到本地
cd ttplayer-project

# 创建并激活虚拟环境（可选但推荐）
python3 -m venv venv
source venv/bin/activate

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

# 开发模式安装（可执行 ttplayer 命令）
pip install -e .
```

### 方法三：直接运行（不安装）

```bash
cd ttplayer-project
./run.sh
```

或手动设置环境变量后运行：

```bash
export QT_QPA_PLATFORM=xcb
export VLC_VERBOSE=-1
python3 -m ttplayer
```

---

## 🔧 依赖说明

- **PyQt5**：图形界面框架
- **pyqtgraph**：频谱绘图库（需通过 pip 安装，系统源通常不提供）
- **python-vlc**：VLC 音频播放引擎
- **requests**：网络歌词获取

## 📝 使用指南

1. **添加歌曲**：点击播放列表区域的 `+` 按钮，或使用“扫描”按钮导入整个文件夹。
2. **播放控制**：使用底部的播放/暂停、上一首/下一首、停止按钮。
3. **歌词窗口**：点击顶部 `LRC` 按钮打开独立歌词窗口，播放歌曲时会自动打开（如有歌词）。
4. **均衡器**：点击 `EQ` 按钮展开均衡器面板，可开关、重置或选择预设。
5. **播放模式**：点击列表上方的 `M` 按钮切换模式（顺序 → 列表循环 → 单曲循环 → 随机）。

---

## 📂 目录结构

```
ttplayer-project/
├── debian/             # Debian 打包控制文件
├── resources/          # 图标和 .desktop 文件
├── ttplayer/           # 主 Python 包
│   ├── player/         # VLC 播放引擎
│   ├── ui/             # 主窗口及歌词控件
│   └── utils/          # 配置、日志、歌词获取工具
├── main.py             # 入口
├── setup.py            # pip 安装脚本
├── requirements.txt    # 依赖列表
└── run.sh              # 快速启动脚本
```

---

## ⚠️ 常见问题

### 1. 提示缺少 `python3-pyqtgraph`
统信 UOS 软件源中不包含此包，请通过 pip 安装：  
`sudo pip3 install pyqtgraph --break-system-packages`

### 2. 启动时出现 VLC 插件缓存警告
不影响使用，可忽略。如需抑制，请在 `engine.py` 中将 `vlc.Instance()` 改为 `vlc.Instance('--quiet', '--no-stats')`，或设置环境变量 `VLC_VERBOSE=-1`。

### 3. 播放无声或闪退
请确保已安装 VLC 多媒体框架：  
`sudo apt install vlc`

### 4. 歌词窗口无法显示
请确保歌曲文件同目录下存在同名 `.lrc` 文件，或歌曲文件名中包含歌手和歌名（以“ - ”分隔），以便从网络获取。

---

## 🤝 贡献

欢迎提交 Issue 或 Pull Request。如果你希望添加新功能或修复 Bug，请先通过 Issue 讨论。

---

## 📄 许可证

本项目采用 GPL-3.0 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 📧 联系方式

如有问题，请通过 [GitHub Issues](https://github.com/yourname/ttplayer/issues) 反馈。

---
**享受你的音乐时光！🎵**