ucmix

ucmix — StudioLive 调音台控制

ucmix 通过 PreSonus StudioLive Series III 调音台自身的网络协议（UCNET），读取和写入调音台上的任意参数。无需使用或涉及 PreSonus 软件——它会直接与调音台的控制端口通信。

首先检查

command -v ucmix
ucmix --version
ucmix profile ls        # is a mixer saved?

如果缺少 ucmix，请安装：

brew install steveclarke/tap/ucmix

如果尚未配置调音台，请查找并保存一台（调音台会在局域网中广播自身信息）：

ucmix discover          # list mixers on the network
ucmix setup             # interactive: pick one, name it, save it as the current profile
# or, if you already know the address:
ucmix profile add foh --host 192.168.1.50 --use

之后每条命令都会使用当前配置。可使用 -p <name> 或 --host <ip> 为单条命令指定其他配置。

模型 — 两个动词，共用一个命名空间

调音台拥有一个扁平的命名空间，其中包含约 20,000 个参数，每个参数都是一个 path → value：

line/ch1/username        = "Drums"      # channel 1 name
line/ch1/48v             = true         # phantom power
line/ch1/volume          = -6           # fader, dB
aux/ch1/limit/threshold  = -6           # monitor-mix limiter, dB
fx/ch1/plugin/reflection = 0.79         # a reverb knob (raw)

调音台能做的一切都由这些路径之一表示。两个动词即可涵盖所有操作：

• ucmix get <path> — 读取一个值
• ucmix set <path> <value> — 写入一个值；也可使用 set p1=v1 p2=v2 … 或 set -f <file>（每行一个 path value）通过单次连接写入多个值

请阅读 reference/paths.md，了解路径语法（分组、通道索引，以及各参数系列的值格式）。若要查看特定调音台上的实时路径，请运行 ucmix dump（全部）或 ucmix dump <prefix>（筛选）。

人类可读值与原始值

常见控件接受人类可读值，工具会将其转换为线路格式：

