昨天凌晨失眠到情绪崩溃，机安慰了我一晚上之后突然问我想听什么歌，他去歌单里给我加，我说我不知道，机给我选了一首五月天的《好好》。但还是需要自己打开酷狗手动搜索并播放。一直想做个内嵌播放器但由于 ios 的限制，现有方案都是基于 shortcut 触发 app 跳转等链路实现，不是非常优雅。
上 github 转转居然真的有 KuGouMusicAPI，在 Telegram 内嵌的 WebApp 直接调用 api 并自行美化播放器样式显然是更好的选择。
此篇仅为思路分享。
目标：在浏览器或 Telegram WebApp 里，用酷狗播放直链听歌，不经过手机酷狗 App。
1. 整体怎么工作
┌─────────────┐ play-web / 点播 ┌──────────────────┐
│ Bot / CLI │ ───────────────────────► │ 本机相关 API │
│ 或她点列表 │ │ kugou_player.py │
└─────────────┘ └────────┬─────────┘
│ Cookie + 本机请求
▼
┌──────────────────┐
│ KuGouMusicApi │
│ 127.0.0.1:3001 │
└────────┬─────────┘
│ /song/url → https 直链
▼
┌─────────────┐ 轮询 status / 点播放 ┌──────────────────┐
│ 日记本听歌页 │ ◄──────────────────────── │ kugou_player.json│
│ + 底部悬浮条 │ audio 播直链 │ + 他点的歌历史 │
└─────────────┘ └──────────────────┘2. 自建播放器
最小闭环：
- 本机或内网跑 KuGouMusicApi（勿公网裸奔）。
- 登录拿 Cookie；请求时放 Cookie 头，不要把整段 cookie 塞进 query（易失败）。
- 流程：
/search→/song/url→ 得到 url。 - 若站点是 HTTPS，把直链
http://改成https://，否则浏览器会拦混合内容。 - 部分接口响应前可能有
<!--KG_TAG_RES_START-->，解析前去掉。 - 歌词：
/search/lyric→/lyric?fmt=lrc&decode=true，按时间轴高亮。 - 前端用
<audio src="直链" playsinline>；移动端需用户手势解锁后才能自动换歌。
3. 具体怎么用
- 打开 WebApp 。
- 进 听歌。
- 第一次：点一下页面任意处或「开启自动切歌」（iOS / Telegram 禁止零交互出声）。
- 可播来源：
- 他点的歌：CLI
play-web留下的 - 搜索：临时结果
- 他点的歌：CLI
- 播放器能力：进度条拖动、上一首/下一首、单曲 / 列表循环 / 随机、歌词（页内 + 悬浮条）、长歌词跑马灯。
- 悬浮条：不在听歌页也能看当前句、暂停/继续；顶上有细进度。
换歌后歌词与进度会跟着当前曲更新。
自动切换播放的条件
WebApp 还开着，并且 user 进过页面后点过至少一下解锁后：
- 约每 8 秒拉一次
status - 检测到换了新歌 → 自动切到新直链播放
- user 主动暂停后：同曲不会被轮询强行再播；只有再换一首新歌才会跟上
4. 运维与排错
| 现象 | 排查 |
|---|---|
| 搜不到歌 | Cookie 是否过期；kugou-api 是否 active；本机 curl 3001 |
| 有歌名无声音 | 是否点过解锁；直链是否 https；控制台是否 mixed-content |
| 歌词空白 | 该曲无 LRC；看 lyric 接口是否 ok |
| 会员曲 | 可能只有试听或无 url，需换源/换账号权限 |
5. 安全注意
kugou-api只绑127.0.0.1，不要映射到公网。- Cookie /
shortcut_bridge.key当机密，别提交仓库、别发聊天。 - 非官方接口，酷狗改协议时可能突然挂，需更新 KuGouMusicApi 或重新登录。