NymphCast 0.2-alpha0 常用 CLI 命令与工具详解

目标：把 NymphCast 两个命令行工具 nymphcast_server（接收端）与 nymphcast_client（发送端）的全部启动参数、真实回显、退出行为一次讲透，并覆盖配置文件指定、服务托管与推流排障的实战命令。已在 Ubuntu 24.04（x86_64）实测全部命令与回显。

一、环境信息

本文所有命令与回显均在以下环境实测采集（实测日期 2026-10-29）：

操作系统：Ubuntu 24.04 LTS（x86_64）
软件版本：NymphCast 服务端 v0.2-alpha0（编译版本串 v0.2-alpha0.20241108）；客户端二进制版本串为 v0.1-release.20220408（v0.2-alpha0 源码树中 client 的 version.mk 未随版本更新，属上游现状，见六、注意事项）
安装方式：源码编译安装（过程见《Ubuntu 24.04 安装 NymphCast 0.2-alpha0 指南》），二进制位于 /usr/local/bin/，配置位于 /usr/local/etc/nymphcast/
网络环境：接收端主机名 nymphcast-build24、IP 10.89.60.3；发送端为另一台主机，IP 10.89.60.4，两机同处一个局域网段
测试媒体：ffmpeg 生成的 30 秒 440Hz 正弦波 WAV 与 8 秒 880Hz 正弦波 MP3（生成命令见四、3 节）

二、工具概览

NymphCast 的命令行工具只有两个，分工明确：

工具	角色	位置	一句话职责
`nymphcast_server`	Receiver（接收端）	`/usr/local/bin/nymphcast_server`	监听 4004 端口，接收客户端推流并用内置 ffplay 内核解码播放
`nymphcast_client`	Sender（发送端）	`/usr/local/bin/nymphcast_client`	扫描发现接收端，把本地文件推送到接收端播放

两个工具都由同一个仓库编译产出：src/server 产出 nymphcast_server，src/client 产出 nymphcast_client。除这两个主工具外，实战中还会配合两类系统工具：systemctl --user（托管接收端服务）与 ffmpeg（生成测试媒体、验证媒体编码信息）。本文一并覆盖。

💡 技术拓展：客户端不止 CLI 一种。NymphCast 官方共提供三类发送端——nymphcast_client（CLI，本文主角，只做"发现 + 推文件"两件事）、NymphCast Player（Qt5 图形客户端，支持 URL 推流、播放控制、多房间分组，是 SDK 参考实现）、LibNymphCast（C++ 库，供二次开发嵌入自有程序）。选 CLI 的理由是服务器上无图形环境且可用脚本编排；需要交互控制时再换 Player。

三、前置条件

接收端与发送端均已完成源码编译安装，nymphcast_server、nymphcast_client 可在 PATH 中直接调用（安装与验证方法见《Ubuntu 24.04 安装 NymphCast 0.2-alpha0 指南》）。
网络可达：发送端到接收端的 TCP 4004 必须放行；接收端还需 UDP 4004 可达（客户端发现靠它广播）。防火墙放行命令：

ufw allow 4004/tcp    # 放行接收端 TCP 会话与推流端口
ufw allow 4004/udp    # 放行接收端 UDP 发现端口
ufw status | grep 4004

实测回显：

4004/tcp                  ALLOW       Anywhere
4004/udp                  ALLOW       Anywhere

测试媒体一个（无真实音频文件时用 ffmpeg 现场生成，见四、3 节）。

四、各工具详解

4.1 nymphcast_server：接收端启动与参数

查看帮助（-h 与 --help 等价），实测：

nymphcast_server --help

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.

NymphCast receiver application. For use with NymphCast clients. More details: http://nyanko.ws/nymphcast.php.

Usage:
	nymphcast_server <options>

Options: 
-h	--help		Get this help message.
-a	--apps		Custom NymphCast apps location.
-w	--wallpaper		Custom NymphCast wallpaper location.
-c	--configuration		Path to configuration file.
-r	--resources		Path to GUI resource folder.
-v	--version		Output the NymphCast version and exit.

