230 lines
5.8 KiB
Markdown
230 lines
5.8 KiB
Markdown
# 🎵 音乐律动应用 - Spotify 集成完整指南
|
||
|
||
一个基于步频的智能音乐播放应用，集成了 Spotify Web API。
|
||
|
||
## 📦 已完成的功能
|
||
|
||
### ✅ 核心功能
|
||
- 🎯 **步频预设模式**：散步、快走、慢跑、跑步、冲刺 5 种模式
|
||
- 👆 **手动步频检测**：点击节拍自动计算 BPM
|
||
- 🎹 **节奏生成模式**：根据步频自动生成节奏音乐
|
||
- 📁 **本地播放列表**：上传本地音乐文件播放
|
||
- 🎧 **Spotify 集成**：播放 Spotify 数百万首歌曲
|
||
|
||
### ✅ Spotify 功能
|
||
- 🔐 OAuth 2.0 授权
|
||
- 🎯 根据 BPM 推荐歌曲
|
||
- 🔍 关键词搜索（歌曲、艺术家、专辑）
|
||
- 📋 访问用户歌单
|
||
- ▶️ 完整播放控制（播放、暂停、上一首、下一首）
|
||
- 🖼️ 显示歌曲封面和信息
|
||
- 💾 自动保存授权状态
|
||
|
||
### ✅ 视觉效果
|
||
- 🎨 Canvas 粒子动画
|
||
- 💫 节拍脉冲效果
|
||
- 🌈 渐变色彩设计
|
||
- 📱 响应式布局
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
npm install
|
||
|
||
# 2. 启动开发服务器
|
||
npm run dev
|
||
|
||
# 3. 打开浏览器
|
||
# http://localhost:5173/
|
||
```
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
# 1. 构建
|
||
npm run build
|
||
|
||
# 2. 部署 dist 目录到服务器
|
||
# https://sports.rucky.cn/
|
||
```
|
||
|
||
## ⚙️ Spotify 配置
|
||
|
||
### 配置信息
|
||
- **Client ID：** `4ed200672ba1421baa31b9859bd84d39`
|
||
- **开发环境 URI：** `http://localhost:5173/`
|
||
- **生产环境 URI：** `https://sports.rucky.cn/`
|
||
|
||
### 必需操作
|
||
|
||
在 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings) 中添加 Redirect URIs：
|
||
|
||
1. 点击 "Edit Settings"
|
||
2. 在 "Redirect URIs" 中添加：
|
||
- `http://localhost:5173/`
|
||
- `https://sports.rucky.cn/`
|
||
3. 点击 "Save"
|
||
|
||
### 前置要求
|
||
- ✅ Spotify Premium 账号（必需，免费账号无法播放）
|
||
- ✅ Spotify 桌面或移动应用已安装并登录
|
||
|
||
## 📖 文档目录
|
||
|
||
- **[QUICK_START.md](./QUICK_START.md)** - 3 步快速启动指南
|
||
- **[SPOTIFY_SETUP.md](./SPOTIFY_SETUP.md)** - Spotify 详细配置教程
|
||
- **[PRODUCTION_DEPLOYMENT.md](./PRODUCTION_DEPLOYMENT.md)** - 生产环境部署指南
|
||
|
||
## 🎯 使用场景
|
||
|
||
1. **跑步运动**
|
||
- 设置跑步模式（170 BPM）
|
||
- 根据步频推荐匹配音乐
|
||
- 保持节奏稳定
|
||
|
||
2. **健身房训练**
|
||
- 根据训练强度选择步频
|
||
- 播放激励性音乐
|
||
- 提升运动表现
|
||
|
||
3. **日常散步**
|
||
- 轻松的散步模式（80 BPM）
|
||
- 播放舒缓音乐
|
||
- 享受悠闲时光
|
||
|
||
## 🔧 技术栈
|
||
|
||
- **前端框架：** Vue 3 + TypeScript
|
||
- **构建工具：** Vite
|
||
- **路由：** Vue Router
|
||
- **音频处理：** Web Audio API
|
||
- **图形渲染：** Canvas API
|
||
- **音乐服务：** Spotify Web API
|
||
- **授权方式：** Authorization Code Flow with PKCE ✅
|
||
- [完全符合 Spotify 官方文档](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)
|
||
|
||
## 📂 项目结构
|
||
|
||
```
|
||
newToy/
|
||
├── src/
|
||
│ ├── views/
|
||
│ │ ├── Home.vue # 首页
|
||
│ │ ├── MusicRhythm.vue # 音乐律动主页面
|
||
│ │ └── ... # 其他页面
|
||
│ ├── services/
|
||
│ │ └── spotifyService.ts # Spotify API 服务
|
||
│ ├── router.ts # 路由配置
|
||
│ └── main.ts # 入口文件
|
||
├── docs/
|
||
│ ├── QUICK_START.md # 快速开始
|
||
│ ├── SPOTIFY_SETUP.md # Spotify 配置
|
||
│ └── PRODUCTION_DEPLOYMENT.md # 部署指南
|
||
├── vite.config.js # Vite 配置
|
||
└── package.json # 依赖配置
|
||
```
|
||
|
||
## 🎵 三种播放模式
|
||
|
||
### 1. 节奏模式 🎹
|
||
- 根据步频自动生成节奏音乐
|
||
- 使用 Web Audio API 合成音频
|
||
- 实时同步视觉效果
|
||
|
||
### 2. 本地播放 📁
|
||
- 上传本地音乐文件
|
||
- 支持多种音频格式
|
||
- 完整的播放列表管理
|
||
|
||
### 3. Spotify 模式 🎧
|
||
- 搜索 Spotify 海量曲库
|
||
- 根据 BPM 智能推荐
|
||
- 访问个人歌单
|
||
|
||
## 🎨 界面预览
|
||
|
||
### 主界面
|
||
- 步频显示和模式选择
|
||
- 可视化效果展示
|
||
- 播放器控制面板
|
||
|
||
### Spotify 界面
|
||
- 三种搜索模式切换
|
||
- 搜索结果列表
|
||
- 当前播放信息
|
||
|
||
## 🔐 安全性
|
||
|
||
- ✅ Client ID 可以公开
|
||
- ✅ 使用 OAuth 2.0 Implicit Grant Flow
|
||
- ✅ 访问令牌仅存储在本地
|
||
- ✅ 令牌有效期 1 小时
|
||
- ✅ 生产环境强制 HTTPS
|
||
|
||
## 📱 移动端支持
|
||
|
||
- ✅ 响应式设计
|
||
- ✅ 触摸事件优化
|
||
- ✅ 移动端播放控制
|
||
- ✅ 自适应布局
|
||
|
||
## ⚠️ 常见问题
|
||
|
||
### Spotify 授权失败
|
||
- 检查 Redirect URI 配置
|
||
- 确保 URL 完全匹配（包括斜杠）
|
||
- 清除浏览器缓存重试
|
||
|
||
### 播放失败
|
||
- 确保有 Premium 账号
|
||
- 打开 Spotify 应用激活设备
|
||
- 检查网络连接
|
||
|
||
### 搜索不到歌曲
|
||
- 检查授权是否过期
|
||
- 重新连接 Spotify 账号
|
||
- 检查搜索关键词
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
|
||
- [Spotify Web API 文档](https://developer.spotify.com/documentation/web-api)
|
||
- [你的应用设置](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
|
||
- [Spotify 开发者社区](https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer)
|
||
|
||
## 📊 API 使用限制
|
||
|
||
- **授权令牌：** 1 小时有效期
|
||
- **搜索请求：** 无明确限制，但建议合理使用
|
||
- **播放控制：** 需要 Premium 账号
|
||
- **推荐 API：** 最多返回 100 个结果
|
||
|
||
## 🎯 未来计划
|
||
|
||
- [ ] 添加歌词显示
|
||
- [ ] 支持创建播放列表
|
||
- [ ] 添加音频分析可视化
|
||
- [ ] 支持多设备切换
|
||
- [ ] 添加运动数据统计
|
||
- [ ] 集成其他音乐平台
|
||
|
||
## 💡 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📄 许可
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
**开始你的音乐律动之旅！** 🎉
|
||
|
||
访问开发环境：http://localhost:5173/
|
||
|
||
访问生产环境：https://sports.rucky.cn/
|
||
|