开放 HTTP API——从外部远程控制洛雪音乐

什么是开放 API

从桌面版 v2.7.0 起，洛雪音乐支持在本地启动一个 HTTP 服务（默认端口 23330），对外提供一系列 REST 风格的接口。第三方软件、浏览器扩展、自动化脚本等可以通过这些接口：

查询当前播放状态。
控制播放 / 暂停 / 切歌 / 调节音量。
获取当前歌曲的 LRC 歌词。
订阅播放器状态变更（实时）。

启用 API 服务

打开「设置 → 开放 API」相关区块。
勾选「启用开放 API 服务」。
记下显示的服务地址（默认 http://127.0.0.1:23330）。

⚠️ 安全提示：API 服务默认只监听 127.0.0.1（本机回环），外部无法访问。不要将监听地址改成 0.0.0.0 或公网 IP——没有鉴权机制，任何人都能控制你的播放器。

接口列表

查询当前播放状态

GET /status

响应示例：

{
  "status": "playing",
  "name": "天使的翅膀",
  "singer": "徐誉滕",
  "albumName": "李雷和韩梅梅",
  "duration": 214.54,
  "progress": 15.20,
  "playbackRate": 1,
  "picUrl": "http://xxx",
  "lyricLineText": "落叶随风将要去何方"
}

常用字段：

字段	类型	说明
status	字符串	`playing` / `paused` / `error` / `stoped`
name	字符串	当前歌曲名
singer	字符串	艺术家
albumName	字符串	专辑名
duration	数字	总时长（秒）
progress	数字	当前进度（秒）
playbackRate	数字	播放速率（1 = 1 倍速）
lyricLineText	字符串	当前正在播放的那行歌词

可以传 filter 参数只获取部分字段：

GET /status?filter=status,name,lyricLineText

获取当前 LRC 歌词

GET /lyric

响应是 UTF-8 编码的纯文本 LRC 格式，比如：

[ar:安琥]
[ti:天使的翅膀]
[00:00.0]徐誉滕 - 天使的翅膀
[00:05.50]词：徐誉滕
[00:15.150]落叶随风将要去何方

获取所有类型的歌词

GET /lyric-all

有些音源脚本返回的 LRC 同时包含翻译歌词（tlyric）、罗马音歌词（rlyric）、逐字歌词（lxlyric）。这个接口返回 JSON：

{
  "lyric": "...",
  "tlyric": "...",
  "rlyric": "...",
  "lxlyric": "..."
}

播放器控制接口

接口	方法	说明	参数
`/play`	GET	播放	无
`/pause`	GET	暂停	无
`/skip-next`	GET	下一曲	无
`/skip-prev`	GET	上一曲	无
`/seek`	GET	调整进度	`offset` 参数，单位秒
`/volume`	GET	调节音量	`volume` 参数，值 1-100
`/mute`	GET	静音开关	`mute` 参数，`true` 或 `false`
`/collect`	GET	收藏当前歌曲	无
`/uncollect`	GET	取消收藏当前歌曲	无

示例：暂停播放

GET http://127.0.0.1:23330/pause

示例：跳到歌曲第 60 秒

GET http://127.0.0.1:23330/seek?offset=60

示例：设置音量为 50%

GET http://127.0.0.1:23330/volume?volume=50

使用示例

curl 测试

# 查询状态
curl http://127.0.0.1:23330/status

# 下一曲
curl http://127.0.0.1:23330/skip-next

# 暂停
curl http://127.0.0.1:23330/pause

Python 脚本

import requests

BASE = "http://127.0.0.1:23330"

# 查询当前播放状态
resp = requests.get(f"{BASE}/status")
data = resp.json()
print(f"当前播放：{data['name']} - {data['singer']}")
print(f"状态：{data['status']}")

# 下一曲
requests.get(f"{BASE}/skip-next")

Shell 脚本（播放控制）

# 暂停
curl -s http://127.0.0.1:23330/pause > /dev/null
# 下一曲
curl -s http://127.0.0.1:23330/skip-next > /dev/null

端口冲突

默认端口 23332 被独立同步服务使用了，开放 API 用的是 23330。如果你发现这个端口也被占用了，可以在设置中修改 API 端口。