WebSocket 连接（根端点，跟随活跃播放器）

WebSocket 实时双向通信接口。连接后跟随当前活跃播放器接收所有事件。

注意： 此端点实际为 WebSocket 协议（ws://），在 OpenAPI 中以 GET 方式描述。导入 Apifox 后请手动修改接口类型为 WebSocket。

统一事件格式： 所有 WebSocket 和 SSE 推送的消息均使用 {"type": "事件名", "player": "播放器名", "data": 载荷} 格式。
无数据时 data 为 {}（空对象）。例外：all_lyrics 在平台未返回歌词时仍是完整对象——lyrics 为空数组、count 为 0，而 title / duration 照常有值。
下游客户端统一按 msg.type 分发，msg.player 识别来源，msg.data 读取载荷即可。

初始化行为： 若连入时存在活跃播放器，会按顺序补发该播放器当前缓存的 status_update → song_info_update → all_lyrics → lyric_update。只补发缓存中已存在的类型——某类型尚无缓存数据时，该条不发送（并非发一条 data:{}）。若连入时当前没有活跃播放器，则只收到一个 player_clear 初始事件。

连接建立时补发的缓存事件（下面逐一说明每种类型的格式）：

1. status_update - 状态更新

有状态时：

{"type":"status_update","player":"wesing","data":{"status":"playing","detail":"晚风 - 陈婧霏"}}

无状态时（服务刚启动尚未获取到状态）：

{"type":"status_update","player":"wesing","data":{}}

status 可能的值及含义：

"waiting_process" - 播放器进程未启动

"waiting_song" - 播放器已启动但未选择歌曲

"loading" - 保留值：当前版本各播放器均不产出此状态（wesing 的 loading 发送已停用，其余四家不产生），下游可不为它单独处理

"playing" - 播放中，detail 为歌曲标题。拼接顺序按播放器而异（wesing / cloudmusicv3 / qqmusic 为 歌曲名 - 歌手，kugou / sodamusic 为 歌手 - 歌曲名），详见 SongInfo.title

"paused" - 暂停中，detail 为歌曲标题。同时会收到一条 playback_pause 事件

"standby" - 待机状态。detail 按播放器而异：cloudmusicv3 为 "网易云音乐已退出" 或 "网易云音乐 v<版本号> 不支持（需 v3+）"（后者表示进程仍在运行、仅版本过低，该状态每 30 秒重发一次且不去重，版本号为实际读到的值）；qqmusic 为 "QQ音乐已退出"；wesing 为 "K歌客户端已退出"；kugou 为 "酷狗音乐 CDP 已断开"；sodamusic 为 "汽水音乐 CDP 已断开"。kugou 例外：切歌瞬间还会多发一条 standby、detail 是新歌标题，约 200 毫秒后即被 song_info_update 覆盖——这是当前实现的缺陷、不属契约，下游不应据此进入待机界面，可用 detail 是否匹配上述固定文案来区分

"error" - 故障终态，仅 kugou 会产生："未找到酷狗安装，已停止" / "酷狗 libcef.dll 版本不受支持，已停止" / "未取得管理员权限，已停止自动修复"。detail 为具体原因，此后该播放器停止自动修复、不再变更状态

2. song_info_update - 歌曲信息更新

有歌曲信息时：

