musikcube 3.0.5 配置参数详解
把 musikcube 3.0.5 全部配置文件的存放位置、字段含义、默认值与修改方法一次讲清，并给出 headless 服务端的可落地配置模板。本文所有文件路径、字段名与默认值均为 Ubuntu 22.04 实机运行 musikcube 3.0.5 后从配置目录逐文件实测采集，websocket/HTTP 行为经 curl 与 websocket 客户端实测验证。
musikcubemusikcube音乐2026/10/30
musikcube 3.0.5 配置参数详解
目标：把 musikcube 3.0.5 全部配置文件的存放位置、字段含义、默认值与修改方法一次讲清，并给出 headless 服务端的可落地配置模板。本文所有文件路径、字段名与默认值均为 Ubuntu 22.04 实机运行 musikcube 3.0.5 后从配置目录逐文件实测采集，websocket/HTTP 行为经 curl 与 websocket 客户端实测验证。
一、环境信息
- 实测系统：Ubuntu 22.04（x86_64），musikcube 3.0.5（官方 deb 安装，含 musikcube TUI 与 musikcubed daemon 两个入口）
- 配置目录：
~/.config/musikcube/（以 root 运行为/root/.config/musikcube/） - 服务端配置：
plugin_musikcubeserver(wss,http).json（websocket 7905 + HTTP 7906，默认开启） - 验证方式：TUI 生成初始配置后逐文件 cat 实测；修改后重启 daemon，经
ws://127.0.0.1:7905（认证回显 api_version 20、app_version 3.0.5）与http://127.0.0.1:7906（Basic 认证音频流 200/401）验证生效
二、前置条件
- 已按《Ubuntu 22.04 安装 musikcube 3.0.5 指南》完成安装，
which musikcube musikcubed返回/usr/bin/下两个可执行文件； - 对 TUI 用户：至少启动过一次 musikcube（首次启动会生成全部初始配置文件）；
- 对 daemon 用户：
~/.config/musikcube/已存在（可先跑一次 TUI 生成，也可以手工创建后从零写配置）； - 修改 JSON 建议使用
python3 -m json.tool校验格式，musikcube 启动时解析失败的 JSON 会被当作未配置处理。
三、参数查看与修改方式
musikcube 的参数分两层：TUI 设置界面（交互修改，退出时写回 JSON）与配置文件（可直接编辑，headless 场景唯一手段）。二者的关系经实测确认如下：
- TUI 设置界面（settings 视图，快捷键
s）覆盖：library type、locale、output driver、颜色主题、server setup（服务端密码/端口/转码）、key bindings 等；每次正常退出（^D）时把内存中的配置写回 JSON 文件。 - JSON 配置文件是唯一事实来源，daemon（musikcubed）启动时只读文件、不开 TUI。实测直接编辑
plugin_musikcubeserver(wss,http).json写入password后重启 daemon，websocket 认证即用新密码通过——headless 服务器上无需进 TUI 也能完成服务端配置。 - ⚠️ TUI 退出时会全量写回配置文件：若 TUI 与手工编辑交叉进行，后退出的一方覆盖另一方。先改文件、后开 TUI 的顺序会导致手工修改丢失；正确顺序是「先退出 TUI → 再编辑 JSON → 再启动 daemon」。
查看配置全貌：
ls -la ~/.config/musikcube/
实测回显：
drwxr-xr-x 4 root root 4096 Oct 29 14:30 .
drwxr-xr-x 3 root root 4096 Oct 29 14:30 ..
drwxr-xr-x 3 root root 4096 Oct 29 14:30 1
drwxr-xr-x 3 root root 4096 Oct 29 14:30 cache
-rw-r--r-- 1 root root 2174 Oct 29 14:33 hotkeys.json
-rw-r--r-- 1 root root 63 Oct 29 14:33 libraries.json
-rw-r--r-- 1 root root 2576 Oct 29 14:33 log.txt
-rw-r--r-- 1 root root 4 Oct 29 14:30 plugin_gmeidecoder.json
-rw-r--r-- 1 root root 4 Oct 29 14:30 plugin_httpidatastream.json
-rw-r--r-- 1 root root 4 Oct 29 14:30 plugin_libopenmptidecoder.json
-rw-r--r-- 1 root root 259 Oct 29 14:33 plugin_musikcubeserver(wss,http).json
-rw-r--r-- 1 root root 4 Oct 29 14:30 plugin_nullioutput.json
-rw-r--r-- 1 root root 4 Oct 29 14:30 plugin_supereqidsp.json
-rw-r--r-- 1 root root 30 Oct 29 14:33 session.json
-rw-r--r-- 1 root root 826 Oct 29 14:33 settings.json
-rw-r--r-- 1 root root 277 Oct 29 14:33 stderr.txt
各文件职责：
| 文件 | 职责 | 谁写 |
|---|---|---|
| settings.json | TUI 全局设置（界面/曲库/远程库客户端参数） | TUI 退出时写回 |
| plugin_musikcubeserver(wss,http).json | 流服务端：端口/密码/转码 | TUI server setup 或手工 |
| hotkeys.json | 快捷键绑定 | TUI（按 ? 打开快捷键界面后生成） |
| libraries.json | 本地库与远程库的默认 ID 映射 | TUI/服务端 |
| session.json | 播放队列会话快照（SaveSessionOnExit） | TUI/daemon 退出时 |
| plugin_*.json（值为 null） | 对应插件的空配置占位 | 首次启动生成 |
| 1/ | 本地曲库 SQLite 数据库（musik.db + wal/shm）与缩略图 thumbs/ | 索引器 |
| cache/transcoder/ | 按需转码缓存（<哈希>-<码率>.mp3） | 流服务 |
| log.txt / stderr.txt | 运行日志与 stderr 捕获 | 运行时追加 |
四、参数总览
4.1 settings.json（TUI 全局设置）
首启生成的默认值全文实测（826 字节）：
{
"AppQuitKey": "^D",
"AutoHideCommandBar": false,
"AutoUpdateCheck": true,
"ColorTheme": "",
"DisableCustomColors": false,
"IndexerLogEnabled": false,
"IndexerThreadCount": 4,
"InheritBackgroundColor": false,
"LibraryType": 1,
"Locale": "en_US",
"MinimizeToTray": false,
"PiggyEnabled": false,
"RemoteLibraryHostname": "127.0.0.1",
"RemoteLibraryHttpPort": 7906,
"RemoteLibraryHttpTls": false,
"RemoteLibraryLatencyTimeoutMs": 5000,
"RemoteLibraryPassword": "",
"RemoteLibraryTranscoderBitrate": 192,
"RemoteLibraryTranscoderEnabled": false,
"RemoteLibraryTranscoderFormat": "ogg",
"RemoteLibraryWssPort": 7905,
"RemoteLibraryWssTls": false,
"RemoveMissingFiles": true,
"SaveSessionOnExit": true,
"StartMinimized": false,
"SyncOnStartup": true,
"UsePaletteColors": true
}
4.2 plugin_musikcubeserver(wss,http).json（流服务端）
TUI 首启生成、手工写入密码后的实测全文：
{
"debug": false,
"http_server_enabled": true,
"http_server_port": 7906,
"password": "q1w2e3r4",
"transcoder_cache_count": 50,
"transcoder_synchronous": false,
"transcoder_synchronous_fallback": false,
"use_ipv6": false,
"websocket_server_enabled": true,
"websocket_server_port": 7905
}
4.3 libraries.json 与 session.json
// libraries.json（实测）
{
"default-local-library": 1,
"default-remote-library": 2
}
// session.json（实测，随退出写回）
{
"LastPlayQueueIndex": -1
}
hotkeys.json 是「快捷键 ID → 键名」的大表（50 余键），结构见第五章 5.3。
五、核心参数分类详解
5.1 曲库与索引参数（settings.json）
| 参数 | 默认值 | 说明 |
|---|---|---|
LibraryType | 1 | 曲库类型：1=本地库。设为 2 时 TUI 变成远程库客户端（连别人的 musikcube 服务端），此时生效的是下面 RemoteLibrary* 一组参数 |
SyncOnStartup | true | 启动时自动扫描音乐目录；daemon 模式同样遵守此参数，改库后重启服务即可重新索引 |
IndexerThreadCount | 4 | 索引扫描并发线程数。大曲库（10 万级）可调到 8；低配 NAS 建议降到 2 |
IndexerLogEnabled | false | 打开后 log.txt 里输出逐文件索引日志，排障索引漏扫时用 |
RemoveMissingFiles | true | 扫描时自动从库中删除已消失的文件。音乐目录挂载点掉线时会导致清库，NAS 场景建议改 false |
metadata_rescan（hotkeys） | ^R | TUI 内手动触发重扫的快捷键 |
实测验证：向 /music 目录放入 2 个测试音轨后通过 websocket 发送 run_indexer（或重启 daemon），SQLite 曲库即时出现两条记录：
1|/music/test_tone.wav|local-3777212199-2477513281|30|2646044
2|/music/test_tone.mp3|local-3777198585-312182025|25|401284
💡 技术拓展：musikcube 的远程库参数（RemoteLibrary*）与服务端参数（plugin_musikcubeserver）是同一协议的两侧——任何一台 musikcube 都可以既是服务端（对外开放 7905/7906）又是客户端（RemoteLibrary* 指向别机）。常见同类「客户端-服务端」音乐架构对比：
架构 代表 客户端身份 服务即客户端 musikcube 自身 TUI + musikdroid 纯服务端 Navidrome/gonic Subsonic 生态任意客户端 多协议网关 mpd/MPRIS 专用协议客户端 musikcube 没有网页端，远程消费只走 musikdroid 或按其 websocket 协议自制客户端。
5.2 流服务端参数（plugin_musikcubeserver(wss,http).json）
| 参数 | 默认值 | 说明 |
|---|---|---|
websocket_server_enabled | true | websocket 控制服务开关（元数据/播放控制/状态广播） |
websocket_server_port | 7905 | websocket 监听端口 |
http_server_enabled | true | HTTP 音频流服务开关（原始流 + 转码流下发） |
http_server_port | 7906 | HTTP 监听端口 |
password | ""（空） | 远程访问密码，明文存储。空密码时远程认证失败；实测写入 q1w2e3r4 重启 daemon 后，websocket 认证返回 "authenticated": true，HTTP Basic 用 default:q1w2e3r4 拉流返回 200，错误密码返回 401 |
use_ipv6 | false | 监听栈。内网纯 IPv4 环境保持 false 可避免双栈监听的绑定歧义 |
transcoder_cache_count | 50 | 转码缓存保留份数（实测缓存文件落 cache/transcoder/<哈希>-<码率>.mp3）。磁盘紧张可降到 10 |
transcoder_synchronous | false | false=异步转码（首个请求实时转、边转边发）；true=同步转码（转完再发，首包延迟高但可 seek） |
transcoder_synchronous_fallback | false | 异步转码失败时是否回退同步转码 |
debug | false | 服务端调试日志 |
转码行为实测（25 秒 128k mp3 源，请求 64k 码率）：
HTTP 200, 192001 bytes, application/octet-stream
cache/transcoder/12584269625272509693-64.mp3 # 转码产物落缓存
原始流实测（同一文件不带 bitrate 参数）：
HTTP 200, 401284 bytes, audio/mpeg
💡 技术拓展：「转码缓存计数」是 musikcube 特有的环形缓存策略（按份数淘汰），同类流服务的转码缓存对比：
策略 代表 特点 按份数环形淘汰 musikcube（transcoder_cache_count） 简单可控，粒度是「一份转码产物」 按容量/时间淘汰 Navidrome 需要配目录大小上限 不缓存（实时转） gonic 部分路径 磁盘零占用，CPU 重复开销 客户端多为移动网络场景、码率档位有限时，50 份缓存足够命中常听曲目。
5.3 快捷键参数（hotkeys.json）
hotkeys.json 在 TUI 内按 ? 打开快捷键界面后生成/更新，格式为「动作 ID → 键名」。实测生成的完整键表（节选，全表以文件为准）：
{
"browse_category_filter": "^F",
"browse_playlists_delete": "KEY_DC",
"browse_playlists_new": "M-n",
"browse_playlists_rename": "M-r",
"browse_playlists_save": "M-s",
"context_menu": "M-enter",
"metadata_rescan": "^R",
"navigate_console": "`",
"navigate_hotkeys": "?",
"navigate_library": "a",
"navigate_library_browse_albums": "2",
"navigate_library_browse_artists": "1",
"navigate_library_browse_directories": "d",
"navigate_library_browse_genres": "3",
"navigate_library_filter": "f",
"navigate_library_play_queue": "n",
"navigate_library_playlists": "5",
"navigate_library_tracks": "t",
"navigate_settings": "s",
"play_queue_move_down": "CTL_DOWN",
"play_queue_move_up": "CTL_UP",
"playback_next": "l",
"playback_previous": "j",
"playback_seek_back": "u",
"playback_seek_forward": "o",
"playback_stop": "^X",
"playback_toggle_mute": "m",
"playback_toggle_pause": "^P",
"playback_toggle_repeat": ".",
"playback_toggle_shuffle": ",",
"playback_volume_down": "k",
"playback_volume_up": "i"
}
键名语法：M- 前缀 = Meta 键（Linux 终端通常是左 Alt）；^ 前缀 = Ctrl；特殊键用 ncurses 键名（KEY_DC 删除键、KEY_NPAGE 翻页等）。改完重启 musikcube 生效，TUI 的 settings → key bindings 里有按键测试器可验证键名。
5.4 远程库客户端参数（settings.json 中 RemoteLibrary*）
当 LibraryType 设为 2（把本机 TUI 当作远程库客户端）时生效：
| 参数 | 默认值 | 说明 |
|---|---|---|
RemoteLibraryHostname | 127.0.0.1 | 服务端地址 |
RemoteLibraryWssPort | 7905 | 对端 websocket 端口 |
RemoteLibraryHttpPort | 7906 | 对端 HTTP 流端口 |
RemoteLibraryWssTls / RemoteLibraryHttpTls | false | 是否走 TLS（服务端本身无 TLS，此参数用于前置反代终结 SSL 的场景） |
RemoteLibraryPassword | "" | 对端服务密码 |
RemoteLibraryTranscoderEnabled | false | 客户端侧启用降码率 |
RemoteLibraryTranscoderBitrate | 192 | 降码率请求的码率（kbps） |
RemoteLibraryTranscoderFormat | ogg | 期望转码格式 |
RemoteLibraryLatencyTimeoutMs | 5000 | 连接超时（毫秒） |
实测补充：TUI 在无服务端环境下启动时会尝试连远程库，stderr.txt 记录失败信息（属正常现象）：
[2026-10-29 14:33:35] [info] asio async_connect error: asio.system:111 (Connection refused)
5.5 输出与外观参数
| 参数 | 位置 | 默认值 | 说明 |
|---|---|---|---|
| 输出驱动 | settings（TUI） | 实测显示 Null | 无声卡环境自动回退 Null；有声卡时可选 alsa/pulse/pipewire |
ColorTheme | settings.json | "" | 空=default 主题；主题文件随包发布 |
UsePaletteColors | settings.json | true | 用终端 256 色调色板，老终端可关 |
DisableCustomColors | settings.json | false | 完全禁用自定义颜色（极简终端） |
InheritBackgroundColor | settings.json | false | 继承终端背景色（透明终端用） |
AppQuitKey | settings.json | ^D | 退出键，可改 |
AutoHideCommandBar | settings.json | false | 自动隐藏底部命令栏 |
无输出设备时的实测证据（log.txt，插件按需加载、缺库自动跳过）：
14:33:35 [error] [PluginFactory] exception while loading plugin /usr/share/musikcube/plugins/libalsaout.so: libasound.so.2: cannot open shared object file
14:33:35 [error] [PluginFactory] exception while loading plugin /usr/share/musikcube/plugins/libpulseout.so: libpulse.so.0: cannot open shared object file
14:33:35 [info] [PluginFactory] loaded: /usr/share/musikcube/plugins/libserver.so
六、headless 服务端生产配置模板
适用场景：无头 Linux 服务器/NAS（2GB 内存以上、NVMe 或 SSD），运行 musikcubed 常驻流服务，musikdroid 局域网+反代公网访问。逐文件给出（密码为本系列文档统一演示口令）：
// ~/.config/musikcube/plugin_musikcubeserver(wss,http).json
{
"debug": false,
"http_server_enabled": true,
"http_server_port": 7906,
"password": "q1w2e3r4",
"transcoder_cache_count": 50,
"transcoder_synchronous": false,
"transcoder_synchronous_fallback": false,
"use_ipv6": false,
"websocket_server_enabled": true,
"websocket_server_port": 7905
}
// ~/.config/musikcube/settings.json（headless 场景关键项）
{
"AppQuitKey": "^D",
"AutoUpdateCheck": false,
"IndexerThreadCount": 4,
"LibraryType": 1,
"RemoveMissingFiles": false,
"SaveSessionOnExit": true,
"SyncOnStartup": true
}
配置要点：
RemoveMissingFiles=false：音乐目录多为挂载卷，挂载掉线时避免索引清库；AutoUpdateCheck=false：服务器环境无意义且减少外联；transcoder_synchronous=false：保持异步转码，首播延迟低；公网弱网客户端靠?bitrate=按需降码率；- 端口 7905/7906 仅监听局域网可达地址，公网一律前置 nginx/caddy 做 TLS 终结后再暴露（服务端本身无 TLS，密码明文存盘）；
- 修改后
musikcubed --stop && musikcubed --start生效（stop 的回显异常见安装篇 FAQ）。
生效验证（三连实测）：
musikcubed --running
curl -s -o /dev/null -w '%{http_code}\n' -u default:q1w2e3r4 http://127.0.0.1:7906/audio/external_id/local-3777198585-312182025
实测回显：第一条 musikcubed is running with pid 751；第二条 200。
七、常见问题
Q1：headless 服务器没开过 TUI，配置文件从哪来？ 先任意方式启动一次 musikcube（SSH 里跑 TUI 再退出，或本地跑一次），全部初始配置即生成；之后只改文件即可。也可以手工创建目录与 JSON 从零配置（字段照本文第四章抄）。
Q2：改了 plugin json 里的密码，musikdroid 连不上？
确认顺序：TUI 若在配置修改后退出过，会覆盖手工值。重新 cat 文件确认密码仍在；再确认 musikdroid 填的是 websocket 端口（默认 7905）而非 HTTP 端口。
Q3：转码请求返回 0 字节？
实测发现个别不合规范的 wav 源会导致 ffmpeg 解码器报 swr_convert_frame() failed: Input changed（log.txt 可见）而转码产物为空；换成常规 mp3/flac 源后转码正常（返回 192001 字节缓存文件）。遇到时先看 log.txt 再确认源文件完整性。
Q4：daemon 启动后配置没生效？
musikcubed 是 shell 封装，实际执行 cd /usr/share/musikcube && exec ./musikcubed "$@"，配置永远从当前用户的 ~/.config/musikcube/ 读取。用 systemd 托管时注意 User= 指定谁，配置就在谁的 HOME 下。
八、参考链接
- 官方用户指南（含设置界面说明）：https://github.com/clangen/musikcube/wiki/user-guide
- 远程 API 文档（websocket/HTTP 行为依据）：https://github.com/clangen/musikcube/wiki/remote-api-documentation
- SSL 反代方案：https://github.com/clangen/musikcube/wiki/ssl-server-setup
- 站内同系列：安装步骤见《Ubuntu 22.04 安装 musikcube 3.0.5 指南》；daemon 运维与快捷键见《musikcube 3.0.5 常用命令与运维实战（核心篇）》
章节目录