wfas 命令完全参考:WiFi Audio Streaming 无头守护与脚本化控制速查手册

原创2026-11-16 17:51:071,385 阅读

wfas 命令完全参考:WiFi Audio Streaming 无头守护与脚本化控制速查手册

WiFi Audio Streaming 是一款局域网音频串流桌面应用,而它内置的 wfas 命令行工具则把它变成了真正的无头守护:一条命令即可启动音频服务器或接收端,配合 wfas control、wfas config 和 --json 输出,就能在脚本、systemd 服务里完成全部控制。本文按场景整理 wfas 全部常用命令、参数与默认端口,作为一份可直接收藏的速查手册。

WiFi Audio Streaming 服务器模式界面,展示 wfas 无头守护的音频串流状态

如何获得 wfas 命令:一键安装到 PATH

wfas 与桌面应用是同一个可执行文件。首次运行应用时,它会询问是否把 wfas 安装到系统 PATH(安装逻辑见 CliPathInstaller.kt):

  • Windows:生成 .exe 垫片并加入用户 PATH
  • macOS:创建符号链接 /usr/local/bin/wfas
  • Linux:写入 PATH 中的 wfas 可执行文件

安装完成后,任何终端输入 wfas --version 都能验证。不带参数直接运行 wfas,在终端里只打印简短提示;双击或无控制台启动则会打开图形界面。

快速上手:5 条命令完成串流

下面是最常用的入口命令(完整列表定义在 CliHelpModel.kt):

wfas --server                 # 把本机音频作为服务器发出
wfas --client                 # 接收端:自动发现并加入第一个服务器
wfas --connect 192.168.1.5    # 加入指定 IP 的服务器(隐含 client 模式)
wfas --mode discover --json   # 扫描网络中活跃的服务器,输出 JSON
wfas --gui --mode server --multicast   # 打开 GUI 并立即开始组播

服务器启动后打印本机 IP、端口与当前链路状态;接收端则直接开始播放。运行中的会话支持终端内单字符命令:

输入 作用
q / quit / stop 停止并退出
v 0-100 调整音量
p / pair (服务器)打印新的配对邀请二维码
r / rekey (服务器)轮换配对密钥
s (启用 Snapcast 时)列出已连接客户端

服务器模式:wfas --server 核心参数

无头部署最常调的服务器选项如下(参数解析实现在 CliArgs.kt):

参数 默认值 说明
--port <n> 9090 WFAS 流媒体 UDP 端口
--mic-port <n> 9092 麦克风回传通道端口
--multicast 关 组播给组内所有设备(单播一次只服务一个客户端)
--persist 关 客户端断开后服务器继续等待下一个,适合 systemd 守护
--no-mute-render 关 串流时本机扬声器继续出声(默认自动静音本地播放)
--interface <name> Auto 绑定并广播用的网卡
--latency <ms> 120 Wi-Fi 链路抖动缓冲(0–5000)
--legacy-engine 关 回退到 FFmpeg 抓取引擎(Linux 无 PulseAudio 时)

典型无头服务命令:

wfas --server --persist --port 9090        # systemd 里常驻的单播服务器
wfas --server --multicast --json --quiet   # 组播 + JSON 事件,便于日志采集

端口被占用时,wfas 会直接报 port_in_use 并提示换端口(退出码 4),不会静默失败。

WiFi Audio Streaming 客户端模式界面,wfas --client 连接服务器后的音频接收视图

多协议同时广播:RTP / HTTP / DLNA / Snapcast

服务器可以在 WFAS 原生协议之外同时启用四种标准协议,让 VLC、浏览器、电视、树莓派都能收听(开启任一项都会自动隐含 --multicast):

参数 默认端口 场景
--rtp 9094 VLC / ffplay / 硬件 RTP 接收端
--http 8080 任意浏览器、媒体播放器直接打开 URL
--http-safari 8080 Safari/iOS 兼容的 AAC
--dlna [--dlna-format auto|lpcm|wav|mp3|adts] 8081 推送到 AV 功放、智能电视
--snapcast [--snapcast-codec pcm|flac|opus] 1704/1705 同步多房间,任意 snapclient 可加入