{"type":"song_info_update","player":"wesing","data":{"name":"晚风","singer":"陈婧霏","title":"晚风 - 陈婧霏","cover":"http://imgcache.qq.com/music/photo/mid_album_800/r/k/003JA09X2m9xrk.jpg","cover_base64":"data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}

无歌曲信息时：

{"type":"song_info_update","player":"wesing","data":{}}

异步封面： 部分播放器的封面 base64 通过异步 HTTP 下载获取。歌曲开始播放时会先发送一条不含 cover_base64 的 song_info_update（仅含 cover URL），待封面下载完成后再补发一条含 cover_base64 的完整版本。前端应使用最新收到的数据覆盖即可。

3. lyric_update - 实时歌词更新

播放中（有歌词时）：

{"type":"lyric_update","player":"wesing","data":{"index":1,"text":"往事就像流星刹那划过心房","sub_text":"","timestamp":31.483,"play_time":31.282999,"position":31.282999,"progress":0.105743244,"text_detailed":{}}}

无歌词时：

{"type":"lyric_update","player":"wesing","data":{}}

4. all_lyrics - 完整歌词列表

有歌词时：

{"type":"all_lyrics","player":"wesing","data":{"title":"都是夜归人 - 许美静","duration":296,"position":1.75,"progress":0.0059121624,"count":38,"lyrics":[{"index":0,"timestamp":25.44,"play_time":25.24,"text":"是冰冻的时分 已过夜深的夜晚","sub_text":"","text_detailed":{}},{"index":1,"timestamp":31.483,"play_time":31.282999,"text":"往事就像流星刹那划过心房","sub_text":"","text_detailed":{}},{"index":2,"timestamp":37.716,"play_time":37.516,"text":"灰暗的深夜 是寂寞的世界","sub_text":"","text_detailed":{}}],"lyrics_detailed":[]}}（lyrics 已裁剪至 3 行，实际 38 行）

无歌词时：

{"type":"all_lyrics","player":"wesing","data":{}}

5. lyric_idle - 歌词空闲通知

仅 wesing 发送此事件——cloudmusicv3 / qqmusic / kugou / sodamusic 不产生 lyric_idle，接这四家的下游不应等待它。

wesing 在歌曲播放结束、切歌或窗口关闭时发送：

{"type":"lyric_idle","player":"wesing","data":{}}

纯通知事件，data 始终为 {}。前端可自行决定是否响应。

6. playback_pause - 暂停播放

播放暂停时发送。data.position 为暂停时刻的整曲播放位置（秒），data.progress 为对应进度：

{"type":"playback_pause","player":"wesing","data":{"position":31.282999,"progress":0.105743244}}

7. playback_resume - 恢复播放 / 跳转

position 发生非连续跳变时发送，两种情形都会触发：从暂停中恢复播放；以及 seek / 拖动进度条。
后者的 position 是跳转后的新位置，可能小于上一次的值。

因此本事件不保证与 playback_pause 成对出现，实际收到的 playback_resume 通常多于 playback_pause。

{"type":"playback_resume","player":"wesing","data":{"position":37.516,"progress":0.1268581}}

前端收到 playback_pause 应停止时间插值，收到 playback_resume 应以 position 为锚点重新开始插值。

8. player_switch - 播放器切换（仅根订阅者收到）

当活跃播放器发生变化时，根订阅者（/ws）会收到此事件：

{"type":"player_switch","player":"cloudmusicv3","data":{"from":"wesing","to":"cloudmusicv3"}}

player 字段为切换后的新播放器

from - 切换前的播放器标识名

to - 切换后的播放器标识名（为空字符串 "" 时表示活跃播放器已清除，无播放器输出）

Per-player 订阅者（如 /wesing/ws）不会收到此事件

当 to 非空时，紧随其后会收到新播放器的已缓存状态事件（status_update + song_info_update + all_lyrics + lyric_update 中已有的部分）

9. player_clear - 活跃播放器清除（仅根订阅者收到）

当所有播放器都停止输出（全员 inert）时，根订阅者收到此事件，表示应清空显示：

{"type":"player_clear","player":"","data":{}}

运行中活跃播放器被清空时，与 player_switch(to="") 一起发送（双重通知，向后兼容）

连接建立时若当前已无活跃播放器，则作为初始事件单独发送（此时没有配对的 player_switch）

前端应清空歌词、封面、进度等所有显示内容

Per-player 订阅者（如 /wesing/ws）不会收到此事件

WS 完整生命周期示例（取自真实录音，lyrics / lyrics_detailed 内容以 ... 略去）：

（客户端连入根端点 /ws，当前没有活跃播放器）
← {"type":"player_clear","player":"","data":{}}

（wesing 开始播放，触发从「无活跃播放器」到 wesing 的切换）
← {"type":"player_switch","player":"wesing","data":{"from":"","to":"wesing"}}
← {"type":"status_update","player":"wesing","data":{"status":"playing","detail":"晚风 - 陈婧霏"}}
← {"type":"song_info_update","player":"wesing","data":{"name":"晚风","singer":"陈婧霏","title":"晚风 - 陈婧霏","cover":"http://imgcache.qq.com/music/photo/mid_album_800/r/k/003JA09X2m9xrk.jpg","cover_base64":""}}
← {"type":"all_lyrics","player":"wesing","data":{"title":"晚风 - 陈婧霏","duration":176,"position":0,"progress":0,"count":34,"lyrics":[...],"lyrics_detailed":[]}}

（封面异步下载完成，补发第二条 song_info_update，此时 cover_base64 有值）
← {"type":"song_info_update","player":"wesing","data":{"name":"晚风","singer":"陈婧霏","title":"晚风 - 陈婧霏","cover":"http://imgcache.qq.com/music/photo/mid_album_800/r/k/003JA09X2m9xrk.jpg","cover_base64":"data:image/jpeg;base64,..."}}

（随播放进度逐行推送 lyric_update，格式见 /lyric_update 端点）

（用户暂停 / 恢复；resume 也可由拖动进度条触发）
← {"type":"playback_pause","player":"wesing","data":{"position":32.2,"progress":0.105743244}}
← {"type":"playback_resume","player":"wesing","data":{"position":32.25,"progress":0.1268581}}

（wesing 歌曲播放结束 / 切歌 / 窗口关闭——lyric_idle 仅 wesing 发送）
← {"type":"lyric_idle","player":"wesing","data":{}}

（K歌客户端退出）
← {"type":"status_update","player":"wesing","data":{"status":"standby","detail":"K歌客户端已退出"}}

客户端使用示例（JavaScript）：

WebSocket 连接（根端点，跟随活跃播放器）

请求参数

请求示例代码

返回响应