musikcube 3.0.5 常用命令与运维实战（核心篇）

目标：把 musikcube 的三套操作面——TUI 键盘操作、musikcubed daemon 启停运维、远程 API（websocket/HTTP）命令——一次讲全，并给出 musikdroid 安卓客户端的对接参数与验证方法。本文全部命令与回显在 Ubuntu 22.04 实机（musikcube 3.0.5 deb 安装、headless 场景）逐条实测，配置字段含义的进一步解释见《musikcube 3.0.5 配置参数详解》。

一、环境信息

实测系统：Ubuntu 22.04（x86_64，无头服务器，无声卡），musikcube 3.0.5（官方 deb：musikcube_3.0.5_linux_x86_64.deb）
服务形态：musikcubed daemon 常驻（websocket 7905 + HTTP 7906），本地测试音轨 2 条（wav/mp3 各一）已入曲库
客户端工具：curl 8.5.0（HTTP 流验证）、python3 + websocket-client 1.9.2（websocket 消息验证）
安装过程见《Ubuntu 22.04 安装 musikcube 3.0.5 指南》；配置文件字段见《musikcube 3.0.5 配置参数详解》

二、命令工具概览

musikcube 的日常操作分散在三个层面，各有分工：

操作面	入口	适用场景
TUI 交互	`musikcube` 命令	有人值守的终端内听歌、首次配置（音乐目录/服务端密码/主题）
daemon 管理	`musikcubed --start/--stop/--running/--foreground/--version/--help`	headless 服务器的启停/巡检/systemd 托管
远程 API	websocket 7905 + HTTP 7906	musikdroid/自制客户端对接、脚本化控制、健康检查

三者共享同一份配置与曲库（~/.config/musikcube/），任何一个层面做的变更（扫描、播放队列、设置）对其他层面即时可见。

三、前置条件

已完成 deb 安装，which musikcube musikcubed 均返回 /usr/bin/ 路径；
终端支持 UTF-8（无头环境建议显式 export LANG=C.UTF-8，否则 TUI 启动时提示警告并自动回退，见第九章 Q3）；
daemon 场景已配置服务端密码（plugin_musikcubeserver(wss,http).json 的 password 字段）；
远程 API 演示账号：服务端密码为本系列统一演示口令 q1w2e3r4（HTTP 流的用户名固定为 default）。

四、musikcubed daemon 命令详解

/usr/bin/musikcubed 是一个 shell 封装（cd /usr/share/musikcube && exec ./musikcubed "$@"），真正逻辑在随包发布的同名二进制中。全部参数实测如下。

4.1 --help：查看全部参数

musikcubed --help

实测回显：


  using lockfile at: /tmp/musikcubed.lock
  musikcubed:
    --start: start the daemon
    --foreground: start the in the foreground
    --stop: shut down the daemon
    --running: check if the daemon is running
    --version: print the version
    --help: show this message

六个参数一次看清：启动（--start 后台 / --foreground 前台）、停止（--stop）、状态（--running）、版本。锁文件固定为 /tmp/musikcubed.lock。

4.2 --version：版本确认

musikcubed --version

实测回显：


  using lockfile at: /tmp/musikcubed.lock
  musikcubed version: 3.0.5 #0c0d8486

版本号后是构建 git 短哈希 #0c0d8486，排障时可用来核对安装的确切构建。

4.3 --start / --running：启动与巡检

musikcubed --start

实测回显：


  using lockfile at: /tmp/musikcubed.lock
  musikcubed is starting...

musikcubed --running

实测回显：


  using lockfile at: /tmp/musikcubed.lock
  musikcubed is running with pid 751

启动后等待约 3-6 秒再巡检（加载插件与曲库需要时间）；--running 返回 pid 可直接用于 kill 兜底。

4.4 --stop：停止

musikcubed --stop

实测回显：


  using lockfile at: /tmp/musikcubed.lock
  stopping musikcubed.......... failed

⚠️ 实测注意：--stop 回显 failed 但实际停止成功——命令返回后立即查日志与进程：~/.config/musikcube/log.txt 末尾出现 [GaplessTransport] stop 收尾记录、进程表无 musikcube 进程、锁文件清空。该参数的退出码/回显判定存在缺陷（0.99.x 时代已知问题），判断「是否真的停了」以 --running 与日志为准，不要被 failed 字样误导。

4.5 --foreground：前台调试运行

musikcubed --foreground

前台模式不 fork、日志直接打终端，配置排障时用；^C 退出。后台化差异：--start 模式下 stdout/stderr 被捕获到 ~/.config/musikcube/stderr.txt。

4.6 服务端健康检查三连（daemon + 双端口）

