NymphCast 0.2-alpha0 配置参数详解

逐项讲透 NymphCast 接收端 INI 配置的全部参数（含义、默认值、改动影响），并给出纯音频接收端的推荐配置模板与常见配置故障的排查方法。已在 Ubuntu 24.04（x86_64）对 v0.2-alpha0 逐项实测参数行为。

NymphCastNymphCast流媒体DockerDocker Compose2026/10/30

NymphCast 0.2-alpha0 配置参数详解

目标：逐项讲透 NymphCast 接收端 INI 配置的全部参数（含义、默认值、改动影响），并给出纯音频接收端的推荐配置模板与常见配置故障的排查方法。已在 Ubuntu 24.04（x86_64）对 v0.2-alpha0 逐项实测参数行为。

一、环境信息

本文基于以下环境实测（实测日期 2026-10-29）：

  • 操作系统：Ubuntu 24.04 LTS（x86_64）
  • 软件版本：NymphCast Server v0.2-alpha0（编译版本串 v0.2-alpha0.20241108）
  • 配置文件来源：源码 src/server/*.ini，经 make install 部署到 /usr/local/etc/nymphcast/，共 5 个文件
  • 实测手段：修改参数后以 nymphcast_server -c <配置> 启动，比对启动日志、监听端口与推流行为；无声卡环境统一设置 SDL_AUDIODRIVER=dummy

二、前置条件

  1. 已按 《Ubuntu 24.04 安装 NymphCast 0.2-alpha0 指南》 完成编译安装，/usr/local/etc/nymphcast/ 下存在 5 个配置文件：
ls /usr/local/etc/nymphcast/

实测回显：

nymphcast_audio_config.ini
nymphcast_config.ini
nymphcast_gui_config.ini
nymphcast_screensaver_config.ini
nymphcast_video_config.ini
  1. 理解配置与运行形态的对应关系：NymphCast 不用命令行开关区分形态，而是靠"一份 INI 一种形态"。启动时用 -c 指定哪个 INI，接收端就运行成哪种形态：
配置文件运行形态关键差异
nymphcast_audio_config.iniNymphCast Audio（纯音频接收）disable_video=1，适合接有源音箱的盒子/树莓派
nymphcast_video_config.iniNymphCast Video（音视频接收）fullscreen=1，接电视的全屏播放
nymphcast_screensaver_config.iniNymphCast ScreenSaver视频形态 + 待机轮播壁纸图片（enable_screensaver=1）
nymphcast_gui_config.iniNymphCast GUI（Smart TV，实验）enable_gui=1，独立图形界面
nymphcast_config.ini当前生效配置systemd 服务默认加载的"活动配置"，由安装脚本或管理员用上述任一文件覆盖

关键机制：make install-systemd 部署的服务单元固定加载 nymphcast_config.ini（见下），官方 install_linux.sh 安装时会询问 audio/video/screensaver/gui 并把所选 profile 复制覆盖到 nymphcast_config.ini。因此改配置要么直接改 nymphcast_config.ini，要么改对应 profile 后重新覆盖。

服务单元内容（/etc/systemd/user/nymphcast.service，实测）：

[Unit]
Description=NymphCast audio/video casting server

[Service]
ExecStart=/usr/local/bin/nymphcast_server -c /usr/local/etc/nymphcast/nymphcast_config.ini -a /usr/local/share/nymphcast/apps/ -w /usr/local/share/nymphcast/wallpapers/
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

三、参数查看与修改方式

查看当前生效配置（直接读活动配置文件）：

grep -vE '^#|^$' /usr/local/etc/nymphcast/nymphcast_config.ini

实测回显（默认值状态）：

fullscreen=0
disable_video=0
buffer_size=20971520
enable_lcdproc=0
enable_local_media=0
media_file=../NymphCast-MediaServer/local_demo.ini

修改方式：INI 为纯 key=value 文本，# 开头为注释行，直接编辑保存后重启接收端生效（服务托管方式 systemctl --user restart nymphcast，前台方式重新启动进程）。参数无运行时热加载机制。

验证修改生效：重启后确认进程正常监听（配置解析失败会直接拒绝启动，见六、常见问题）：

systemctl --user restart nymphcast
systemctl --user --no-pager status nymphcast | grep Active
ss -lntup | grep 4004

实测回显：

     Active: active (running) since Thu 2026-10-29 15:06:18 UTC; 3s ago
udp   UNCONN 0      0            0.0.0.0:4004       0.0.0.0:*    users:(("nymphcast_serve",pid=10463,fd=7))
tcp   LISTEN 0      64           0.0.0.0:4004       0.0.0.0:*    users:(("nymphcast_serve",pid=10463,fd=5))

四、参数总览

v0.2-alpha0 接收端全部 9 个参数（实读 5 个 INI 与官方 README 汇总）：

参数类型默认值取值作用出现的 profile
fullscreen布尔00/1视频窗口是否全屏（disable_video=1 时无意义）全部 5 个
disable_video布尔00/1禁用视频输出；音频形态设 1全部 5 个
enable_gui布尔00/1启用 Smart TV 图形界面（需 disable_video=0）仅 gui
enable_screensaver布尔0（注释）0/1待机时轮播壁纸图片仅 screensaver
buffer_size整数（字节）20971520≥1流式接收的内存缓冲区大小（默认 20 MB）全部 5 个
enable_lcdproc布尔00/1向 LCDProc 守护进程输出"歌手 - 曲名"信息全部 5 个
lcdproc_host字符串localhost主机名/IPLCDProc 服务端地址（默认注释）全部 5 个
enable_local_media布尔00/1启用接收端本地媒体库（v0.2-alpha0 基础实现）仅默认 config
media_file路径../NymphCast-MediaServer/local_demo.ini文件路径本地媒体清单文件，指向 NCMS 格式的列表仅默认 config

💡 技术拓展：buffer_size 属于"流式播放缓冲"策略——接收端并不把整个文件下载完再播，而是边收边播，这段内存就是"已收未播"的蓄水池。同类方案中，Chromecast/AirPlay 在接收端用更大的秒级缓冲（不可调），NymphCast 把字节数直接暴露给用户：缓冲越小起播越快但抗网络抖动差，越大则起播延迟高、内存占用多。

五、核心参数分类详解

5.1 输出形态控制：fullscreen / disable_video / enable_gui / enable_screensaver

这四个参数决定接收端"长什么样"，组合关系严格：

  • 纯音频盒子（推荐音箱场景）：disable_video=1。此时 fullscreen 无效，进程完全不初始化视频窗口，实测无声卡环境配合 SDL_AUDIODRIVER=dummy 可在无任何显示设备的机器上运行。
  • 接电视：disable_video=0 + fullscreen=1（video profile 的默认组合）。
  • Smart TV 独立界面：disable_video=0 + enable_gui=1（gui profile）。⚠️ 官方注释明确要求 enable_gui=1 必须搭配 disable_video=0，否则 GUI 无渲染出口。
  • 待机屏保：enable_screensaver=1（screensaver profile），不播放时轮播 wallpapers/ 目录图片。

实测验证（音频 profile 启动后推流，服务端日志只出现音频流处理、无视频初始化行）：

Format WAV / WAVE (Waveform Audio), duration -9223372036854775808 usInput #0, wav, from '':
  Duration: 00:00:30.00, bitrate: 1411 kb/s
  Stream #0:0: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 44100 Hz, 2 channels, s16, 1411 kb/s
Finding audio stream...
Found audio stream: 0.
A: 0, V: -1, S: -1

（V: -1 表示无视频流参与，S: -1 表示无字幕流。）

5.2 接收缓冲：buffer_size

默认 20971520（20 MB，官方 README 注明"服务端 20 MB 内部缓冲"，另 ffmpeg 库内部固定 32 kB 缓冲不受此参数控制）。实测把缓冲调到 1 MB（1048576）后服务正常启动、推流正常播放，说明该参数只影响内存水位不改变功能：

sed 's/buffer_size=20971520/buffer_size=1048576/' /usr/local/etc/nymphcast/nymphcast_audio_config.ini > /root/test_small_buf.ini
grep buffer_size /root/test_small_buf.ini

buffer_size=1048576

nymphcast_server -c /root/test_small_buf.ini -a /usr/local/share/nymphcast/apps/

实测启动日志（-a 未传时 apps 目录按当前工作目录相对路径解析，仅告警不阻断——这也是一个行为发现）：

Setting resource folder to default location.
Failed to parse the 'apps/apps.ini' file.
Failed to read in app list.

内存受限设备（如 256 MB 内存的老树莓派）建议降到 2–4 MB；有线局域网环境 1 MB 起播也稳定，无线环境建议保留默认 20 MB。

5.3 LCDProc 小屏输出：enable_lcdproc / lcdproc_host

面向带 LCD 小屏的硬件形态（如自制网络音箱的显示屏）：enable_lcdproc=1 后接收端把"艺术家 - 标题"文本送到 LCDProc 守护进程。需要系统已安装并配置 LCDProc；lcdproc_host 指向 LCDProc 服务端，默认 localhost。本机未部署 LCDProc 时保持默认 enable_lcdproc=0 即可，无需其他改动。

5.4 本地媒体库：enable_local_media / media_file

v0.2-alpha0 新增的实验特性：接收端不经客户端、直接播放本地磁盘媒体。enable_local_media=1 打开开关，media_file 指向一个 NCMS 格式的清单文件（列出媒体目录路径）。

实测行为（enable_local_media=1 且 media_file 指向不存在的文件）：纯音频形态启动无任何与本地媒体相关的日志输出、不影响正常接收推流——该功能在 v0.2-alpha0 属"基础实现"，仅在有 GUI 的形态下有可见入口。依赖它做媒体库前请先验证自身使用形态。

六、生产配置模板

适用场景：2 GB 内存的树莓派/迷你主机 + 有源音箱，纯音频接收端，无线局域网（100 Mbps 级），兼顾起播速度与抗抖动。

# /usr/local/etc/nymphcast/nymphcast_config.ini
# NymphCast Audio 生产模板（2GB 内存、Wi-Fi 局域网、有源音箱）

# 视频输出关闭：音频盒子用不到视频窗口
disable_video=1

# 全屏开关（disable_video=1 时无效，保持默认）
fullscreen=0

# 接收缓冲 8 MB：无线网络下兼顾起播延迟与抗抖动
buffer_size=8388608

# 未部署 LCD 小屏，关闭 LCDProc
enable_lcdproc=0

# 本地媒体库为 v0.2-alpha0 实验特性，生产关闭
enable_local_media=0

有线局域网 + 内存吃紧的老设备（512 MB 以下）建议把 buffer_size 降到 2097152（2 MB）；作为对照，默认 20 MB 适合"多房间同步 + 高码率音源"场景。模板落地后按三、节的方法重启并验证监听。

七、常见问题

Q1：改了配置不生效？

按顺序排查：① 改的是不是 nymphcast_config.ini？systemd 服务只加载它，改了 audio/video 等 profile 而没覆盖活动配置等于没改；② 改完是否重启了服务（systemctl --user restart nymphcast）；③ ps aux | grep nymphcast 确认没有另一个前台实例占着 4004 端口、systemd 实例反复重启。

Q2：启动直接退出，无监听端口？

配置文件路径错误或内容无法解析会拒绝启动。用前台方式跑一次看报错：

nymphcast_server -c /usr/local/etc/nymphcast/nymphcast_config.ini

配置正常时应看到 Initialising server...；若报路径相关错误，修正 -c 指向或文件权限。

Q3：日志出现 Failed to parse the 'apps/apps.ini' file.？

未用 -a 指定应用目录时，应用列表按当前工作目录的相对路径 apps/apps.ini 解析，找不到仅告警不退出（实测确认服务仍正常监听 4004 并可接收推流）。规范做法是启动命令始终带上 -a /usr/local/share/nymphcast/apps/ -w /usr/local/share/nymphcast/wallpapers/。

Q4：无声卡服务器启动后推流无声算故障吗？

不算。NymphCast 通过 SDL2 输出音频，无音频设备的机器上需 export SDL_AUDIODRIVER=dummy（哑驱动，链路全通、不出声）。这是验证部署与排障的利器；真正接音箱的机器不要设置它。

Q5：enable_gui=1 后黑屏或退出？

GUI 模式需要可用图形输出（SDL 视频后端 + OpenGL），并要求 disable_video=0。无显示器的服务器请用 audio profile；要远程验证 GUI 形态需接真实显示器或配置 X 虚拟输出，属进阶场景。

八、参考链接