WiFi Audio Streaming 多房间音频串流界面,Snapcast 与 RTP 等协议同时广播

搭配 --sdp / --sdp-out <path> 还能在启动时打印或写出 SDP 描述文件,交给 VLC 之类的播放器直接打开。注意:只有原生 WFAS 流支持认证与加密,标准协议始终明文。

安全三件套:密钥、加密与 QR 配对

--auth-mode 仅作用于单播 WFAS 流,可选 off | ask | key:

# 密钥模式:密钥不会在链路上明文传输,靠 HMAC 挑战-响应互相证明
wfas --server --auth-mode key --auth-key <key> --encrypt   # ChaCha20-Poly1305 端到端加密
wfas --server --auth-mode key --auth-key -                # 密钥从 stdin 读,避免留在 shell 历史
wfas --server --auth-mode key --auth-key-file ~/.wfas.key  # 从文件读(取第一个非空行)
WFAS_AUTH_KEY=xxx wfas --server --auth-mode key           # 环境变量方式,适合无人值守

密钥的查找顺序是:命令行 → 环境变量 WFAS_AUTH_KEY → 系统凭据库 → 终端交互输入;全部落空则拒绝启动(fail-closed),相关逻辑见 CliMode.kt。

QR 配对把「地址 + 端口 + 256 位密钥」一次打包成二维码:

wfas --server --qr                          # 自动生成密钥、加密启动并打印终端二维码
wfas pair invite --watch                    # 活体二维码:到期自动刷新,n 新邀请 / r 换密钥
wfas pair connect 'wifiaudio://pair?...'     # 接收端凭邀请链接直接加入
wfas pair inspect '<link>'                  # 不解码不连接,只看链接内容
wfas pair regenerate                        # 换新密钥,踢掉仍用旧密钥的监听者

--qr 的密钥只存在于当前进程,不写配置、不进凭据库,服务器关闭即失效。

WFAS v2 协议时序图,wfas 命令行加密配对与音频包传输

wfas config:GUI 与 CLI 共享的配置读写

GUI 和 wfas 共用同一个 config.json,用 wfas config 就能完整读写(实现见 ConfigCli.kt):

wfas config list                     # 列出全部设置及当前值
wfas config get audio.sampleRate     # 读单个键
wfas config set audio.latencyMs 60   # 改并保存(GUI/CLI 下次启动生效)
wfas config path                    # 打印 config.json 的绝对路径
wfas config edit                     # 用默认编辑器打开
wfas config reset                    # 恢复全部默认
wfas config export backup.json       # 导出(密钥默认掩码)
wfas config import backup.json       # 导入并激活

配置文件位置(见 ConfigPaths.kt):

系统 路径
Windows %APPDATA%\wfas\config.json
macOS ~/Library/Application Support/wfas/config.json
Linux ~/.config/wfas/config.json(遵循 XDG_CONFIG_HOME)

常用键名:audio.sampleRate、audio.latencyMs、net.streamingPort、net.usbMode、server.persist、server.muteRender、security.mode、security.authKey、app.theme。密钥类值默认显示为 ********,需要时加 --reveal(只允许在交互终端打印,拒绝管道与 --json,防止密钥意外进日志)。--config <path> 可临时指定另一份配置文件。

WiFi Audio Streaming 设置界面,wfas config 可读写同一份 JSON 配置

wfas control:不重启实例的远程遥控

wfas control 通过本地 IPC 通道(见 IpcClient.kt)与正在运行的实例通信——GUI 或 CLI 都一样:

wfas control volume 75     # 设置输出音量(0-100)
wfas control mute          # 静音
wfas control unmute        # 取消静音
wfas control status        # 当前串流状态,含 RTP/HTTP/DLNA/Snapcast 侧协议
wfas control stop          # 停止运行中的实例

找不到运行实例时输出 No running wfas instance found. 并以退出码 2 结束,方便脚本判断。

接收别人发起的流:wfas rtp 与 wfas snapcast

wfas 既是发送端也是接收端:

