# music-player

**Repository Path**: AMDMolang/music-player

## Basic Information

- **Project Name**: music-player
- **Description**: 🎵 智能音乐播放器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎵 智能音乐播放器 — Music Player

> 基于 PyQt6 + pygame 的桌面音乐播放器 | Python 课程设计项目

<div align="center">

![Python](https://img.shields.io/badge/Python-3.9+-blue?logo=python)
![PyQt6](https://img.shields.io/badge/PyQt-6.5+-green?logo=qt)
![License](https://img.shields.io/badge/License-MIT-yellow)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)

</div>

---

## 📖 项目简介

智能音乐播放器是一款跨平台桌面音乐应用，基于 **PyQt6** 和 **pygame** 开发。采用 MVC 分层架构（`core/` 业务层 + `ui/` 表现层），通过信号/槽机制实现松耦合通信。提供本地音乐管理、LRC 歌词同步、桌面歌词悬浮窗、10段均衡器、多主题切换等完整功能。

---

## ✨ 核心功能

| 模块 | 功能描述 |
|------|----------|
| 🎵 **播放控制** | 播放/暂停/停止/上一首/下一首/快进快退，支持进度拖拽与音量调节 |
| 📂 **歌单管理** | 多歌单创建/删除/切换，批量导入本地歌曲，自动复制到音乐目录，批量管理模式 |
| 🔀 **播放模式** | 三种播放顺序：随机播放 / 歌单循环 / 单曲循环 |
| 🎚 **均衡器** | 10段频率均衡器（31Hz～16kHz），9种预设音效（流行/摇滚/爵士/古典/电子/低音增强/高音增强/人声增强/舞曲） |
| 📝 **歌词同步** | LRC 歌词解析，实时滚动显示，当前行渐变色高亮，支持 UTF-8 / GBK 编码 |
| 🎤 **桌面歌词** | 独立悬浮歌词窗口（always-on-top），拖拽定位，卡拉OK逐字高亮效果，可配置字体颜色 |
| 🔍 **音乐搜索** | 本地音乐库浏览，模糊搜索（歌名/艺术家/专辑/文件名），300ms 防抖，批量添加 |
| 🎨 **主题切换** | 4套预设主题（暗夜红 / 深海蓝 / 翡翠绿 / 极简白），深色/浅色双模式 QSS |
| ⚙ **个性化设置** | 音乐目录/默认音量/歌词字体颜色/主题等多参数可配置，JSON 持久化 |
| ⌨ **键盘快捷键** | Space 播放暂停 / ←→ 快进快退 / ↑↓ 音量调节 / Ctrl+I 导入 / Ctrl+S 保存等 |

---

## 🏗️ 技术架构

```
music_player/
├── main.py                      # 程序入口
├── requirements.txt             # 依赖清单
├── core/                        # 核心业务层
│   ├── player.py                #   pygame.mixer 音频引擎封装
│   ├── playlist_manager.py      #   歌单 CRUD + mutagen 元数据 + JSON 持久化
│   ├── lyrics_manager.py        #   LRC 歌词解析 + 毫秒级时间同步
│   └── equalizer.py             #   10段软件均衡器 + 9种预设
└── ui/                          # 界面表现层
    ├── styles.py                #   QSS 深色/浅色主题系统（4套预设）
    ├── main_window.py           #   主窗口：侧边栏/菜单栏/工具栏/状态栏/页面栈
    ├── player_widget.py         #   播放栏 + 桌面歌词悬浮窗（LyricsOverlay）
    ├── playlist_widget.py       #   歌单面板：QTableView + 自定义 Model + 批量管理
    ├── lyrics_widget.py         #   歌词面板：自绘渐变 + 滚动动画
    ├── search_widget.py         #   搜索面板：音乐库浏览 + 防抖搜索 + 批量添加
    ├── equalizer_widget.py      #   均衡器面板：10段滑条 + 预设选择
    ├── settings_dialog.py       #   设置窗口：常规/外观/桌面歌词三页签
    └── about_dialog.py          #   关于窗口：项目信息/功能/使用指南/技术说明
```

### 技术栈

| 层级 | 技术 |
|------|------|
| **UI 框架** | PyQt6 (Qt 6.x) |
| **音频引擎** | pygame.mixer (SDL2) |
| **元数据** | mutagen (ID3/Vorbis/MP4 标签解析) |
| **持久化** | JSON 文件存储 |
| **样式** | Qt Style Sheets (QSS) 深色主题 |

### 设计模式

- **信号/槽机制**：15+ 自定义 `pyqtSignal`，实现跨组件松耦合通信
- **Model/View 架构**：`QAbstractTableModel` 驱动 `QTableView` 数据绑定
- **页面栈导航**：`QStackedWidget` 管理 3 个独立功能页面

---

## 🚀 快速开始

### 环境要求

- Python 3.9+
- PyQt6 ≥ 6.5.0

### 安装与运行

```bash
# 1. 克隆仓库
git clone <your-gitee-repo-url>
cd music_player

# 2. 创建虚拟环境
python -m venv .venv

# 3. 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

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

# 5. 运行
python main.py
```

### 依赖说明

```
PyQt6>=6.5.0        # GUI 框架
pygame>=2.5.0       # 音频播放引擎
mutagen>=1.47.0     # 音频元数据解析（可选，无此库会自动降级）
```

---

## 🎮 使用指南

### 基本操作

| 操作 | 方式 |
|------|------|
| 导入歌曲 | 工具栏「📂 导入」或 `Ctrl+I`（支持多选音频 + 歌词文件） |
| 播放/暂停 | 点击 ▶/⏸ 按钮或按 `Space` |
| 停止播放 | 点击 ⏹ 按钮 |
| 切歌 | 点击 ⏮ ⏭ 或 `Ctrl+←` `Ctrl+→` |
| 快进/快退 | `←` `→` 键（5秒步长） |
| 音量调节 | 拖动音量滑块或 `↑` `↓` 键 |
| 页面切换 | 侧边栏导航按钮或「视图」菜单 |
| 保存歌单 | `Ctrl+S` |
| 打开设置 | `Ctrl+,` |
| 删除选中歌曲 | `Delete` 键 |

### 歌单管理

| 操作 | 方式 |
|------|------|
| 新建歌单 | 点击首页「➕ 新建」按钮 |
| 删除歌单 | 选中歌单后点击「🗑 删除」 |
| 切换歌单 | 首页顶部下拉框选择 |
| 移除歌曲 | 选中后点击「🗑 移除选中」或按 `Delete` |
| 清空歌单 | 点击「清空歌单」按钮 |
| 批量管理 | 点击「📋 批量处理」进入批量模式，可勾选多首后批量添加到其他歌单或批量删除 |

### 播放模式切换

点击播放栏的 🔁 按钮，在弹出的菜单中选择：
- **🔀 随机播放** — 随机打乱播放顺序
- **🔁 歌单循环** — 列表播放完毕后从头开始（默认）
- **🔂 单曲循环** — 重复播放当前歌曲

### 歌词显示

将 `.lrc` 歌词文件与歌曲放在**同一目录**下，程序会自动加载并同步滚动显示。也支持在导入歌曲时**同时选中 .lrc 文件**，程序会自动匹配并关联。

### 桌面歌词

点击播放栏的「**词**」按钮打开桌面歌词悬浮窗：
- 歌词窗口**始终置顶**，即使主窗口最小化也能看到
- **拖拽歌词文字**可调整显示位置
- **拖拽空白区域**可移动整个窗口
- 鼠标悬停时显示关闭按钮
- 在设置 → 桌面歌词中可自定义**字体 / 字号 / 颜色**

### 均衡器

在均衡器页面：
- 分别调整 **10个频段**（31Hz ~ 16kHz）的增益值（-12dB ~ +12dB）
- 从预设下拉框选择音效，或手动调节
- 修改任意滑条后自动切换为「Custom」自定义方案

### 主题切换

在设置（`Ctrl+,`）→ 外观中选择主题：
- **暗夜红**（默认）— 深色 + 红色强调
- **深海蓝** — 深色 + 蓝色强调
- **翡翠绿** — 深色 + 绿色强调
- **极简白** — 浅色明亮主题

---

## 🎨 界面预览

### 主题配色

| 主题 | 强调色 | 背景色 | 面板色 | 风格 |
|------|--------|--------|--------|------|
| 暗夜红 | `#e94560` | `#1a1a2e` | `#16213e` | 深色 + 热情红 |
| 深海蓝 | `#3498db` | `#1a1a2e` | `#16213e` | 深色 + 冷静蓝 |
| 翡翠绿 | `#2ecc71` | `#1a1a2e` | `#16213e` | 深色 + 清新绿 |
| 极简白 | — | `#ffffff` | `#f0f0f0` | 浅色明亮 |

> 所有深色主题共用同一套基础配色（背景 `#1a1a2e` / 面板 `#16213e` / 边框 `#0f3460` / 文字 `#e0e0e0` / 次要文字 `#a0a0b0`），仅强调色不同。极简白为独立浅色方案。

### 设计细节

- 播放按钮圆形设计 + 阴影效果
- 歌词当前行渐变色高亮（强调色渐变）
- 侧边栏导航按钮选中态高亮
- 对话框阴影叠加
- 滑块/进度条自定义渲染
- 表格交替行颜色
- 设置页面主题预览卡片

## 🔧 开发说明

### 项目约定

- Python 文件使用 UTF-8 编码
- 核心逻辑与 UI 严格分层（`core/` vs `ui/`）
- 信号命名：`xxx_changed`（状态变化）、`xxx_requested`（请求动作）
- 模型类使用 `@dataclass`（Song, Playlist, EQPreset）
- mutagen 为可选依赖，代码中通过 `HAS_MUTAGEN` 标志优雅降级
- `QGraphicsDropShadowEffect` 在 PyQt6 中属于 `QtWidgets`

---

## 📄 License

MIT License — 仅供学习交流使用。