Lyrion Music Server 9.1.1 CLI 命令详解
基于 Lyrion Music Server 9.1.1 实测：9090 端口 telnet CLI 的接入规范、? 占位符语法、URL 编码规则与服务器/播放器/播放列表/媒体库全命令矩阵。
Lyrion Music Server 9.1.1 CLI 命令详解
目标：完整梳理 Lyrion Music Server 9.1.1 的 telnet CLI（9090 端口）命令体系——接入方式、查询/动作两种语法、URL 编码规则，并按「服务器信息、播放器枚举、播放控制、播放列表、媒体库浏览、收藏」六个命令域给出实测回显与语义解读。本文全部回显均在真实部署环境逐条执行取得，可直接作为自动化脚本的对照基线。
一、环境信息
| 项目 | 值 | 说明 |
|---|---|---|
| 组件版本 | Lyrion Music Server 9.1.1 | CLI version ? 实测回显 |
| CLI 端口 | 9090（TCP） | telnet 协议语义，换行终止命令 |
| 部署形态 | 按《Lyrion Music Server 9.1.1 Docker Compose 部署指南》部署 | 该形态下 9090 映射到宿主 8130，客户端改连 8130，命令与回显完全一致 |
| 实测播放器 | G23-TestPlayer（squeezelite 2.0.0-1517） | 播放器 ID 04:53:82:81:67:39 |
| 实测客户端 | 3 个（squeezelite ×2、HTTP 软件客户端 ×1） | player count ? 实测回显 3 |
| 曲库规模 | 5 专辑 / 5 艺术家 / 3 流派 / 10 首曲目 / 总时长 343.111 秒 | info total * ? 实测 |
二、工具概览
9090 端口的 CLI 是 LMS 的完整控制面：Web 界面能做的操作，CLI 都有对应命令，因此它是家庭自动化、监控脚本与批量运维的首选接口。三个基础规范，先于一切命令：
1. 两种语法形态：查询带 ?，动作不带。
$ telnet 127.0.0.1 9090
version ?
version 9.1.1
version ? 是查询（? 是占位符，回显填入实际值）。不带 ? 的 version 是「设置」语义，服务器把它当作赋值动作而不返回值——实测发送 version 后无任何回显。这是本 CLI 最常见的入门坑，规则总结：
| 形态 | 语义 | 回显 |
|---|---|---|
version ? | 查询版本 | version 9.1.1 |
version（无参数无 ?） | 无意义赋值 | 无回显 |
04:53:82:81:67:39 mode ? | 查询播放状态 | 04%3A...%3A39 mode play |
04:53:82:81:67:39 play | 执行播放动作 | 04%3A...%3A39 play（命令回显） |
2. URL 编码规则。 所有回显中的特殊字符一律 URL 编码：: → %3A、/ → %2F、空格 → %20、? → %3F。播放器 ID 的冒号在回显中呈现为 04%3A53%3A82%3A81%3A67%3A39，输入侧可直写冒号（服务端兼容明文），阅读回显时按上表反解。
3. 逐行应答。 每条命令一行回显，以换行结束；一条连接内可连续发送多条命令，顺序应答，适合流水线脚本（nc/socket 均可，见第四章）。
三、前置条件
- 服务端可达且 CLI 端口开放（9090，或部署映射端口 8130）。
- 已有至少一个播放器注册（软播放器接入方法见部署篇 4.3 节）。
- 客户端工具任选其一：
telnet（交互式）、nc/netcat（脚本式）、编程语言 socket。脚本场景注意逐条发送、逐条收包的节奏控制（本文实测探针采用「发送后等待 0.6-1.5 秒再收包」的简单节奏，稳定可靠）。
四、命令详解
以下示例统一使用实测环境的播放器 ID 04:53:82:81:67:39，回显为原始输出照抄（URL 编码形态）。
4.1 服务器信息域
version ? — 服务端版本：
version ?
version 9.1.1
serverstatus <起始条数> <每页条数> — 服务器全量状态（版本、UUID、库统计、播放器列表一网打尽），实测回显节选：
serverstatus 0 3
serverstatus 0 3 lastscan%3A1793207612 version%3A9.1.1 uuid%3A3aa0429b-d91a-4e17-867b-f8592d39cab5 ip%3A10.89.56.2 httpport%3A9000 info%20total%20albums%3A5 info%20total%20artists%3A5 info%20total%20genres%3A3 info%20total%20songs%3A10 info%20total%20duration%3A343.111 player%20count%3A3 playerindex%3A0 playerid%3A04%3A53%3A82%3A81%3A67%3A39 uuid%3A ip%3A10.89.56.3%3A47584 name%3AG23-TestPlayer seq_no%3A0 model%3Asqueezelite modelname%3ASqueezeLite power%3A1 isplaying%3A0 displaytype%3Anone isplayer%3A1 canpoweroff%3A1 connected%3A1 firmware%3A2.0.0-1517 ...
解读：lastscan 是最近一次扫描的 Unix 时间戳；info total * 五项即库统计；随后内联播放器条目（字段与 players 命令相同）。做监控探针时，一条 serverstatus 0 1 就能同时拿到服务端存活、版本与库规模。
info total <对象> ? — 库统计，五连发实测：
info total genres ?
info total genres 3
info total artists ?
info total artists 5
info total albums ?
info total albums 5
info total songs ?
info total songs 10
info total duration ?
info total duration 343.111
rescan / wipecache — 扫描控制：rescan 触发增量扫描（回显 rescan done），wipecache 清空库缓存（配合 rescan 完成全量重建）。用法与生效细节见《Lyrion Music Server 9.1.1 配置参数详解》5.1 节。
pref 域 — 参数读写（语法与回显细节见配置篇 3.1 节）：
pref httpport ?
pref httpport 9000
pref language ?
pref language EN
4.2 播放器枚举与属性域
players <起始条数> — 播放器清单，实测回显（三个客户端，节选）：
players 0
players 0 count%3A3 playerindex%3A0 playerid%3A04%3A53%3A82%3A81%3A67%3A39 uuid%3A ip%3A10.89.56.3%3A49446 name%3AG23-TestPlayer seq_no%3A0 model%3Asqueezelite modelname%3ASqueezeLite power%3A1 isplaying%3A0 displaytype%3Anone isplayer%3A1 canpoweroff%3A1 connected%3A1 firmware%3A2.0.0-1517 playerindex%3A1 playerid%3A10.89.56.1 uuid%3A ip%3A10.89.56.1%3A48220 name%3Acurl%20from%2010.89.56.1 seq_no%3A0 model%3Ahttp modelname%3AWeb%20Client power%3A1 isplaying%3A0 isplayer%3A0 canpoweroff%3A0 connected%3A0 firmware%3A ...
逐字段解读（第一个条目）：
| 字段 | 值（解码后） | 含义 |
|---|---|---|
| count | 3 | 当前注册的播放器总数（含 HTTP 客户端） |
| playerid | 04:53:82:81:67:39 | 播放器唯一 ID（软播放器为伪造 MAC） |
| ip | 10.89.56.3:49446 | 来源地址与端口 |
| name | G23-TestPlayer | 显示名 |
| model | squeezelite | 客户端类型（HTTP 客户端为 http） |
| power | 1 | 电源状态 |
| isplaying | 0 | 是否正在播放 |
| connected | 1 | 连接是否存活（第二个 curl 条目为 0，即已断连但仍留册） |
| firmware | 2.0.0-1517 | 固件/客户端版本串 |
注意第二个条目：model:http、name:curl from 10.89.56.1、connected:0——任何发起 stream.mp3 请求的 HTTP 客户端都会注册成一个播放器，断开后条目保留。清理这类残留条目无需操作，服务端在后续扫描/重启周期自动收敛。
player count ? — 快速拿总数：
player count ?
player count 3
播放器属性查询（把 <id> 换成具体播放器 ID，实测一组）：
04:53:82:81:67:39 connected ?
04%3A53%3A82%3A81%3A67%3A39 connected 1
04:53:82:81:67:39 name ?
04%3A53%3A82%3A81%3A67%3A39 name %3F G23-TestPlayer
04:53:82:81:67:39 model ?
04%3A53%3A82%3A81%3A67%3A39 model %3F squeezelite
04:53:82:81:67:39 firmware ?
04%3A53%3A82%3A81%3A67%3A39 firmware %3F 2.0.0-1517
04:53:82:81:67:39 ip ?
04%3A53%3A82%3A81%3A67%3A39 ip %3F 10.89.56.3
04:53:82:81:67:39 power ?
04%3A53%3A82%3A81%3A67%3A39 power 1
sync 域 — 同步组管理，查询当前同步状态：
04:53:82:81:67:39 sync ?
04%3A53%3A82%3A81%3A67%3A39 sync -
回显 - 表示未加入任何同步组；把另一播放器 ID 作为参数（sync <另一ID>）即组成同步组，实现多房间同步播放。
4.3 播放控制域
mode 域 — 播放状态机查询与切换，实测完整序列（play → pause → 查询 → stop）：
04:53:82:81:67:39 play
04%3A53%3A82%3A81%3A67%3A39 play
04:53:82:81:67:39 mode ?
04%3A53%3A82%3A81%3A67%3A39 mode play
04:53:82:81:67:39 pause 1
04%3A53%3A82%3A81%3A67%3A39 pause 1
04:53:82:81:67:39 stop
04%3A53%3A82%3A81%3A67%3A39 stop
04:53:82:81:67:39 mode ?
04%3A53%3A82%3A81%3A67%3A39 mode stop
mode 的取值域为 play / pause / stop；pause 1 暂停、pause 0 恢复、pause 在两态间切换。
time / duration / rate / sleep — 播放进度与定时（实测回显）：
04:53:82:81:67:39 time ?
04%3A53%3A82%3A81%3A67%3A39 time 45.035
04:53:82:81:67:39 duration ?
04%3A53%3A82%3A81%3A67%3A39 duration %3F 45.035
04:53:82:81:67:39 rate ?
04%3A53%3A82%3A81%3A67%3A39 rate %3F 1
04:53:82:81:67:39 sleep ?
04%3A53%3A82%3A81%3A67%3A39 sleep 0
time ? 回显当前播放秒数；time 30 可跳转到第 30 秒（seek）；rate 是播放速率（1 为正常）；sleep 为睡眠定时器秒数，0 表示未设置。
mixer 域 — 音量控制，实测（设置 80 后回读）：
04:53:82:81:67:39 mixer volume 80
04%3A53%3A82%3A81%3A67%3A39 mixer volume 80
04:53:82:81:67:39 mixer volume ?
04%3A53%3A82%3A81%3A67%3A39 mixer volume 80
音量域 0-100，支持 mixer volume +5 相对调整。
power 域 — 播放器电源（实测开关一轮）：
04:53:82:81:67:39 power 0
04%3A53%3A82%3A81%3A67%3A39 power 0
04:53:82:81:67:39 power ?
04%3A53%3A82%3A81%3A67%3A39 power 0
04:53:82:81:67:39 power 1
04%3A53%3A82%3A81%3A67%3A39 power 1
4.4 播放列表域
这是自动化场景最常用的一组命令。实测全链（清空 → 追加 → 查询 → 保存）：
playlist clear / add — 清空与追加：
04:53:82:81:67:39 playlist clear
04%3A53%3A82%3A81%3A67%3A39 playlist clear
04:53:82:81:67:39 playlist add file:///music/ss1.ogg
04%3A53%3A82%3A81%3A67%3A39 playlist add %2Fmusic%2Fss1.ogg
04:53:82:81:67:39 playlist add file:///music/ss2.mp3
04%3A53%3A82%3A81%3A67%3A39 playlist add %2Fmusic%2Fss2.mp3
04:53:82:81:67:39 playlist tracks ?
04%3A53%3A82%3A81%3A67%3A39 playlist tracks 2
注意 add 的回显：输入是完整 file:// URL，回显被规范化为路径形态（%2Fmusic%2Fss1.ogg）。追加两首后 playlist index ? 实测为 1——当前指针指向最后追加的曲目，这是实测观察到的行为，编写依赖当前曲目的脚本时需要留意。
playlist title/artist/album/genre/path ? — 当前曲目元数据，实测：
04:53:82:81:67:39 playlist title ?
04%3A53%3A82%3A81%3A67%3A39 playlist title %3F Northern%20Line
04:53:82:81:67:39 playlist artist ?
04%3A53%3A82%3A81%3A67%3A39 playlist artist %3F Northway%20Trio
04:53:82:81:67:39 playlist album ?
04%3A53%3A82%3A81%3A67%3A39 playlist album %3F Field%20Notes
04:53:82:81:67:39 playlist genre ?
04%3A53%3A82%3A81%3A67%3A39 playlist genre %3F Folk
04:53:82:81:67:39 playlist path ?
04%3A53%3A82%3A81%3A67%3A39 playlist path %3F file%3A%2F%2F%2Fmusic%2Fss2.mp3
回显中的 %3F 是查询占位符的原样回传，其后才是答案。
playlist index — 指针选择，实测（跳转后 index ? 立即反映）：
04:53:82:81:67:39 playlist index 0
04%3A53%3A82%3A81%3A67%3A39 playlist index 0
04:53:82:81:67:39 playlist index ?
04%3A53%3A82%3A81%3A67%3A39 playlist index 0
语义注意：playlist title ? 等元数据查询反映的是当前已加载曲目，实测在停止态调整索引后，标题查询仍返回原加载曲目；让选择真正生效需驱动播放（或直接用 playlist index <n> 后接 play）。测试播放器（输出空设备）会以网络速度瞬时消费曲目，指针会快速前进，实验室脚本判读时要叠加这一因素。
playlist save / load — 落盘与加载，实测：
04:53:82:81:67:39 playlist save G23CLI
04%3A53%3A82%3A81%3A67%3A39 playlist save G23CLI
04:53:82:81:67:39 playlist load G23CLI
04%3A53%3A82%3A81%3A67%3A39 playlist load %2Fplaylist%2FG23CLI.m3u
save 以名字落盘到播放列表目录（playlistdir 参数决定位置），load 的回显显示服务端把名字解析成了完整路径 /playlist/G23CLI.m3u。落盘产物核对（服务端文件系统侧）：
$ ls -la /playlist
-rw-r--r-- 1 1000 1000 26 G23CLI.m3u
$ cat /playlist/G23CLI.m3u
file:///music/ss2.mp3
playlist move / delete / shuffle / repeat — 队列编辑与播放模式，实测：
04:53:82:81:67:39 playlist move 1 0
04%3A53%3A82%3A81%3A67%3A39 playlist move 1 0
04:53:82:81:67:39 playlist delete 0
04%3A53%3A82%3A81%3A67%3A39 playlist delete 0
04:53:82:81:67:39 playlist shuffle 1
04%3A53%3A82%3A81%3A67%3A39 playlist shuffle 1
04:53:82:81:67:39 playlist shuffle ?
04%3A53%3A82%3A81%3A67%3A39 playlist shuffle 1
04:53:82:81:67:39 playlist repeat 2
04%3A53%3A82%3A81%3A67%3A39 playlist repeat 2
04:53:82:81:67:39 playlist repeat ?
04%3A53%3A82%3A81%3A67%3A39 playlist repeat 2
move <源> <目标> 移动曲目位置，delete <索引> 删除指定曲目；shuffle 取值 0 关 / 1 曲目随机 / 2 专辑随机；repeat 取值 0 关 / 1 单曲循环 / 2 全列表循环。
4.5 媒体库浏览域
浏览类命令统一遵循 对象 <起始> <数量> tags:<标签串> [过滤参数] 的形态。
albums — 专辑列表，实测（tags 串 lyaj = 专辑名 l、年份 y、艺术家 a、流派 j）：
albums 0 20 tags:lyaj
albums 0 20 tags%3Alyaj id%3A5 performance%3A favorites_url%3Adb%3Aalbum.title%3DAnalog%2520Dreams%26contributor.name%3DEcho%2520Valley favorites_title%3AAnalog%20Dreams album%3AAnalog%20Dreams year%3A0 artist%3AEcho%20Valley id%3A1 performance%3A favorites_url%3Adb%3Aalbum.title%3DField%2520Notes%26contributor.name%3DNorthway%2520Trio favorites_title%3AField%20Notes album%3AField%20Notes year%3A2023 artist%3ANorthway%20Trio id%3A2 ... id%3A4 ... count%3A5
解读（解码后关键字段）：五张专辑 Analog Dreams（Echo Valley）、Field Notes（Northway Trio，2023）、Test Album 1-3；count:5 是总量，分页参数 <起始> <数量> 据此翻页。tags 串里没要的字段就不返回——按需取字段是控制回显体积的关键手段。
artists / genres — 艺术家与流派，实测：
artists 0 20
artists 0 20 id%3A1 artist%3ANorthway%20Trio id%3A2 artist%3AEcho%20Valley id%3A3 artist%3ATest%20Artist%201 id%3A4 artist%3ATest%20Artist%202 id%3A5 artist%3ATest%20Artist%203 count%3A5
genres 0 20
genres 0 20 id%3A1 genre%3AElectronic id%3A2 genre%3AFolk id%3A3 genre%3ATest count%3A3
titles — 曲目列表，实测（tags 串 glad = 曲目 g、流派 l、专辑 a、时长 d）：
titles 0 20 tags:glad
titles 0 20 tags%3Aglad id%3A10 title%3ADeep%20Field genre%3AElectronic album%3AAnalog%20Dreams artist%3AEcho%20Valley duration%3A40.045 id%3A11 title%3ADeep%20Field ... id%3A2 title%3ANorthern%20Line genre%3AFolk album%3AField%20Notes artist%3ANorthway%20Trio duration%3A45.035 id%3A1 title%3AOpen%20Water ... duration%3A37.791 id%3A3 title%3ATest%20Song%20 ... count%3A10
十首曲目的标题、流派、专辑、艺术家、时长一次取齐，是做库巡检脚本的标准查询。
songinfo — 单曲详情（按 URL 定位），实测：
songinfo 0 50 tags:ldstu url:file:///music/ss2.mp3
songinfo 0 50 tags%3Aldstu url%3Afile%3A%2F%2F%2Fmusic%2Fss2.mp3 id%3A2 title%3ANorthern%20Line album%3AField%20Notes duration%3A45.035 artist_id%3A2 tracknum%3A2 url%3Afile%3A%2F%2F%2Fmusic%2Fss2.mp3
url: 过滤参数的值必须 URL 编码后传入；tags 串 ldstu 取回流派 l、时长 d、音轨号 t、标题 s、URL u。
4.6 收藏域
favorites items — 收藏夹内容，实测（空收藏夹）：
favorites items 0 20
favorites items 0 20 count%3A0
收藏以 OPML 持久化在配置目录（prefs/favorites.opml），实测文件内容为空骨架：
<?xml version="1.0" encoding="UTF-8"?>
<opml version="1.0">
<head title="Favorites">
<expansionState></expansionState>
</head>
<body>
</body>
</opml>
在 Web 界面收藏电台/专辑后，此处出现对应 <outline> 节点，CLI 侧 favorites items 即可枚举，两侧行为一致。
五、注意事项
汇总实测中沉淀的四条关键经验：
?占位符是查询与动作的分水岭。version ?有回显、version无回显（实测）；同样player count ?有效。回显缺失时先检查是否漏了?，再检查命令拼写。- URL 编码贯穿输入与输出。 输入侧路径类参数（
url:file:///music/ss2.mp3）服务端兼容明文，但回显全部编码；脚本解析回显前先做 URL 解码（%3A→:、%20→ 空格）。 - 播放态依赖客户端真实消费。 LMS 的推流模型是服务端主动推送、客户端拉取解码。实测中输出空设备的软播放器会把 45 秒曲目在一两秒内消费完，
time ?直接跳到末值、mode停留在play直至手动stop。这对回显判读影响很大：判断播放是否成功应组合mode ?+time ?+ 播放器侧日志，不能只看单条命令。 - 播放器 ID 的两种书写形态。 输入可用明文 MAC（
04:53:82:81:67:39），服务端均正确处理；回显固定为编码形态。从players回显复制 ID 后直接粘贴即可，无需手工编码。
六、常见问题
6.1 命令发出去没有任何回显
现象：连接成功、命令发送正常，但服务器不回应（如发送 version）。
定位与处置：逐项检查——命令是否需要查询占位符（标量查询必须带 ?，本例 version ? 即回显 version 9.1.1）；播放器私有命令是否带了正确的播放器 ID 前缀；行尾是否为换行符（telnet 交互模式回车即可，脚本模式必须显式 \n）。
6.2 playlist save 后找不到文件
现象：playlist save G23CLI 回显正常，但在曲库目录里找不到 m3u。
定位：播放列表落盘位置由 playlistdir 决定（实测 /playlist），与曲库目录（audiodir）是两个目录。用 pref playlistdir ? 确认落盘位置后到对应目录查找；部署时该目录必须以可写方式挂载（见部署篇第五节）。
6.3 players 0 里有一个陌生的 curl 条目
现象：播放器列表中出现 model:http、名称 curl from <ip> 的条目。
判定：这是 HTTP 软件客户端的注册条目——任何对服务端音频流端点的 HTTP 请求都会形成一个临时播放器，属正常机制，不是入侵。connected:0 表示已断开。公网暴露服务端前务必收紧访问控制（见配置篇 5.5 节）。
6.4 注册成功但播放无声
现象：players 0 可见播放器且 connected:1，下发 play 后无声音。
定位：LMS 有两条通道——3483（注册/控制）与 9000（音频流）。此现象通常是音频流通道不可达（推流地址按服务端坐标生成）。按部署篇 11.2 节的排查路径处理：确认播放器到服务端 9000 端口的连通性，端口映射环境优先让播放器与服务端同网部署。
七、参考链接
- 服务端内置 CLI 参考（完整命令域清单）：
http://<服务器地址>:9000/html/docs/cli-api.html - 官方站点：https://lyrion.org
- 源码仓库：https://github.com/LMS-Community/slimserver
- 本专栏相关篇目：《Lyrion Music Server 9.1.1 介绍与选型指南》《Lyrion Music Server 9.1.1 Docker Compose 部署指南》《Lyrion Music Server 9.1.1 配置参数详解》