# RTP 接收:源可以是 .sdp 文件、标准输入、地址或已保存的名字
wfas rtp listen stream.sdp
wfas rtp listen 239.255.0.1:9094 --rtp-codec L16
wfas rtp inspect stream.sdp        # 不打开 socket,解析描述符并列出假设项
wfas rtp sources                   # 查看已保存源(#n 索引)
wfas rtp save kitchen --rtp-address 239.255.0.1
wfas rtp forget kitchen

# Snapcast 客户端:加入多房间系统并从控制通道管理全屋
wfas snapcast discover             # 发现网内 Snapcast 服务器
wfas snapcast listen               # 加入并同步播放
wfas snapcast mixer                # 全屏键盘遥控器:播放 + 管理所有房间
wfas snapcast mixer --no-audio     # 只遥控不发声(笔记本当遥控器)
wfas snapcast status --watch       # 实时跟踪全屋状态
wfas snapcast volume kitchen 40    # 按名字/ID/#n 指定客户端
wfas snapcast latency #1 300       # 单房间延迟校准(-2000~2000ms)
wfas snapcast move kitchen Living  # 移动客户端到分组

监控与排障:--viz、--debug、--json

参数 用途
--viz [主题] 终端 ASCII 频谱可视化;主题支持 rainbow 或任意十六进制色如 #1e88e5
--groove [soft|normal|hard] 与 --viz 搭配,自适应频谱跟随旋律而非原始电平
--monitor 不建服务器,只可视化本机系统音频(wfas --viz --monitor)
--debug 实时 UDP 数据包表 + 内部状态 HUD,并列出网卡(供 --usb-iface 参考)
--json 几乎所有命令/事件输出 JSON 行,专为脚本和日志设计
--quiet 只保留 stderr 错误

USB 直连相关:--usb(走 USB tethering,抖动更低)、--usb-latency <ms>、--usb-iface <name>、--wfas-mode always\|not-on-usb\|off;--ip4 / --ip6 可强制地址族。

防火墙与系统命令

wfas firewall allow              # Windows:一键放行入站 UDP(流/发现 9091/麦克风)
wfas firewall allow 9090,9091    # 只放行指定端口
wfas firewall status             # 检查 WFAS 防火墙规则是否生效
wfas devices --json              # 列出全部音频设备及精确名称(供 --output 使用)
wfas --protocol                  # 打印 WFAS v2 线协议说明
wfas --check-update              # 检查新版本
wfas --auto-check-update off     # 关闭启动时自动检查更新

退出码速查:脚本里判断结果

wfas 用固定退出码区分失败原因(定义在 CliMode.kt):

退出码 常量 含义
0 OK 成功
1 USAGE_ERROR 参数错误 / 缺少密钥
2 NOT_FOUND 未找到实例或未找到服务器
3 DISCONNECTED 连接中断 / 超时 / 协议不兼容
4 RESOURCE_ERROR 端口被占、无输出设备等
5 AUTH_FAILED 控制通道认证失败或密钥错误

一段典型守护脚本:

wfas --server --persist --auth-mode key --auth-key-file /etc/wfas/key --json >> /var/log/wfas.log 2>&1
# 另开终端
wfas control status --json   # 查看状态
wfas control stop            # 优雅停止

如何查更多帮助:--help 的主题系统

wfas --help 打开交互式帮助浏览器,也可精确取某一部分:

wfas --help                # 交互浏览(非终端输出自动降级为全文)
wfas --help all            # 一次性打印全部章节
wfas --help server         # 只看某个主题
wfas --help --json         # 整张参数表输出 JSON,供补全或文档生成

主题共 10 个:start、server、client、protocols、receive、network、security、config、runtime、reference,协议细节另见仓库根目录的 WFAS_PROTOCOL.md。

小结

掌握三条主线就能驾驭 wfas:

  1. 起服务:wfas --server(+ 协议参数 + --persist)
  2. 管状态:wfas control / wfas config(IPC 热控制 + 持久配置)
  3. 进脚本:--json + 退出码(机器可读、可判断)

再配上 --qr 配对与 --encrypt 加密,一台无显示器的机器就能长期充当局域网音频源,或作为 Snapcast / RTP 的同步接收端运行。

登录后查看全文
WiFiAudioStreaming-Desktop