Spotube 连接 Spotify——导入播放列表与同步收藏
Spotube 与 Spotify 的关系
Spotube 不是 Spotify 的客户端（不能播放 Spotify Premium 曲目），但它可以用 Spotify 的元数据 API——不登录也能搜索，登录后能导入个人播放列表和收藏。这是 Spotube 最受欢迎的使用方式："用 Spotify 元数据 + YouTube 音频流"。
OAuth 授权流程
Spotube 通过 Spotify Metadata 插件走标准的 Spotify Web API OAuth 流程：
- Spotube 内置了一个 Spotify Developer Dashboard 注册的应用（Client ID + Secret）
- 插件页面点 "Connect Spotify →"
- Spotube 弹出系统浏览器 → 跳转到 Spotify 登录页
- 输入 Spotify 账号密码 → 授权
- Spotify 回调带临时 auth code 到 Spotube 的 redirect URL
- 插件拿到 code → 调 Spotify API 换 access token + refresh token
- Token 用 flutter_secure_storage 加密存储在本地（iOS 用 Keychain、Android 用 KeyStore、桌面用 DPAPI / Keychain）
Token 有效期约 1 小时，Spotube 自动用 refresh token 续期——用户不需要重新登录。
自动导入什么
Spotube 在登录成功后自动导入：
| 导入内容 | 数量上限 | 来源 API |
|---|---|---|
| 个人播放列表（自己创建的） | 全部（Spotify API 上限 50/请求，Spotube 自动翻页） | GET /me/playlists |
| 关注的播放列表 | 全部 | 同上 |
| 收藏曲目（Liked Songs） | 全部 | GET /me/tracks |
| 收藏专辑 | 全部 | GET /me/albums |
| 关注的艺人 | 全部 | GET /me/following?type=artist |
Spotube 创建本地副本，存在 Drift（reactive SQLite）数据库里。
实时同步
Spotube 不做实时同步（Spotify 没有 webhook 推送新播放列表变化）。Spotube 的同步策略是：
- 手动触发：Spotify 连接页有 "Sync now" 按钮 → 每次全量对比更新
- 定期提醒：Spotube 每隔 7 天提示一次"是否要同步 Spotify"（可关闭）
- 本地优先：同步只影响 Spotube 里的 Spotify 来源播放列表，Spotify 侧不会被改动（Spotube 只读 Spotify，不写）
⚠️ Spotube 没有双向同步——你在 Spotube 里新建或修改播放列表，不会推送到 Spotify。这是 Spotify Web API 的限制（Spotube 无法替你写回 Spotify）。
用 Spotify 元数据但不登录
Spotify Metadata 插件支持匿名使用：
- 不登录时可以搜索曲目、专辑、歌手、分类歌单（Spotify Web API 的公开搜索 endpoint 不需要登录）
- 可以浏览 Spotify 公开的热门榜和编辑精选
- 但无法访问个人数据（Liked、个人播放列表、Discover Weekly）
多个 Spotify 账号
Spotube 支持同时连接多个 Spotify 账号（少见需求，但有人用）。每个账号的 token 独立存储、独立显示在 Spotube 里，搜索时所有已连接账号的权限合并。
退出 / 撤销连接
- Spotube 设置 → Spotify Metadata → "Disconnect"
- Spotube 删除本地 token、删除从该账号导入的所有播放列表
- 建议同时到 Spotify 网页端 "Account → Apps" 手动撤销 Spotube 的授权
常见问题
登录后发现播放列表没完全导入
Spotify Web API 的 /me/playlists 默认返回 50 条。Spotube 会自动翻页，但如果你的网络较慢，可能需要多等一会或手动点 "Sync now"。
Spotify token 过期导致搜索失败
Spotube 有自动 refresh 机制，但 refresh token 本身也会过期（通常半年到一年）。过期后需要重新走 OAuth 流程。Spotube 会在失败时自动弹出重新登录提示。
发现同名曲目在不同播放列表里都有重复条目
Spotube 不做跨播放列表去重——Spotify API 返回的每个列表里的曲目都是独立对象，Spotube 原样导入。这是 Spotube 目前的行为，可能在未来版本改进。