musikcubed --running | grep -o 'running.*' ; ss -ltn | grep -E '7905|7906' ; curl -s -o /dev/null -w 'HTTP %{http_code}\n' -u default:q1w2e3r4 "http://127.0.0.1:7906/audio/external_id/local-3777198585-312182025"

实测回显（本机实测端口监听与音频流各一）：

running with pid 751
LISTEN 0      128          0.0.0.0:7905       0.0.0.0:*
LISTEN 0      128          0.0.0.0:7906       0.0.0.0:*
HTTP 200

三连全部通过即为健康：daemon 存活、双端口监听、HTTP 流可拉取且认证通过。

五、TUI 快捷键矩阵

5.1 启动与首屏

musikcube

无参数直接进 TUI（musikcube 不接受 --help/--version 之类 CLI 参数，传参行为见第九章 Q1）。无头环境实测首屏（欢迎对话框 + settings 视图，节选）：

 > library type: local
    +--------------------------------------------------------------------------------------------+
    | welcome to musikcube!                                                                      |
    | add some directories that contain music files, then press 'a' to show the library view ... |
    | for troubleshooting, press '`' to enter the console view.                                  |
    +--------------------------------------------------------------------------------------------+
 > preamp and replaygain                                    [x] sync metadata on startup
 > playback mode: gapless                                   [x] remove missing files from library
 > color theme: default                                     > configure plugins
 > key bindings                                             > advanced settings
 > server setup                                             > check for updates now

                                           musikcube version 3.0.5 #0c0d8486
                                      s  settings   a  library   `  logs   ^D  quit

首次使用流程：回车关闭欢迎框 → settings 里 server setup 配服务端密码、browse 面板加音乐目录 → a 进曲库。

5.2 曲库视图实测

按 a 进入 library 视图（实测，左侧艺术家、右侧曲目，底部播放状态与音量条）：

+ artists -----------------+ + tracks (sorted by album) ---------------------------------------+
| [unknown #1]             | |  1   /music/test_tone.wav                        0:30          |
+--------------------------+ +-----------------------------------------------------------------+
 playback is stopped                                                                         shuffle
 vol ----------■ 100%  0:00 ■---------------------------------------------- 0:00  repeat off

按 ESC 呼出命令栏后底部显示当前视图可用快捷键（实测）：

                       b  browse   f  filter   t  tracks   n  play queue   s  settings   ^D  quit

5.3 全局导航与视图切换

以下为 user-guide 官方定义 + 实机 hotkeys.json 双重确认的默认值：

键	作用	键	作用
`ESC`	聚焦/脱离底部命令栏	`TAB` / `SHIFT+TAB`	下一个 / 上一个面板
`ENTER`	激活/切换选中项	`M-ENTER`	弹出上下文菜单
`^D`	退出 musikcube	`?`	查看/编辑快捷键
`a`	曲库视图	`s`	设置视图
`	控制台（日志）视图	`b`	浏览视图
`n`	播放队列	`f`	曲目过滤搜索
`t`	曲目搜索	`x`	跳转到正在播放的艺术家/专辑
`1`~`6`	浏览方式：艺术家/专辑/流派/专辑艺术家/播放列表/分类	`d`	按目录浏览

5.4 播放控制

键	作用	键	作用
`^P`	全局暂停/恢复	`^X`	停止并释放资源
`i` / `k`	音量 +5% / -5%	`m`	静音切换
`j` / `l`	上一曲 / 下一曲	`u` / `o`	后退 / 前进 10 秒
`.`	循环模式切换（关/单曲/列表）	`,`	播放队列随机化切换
`SPACE`	（曲目列表聚焦时）暂停/恢复	`M-a`	选中列表热替换进播放队列（不打断播放）
`v`	可视化器开关	`^E`	均衡器配置

5.5 播放队列与播放列表管理

键	作用
`M-s`	当前队列存为播放列表
`M-l` / `M-x`	加载 / 删除已存播放列表
`M-r`	重命名播放列表
`M-n`	新建空播放列表（播放列表浏览模式）
`M-UP` / `M-DOWN`	上移 / 下移选中曲目
`DEL`	删除选中的播放列表或队列中的曲目

💡 技术拓展：TUI 键位体系中的「Meta 键」在不同平台的实际按键——Linux 终端一般是左 Alt；macOS 需在终端模拟器里把 Option 设为 +Esc；Windows 上 Alt 即 Meta。^X 写法恒等于 Ctrl+X。改键统一走 ~/.config/musikcube/hotkeys.json（字段含义见《musikcube 3.0.5 配置参数详解》5.3 节），不要直接改系统键盘映射。

六、远程 API 命令面（websocket + HTTP）

6.1 协议总览与认证

websocket（默认 7905）承载全部控制与元数据：消息为 JSON，request 必有 response；HTTP（默认 7906）只做两件事：按 external_id 下发音频、下发封面缩略图。连接后第一条消息必须是认证：

