From a93f7e4ff5fc36216346bba4de84faaf8c0842ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E4=B9=BE?= Date: Fri, 30 Jan 2026 14:18:15 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 203 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 201 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ed1b68b..17326c0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,202 @@ -# audio-player +# 音乐播放器 - 波形图可视化 -音乐播放器 - 波形图可视化 \ No newline at end of file +一个现代化的音乐播放器，具有实时波形图可视化功能。支持文件夹播放、多种循环模式和丰富的键盘快捷键。使用 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 让音频可视化成为可能 + +--- + +**享受音乐，享受代码！** 🎶✨