ws - Metabox-Nexus-WesingCap

WebSocket 接口

`/ws` - WebSocket 连接

统一事件格式： 所有 WebSocket 和 SSE 推送的消息均使用 {"type": "事件名", "data": 载荷} 格式。
所有事件无数据时 data 均为 {}（空对象）。
下游客户端统一按 msg.type 分发，msg.data 读取载荷即可。

连接建立时立即接收以下 4 条消息（始终全部发送，无数据时 data 为 {}）：

1. `status_update` - 状态更新

有状态时：

{
  "type": "status_update",
  "data": {
    "status": "playing",
    "detail": "告白 - 花澤香菜"
  }
}

status 可能的值及含义：

"waiting_process" - K歌客户端未启动，等待用户运行 WeSing.exe

"loading" - 歌曲加载中，detail为歌曲名称

"playing" - 播放中，detail为歌曲标题（格式: 歌曲名 - 歌手）

"paused" - 暂停中（play_time 停止推进时自动检测），detail为歌曲标题

"waiting_song" - K歌窗口未打开/焦点丢失，等待用户打开或点击K歌窗口

"standby" - 待机状态，K歌客户端已退出

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

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

2. `song_info_update` - 歌曲信息更新

有歌曲信息时：

{
  "type": "song_info_update",
  "data": {
    "name": "告白",
    "singer": "花澤香菜",
    "title": "告白 - 花澤香菜"
  }
}

无歌曲信息时（K歌窗口未打开 / 已关闭）：

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

清空行为：

K歌窗口关闭时，服务主动广播 data: {} 清空歌曲信息

直接切歌（A→B）时，不会先广播空再广播B，而是直接广播B的信息

3. `lyric_update` - 实时歌词更新

播放中（有歌词时）：

{
  "type": "lyric_update",
  "data": {
    "line_index": 5,
    "text": "君に嘘をついていた",
    "timestamp": 9.0,
    "play_time": 9.15,
    "progress": 0.4167
  }
}

无歌词时（歌曲未开始 / K歌窗口已关闭）：

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

清空行为：

K歌窗口关闭时，主动广播 data: {} 清空歌词

仅在状态变化时发送一次，不会重复发送

客户端接收到 data: {} 时应清空显示的歌词内容

4. `all_lyrics` - 完整歌词列表

有歌词时：

{
  "type": "all_lyrics",
  "data": {
    "song_title": "告白 - 花澤香菜",
    "duration": 236.0,
    "play_time": 1.2,
    "count": 12,
    "lyrics": [
      {"index": 0, "time": 0.5, "text": "いつもそばにいるのに"},
      {"index": 1, "time": 2.1, "text": "ふと気付くと遠すぎて"},
      {"index": 2, "time": 3.8, "text": "手を伸ばしても届かない"}
      ...
    ]
  }
}

无歌词时（K歌窗口未打开 / 已关闭）：

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

5. `lyric_idle` - 空闲消息（歌曲播放结束）

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

注：lyric_idle 仅在歌曲播放完毕后发送，data 始终为 {}。

6. `playback_pause` - 暂停播放

当 play_time 连续多次不变时检测为暂停：

{
  "type": "playback_pause",
  "data": {
    "play_time": 45.2
  }
}

7. `playback_resume` - 恢复播放

play_time 重新推进时发送：

{
  "type": "playback_resume",
  "data": {
    "play_time": 45.2
  }
}

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

WS 完整生命周期示例

（客户端连接，K歌窗口未打开）
← {"type":"status_update","data":{"status":"waiting_song","detail":"等待打开K歌窗口"}}
← {"type":"song_info_update","data":{}}
← {"type":"lyric_update","data":{}}
← {"type":"all_lyrics","data":{}}

（用户打开K歌窗口，选择歌曲A）
← {"type":"status_update","data":{"status":"loading","detail":"有点甜"}}
← {"type":"song_info_update","data":{"name":"有点甜","singer":"汪苏泷/BY2","title":"有点甜 - 汪苏泷/BY2"}}
← {"type":"status_update","data":{"status":"playing","detail":"有点甜 - 汪苏泷/BY2"}}
← {"type":"all_lyrics","data":{"song_title":"有点甜 - 汪苏泷/BY2","duration":236.0,"play_time":0.5,"count":28,"lyrics":[...]}}
← {"type":"lyric_update","data":{"line_index":0,"text":"男：摘一颗苹果","timestamp":18.326,"play_time":18.15,"progress":0.05}}
← {"type":"lyric_update","data":{"line_index":1,"text":"男：等你从门前经过","timestamp":20.198,"play_time":20.05,"progress":0.1}}
...

（用户关闭K歌窗口）
← {"type":"status_update","data":{"status":"waiting_song","detail":"等待打开K歌窗口"}}
← {"type":"song_info_update","data":{}}
← {"type":"all_lyrics","data":{}}
← {"type":"lyric_update","data":{}}

（用户重新打开K歌窗口，选择歌曲B）
← {"type":"status_update","data":{"status":"loading","detail":"如愿"}}
← {"type":"song_info_update","data":{"name":"如愿","singer":"王菲","title":"如愿 - 王菲"}}
← {"type":"status_update","data":{"status":"playing","detail":"如愿 - 王菲"}}
← {"type":"all_lyrics","data":{"song_title":"如愿 - 王菲","duration":280.0,"play_time":0.3,"count":35,"lyrics":[...]}}
← {"type":"lyric_update","data":{"line_index":0,"text":"我在时间尽头等你","timestamp":25.5,"play_time":25.3,"progress":0.03}}
...

（用户暂停播放）
← {"type":"playback_pause","data":{"play_time":45.2}}

（用户恢复播放）
← {"type":"playback_resume","data":{"play_time":45.2}}
← {"type":"lyric_update","data":{"line_index":5,"text":"在时间里等你","timestamp":46.0,"play_time":46.1,"progress":0.16}}
...

（歌曲播放完毕）
← {"type":"lyric_idle","data":{}}

客户端使用示例（JavaScript）

空数据判断规则速查

事件类型	有数据时 `data`	无数据时 `data`	客户端判断有无数据
`status_update`	`{"status":"...","detail":"..."}`	`{}`	`msg.data && msg.data.status`
`song_info_update`	`{"name":"...","singer":"...","title":"..."}`	`{}`	`msg.data && msg.data.title`
`all_lyrics`	`{"song_title":"...","duration":N,"play_time":N,"count":N,"lyrics":[...]}`	`{}`	`msg.data && msg.data.lyrics`
`lyric_update`	`{"line_index":N,"text":"...","timestamp":N,...}`	`{}`	`msg.data && msg.data.text`
`lyric_idle`	—	`{}`（始终）	收到即为空闲
`playback_pause`	`{"play_time":N}`	—	收到即为暂停
`playback_resume`	`{"play_time":N}`	—	收到即为恢复

ws

WebSocket 接口#

/ws - WebSocket 连接#

1. status_update - 状态更新#

2. song_info_update - 歌曲信息更新#

3. lyric_update - 实时歌词更新#

4. all_lyrics - 完整歌词列表#

5. lyric_idle - 空闲消息（歌曲播放结束）#

6. playback_pause - 暂停播放#

7. playback_resume - 恢复播放#

WS 完整生命周期示例#

客户端使用示例（JavaScript）#

空数据判断规则速查#

请求参数