{
    "name": "authenticate",
    "type": "request",
    "id": "r1",
    "device_id": "dev-doc-01",
    "options": { "password": "q1w2e3r4" }
}

实测响应（python websocket-client，服务端 3.0.5）：

<< auth: {"id": "r1", "name": "authenticate", "options": {"authenticated": true, "environment": {"api_version": 20, "app_version": "3.0.5", "http_server_enabled": true, "http_server_port": 7906, "sdk_version": 21}}, "type": "response"}

环境信息随认证一并返回（api_version 20 / sdk_version 21），客户端可用它做版本协商。密码错误时服务端直接断开连接。

6.2 曲库查询：query_tracks

大曲库遵守「先 count_only 再分页」两步法：

import json, websocket
ws = websocket.create_connection('ws://127.0.0.1:7905', timeout=8)
def rpc(name, options, rid):
    ws.send(json.dumps({'name': name, 'type': 'request', 'id': rid,
                        'device_id': 'dev-doc-01', 'options': options}))
    return json.loads(ws.recv())
rpc('authenticate', {'password': 'q1w2e3r4'}, 'r0')
print(json.dumps(rpc('query_tracks', {'count_only': True}, 'r1')))
print(json.dumps(rpc('query_tracks', {'offset': 0, 'limit': 5}, 'r2')))
ws.close()

实测回显（2 曲曲库）：

<< count_only: {"id": "r1", "name": "query_tracks", "options": {"count": 1, "data": []}, "type": "response"}
<< query_tracks: {"id": "r2", "name": "query_tracks", "options": {"count": 1, "limit": 5, "offset": 0, "data": [{"album": "", "album_artist": "", "album_artist_id": 1, "album_id": 46, "artist": "", "artist_id": 1, "external_id": "local-3777198585-312182025", "genre": "", "genre_id": 1, "id": 2, "thumbnail_id": 0, "title": "/music/test_tone.mp3", "track": 1}]}, "type": "response"}

external_id 是后续一切音频流请求的钥匙。同族查询消息还有 query_tracks_by_external_ids、query_tracks_by_category、query_albums、query_category、list_categories、query_play_queue_tracks。

6.3 曲库扫描：run_indexer

print(json.dumps(rpc('run_indexer', {}, 'r3')))

实测回显：

{"id": "r3", "name": "run_indexer", "options": {"success": true}, "type": "response"}

往音乐目录加完文件后调用即可重扫（无需重启 daemon），扫描进度以 indexer_running 类广播推送。

6.4 播放控制与状态

可用消息：play_all_tracks、play_tracks、play_tracks_by_category、play_at_index、seek_to/seek_relative、set_volume（绝对/相对两种 options）、get_playback_overview。实测播放全库：

print(json.dumps(rpc('play_all_tracks', {}, 'r4')))

实测回显（注意先到一条广播，再是命令响应）：

{"id": "musikcube-server-1", "name": "play_queue_changed", "options": null, "type": "broadcast"}
{"id": "r4", "name": "play_all_tracks", "options": {"success": true}, "type": "response"}

随后服务端推送状态广播 playback_overview_changed（节选实测）：

"playing_track": {"external_id": "local-3777212199-2477513281", "title": "/music/test_tone.wav", ...},
"play_queue_position": 0, "track_count": 2, "volume": 1.0, "state": "stopped"

⚠️ 实测要点：响应与广播在同一条连接上按到达顺序混排，客户端必须按 id 字段区分「命令响应」（原样回传请求 id）与「服务端广播」（musikcube-server-N 自增 id），不能假设一问一答。

6.5 HTTP 音频流与认证边界

URL 固定格式：http://<host>:<port>/audio/external_id/<external_id>[?bitrate=<kbps>]，认证为 HTTP Basic，用户名固定 default、密码同 websocket。实测三条边界：

# 原始流（按原格式原码率下发）
curl -s -o /dev/null -w 'HTTP %{http_code}, %{size_download} bytes, %{content_type}\n' -u default:q1w2e3r4 "http://127.0.0.1:7906/audio/external_id/local-3777198585-312182025"
# 错误密码
curl -s -o /dev/null -w 'HTTP %{http_code}\n' -u default:wrongpass "http://127.0.0.1:7906/audio/external_id/local-3777198585-312182025"
# 按 64kbps 转码下发
curl -s -o /dev/null -w 'HTTP %{http_code}, %{size_download} bytes, %{content_type}\n' -u default:q1w2e3r4 "http://127.0.0.1:7906/audio/external_id/local-3777198585-312182025?bitrate=64"

实测回显：

HTTP 200, 401284 bytes, audio/mpeg
HTTP 401
HTTP 200, 192001 bytes, application/octet-stream

