newToy/WEB_PLAYER_GUIDE.md

Spotify Web Player 集成指南

🎵 功能概述

现在网页已经集成了 Spotify Web Playback SDK，浏览器本身就是一个完整的 Spotify 播放器！

✨ 主要优势

1. 无需外部应用：不需要打开 Spotify 桌面应用或手机 App
2. 直接在浏览器播放：音乐直接在当前浏览器标签页播放
3. 完全控制：支持播放、暂停、切歌、音量控制等所有功能
4. 低延迟：浏览器直接播放，响应更快
5. 自动选择：登录后自动初始化并选择浏览器作为默认播放设备

🚀 使用方法

1. 授权登录

• 点击"连接 Spotify 账号"按钮
• 使用 Spotify Premium 账号登录（免费账号不支持 Web Player）
• 授权应用访问您的 Spotify 账号

2. 自动初始化

• 登录成功后，系统会自动初始化 Web Player
• 浏览器会自动注册为一个名为"音乐律动 Web Player"的播放设备
• 设备会自动被选中作为默认播放设备

3. 播放音乐

• 搜索或选择想要播放的歌曲
• 点击歌曲即可在浏览器中播放
• 使用播放控制按钮控制播放

4. 设备切换

• 点击"刷新设备"按钮可以看到所有可用设备
• "音乐律动 Web Player"就是当前浏览器
• 可以随时切换到其他设备（手机、电脑等）

🎯 技术实现

集成的组件

1. HTML

   • 引入 Spotify Web Playback SDK 脚本

   <script src="https://sdk.scdn.co/spotify-player.js"></script>
   

2. spotifyService.ts

   • initializeWebPlayer(): 初始化 Web Player
   • setupPlayer(): 配置播放器和事件监听
   • getWebPlayerDeviceId(): 获取设备 ID
   • isWebPlayerReady(): 检查播放器状态
   • disconnectWebPlayer(): 断开播放器

3. MusicRhythm.vue

   • 登录后自动初始化 Web Player
   • 自动选择 Web Player 作为默认设备
   • 页面卸载时自动清理资源

播放器事件处理

• ✅ ready: 播放器准备就绪
• ✅ not_ready: 播放器断开连接
• ✅ player_state_changed: 播放状态变化
• ✅ initialization_error: 初始化错误
• ✅ authentication_error: 认证错误
• ✅ account_error: 账号错误（如非 Premium）
• ✅ playback_error: 播放错误

📋 要求

1. Spotify Premium 账号（必需）

   • 免费账号不支持 Web Playback SDK
   • Web Player 需要 Premium 订阅

2. 现代浏览器

   • Chrome/Edge (推荐)
   • Firefox
   • Safari
   • Opera

3. 稳定的网络连接

   • 用于流式播放音乐

🔧 设备管理

设备列表显示

• 💻 电脑设备（包括 Web Player）
• 📱 手机设备
• 🔊 音箱设备
• ✓ 当前选中的设备
• ● 活跃的设备

优先级顺序

1. 浏览器 Web Player（自动选择）
2. 当前活跃的设备
3. 设备列表中的第一个设备

💡 使用建议

1. 首选 Web Player

   • 登录后会自动选择浏览器作为播放设备
   • 适合在电脑上使用，无需额外应用

2. 切换到其他设备

   • 如果想在手机或其他设备上播放
   • 点击"刷新设备"查看所有设备
   • 点击目标设备即可切换

3. 保持标签页打开

   • 播放时请保持浏览器标签页打开
   • 关闭标签页会停止播放

4. 音量控制

   • 可以通过浏览器标签页控制音量
   • 也可以通过系统音量控制

🐛 常见问题

Q: 为什么看不到 Web Player？

A: 需要 Spotify Premium 账号。免费账号不支持 Web Playback SDK。

Q: 播放时没有声音？

A: 检查：

• 浏览器是否允许自动播放
• 系统音量是否打开
• 浏览器标签页是否静音

Q: 提示"设备不可用"？

A:

• 等待几秒让 Web Player 初始化完成
• 点击"刷新设备"重新获取设备列表
• 确保网络连接正常

Q: 想在手机上播放怎么办？

A:

• 打开手机上的 Spotify 应用
• 播放任意歌曲激活设备
• 在网页上刷新设备并选择手机

🎨 用户体验

• ✅ 零配置：登录后自动初始化，无需手动设置
• ✅ 智能选择：自动选择最合适的播放设备
• ✅ 实时反馈：显示播放状态和设备信息
• ✅ 优雅降级：Web Player 不可用时自动切换到其他设备

📚 参考文档

• Spotify Web Playback SDK
• Web Playback SDK Quick Start
• Web API Authorization

🔐 权限要求

Web Player 需要以下 Spotify 权限：

• streaming - 在 Web Player 中播放音乐（必需）
• user-read-playback-state - 读取播放状态
• user-modify-playback-state - 控制播放
• user-read-currently-playing - 读取当前播放
• user-read-email - 读取用户邮箱
• user-read-private - 读取用户信息

这些权限在用户授权时会自动请求。