路径系列	输入值	而非原始线路值
.../48v、.../mute、.../*on*、.../link	on / off	（布尔值）
.../volume、.../aux{n}、.../FXA...../FXH、.../limit/threshold	dB，例如 -6dB
.../limit/release	ms，例如 400
.../username	字符串，例如 "Vox Steve"
.../color	十六进制值，例如 4ed2ff	读取结果为 8 位小写 RGBA 数字（4ed2ffff）
.../iconid	图标 ID，例如 vocals/leadvocals
.../adc_src（输入跳线）	输入编号，例如 5

其他所有路径都没有人类可读值转换层——你必须传入调音台所需的原始线路值，通常是 0..1 范围内的浮点数（例如 fx/ch1/plugin/lpf 0.869）、整数索引或枚举值。get <path> 会返回原始值；get <path> --raw 会强制返回原始值，即使路径支持人类可读值也一样。复现已捕获的设置时，请读取其原始值，并将相同的原始值写回。

命令

运行 ucmix <command> --help 查看标志；CLI 会不断演进，因此请以 --help 为准，不要认为此列表面面俱到。

• get <path> / set <path> <value> — 读取 / 写入一个参数
• set p1=v1 p2=v2 … / set -f <file> — 通过一个连接写入多个参数
• channel <n> <verb> <value> / mix <name|n> <verb> <value> / send <ch> <mix> <dB> — set 的便捷人性化命令，用于常见的通道条、监听混音和发送操作（只是薄薄一层封装；原始的 set 路径模型仍涵盖所有操作）。这些命令是为使用键盘的用户设计的——Agent 应继续使用下文的原始 get/set。
• dump [prefix] — 读取所有路径（或指定前缀下的路径）；--as-config 输出 YAML
• verify <config.yml> / apply <config.yml> — 将调音台作为代码管理：比较差异 / 写入整个配置
• store <project> <name> — 将当前状态存储为新场景（使用 --replace 覆盖现有场景）；recall <project> <scene> — 加载已存储的场景； rename <project> <scene> <new-name> — 重命名场景； delete <project> <scene> — 删除场景（具有破坏性；需要 --yes 或进行提示）。 项目和场景参数可使用显示标题（"135 Main Live"、"Opening"），也可使用调音台的槽位名称（"03.135 Main Live.proj"、"04.Opening.scn"）
• reset — 恢复出厂设置（具有破坏性；需要 --yes）
• ls projects — 列出调音台上的项目；ls scenes <project> — 列出项目的场景。<project> 是 ls projects 输出的名称（例如 01.Sevenview Live.proj）。两者都支持 --json。
• project ls — 列出项目及其标题，并标记调音台当前加载的项目
• filters ls [scene|advanced|project] / filters set <group> <tile> <on|off> — 范围筛选器，用于决定存储、调用或重置会影响哪些内容
• discover / setup / profile / config — 查找 / 保存 / 管理调音台连接

Agent 规则

• 对于输出需要解析的命令，使用 --json；纯文本输出使用 --no-color。
• 写入后用新的 get 验证。 set 报告的是已发送该值，并不表示调音台现在已处于该状态。请读回确认。
• 如果某个路径系列支持，请优先使用人性化的值（-6dB、on、输入编号）；其他情况则使用原始的 0..1 线路值。
• 要将一个调音台 / 状态的设置复制到另一个调音台 / 状态，请先运行 get <path> --raw，再运行 set <path> <that raw value>——原始值可精确往返。
• 一次调用中写入多个参数——使用 set p1=v1 p2=v2 … 或 set -f <file>——不要循环调用 set。批量操作会复用一个连接并一次性提交；单独的 set 进程会在每次写入时重新连接，快速重连时可能丢失写入。
• reset 和 apply --reset 具有破坏性——仅在指定了 --yes 且目标明确时使用。
• 切勿假设某个路径存在；请用 dump <prefix> 或在真实调音台上运行 get 进行确认。

场景 — 存储、调用、重命名

store 会像 UC Surface 一样自动分配下一个空闲的场景槽位；除非指定 --replace，否则拒绝覆盖同名的现有场景。一个项目最多有 20 个场景槽位；ErrNoFreeSlot 表示槽位已全部占用（请在 UC Surface 中删除一个）。

store 和 recall 会等待调音台确认操作，如果调音台始终未确认，就会失败——报告成功的存储操作确实已写入磁盘。这一点很重要，因为底层请求采用发送后即不再跟踪的方式：早期版本会在发送字节后立即报告成功，调音台丢弃的场景看起来却像是已保存。如果 store 报错，请视为场景未存储。

由于需要等待调音台确认，这两个命令都要花几秒钟。这是调音台正在提交到闪存，并非卡住。

ucmix store "135 Main Live" "Opening"                 # new scene, next free slot
ucmix store "135 Main Live" "Opening" --replace        # overwrite it deliberately
ucmix rename "135 Main Live" "Opening" "Opening Set"   # retitle, keeps its slot
ucmix recall "135 Main Live" "Opening Set"
ucmix delete "135 Main Live" "Opening Set" --yes      # destructive, frees the slot

delete 会释放场景槽位，供下次 store 复用。与 store 和 recall 一样，它会等待调音台确认。执行前会提示确认；--yes 可跳过提示，并且在没有终端时必须使用。

项目层与范围筛选器

项目是场景所依托的设置：输入源和跳线、AVB/SD/USB 路由、Flex 模式、GEQ、独奏。场景位于项目中。project ls 会列出项目并标记已加载的项目。将项目作为一个整体存储或调取尚未实现——UC Surface 发送的相关请求尚未捕获（issue #6），因此 project store / project recall 会给出该说明并失败，而不是猜测格式。

范围筛选器是蓝色方块，用于决定存储、调取或重置实际影响哪些内容。每个方块都是普通参数，因此可通过 get/dump 读取，并通过 set 写入；filters 是对它们的命名界面。

ucmix filters ls                       # every tile in every group, with its state
ucmix filters ls scene --json          # one group, machine-readable
ucmix filters set scene 48v on         # include phantom power in a store/recall
ucmix filters set project inputpatching off

分组：scene（场景筛选器，global/fltr*）、advanced（高级场景筛选器，advancedscenefilters/*）、project（项目筛选器，projectfilters/*）。方块名称采用调音台自身的键名，因此方块名称对应它写入的参数；- 和 _ 可以互换。filters set 会在新连接上读取方块状态并报告调音台中的值，与 set 和名词动词的行为相同。

调音台出厂时，场景筛选器的 48v 方块未选中，因此调取场景时幻象电源会保持原状。更改筛选器会影响此后每次存储和调取所包含的内容——这是全局设置，而非每条命令的标志。

已知限制

• ls projects / ls scenes 会通过 FR/FD 文件请求协议列出调音台上的预设（与 UC Surface 使用的协议相同）。调音台始终不响应时，会清楚地提示超时和解决建议，而不会一直卡住。空槽位和项目配置文件不会显示在输出中；只显示已占用的项目/场景。
• apply 会通过一个连接写入，并使用库提交屏障，然后在新连接上验证（执行新的 get）。set -f <file> 使用相同的批量写入路径，但不进行验证。
• rename 通过重新列出项目来确认，而非通过调音台的确认响应（调音台重命名时不会发送确认）。store、recall 和 delete 都会等待实际确认。 reset 仍是未经确认的即发即弃操作——它报告的是请求已发送，而非调音台已执行。
• 范围筛选器的读取已在 32R（固件 3.4.0）上通过硬件确认，写入路径也通过翻转一个方块并读回进行了确认。项目存储/调取请求尚未捕获，因此尚未实现。
• 高通滤波器已校准：频率单位为 Hz，范围是调音台的 24 Hz – 1 kHz 扫频，采用对数刻度，0 = 关闭。限制器释音曲线和混响类型枚举未经校准——其人性化转换结果为近似值。要求精确时请使用原始值。
• 部分 UCNET 参数在 UC Surface 中没有对应控件（例如 FX 返回的 Main/LR 指派，fxreturn/chN/lr）。写入此类参数会使调音台进入操作员无法通过控制台查看或撤销的状态。请优先采用对应 UC Surface 可见控件的更改（例如，要让主混音不含 FX 返回的声音，应拉低 FX 返回推子，而非取消 LR 指派）；如果某项写入在界面中没有对应操作，也请明确说明。