查看版本，实测：

nymphcast_server --version

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.
NymphCast version: v0.2-alpha0.20241108

参数说明（-a/-w/-c/-r 均需跟一个值）：

参数	说明	实测行为
`-c`	指定配置 INI 文件路径	必带项。指定 `/usr/local/etc/nymphcast/nymphcast_audio_config.ini` 时以纯音频模式启动
`-a`	NymphCast Apps 目录	传入 `/usr/local/share/nymphcast/apps/` 时启动日志出现 `Adding app: HelloCast`、`Adding app: SoundCloud`
`-w`	壁纸目录	视频/GUI/屏保形态显示背景图用
`-r`	GUI 资源目录	GUI 模式的界面资源；不传时日志提示 `Setting resource folder to default location.`
`-h` / `-v`	帮助 / 版本	输出后即退出

启动接收端（纯音频形态，后台运行并记录日志）：

export SDL_AUDIODRIVER=dummy   # 服务器无声卡时用 SDL dummy 音频驱动；接了音箱的真机可省略
nohup nymphcast_server -c /usr/local/etc/nymphcast/nymphcast_audio_config.ini \
  -a /usr/local/share/nymphcast/apps/ -w /usr/local/share/nymphcast/wallpapers/ \
  > /root/server.log 2>&1 &

验证监听端口（4004 TCP+UDP 均应处于监听）：

ss -lntup | grep 4004

实测回显（进程名受系统 15 字符截断限制显示为 nymphcast_serve）：

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))

查看运行日志：

tail -5 /root/server.log

实测回显：

Setting resource folder to default location.
Adding app: HelloCast
Adding app: SoundCloud
Initialising server...
Dispatcher: Setting max pool size to 10 workers.

4.2 nymphcast_client：发现与推流

查看帮助，实测：

nymphcast_client --help

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.

NymphCast client application. For use with NymphCast servers. More details: http://nyanko.ws/nymphcast.php.

Usage:
	nymphcast_client <options>

Options: 
-h	--help		Get this help message.
-v	--version		Output the NymphCast client version and exit.
-r	--remotes		Display online NymphCast receivers and quit.
-f	--file		Name of file to stream to remote receiver.
-i	--ip		IP address of the target NymphCast receiver.

查看版本，实测：

nymphcast_client --version

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.
NymphCast client version: v0.1-release.20220408

参数说明：

参数	说明	默认值
`-r`	扫描局域网内的在线接收端，列完即退出	—
`-f <文件>`	要推送到接收端的媒体文件路径	必填（缺省时报错，见 4.5）
`-i <IP>`	目标接收端 IP	`127.0.0.1`
`-h` / `-v`	帮助 / 版本	—

4.3 发现接收端：-r

-r 通过向 UDP 4004 广播探测在线接收端，实测（在发送端执行）：

nymphcast_client -r

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.
Dispatcher: Setting max pool size to 10 workers.
Scanning for online remote receivers...
Found remotes:
0. nymphcast-build24 <10.89.60.3:4004> ()

输出格式为 序号. 主机名 <IPv4:端口> (IPv6)，IPv6 为空时显示 ()。主机名即接收端系统主机名，可用 hostnamectl set-hostname 改名让它更有辨识度。当网段内没有接收端时（实测把接收端停掉后扫描）：

Scanning for online remote receivers...
No remotes found.

4.4 推流播放：-f + -i

先准备测试媒体（用 ffmpeg 合成正弦波，无需真实素材），实测：

ffmpeg -y -f lavfi -i 'sine=frequency=440:duration=30' -acodec pcm_s16le -ar 44100 -ac 2 /root/test_tone.wav

size=    5168kB time=00:00:29.97 bitrate=1412.3kbits/s speed= 239x    
video:0kB audio:5100kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 1.331825%

再生成一个 MP3 用于压缩格式验证：

