wfas 命令完全参考:WiFi Audio Streaming 无头守护与脚本化控制速查手册
wfas 命令完全参考:WiFi Audio Streaming 无头守护与脚本化控制速查手册
WiFi Audio Streaming 是一款局域网音频串流桌面应用,而它内置的 wfas 命令行工具则把它变成了真正的无头守护:一条命令即可启动音频服务器或接收端,配合 wfas control、wfas config 和 --json 输出,就能在脚本、systemd 服务里完成全部控制。本文按场景整理 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),不会静默失败。
多协议同时广播: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 可加入 |
搭配 --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 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> 可临时指定另一份配置文件。
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:
- 起服务:
wfas --server(+ 协议参数 +--persist) - 管状态:
wfas control/wfas config(IPC 热控制 + 持久配置) - 进脚本:
--json+ 退出码(机器可读、可判断)
再配上 --qr 配对与 --encrypt 加密,一台无显示器的机器就能长期充当局域网音频源,或作为 Snapcast / RTP 的同步接收端运行。




