# 音乐播放器 - 波形图可视化

一个现代化的音乐播放器，具有实时波形图可视化功能。支持文件夹播放、多种循环模式和丰富的键盘快捷键。使用 Web Audio API 和 Canvas 技术实现音频分析和可视化效果。

## 🎵 功能特性

### 核心播放功能
- ✅ **本地音乐文件播放** - 支持 MP3、WAV、OGG、M4A、FLAC、AAC 等格式
- 📁 **文件夹播放** - 支持选择整个文件夹，自动循环播放
- 🔄 **多种播放模式**：
  - 🔁 列表循环（默认）- 播放完最后一首回到第一首
  - 🔂 单曲循环 - 重复播放当前曲目
  - 🔀 随机播放 - 随机选择下一首
- ⏭️ **播放控制** - 上一首、下一首、播放/暂停、停止

### 可视化效果
- 📊 **三种可视化模式**：
  - 条形图频谱 - 经典频谱分析仪效果
  - 波形图 - 实时音频波形显示
  - 圆形频谱 - 现代化圆形频谱效果，圆心居中显示
- 🎯 **圆心居中** - 圆形图圆心准确位于画布中央
- 📏 **自适应大小** - 可视化效果根据画布尺寸自动调整

### 用户界面
- 📈 **实时进度条** - 可拖动跳转，显示当前时间和总时长
- 🔊 **智能音量控制**：
  - 0-30%：🔈 低音量图标
  - 30-70%：🔉 中音量图标  
  - 70-100%：🔊 高音量图标
  - 静音：🔇 静音图标
- 🎨 **现代化界面** - 渐变背景、毛玻璃效果、流畅动画
- 📱 **响应式设计** - 完美适配桌面端和移动端

### 交互体验
- 🖱️ **直观操作** - 所有控制按钮都有悬停提示
- 🔄 **无缝切换** - 切换歌曲时自动播放
- 💡 **视觉反馈** - 模式切换、操作反馈等动画效果
- ⌨️ **丰富快捷键** - 支持键盘操作，提升效率

## 🛠️ 技术栈

- **Vite** - 快速的前端构建工具
- **Web Audio API** - 音频处理、分析和频谱数据获取
- **Canvas API** - 实时波形图绘制和可视化效果
- **File API** - 本地文件和文件夹读取
- **原生 JavaScript** - 无需额外依赖，轻量级实现
- **CSS3** - 现代化渐变、毛玻璃效果和响应式动画
- **HTML5** - 语义化标签和现代Web标准

## 🚀 使用方法

### 1. 选择音乐
- **单个文件**：点击"选择音乐文件"按钮，选择本地音频文件
- **整个文件夹**：点击"选择音乐文件夹"按钮，选择包含音频文件的文件夹

### 2. 播放控制
- **▶️/⏸️ 播放/暂停**：开始或暂停播放
- **⏹️ 停止**：停止播放并重置到开始位置
- **⏮️ 上一首**：切换到播放列表中的上一首（文件夹模式）
- **⏭️ 下一首**：切换到播放列表中的下一首（文件夹模式）

### 3. 播放模式（文件夹模式）
- **🔁 列表循环**（默认）：播放完最后一首后回到第一首
- **🔂 单曲循环**：重复播放当前曲目
- **🔀 随机播放**：随机选择下一首
点击播放模式按钮可循环切换

### 4. 可视化效果
- **🎨 切换可视化**：在三种波形图效果之间切换
- **条形图频谱**：经典频谱分析仪效果
- **波形图**：实时音频波形显示  
- **圆形频谱**：现代化圆形频谱效果，圆心居中显示

### 5. 进度和音量控制
- **进度条**：可拖动跳转，显示当前时间和总时长
- **音量滑块**：精确调节音量（0-100%）
- **音量图标**：根据音量大小动态变化（🔇🔈🔉🔊）
- **一键静音**：点击音量图标快速静音/取消静音