ffmpeg -y -f lavfi -i 'sine=frequency=880:duration=8' -acodec libmp3lame -b:a 128k /root/test_tone.mp3

size=     126kB time=00:00:07.99 bitrate= 129.3kbits/s speed= 205x    
video:0kB audio:118kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 6.750000%

推流（在发送端执行，-i 指向接收端 IP）：

nymphcast_client -f /root/test_tone.wav -i 10.89.60.3

实测回显（日志较长，输出节选，实测首尾）：

Detected Host Little Endian.
Dispatcher: Setting max pool size to 10 workers.
Dispatcher: Setting max pool size to 10 workers.
Opening file /root/test_tone.wav
5 - 10498.0	NymphRemoteServer	515	Connect remote server...		- src/remote_server.cpp
5 - 10498.0	NymphListener	77	Adding connection. Handle: 0.		- src/nymph_listener.cpp
……（中略：推流数据块回调 MediaReadCallback、播放状态回调 MediaStatusCallback 交替出现）……
Press Ctrl+c to quit.
5 - 10528.1	NymphListener	116	Removing connection for handle: 0.		- src/nymph_listener_list.cpp
Shutting down client...

行为解读：

Opening file 出现两次（一次客户端本地、一次接收端确认）后开始传输；
Press Ctrl+c to quit. 表示推流中，此时在接收端可听到播放（无声卡验证环境则只见解码日志）；
30 秒文件播放约 30 秒后客户端自动退出（退出码 0），无需手动 Ctrl+C——播放结束的 MediaStatusCallback 会触发优雅退出；
若接收端播放中途想手动停止，在客户端按 Ctrl+C 即可断开。

接收端同步打印解码信息（tail /root/server.log，实测）：

Format WAV / WAVE (Waveform Audio), duration -9223372036854775808 usInput #0, wav, from '':
  Metadata:
    encoder         : Lavf60.16.100
  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
SetDuration. 30

MP3 压缩格式同样实测通过（跨机推流后接收端日志出现 EOF is 1、Closing audio stream component...、Closing audio device...、Terminating player...，随后客户端优雅退出）。

4.5 错误场景实测

目标 IP 不可达（实测把 IP 改成网段内不存在的 10.89.60.99）：

2 - 79.0	NymphCastClient	664	Connecting to remote server failed: Net exception: Net Exception: No route to host: 10.89.60.99:4004		- src/nymphcast_client.cpp
Failed to connect to server '10.89.60.99'

缺少 -f 参数（只给 -i）：

Please specify filename using option -f, --file

两种场景客户端均以退出码 0 结束（设计如此），脚本编排时应以输出文本而非退出码判断成败。

4.6 服务托管与辅助命令

用 systemd 用户服务托管接收端（服务文件由 make install-systemd 部署到 /etc/systemd/user/nymphcast.service，内容见《Ubuntu 24.04 安装 NymphCast 0.2-alpha0 指南》）：

systemctl --user daemon-reload        # 部署/修改服务文件后重载
systemctl --user enable nymphcast     # 开机自启（用户级）
systemctl --user start nymphcast      # 启动接收端
systemctl --user status nymphcast     # 查看状态

status 实测回显：

