203 lines
7.2 KiB
Markdown
203 lines
7.2 KiB
Markdown
# 音乐播放器 - 波形图可视化
|
||
|
||
一个现代化的音乐播放器，具有实时波形图可视化功能。支持文件夹播放、多种循环模式和丰富的键盘快捷键。使用 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 让音频可视化成为可能
|
||
|
||
---
|
||
|
||
**享受音乐，享受代码！** 🎶✨
|