# 🎯 Haoyun Music Player - 功能特性详解

<div align="center">

**探索 Haoyun Music Player 的强大功能**

*每一个细节，都为您精心打造*

[🏠 返回首页](./WEBSITE.md) • [📖 快速开始](./QUICKSTART.md) • [⌨️ 快捷键](./KEYBOARD_SHORTCUTS.md)

</div>

---

## 📋 目录

- [🎵 音频播放核心](#-音频播放核心)
- [📂 音乐库管理](#-音乐库管理)
- [🎨 用户界面](#-用户界面)
- [⚙️ 系统设置](#️-系统设置)
- [🔧 高级功能](#-高级功能)
- [🌐 系统集成](#-系统集成)
- [📊 数据统计](#-数据统计)

---

## 🎵 音频播放核心

### 全格式支持

Haoyun Music Player 通过原生解码器和 FFmpeg 引擎，支持几乎所有主流音频格式：

#### 原生支持（高性能）

| 格式 | 解码器 | 特点 |
|------|--------|------|
| **MP3** | go-mp3 | 流式解码，内存效率高 |
| **WAV** | go-audio/wav | 无损音质，快速加载 |
| **FLAC** | mewkiz/flac | 无损压缩，元数据完整 |

#### FFmpeg 支持（广泛兼容）

| 格式 | 说明 | 应用场景 |
|------|------|---------|
| **AAC** | Advanced Audio Coding | iTunes、Apple Music |
| **M4A** | MPEG-4 Audio | Apple 设备常用格式 |
| **OGG** | Ogg Vorbis | Spotify、YouTube Music |
| **WMA** | Windows Media Audio | Windows 平台常见格式 |
| **APE** | Monkey's Audio | 无损压缩格式 |
| **Opus** | Opus Codec | 低延迟、高质量编码 |
| **更多...** | 通过 FFmpeg 自动支持 | 几乎涵盖所有音频格式 |

> 💡 **提示**: 首次使用非原生格式时，应用会自动检测并提示安装 FFmpeg。详见 [FFmpeg 安装指南](./FFMPEG_GUIDE.md)。

### 专业播放控制

#### 基础控制

- ✅ **播放 / 暂停** - 空格键或点击按钮
- ✅ **上一曲 / 下一曲** - 快捷键 `Cmd/Ctrl + [` 和 `Cmd/Ctrl + ]`
- ✅ **进度拖拽** - 精确跳转到任意位置
- ✅ **断点续播** - 暂停后恢复时自动回到原位置

#### 播放模式

```
🔄 顺序播放    → 按列表顺序依次播放，结束后停止
🔁 循环播放    → 播放完最后一首后回到第一首继续
🔀 随机播放    → 随机打乱播放顺序
🔂 单曲循环    → 重复播放当前歌曲
```

**使用方式**:
- 托盘菜单: `播放模式` 子菜单
- 主菜单: `Music` → `播放模式`
- 前端界面: 播放控制区域（开发中）

### 音量管理

- **精细调节** - 0-100% 无级调节
- **记忆功能** - 自动保存上次音量设置
- **静音切换** - 快速静音/恢复（开发中）

---

## 📂 音乐库管理

### 多库支持

同时管理多个音乐文件夹，每个库独立索引和统计：

```
示例配置：
├── 📁 我的收藏          (1,250 首歌曲)
├── 📁 工作背景音乐      (320 首歌曲)
├── 📁 运动健身          (180 首歌曲)
└── 📁 学习专注          (95 首歌曲)
```

#### 库操作

| 操作 | 说明 | 快捷方式 |
|------|------|---------|
| **添加新库** | 选择文件夹，自动扫描 | 托盘菜单 → 音乐库 → 添加新音乐库 |
| **切换库** | 在不同库之间快速切换 | 托盘菜单 → 音乐库 → 选择库名 |
| **刷新库** | 重新扫描文件变化 | `Cmd/Ctrl + R` |
| **重命名库** | 修改库的显示名称 | 托盘菜单 → 音乐库 → 重命名 |
| **删除库** | 移除库配置（不删除文件） | 托盘菜单 → 音乐库 → 删除 |

### 智能扫描

- **后台异步** - 不阻塞主界面，可随时取消
- **增量更新** - 仅扫描新增/修改的文件
- **元数据提取** - 自动读取 ID3 标签（标题、艺术家、专辑、时长等）
- **持久化存储** - 扫描结果保存到 JSON 文件（`~/.haoyun-music/`）

### 浏览与搜索

#### 表格视图

```
#  | 标题            | 艺术家   | 专辑       | 时长 | 大小
─────────────────────────────────────────────────────────
1  | XXX            | XXX   | XXX | 3:45 | 8.2MB
2  | XXX            | XXX   | XXX     | 4:29 | 9.8MB
3  | XXX            | XXX   | XXX     | 3:43 | 7.9MB
...
```

**功能特性**:
- ✅ 列排序（点击表头）
- ✅ 双击播放
- ✅ 右键菜单（添加到播放列表、查看信息等）

#### 实时搜索

- **模糊匹配** - 支持标题、艺术家、专辑的模糊搜索
- **即时响应** - 输入即搜，无需点击按钮
- **高亮显示** - 匹配关键词高亮显示（开发中）

#### 分页浏览

针对大型音乐库优化，避免一次性加载过多数据：

| 每页显示 | 适用场景 |
|---------|---------|
| 20 首 | 小屏幕或网络较慢 |
| 50 首 | 默认选项，平衡性能和体验 |
| 100 首 | 大屏幕快速浏览 |
| 200 首 | 超大型音乐库 |

**翻页控件**:
```
⏮ ◀ 1 2 3 4 5 ... 25 ▶ ⏭
显示第 1-50 首，共 1,250 首
```

---

## 🎨 用户界面

### 多窗口架构

Haoyun Music Player 采用多窗口设计，每个窗口专注特定功能：

#### 1️⃣ 主播放器窗口

**核心功能**:
- 🎵 当前播放信息显示（封面、标题、艺术家、专辑）
- ⏯ 播放控制（播放/暂停、上一曲、下一曲）
- 📊 进度条和音量滑块
- 📋 播放列表展示
- 🔍 快速搜索框（开发中）

**设计理念**: 简洁直观，让您专注于音乐本身。

#### 2️⃣ 浏览窗口

**核心功能**:
- 📂 音乐库选择和切换
- 🔍 强大的搜索过滤
- 📊 歌曲列表表格展示
- 📈 库统计信息（总数、时长、大小）
- 📄 分页导航

**设计理念**: 高效管理海量音乐资源。

#### 3️⃣ 喜爱音乐窗口

**核心功能**:
- ❤️ 按播放次数智能排序
- 📊 播放历史统计
- 🎯 发现您最常听的音乐
- 📈 播放趋势分析（开发中）

**设计理念**: 帮您发现真正的最爱。

#### 4️⃣ 设置窗口

**核心功能**:
- 🌍 语言切换（中文 / English）
- 🎨 主题选择（开发中）
- 🔊 默认音量设置
- ⌨️ 媒体键启用/禁用
- 📄 歌词显示开关
- 🚀 开机自启设置
- 😴 保持唤醒设置

**设计理念**: 个性化您的使用体验。

### 视觉设计

#### 色彩方案

```
主色调:    #1B2636 (深蓝灰) - 沉稳专业
强调色:    #4A90E2 (天蓝)   - 活力清新
背景渐变:  深色系渐变       - 层次丰富
文字颜色:  #FFFFFF / #CCCCCC - 清晰易读
```

#### 毛玻璃特效

- **macOS** - 原生半透明标题栏和背景
- **Windows** - Acrylic 效果（开发中）
- **Linux** - 模拟毛玻璃效果

#### 响应式布局

- 自适应窗口大小变化
- 最小尺寸限制，保证可用性
- 最大宽度限制，避免过度拉伸

---

## ⚙️ 系统设置

### 通用设置

#### 语言设置

- 🇨🇳 **简体中文** - 默认语言
- 🇺🇸 **English** - 国际通用

**切换方式**:
1. 打开设置窗口 (`Cmd/Ctrl + S`)
2. 选择目标语言
3. 点击"应用"
4. **注意**: 部分界面需要重启应用才能完全生效

**持久化**: 语言偏好自动保存，下次启动自动应用。

#### 主题设置（开发中）

- 🌙 深色模式（默认）
- ☀️ 浅色模式
- 🎨 自定义主题色

### 播放设置

| 设置项 | 说明 | 默认值 |
|--------|------|--------|
| **默认音量** | 启动时的初始音量 | 80% |
| **默认播放模式** | 启动时的播放模式 | 循环播放 |
| **显示歌词** | 是否在主界面显示歌词 | 开启 |
| **启用媒体键** | 响应系统媒体键 | 开启 |

### 系统设置

| 设置项 | 说明 | 平台支持 |
|--------|------|---------|
| **开机自启** | 系统启动时自动运行 | macOS / Windows / Linux |
| **保持唤醒** | 播放时阻止系统休眠 | macOS / Windows |
| **最小化到托盘** | 关闭窗口时隐藏到托盘 | 所有平台 |

### 高级设置（开发中）

- **音频输出设备** - 选择扬声器/耳机
- **均衡器预设** - 流行、摇滚、古典等
- **交叉淡入淡出** - 歌曲切换时的平滑过渡
- **增益标准化** - 统一不同歌曲的音量

---

## 🔧 高级功能

### 播放历史记录

#### 自动记录

每次播放都会自动记录到历史数据库：

```json
{
  "filePath": "/Users/yanghao/Music/XXX.mp3",
  "title": "XXX",
  "artist": "XXX",
  "album": "XXX",
  "playCount": 42,
  "lastPlayed": "2026-04-08T23:30:00Z",
  "totalDuration": 9240 // 秒
}
```

#### 统计分析

- **总播放次数** - 了解您的聆听习惯
- **最近播放** - 快速回顾刚听过的歌
- **最爱排行** - 按播放次数排序

#### 数据管理

- **自动清理** - 超过 1000 条记录时自动清理旧记录
- **手动清除** - 一键清空所有历史
- **导出功能** - 导出为 CSV/JSON（开发中）

### 歌词显示

#### LRC 格式支持

自动扫描与音频文件同名的 `.lrc` 文件：

```
[00:00.00] XXX - XXX
[00:05.50] 一群嗜血的蚂蚁被腐肉所吸引
[00:10.20] 我面无表情看孤独的风景
[00:15.80] 失去你爱恨开始分明
...
```

#### 显示方式

- **主界面显示** - 在播放器底部滚动显示
- **同步高亮** - 根据播放进度高亮当前行
- **字体调节** - 自定义字体大小和颜色（开发中）

#### 关联规则

优先级从高到低：
1. 同名文件（`XXX.mp3` → `XXX.lrc`）
2. 文件夹内任意 `.lrc` 文件
3. 在线搜索（开发中）

### 专辑封面提取

#### 支持的来源

- **MP3 ID3v2** - 嵌入的 APIC 帧
- **FLAC METADATA** - 嵌入的图片块
- **外部文件** - `cover.jpg`、`folder.jpg`、`AlbumArt.jpg`

#### 显示位置

- 主播放器窗口左侧
- 系统通知（切换歌曲时）
- 托盘菜单（简化版）

#### 缓存机制

- 提取后缓存到 `~/.haoyun-music/covers/`
- 避免重复解码，提升性能
- 自动清理过期缓存（开发中）

### 依赖工具管理

#### 自动检测

启动时自动检查以下工具：

| 工具 | 用途 | 必需性 |
|------|------|--------|
| **FFmpeg** | 音频解码引擎 | 推荐（支持更多格式） |
| **ffprobe** | 音频信息探测 | 推荐（元数据提取） |

#### 状态指示

- ✅ **已安装** - 绿色勾选，显示版本号
- ❌ **未安装** - 红色叉号，提供安装指引
- 🔧 **安装中** - 黄色扳手，显示进度
- ⚠️ **安装失败** - 橙色警告，显示错误信息

#### 一键安装

- **托盘菜单** - `🛠️ 依赖工具` → 选择工具 → `📦 安装`
- **前端界面** - 设置页面 → 依赖管理（开发中）
- **后台执行** - 不阻塞主界面，完成后通知

#### 手动安装指南

如果自动安装失败，可参考 [FFmpeg 安装指南](./FFMPEG_GUIDE.md) 手动安装。

---

## 🌐 系统集成

### 系统托盘

#### 托盘图标

- **默认图标** - 应用 Logo
- **状态指示** - 播放时动态效果（开发中）
- **悬停提示** - 显示当前播放歌曲

#### 托盘菜单

完整的控制功能，无需打开主窗口：

```
🎵 正在播放：XXX - XXX
─────────────────────────────
⏯ 播放/暂停          Space
⏮ 上一曲        Cmd+[
⏭ 下一曲        Cmd+]
─────────────────────────────
📂 浏览歌曲       Cmd+F
❤️ 喜爱音乐       Cmd+H
🔄 播放模式
📚 音乐库管理
🛠️ 依赖工具
⬇️ 下载音乐       Cmd+D
─────────────────────────────
⚙️ 设置           Cmd+S
🪟 显示主窗口
─────────────────────────────
v1.0.0
❌ 退出
```

#### 交互行为

- **单击** - 显示/隐藏菜单
- **双击** - 显示主窗口（可选，开发中）
- **右键** - 显示菜单（Windows/Linux）

### 菜单栏（macOS）

#### 菜单结构

```
 Haoyun Music Player File Music Development Edit Playback View Help
```

**Music 菜单**:
- 正在播放（动态更新）
- 播放控制（播放/暂停、上一曲、下一曲）
- 窗口管理（主窗口、浏览、喜爱音乐、设置）
- 播放模式
- 音乐库管理
- 其他功能

**Playback 菜单**:
- 全局快捷键（Space、Cmd+[、Cmd/]）
- 必须在菜单栏定义才能生效

#### 动态更新

- **正在播放** - 实时显示当前歌曲
- **播放模式** - 勾选当前模式
- **语言切换** - 重建菜单以应用新语言

### 键盘快捷键

#### 全局快捷键

| 快捷键 | 功能 | 作用域 |
|--------|------|--------|
| `Space` | 播放/暂停 | 全局 |
| `Cmd/Ctrl + [` | 上一曲 | 全局 |
| `Cmd/Ctrl + ]` | 下一曲 | 全局 |
| `Cmd/Ctrl + F` | 打开浏览窗口 | 全局 |
| `Cmd/Ctrl + H` | 打开喜爱音乐 | 全局 |
| `Cmd/Ctrl + S` | 打开设置 | 全局 |
| `Cmd/Ctrl + R` | 刷新音乐库 | 全局 |

#### 窗口内快捷键

| 快捷键 | 功能 | 作用域 |
|--------|------|--------|
| `Cmd/Ctrl + O` | 打开文件 | 主窗口 |
| `Cmd/Ctrl + N` | 新建播放列表 | 主窗口（开发中） |
| `Cmd/Ctrl + D` | 下载音乐 | 主窗口（开发中） |
| `Esc` | 关闭窗口 | 所有窗口 |

> 📖 完整快捷键列表请查看 [键盘快捷键文档](./KEYBOARD_SHORTCUTS.md)。

### 文件关联（开发中）

- **双击音频文件** - 自动用 Haoyun Music Player 打开
- **拖拽到窗口** - 添加到播放列表
- **右键菜单** - "用 Haoyun Music Player 播放"

---

## 📊 数据统计

### 音乐库统计

#### 概览信息

```
📁 我的收藏
├── 🎵 歌曲数量: 1,250 首
├── ⏱️ 总时长: 3天 12小时 35分钟
├── 💾 占用空间: 8.5 GB
├── 📂 文件路径: /Users/yanghao/Music
└── 📅 最后扫描: 2026-04-08 23:30:00
```

#### 分类统计（开发中）

- **按艺术家** - 每位艺术家的歌曲数量和时长
- **按专辑** - 每张专辑的歌曲数量和时长
- **按年份** - 不同年代的歌曲分布
- **按流派** - 各种音乐风格的比例

### 播放统计

#### 个人数据

- **总播放时长** - 累计聆听时间
- **日均播放** - 平均每天听歌时长
- **活跃时段** - 一天中哪个时段听得最多
- **最爱艺术家** - 播放次数最多的前 10 位
- **最爱专辑** - 播放次数最多的前 10 张

#### 可视化图表（开发中）

- 📊 柱状图 - 每日播放时长趋势
- 🥧 饼图 - 音乐流派分布
- 📈 折线图 - 月度播放量变化
- 🎯 雷达图 - 音乐品味分析

### 数据导出（开发中）

支持导出格式：
- **CSV** - 便于 Excel 分析
- **JSON** - 便于程序处理
- **PDF** - 精美的报告格式

---

## 🎯 未来规划

### 短期目标（v1.x）

- [ ] 均衡器功能
- [ ] 睡眠定时器
- [ ] 歌词在线搜索
- [ ] 浅色主题
- [ ] 文件拖拽添加
- [ ] 播放队列管理

### 中期目标（v2.x）

- [ ] 在线音乐搜索
- [ ] 歌词同步编辑
- [ ] 社交分享功能
- [ ] 插件系统
- [ ] 云端同步
- [ ] 移动端配套应用

### 长期愿景（v3.x+）

- [ ] AI 推荐系统
- [ ] 虚拟现实界面
- [ ] 语音控制
- [ ] 协作播放列表
- [ ] 音乐社区

---

## 📝 更新日志

### v1.0.0 (2026-04-08)

**✨ 新功能**:
- ✅ 基础音频播放（MP3/WAV/FLAC）
- ✅ FFmpeg 集成（AAC/M4A/OGG/WMA/APE/Opus）
- ✅ 多音乐库管理
- ✅ 播放历史记录
- ✅ 歌词显示支持
- ✅ 专辑封面提取
- ✅ 中英文界面
- ✅ 系统托盘集成
- ✅ 全局快捷键
- ✅ 浏览窗口和喜爱音乐窗口

**🐛 Bug 修复**:
- ✅ 修复菜单空指针崩溃
- ✅ 修复托盘菜单时机问题
- ✅ 修复配置加载问题

**📚 文档**:
- ✅ 完整用户文档
- ✅ 开发者指南
- ✅ API 文档
- ✅ 故障排除指南

---

<div align="center">

**探索更多功能，立即下载体验！**

[📥 下载安装](./WEBSITE.md#-下载安装) • [🚀 快速开始](./QUICKSTART.md) • [📖 完整文档](./WEBSITE.md#-完整文档)

</div>