● nymphcast.service - NymphCast audio/video casting server
     Loaded: loaded (/etc/xdg/systemd/user/nymphcast.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-29 15:06:18 UTC; 3s ago
   Main PID: 3960 (nymphcast_serve)
      Tasks: 8 (limit: 2506)
     Memory: 15.1M (peak: 16.0M)
        CPU: 50ms
     CGroup: /system.slice/…/user@0.service/app.slice/nymphcast.service

纯音频模式下服务刚启动时常驻内存约 15 MB（实测峰值 16 MB），对低配硬件非常友好。

⚠️ 前置要求：systemctl --user 依赖 systemd 用户管理器，需要启用 systemd 的 Linux 真机。root 用户需先 loginctl enable-linger root 让用户管理器常驻，否则用户服务只在登录会话内运行。

服务日志通过 journald 查看（替代前台方式 tail 日志文件），实测：

journalctl --user -u nymphcast --no-pager -n 6

Oct 29 15:06:38 nymphcast-sysd nymphcast_server[3960]: EOF is 1
Oct 29 15:06:38 nymphcast-sysd nymphcast_server[3960]: Goto 'fail'. Exiting main loop...
Oct 29 15:06:38 nymphcast-sysd nymphcast_server[3960]: SetDuration. 0
Oct 29 15:06:38 nymphcast-sysd nymphcast_server[3960]: Closing audio stream component...
Oct 29 15:06:38 nymphcast-sysd nymphcast_server[3960]: Closing audio device...
Oct 29 15:06:39 nymphcast-sysd nymphcast_server[3960]: Terminating player...

（以上为一次 8 秒 MP3 推流播完时的服务端日志，Closing audio device... 表明一次完整播放正常收尾。）

手动检查端口是否被接收端占用：

ss -lntup | grep 4004

五、注意事项

客户端与服务端版本串不同步：v0.2-alpha0 源码编译出的 client 仍报 v0.1-release.20220408（上游 src/client/version.mk 未随版本更新）。这不是装错包，以服务端 nymphcast_server --version 的 v0.2-alpha0.20241108 判断实际版本。
单会话限制：一个接收端同一时刻只服务一个客户端会话，第二个客户端推流会被拒绝（排障见六、FAQ）。
无声卡服务器：必须设置 SDL_AUDIODRIVER=dummy 再启动接收端，否则 SDL 初始化音频子系统失败；此模式可完整验证推流与解码链路，但听不到声音。有声卡真机不要设置该变量。
发现与连接走不同协议：-r 扫描靠 UDP 广播，跨路由网段收不到；此时跳过 -r，直接用 -i <接收端IP> 推流即可（TCP 4004 可达就行）。
-f 路径是发送端本地路径：文件由客户端读取后流式推送，接收端不需要挂载该文件。

六、常见问题

Q1：推流报 Failed to cast file ... to server ...，接收端日志出现 Trying to start a new session with session already active. Abort.？

这是接收端单会话限制被触发：上一会话尚未释放时新会话被拒。实测处理：等上一客户端正常退出（播放结束自动退出后可立即再次推流，实测连续两次推流均成功）；若上一客户端被强杀导致会话卡死，重启接收端释放：

systemctl --user restart nymphcast    # 服务托管方式
# 或前台方式：killall nymphcast_server 后重新启动

重启后再次推流即恢复（实测验证）。

Q2：-r 扫描不到接收端，但 -i 直连能通？

发现走 UDP 广播（4004/udp），跨路由网段或 UDP 被防火墙拦截时失效。实测结论：同网段扫描秒回 Found remotes:；跨网段场景直接 -i <IP> 推流，效果等同。

Q3：接收端启动即退出，日志没有报错？

九成是配置文件路径不对或文件不可读。用 -v 确认版本、用绝对路径指定 -c /usr/local/etc/nymphcast/nymphcast_audio_config.ini 重试；同时确认启动环境有声卡或已设置 SDL_AUDIODRIVER=dummy。

Q4：客户端播放结束后不自动退出？

自动退出依赖接收端回报的播放完成状态（MediaStatusCallback）。若推流后客户端长时间停在 Press Ctrl+c to quit.，多为网络中断导致状态回调丢失，Ctrl+C 手动退出即可，接收端会话在连接断开后释放；若释放延迟触发单会话拒绝，按 Q1 重启接收端。

七、参考链接

官方仓库 README（客户端参数表来源）：https://github.com/MayaPosch/NymphCast
LibNymphCast SDK（二次开发用）：https://github.com/MayaPosch/libnymphcast
站内实操篇：《Ubuntu 24.04 安装 NymphCast 0.2-alpha0 指南》（编译安装与 systemd 托管）、《NymphCast 0.2-alpha0 配置参数详解》（-c 指定的 INI 参数全解）、《NymphCast 介绍与选型指南》（架构与选型）