要点：无 bitrate 参数原样透传（audio/mpeg）；带参数实时转 mp3 并落 cache/transcoder/ 缓存（实测 25 秒 128k 源转 64k 产出约 192KB），首次转码未完成前带 Range 头的请求返回 416；封面缩略图走 http://<host>:<port>/thumbnail/<thumbnail_id>。

6.6 musikdroid 客户端对接

musikdroid 是官方 Android 客户端（遥控 + 串流双模式），APK 随桌面版同步发布：

curl -sL -o musikdroid_3.0.3.apk "https://github.com/clangen/musikcube/releases/download/3.0.5/musikdroid_3.0.3.apk"

安装后在新建设置中填写（全部参数值都有服务端实测对应项）：

musikdroid 字段	填写值	对应服务端
服务器地址	`192.168.1.x`（服务器 IP）	—
websocket 端口	`7905`	`websocket_server_port`
密码	`q1w2e3r4`	`password`
HTTP 流端口	`7906`	`http_server_port`

对接验证（服务端侧）：手机连上后立即 tail -f ~/.config/musikcube/log.txt，可见新的 websocket 连接与认证记录；或保持 6.1 的连接观察广播——musikdroid 的每次操作都会推 playback_overview_changed。

七、日常运维场景

改库后刷新：新文件入目录后跑 run_indexer（websocket）或在 TUI 按 ^R；daemon 模式下也可以 musikcubed --stop && musikcubed --start（SyncOnStartup=true 时启动即扫）。
改配置后生效：任何 JSON 修改都需重启 daemon；TUI 退出会写回配置，与手工编辑不要交叉（详见《配置参数详解》第三章）。
日志位置：运行日志 ~/.config/musikcube/log.txt（插件加载/索引/库查询），stderr 捕获 stderr.txt（网络连接错误等），转码缓存 cache/transcoder/。
systemd 开机自启：官方 Wiki 给出的服务单元模板（Type=forking，ExecStart=/usr/bin/musikcubed --start、ExecStop=/usr/bin/musikcubed --stop，User= 指定运行者），写入 /etc/systemd/system/musikcube.service 后 systemctl enable musikcube。注意 User= 决定配置目录归属（/home/<user>/.config/musikcube/）。

八、注意事项

musikcube 是纯 TUI 程序，没有 CLI 参数解析：--help/--version 都不是它的参数（见第九章 Q1），版本查询用 musikcubed --version。
远程 API 无 TLS、密码明文存盘，仅限内网；公网必须前置反代终结 SSL。
daemon 与 TUI 不要同时以同一用户运行（锁文件与配置写回互相干扰）；先停 daemon 再进 TUI 改配置。
headless 环境输出驱动回退 Null 属正常（无声卡），流服务不受影响；有声卡后重启会自动挂 alsa/pulse 插件。

九、常见问题

Q1：musikcube --help 段错误？ 实测：不带 LANG/TERM 直接执行 musikcube --help 得到 Segmentation fault (core dumped)（退出码 139）。原因是 musikcube 无 CLI 参数处理，任何参数都会走 TUI 初始化路径，而检测到非 UTF-8/无终端环境时初始化失败崩溃。正确做法：TUI 直接裸命令 musikcube（终端内），版本与参数用 musikcubed --version / musikcubed --help。

Q2：musikcubed --stop 显示 failed？ 见 4.4 节实测：回显不可信，以 --running（应为 NOT running）与 log.txt 的 [GaplessTransport] stop 为准。紧急兜底：musikcubed --running 拿 pid 后 kill <pid>。

Q3：启动提示 UTF-8 警告？ 实测回显：

This application requires a UTF-8 compatible LANG environment variable to be set in the controlling terminal. Setting to C.UTF-8. ...

musikcube 检测到非 UTF-8 LANG 时自动回退并提示，界面可能乱码。在 shell 配置或 systemd 单元里显式 Environment=LANG=C.UTF-8 消除。

Q4：websocket 认证成功但查询返回 {"error": "invalid"}？ 消息名或参数写错。例如查询曲库的合法消息名是 query_tracks（不是 get_tracks），分页参数为 offset/limit；全部消息名以官方 remote-api 文档为准（参考链接）。

十、参考链接

官方用户指南（快捷键权威表）：https://github.com/clangen/musikcube/wiki/user-guide
远程 API 文档：https://github.com/clangen/musikcube/wiki/remote-api-documentation
systemd 服务单元（社区贡献）：https://github.com/clangen/musikcube/wiki/installing
musikdroid 源码：https://github.com/clangen/musikcube/tree/master/src/musikdroid
站内同系列：《Ubuntu 22.04 安装 musikcube 3.0.5 指南》、《musikcube 3.0.5 配置参数详解》、《musikcube 介绍与选型指南》