Spotube 下载慢或卡住——从网络到 v5.1 下载管理器的排查
Spotube 下载链路
Spotube 下载器（v5.1 已重写）做这些事：
1. AudioAPI.getAudioStream(track) → 拿到音频流 URL + codec + 支持的 HTTP range
2. 并行分块下载（多连接同时拉不同段）
3. 合并成单一音频文件
4. metadata_god 写入 ID3 标签（艺人、专辑、封面图）
5. LyricsAPI.getLyrics(track) → 保存同名 .lrc 文件
6. 标记为"已下载"任何一步失败都会导致卡住或中断。
下载卡住排查
1. 先看进度条状态
Spotube 下载管理器（设置 → Downloads）显示每个任务的状态：
| 状态 | 含义 | 下一步 |
|---|---|---|
| Pending | 排队中 | 正常，等前面的下载完成 |
| Downloading | 下载中 | 看速度是否在变（动=没问题） |
| Tagging | 正在写 ID3 标签 | 速度慢但会完成 |
| Failed | 失败 | 看错误详情，通常有说明 |
| Stopped | 手动取消 | 手动重新触发 |
2. 并行下载数和网络带宽
Spotube v5.1 并行分块下载默认用 3 个并发连接。如果你带宽不够：
- 设置 → Downloads → 把 "Download concurrency" 调到 1 或 2
- 关闭其他正在下载的任务（排队更稳定）
- 如果网络本身有抖动，下载可能会被重试——v5.1 每个块自动重试 3 次
3. 某些音频源不支持 Range 请求
并行分块下载依赖 HTTP Range header（服务器支持返回文件某一段）。某些音频源（比如某些自建 Piped 实例）不支持 Range → Spotube 退化成单连接串行下载（速度会慢很多，但不会报错）。
解法：换音频源插件（YouTube Audio 官方源肯定支持 Range）。
4. 磁盘空间不足
Spotube 下载前会检查磁盘剩余空间。目标目录剩余空间小于 下载文件大小 × 2 时（并行分块需要临时空间），会停止并报错 "Insufficient disk space"。
检查方法：
- Windows：
%USERPROFILE%\Music\Spotube Downloads\→ 属性看剩余 - macOS / Linux：Spotube 设置 → Downloads → 看 "Free space"
5. 下载后 ID3 标签丢失
v5.1.0 已知修复：Downloaded tracks are not tagged with metadata（GitHub PR #xxxx）。如果你在 v5.0.x 遇到这个问题，升级到 v5.1.0+ 即可解决。
如果升级后仍然丢失：
- 确认 MetadataSearchAPI 插件返回了完整数据（title + artists + coverImageUrl 都不为空）
- metadata_god 包对某些旧格式（如 WMA）的写入可能有问题 → 先下载成 MP3 或 FLAC
- 下载完成后去下载目录手动检查文件大小（如果只有几 KB 说明真的没写入成功）
6. Android 特定问题
Android 的 Scoped Storage（API 30+）会限制外部应用的文件访问。Spotube 默认下载到应用私有目录，可以在设置里改到 ~/Music/Spotube Downloads/（系统音乐目录，不受 Scoped Storage 限制）。
如果下载目录被系统权限锁住，Spotube 会静默失败（某些国产 ROM）。解法：手动在设置里改下载目录到系统音乐目录。
v5.1 下载管理器升级速览
| 问题 | v5.0.x 表现 | v5.1.0 修复 |
|---|---|---|
| 下载速度慢 | 单连接串行 | 并行分块下载（默认 3 连接） |
| 不同设备上下载失败 | 某些音频源在不同地区表现差异 | 加了更多重试逻辑 |
| 下载卡住不动 | 无超时，可能无限等待 | 每个块重试 3 次 + 总超时 10 分钟 |
| 下载器 UI | 只显示总进度 | 每个任务独立进度条 + 状态标签 |
| ID3 标签缺失 | 偶发（metadata_god 调用时机） | 修复写入时机，保证所有字段都写 |
手动触发重试
下载管理器里 Failed 状态的任务：
- 右键（桌面）或长按（移动）→ "Retry"
- Spotube 重新从头走一遍下载链路
- 如果重试 3 次都失败 → 大概率是该音频源插件的问题，换一个源
下载后播放失败
下载成功了但本地文件放不出来：
- 确认文件大小不是 0 或几 KB（可能是下载时出问题但没报错）
- 用系统播放器（Windows Media Player / macOS Music / VLC）打开 → 如果 VLC 也放不出来，文件本身坏了
- 如果 VLC 能放但 Spotube 不能 → 可能是 Spotube 对该格式的支持问题 → 去 GitHub Issues 搜有没有类似报告