VxAPO CLI 是 VxAPO 的命令行工具,负责设备管理、配置读写与诊断。App(Tauri)通过提权子进程 调用它完成安装、卸载与验证。CLI 把注册表写入交给 driver 的事务层,自己不决定槽位策略。
阅读顺序:定位与边界 → 命令一览 → 安装与验证 → 交互模式 → 契约 crate → 与 Driver / App 的 边界 → 上手 → 测试 → 参考。
在本仓工作前先读
AGENTS.md(面向人与 AI):格式由cargo fmt单一 权威决定、提交前须git config core.hooksPath .githooks、cargo fmt --all会连带 格式化 driver 的文件(故一律用-p)、以及只能用 driver facade 登记的 API。
| CLI 负责 | CLI 不负责 |
|---|---|
端点枚举与状态展示(list / status) |
槽位模式的选择与写入策略(driver install/selector) |
| 调用 driver 的安装 / 卸载事务 | 回滚:CLI 没有回滚子命令;App 的 rollback_install 失败兜底时改调 vxapo-cli uninstall |
配置文件读写与旧格式转换(config) |
配置的校验规则(边界由 driver 定义,CLI 只按边界限幅) |
注册表基线快照(snapshot) |
实时热重载(driver 侧事件驱动) |
效果器参数表透传(effects schema) |
参数范围的维护(来源是 driver 的 effect_param_specs()) |
旧 GUID 残留的查询 / 迁移 / 清理(stale) |
设备端点的身份判定(以设备实例 ID 为稳定身份) |
| 命令 | 作用 | 关键选项 / 子命令 | 实现位置 |
|---|---|---|---|
list / status |
枚举端点 | --json 供 App 与脚本消费 |
src/commands/status.rs |
install -d <device> |
安装 | --mode、--no-child、--verify、--progress-file、--timeout |
src/commands/install.rs |
uninstall -d <device> |
卸载 | -d 或裸 <device> 均可 |
src/commands/uninstall.rs |
register |
注册 COM CLSID | 使用 exe 同级的 vxapo_driver.dll |
src/commands/register.rs |
config show -d <device> |
读配置 | 每设备 C:\ProgramData\VxAPO\{GUID}\config.toml |
src/commands/convert.rs |
config set -d <device> -f <file> |
写配置 | 写回前按 driver 边界限幅 | 同上 |
config convert <old> <out> |
旧文本配置转 TOML | 一次性迁移 | 同上 |
snapshot create / diff / restore -d <device> |
注册表基线 | 只动注册表,不触碰配置内容 | src/commands/snapshot.rs |
stale list / migrate / cleanup / fix-acl |
旧 GUID 残留 | 以设备实例 ID 匹配活跃端点 | src/commands/install.rs |
effects schema [--json] |
效果器参数表 | App 据此生成 TS 表 | src/commands/effects.rs |
help / 无参数 |
打印帮助 / 进入交互模式 | — | src/main.rs |
--verify不是默认开启。install的签名是verify: bool(src/commands/install.rs)。 不传该开关时,install直接调用 driver 的install_endpoint,不跑验证闭环。- CLI 没有
rollback子命令。回滚是 App 侧兜底:rollback_install(vxapo-app/src-tauri/src/lib.rs)改调vxapo-cli uninstall。
install --verify 的执行顺序(src/commands/install.rs 与 src/verify.rs):
require_admin():非管理员直接失败。auto_register_driver():定位 exe 同级的vxapo_driver.dll,注册 COM CLSID 绑定。- 确保
config.toml存在。缺失时导入默认配置,使验证通过后的状态就是最终可用状态。 - 走验证闭环:停服务 → 启服务 →
CoCreateInstance→GetMixFormat→Initialize→test_pipe回环。
--progress-file <path> 把阶段事件写成 JSON 事件流:register / config / verify 等阶段
由 emit_phase 发出,App 后端订阅后展示进度。
不带 --verify 时,install 只调 driver 的 install_endpoint。DisableProtectedAudioDG、
槽位与 ProcessingModes 写入、安装后重启都由 driver 在该调用内完成,CLI 不重复。
无参数运行进入交互模式。程序先询问语言,再询问模式。
| 选择 | 模式 | 内容 |
|---|---|---|
1 |
查看模式 | 枚举端点,检查槽位 / 格式 / 增强 |
2 |
Driver 模式 | 安装 / 卸载 / 配置 / 快照 |
q |
— | 退出 |
本仓是 cargo workspace,成员 protocol/ 只依赖 serde、serde_json 与 ts-rs,不依赖 driver:
- 安装 / 卸载进度事件:
InstallProgressEvent(#[serde(tag = "event")],六类 variant)。 - 残留列表:
StaleInstall/StaleTargetState/StaleMatchedBy。迁移报告:MigrationReport。 - App 侧类型由 ts-rs 生成,两端因此不各自维护一份。
进度事件以类型化方式发射(EventSink::emit 接收 impl Serialize),并有逐字节形状回归测试
锁定输出形状。stale 相关 JSON 在 CLI 侧从 driver 类型映射,protocol 因此保持无 driver 依赖。
| 事项 | 决定方 | CLI 的角色 |
|---|---|---|
| 安装模式与子 APO 保留策略 | driver install/selector |
透传参数 |
数值边界(增益 [-120,+48]、段数上限、NaN/inf) |
driver | 写回前按边界限幅。driver 只在内存 clamp |
配置模型(version=1 / enabled / [meta] / [[effects]]) |
driver | config convert 按当前模型生成 |
旧类型名兼容(maximizer / leveler / auralenhancer / loudnesscorrection) |
driver 解析时映射 | 不做额外处理 |
| 注册表写入 | driver 事务层 | 只调用,不自己拼槽位 |
App 不直接写注册表,一律经提权 CLI 执行。
前提:Windows 8.1+ 与 Rust(MSVC)工具链。对设备做安装 / 卸载需要管理员权限。
cargo build --release # 产物 vxapo-cli.exe
vxapo-cli list # 查设备(序号或 {GUID})
vxapo-cli install -d 0 --mode SfxEfx --verify # 安装并跑验证闭环
vxapo-cli snapshot diff -d 0 # 核对注册表变更
vxapo-cli uninstall -d 0cargo test # 22 个测试安装模型(逐设备注册 APO 槽位、把原 APO 保留为子 APO)与验证流程参考了 Equalizer APO 的公开实践。本工具是独立实现, 不含 Equalizer APO 代码。Equalizer APO © Jonas Thedering,GPL-2.0。
- 项目文档见
../vxapo-docs,CLI 规范见../vxapo-docs/cli。 - 许可证:GPL-3.0-or-later(全文见
LICENSE)。 Copyright (C) 2026 VxAPO。本程序不提供任何担保,详见 GPL-3.0 第 15、16 条。
VxAPO CLI is the command-line tool for VxAPO. It manages devices, reads and writes config, and runs diagnostics. The App (Tauri) calls it as an elevated subprocess for install, uninstall and verification. The CLI hands registry writes to the driver transaction layer and does not choose the slot strategy itself.
Reading order: scope and boundaries → commands → install and verification → interactive mode → contract crate → boundaries with the Driver / App → getting started → tests → references.
Read
AGENTS.mdbefore working in this repository (for humans and AI): formatting is decided solely bycargo fmt, rungit config core.hooksPath .githooksonce per clone,cargo fmt --allalso reformats driver's files (always use-p), and only APIs registered in driver's facade may be used.
| The CLI owns | The CLI does not own |
|---|---|
Endpoint enumeration and status output (list / status) |
Slot mode selection and the write strategy (driver install/selector) |
| Calls to the driver install / uninstall transaction | Rollback. The CLI has no rollback command. The App's rollback_install fallback calls vxapo-cli uninstall instead |
Config read/write and legacy format conversion (config) |
Config validation rules. The driver defines the bounds, and the CLI only clamps to them |
Registry baseline snapshots (snapshot) |
Hot reload. The driver watches file events |
Relaying the effect parameter table (effects schema) |
Parameter range maintenance. The ranges come from the driver's effect_param_specs() |
Query, migration and cleanup of stale GUIDs (stale) |
Endpoint identity. The driver matches on the device instance ID |
| Command | Purpose | Key options / subcommands | Where implemented |
|---|---|---|---|
list / status |
Enumerate endpoints | --json for the App and scripts |
src/commands/status.rs |
install -d <device> |
Install | --mode, --no-child, --verify, --progress-file, --timeout |
src/commands/install.rs |
uninstall -d <device> |
Uninstall | -d and a bare <device> both work |
src/commands/uninstall.rs |
register |
Register the COM CLSID | Uses vxapo_driver.dll next to the executable |
src/commands/register.rs |
config show -d <device> |
Read config | Per device C:\ProgramData\VxAPO\{GUID}\config.toml |
src/commands/convert.rs |
config set -d <device> -f <file> |
Write config | Clamps to driver bounds before writing | same |
config convert <old> <out> |
Legacy text config to TOML | One-time migration | same |
snapshot create / diff / restore -d <device> |
Registry baseline | Touches the registry only, never config content | src/commands/snapshot.rs |
stale list / migrate / cleanup / fix-acl |
Stale GUID records | Matches active endpoints by device instance ID | src/commands/install.rs |
effects schema [--json] |
Effect parameter table | The App generates its TS table from this | src/commands/effects.rs |
help / no arguments |
Print help / enter interactive mode | — | src/main.rs |
--verifyis not the default. Theinstallsignature takesverify: bool(src/commands/install.rs). Without the flag,installcalls the driver'sinstall_endpointdirectly and runs no verification loop.- The CLI has no
rollbacksubcommand. Rollback is an App-side fallback:rollback_install(vxapo-app/src-tauri/src/lib.rs) callsvxapo-cli uninstall.
install --verify runs these steps in order (src/commands/install.rs, src/verify.rs):
require_admin()fails the run when the process is not elevated.auto_register_driver()locatesvxapo_driver.dllnext to the executable and registers the COM CLSID binding.- The CLI makes sure
config.tomlexists. When it is missing, the CLI imports the default config, so a passing verification leaves the device in its final usable state. - The verification loop runs: stop service → start service →
CoCreateInstance→GetMixFormat→Initialize→test_piperound trip.
--progress-file <path> writes the phase events as a JSON stream. emit_phase emits phases
such as register, config and verify. The App backend subscribes and shows progress.
Without --verify, install calls only the driver's install_endpoint. That call handles
DisableProtectedAudioDG, the slot and ProcessingModes writes, and the post-install
restart. The CLI does not repeat any of it.
Run the tool with no arguments to enter interactive mode. It asks for a language first, then for a mode.
| Choice | Mode | Contents |
|---|---|---|
1 |
Viewer | Enumerate endpoints and inspect slots, formats and enhancements |
2 |
Driver | Install, uninstall, config and snapshot operations |
q |
— | Quit |
This repository is a cargo workspace. The protocol/ member depends on serde, serde_json and
ts-rs only, and never on the driver:
- Install and uninstall progress events:
InstallProgressEvent, with six variants tagged byevent. - Stale records:
StaleInstall/StaleTargetState/StaleMatchedBy. Migration report:MigrationReport. - ts-rs generates the App-side types, so the two sides do not maintain separate copies.
The CLI emits progress events as typed values (EventSink::emit takes impl Serialize), and
byte-exact shape regression tests pin the output. The CLI maps stale JSON from driver types,
which keeps protocol free of driver dependencies.
| Item | Decided by | The CLI's role |
|---|---|---|
| Install mode and child-APO preservation policy | driver install/selector |
Passes parameters through |
Numeric bounds (gain [-120,+48], band-count limit, NaN/inf) |
driver | Clamps on write. The driver clamps in memory only |
Config model (version=1 / enabled / [meta] / [[effects]]) |
driver | config convert generates the current model |
Legacy type names (maximizer / leveler / auralenhancer / loudnesscorrection) |
driver parse time | No extra handling |
| Registry writes | driver transaction layer | Calls into it and never assembles slots itself |
The App never writes the registry directly. It always goes through the elevated CLI.
Prerequisites: Windows 8.1+ and a Rust (MSVC) toolchain. Device install and uninstall need administrator rights.
cargo build --release # produces vxapo-cli.exe
vxapo-cli list # list devices (index or {GUID})
vxapo-cli install -d 0 --mode SfxEfx --verify # install and verify
vxapo-cli snapshot diff -d 0 # inspect registry changes
vxapo-cli uninstall -d 0cargo test # 22 testsThe install model (per-device APO slot registration, keeping the original APO as a child) and the verification workflow reference the public practice of Equalizer APO. This tool is an independent implementation and contains no Equalizer APO code. Equalizer APO © Jonas Thedering, GPL-2.0.
- Project documentation:
../vxapo-docs. CLI reference:../vxapo-docs/cli. - License: GPL-3.0-or-later (full text in
LICENSE). Copyright (C) 2026 VxAPO. This program comes with absolutely no warranty; see sections 15 and 16 of GPL-3.0.