### 6. 键盘快捷键
- **空格键**：播放/暂停
- **M键**：静音/取消静音
- **P键**：上一首（文件夹模式）
- **N键**：下一首（文件夹模式）
- **↑↓键**：增加/减少音量
- **←→键**：快退/快进5秒
- **Ctrl+←/→**：上一首/下一首（文件夹模式）

## ✨ 功能亮点

### 🎵 智能播放
- **文件夹播放**：支持选择整个音乐文件夹，自动创建播放列表
- **无缝切换**：切换歌曲时自动播放，无需手动操作
- **多种循环**：列表循环、单曲循环、随机播放三种模式
- **格式支持**：支持 MP3、WAV、OGG、M4A、FLAC、AAC、WMA、OPUS、WebM 等主流格式

### 📊 专业可视化
- **实时频谱**：基于 Web Audio API 的实时音频分析
- **三种模式**：条形图、波形图、圆形频谱，各具特色
- **性能优化**：智能帧率控制，流畅不卡顿
- **自适应布局**：圆形图圆心始终居中，大小自适应

### 🎮 人性化交互
- **直观操作**：所有控制按钮都有悬停提示
- **键盘支持**：丰富的快捷键，提升操作效率
- **视觉反馈**：模式切换、操作成功都有动画反馈
- **响应式设计**：完美适配手机、平板、桌面各种设备

### 🔧 技术特色
- **现代架构**：基于 Vite 构建，开发体验优秀
- **零依赖**：纯原生 JavaScript，无需外部库
- **模块化**：代码结构清晰，易于维护和扩展
- **错误处理**：完善的错误处理和用户提示

## 🔄 版本更新

### v2.0.0 (最新版本)
- ✅ **新增文件夹播放功能** - 支持选择整个音乐文件夹
- 🔄 **新增多种播放模式** - 列表循环、单曲循环、随机播放
- ⏭️ **新增上一首/下一首控制** - 完整的播放列表导航
- 🎹 **扩展键盘快捷键** - 支持 P/N 键和 Ctrl+方向键
- 🎯 **优化圆形图显示** - 圆心居中，大小适中
- 🔧 **改进音频上下文管理** - 更稳定的切换和播放体验
- 📱 **增强移动端适配** - 更好的响应式设计

### v1.0.0
- 🎵 基础音乐播放功能
- 📊 三种波形图可视化模式
- 🎮 完整的播放控制
- 🔊 智能音量控制
- 📱 基础响应式设计

## 🌐 浏览器兼容性

- **Chrome/Edge**: ✅ 完全支持（推荐）
- **Firefox**: ✅ 完全支持
- **Safari**: ✅ 完全支持（可能需要用户交互启动音频）
- **移动端浏览器**: ✅ 支持触摸操作和响应式布局

> **注意**：由于浏览器安全策略，音频播放可能需要用户交互（如点击）才能自动开始。

## 📁 项目结构

```
audio-player/
├── src/
│   ├── main.js              # 主播放器逻辑和UI控制
│   ├── waveformVisualizer.js # 音频可视化核心算法
│   ├── style.css            # 现代化样式和动画
│   ├── counter.js           # 计数器示例（可忽略）
│   └── javascript.svg       # JS图标
├── public/
│   └── vite.svg            # Vite图标
├── index.html              # 主HTML文件
├── package.json            # 项目配置
├── vite.config.js          # Vite构建配置
└── README.md               # 项目文档
```


## 🚀 快速开始

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

### 构建项目

```bash
npm run build
```

### 预览构建结果

```bash
npm run preview
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！如果您有任何改进建议或发现了bug，请随时告诉我们。

## 📄 许可证

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

## 🙏 致谢

- 感谢 [Vite](https://vitejs.dev/) 提供优秀的构建工具
- 感谢 Web Audio API 和 Canvas API 让音频可视化成为可能

---

**享受音乐，享受代码！** 🎶✨