Collaplex 音效

把系统音频接成一条耳机空间音效链(PipeWire + 自研 DSP), 带本地控制面板。

第二代(2026-09-19): 对第一代 edgevoid/cinema-spatial 推倒重构 —— 从"一张 40+ 节点的大图、 改个参数要重装重载"改成"每个效果级独立实例 + 自研 DSP、参数实时生效"。

	第一代 (cinema-spatial)	第二代 (本项目)
架构	filter-chain 大图(40+ 节点), 串联调试	每个效果级独立实例 + 自研 DSP, 靠 node.target 串链, 可单独推流取证
EQ	param_eq 三段, 改配置要重装	32 段 1/3 倍频程(实时) + 10 个预设
响度	无	响度归一化(能量滑窗 + 6 dB/s 限速, 左右 flock 共享增益防声像漂)
混响	混在图里, 湿量写死	convolver(3 秒长 IR) + 独立湿量级(滑块实时可调)
控制	简单开关	本地面板 62 Hz 推送: 4 个双声道电平表 / 归一化电平与动态增益 / 湿度与总音量 / 32 段 EQ
分发	deb	deb + 主命令 collaplex-audio start/stop/web(装完不动系统音频)

第二代把"能跑"升级成**"可调 + 可验"**: 每个效果级都能单独推流取证, 参数走共享内存立即生效, 失真 / 削波 / 底噪 / 混响尾巴全部拿实测数据说话(见文末「实测」与「测试脚本」)。

全局音频(应用输出)
  → collaplex_vsink          虚拟声卡(全局默认输出)
  → 响度归一化              pipe DSP ×2(左右各一进程, flock 共享增益)
  → collaplex_hrtf_in       双耳 HRTF(SADIE II / H4, 4 条卷积)
  → 房间混响                convolver(3 秒 IR) + 湿量级(pipe DSP ×2)
  → collaplex_eq_in         32 段 EQ + 总音量 + 软限幅(pipe DSP ×2)
  → 数字输出(S/PDIF)

共 6 个节点 + 6 个 DSP 进程。全链 96 kHz。

安装

源码树里(开发用):

collaplex-audio start            # 等价于 bash 脚本/安装.sh

deb 包:

sudo dpkg -i collaplex-audio_1.0.0_all.deb
collaplex-audio start            # 装完不会自动接管, 必须手动这一步

依赖 python3-numpy / python3-scipy / pipewire / wireplumber。 装完不动你的系统音频: 不写 pipewire 配置、不做开机自启, 手动 start 才接管, stop 即还原(默认输出回到硬件设备)。

主命令

日常就三个动作:

collaplex-audio start    # 启动: 接管系统音频(部署配置 + 重载 PipeWire + 自检)
collaplex-audio stop     # 停止: 恢复系统默认输出, 同时关掉面板
collaplex-audio web      # 面板: 起控制面板并打开浏览器

start 做的事: 探测数字输出 → 部署 pipe 插件入口 → 渲染 4 份配置 → 清掉残留 DSP (占住共享槽位会让新实例起不来) → 重载 PipeWire → 自检。 WET=0.4 bash 脚本/安装.sh 可指定初始湿量(默认 0.3)。 面板端口可换: WEB_PORT=8899 collaplex-audio web。

开机自启

链路不需要服务 —— 4 份 conf 部署在 ~/.config/pipewire/pipewire.conf.d/, PipeWire 一起来 就自动加载, 虚拟节点与 DSP 进程跟着起; 默认输出由 WirePlumber 记忆, 开机仍是 collaplex_vsink。 所以 start 跑过一次就长期有效。

面板用 systemd 用户服务 collaplex-audio-panel.service 自启(登录即起, Restart=no), start 时会自动装上并 enable。不要了:

systemctl --user disable --now collaplex-audio-panel.service   # 取消自启并停掉面板
collaplex-audio stop                                          # 连链路一起还原成系统默认输出

音频设备与 PipeWire 都是用户级的, 所以"开机自启"实际是登录自启。

控制面板

collaplex-audio web → http://127.0.0.1:8789

区域	内容
电平	双声道 4 个表: 入 L / 出 L / 入 R / 出 R。条长 = 实时 RMS(−60~0 dBFS), 小字 = 本块峰值
电平归一化	响度目标滑块 + 输入电平条 + 动态增益推子(0 dB 在 60% 刻度线上, 量程 −18~+12 dB)
混响湿度	0 ~ 1, 实时生效
总音量	±12 dB, 实时生效
32 段 EQ	1/3 倍频程(20 Hz ~ 25 kHz), 每段 ±15 dB,10 个预设

• 所有滑块: 滚轮调节 · Shift+滚轮微调 · 双击归零
• 面板刷新 62 Hz(SSE 推送), 表头带快起慢落 + 峰值保持 1.6 秒
• 预设: 平直 / 流行 / 摇滚 / 爵士 / 古典 / 人声 / 低音 / 高音 / 深夜 / 柔化 —— 每个只写 4~5 个「频率+增益」控制点, 在对数频率轴上插值成 32 段
• 参数落点: /dev/shm/collaplex-eq(前端写、DSP 读, 版本号保证不会读到半更新); 响度目标写 ~/.local/state/cinema-spatial/loudness.json(归一化 DSP 每秒重读)
• 改参数不用重装 —— 只有改 DSP 代码或 PipeWire 图才需要重跑 start

空间数据来源

用途	数据	来源
双耳 HRTF	SADIE II 受试者 H4, 96 kHz / 24 bit, 每条 4800 tap(约 50 ms)	University of York 音频实验室, Zenodo DOI 10.5281/zenodo.12092466
房间混响	自家房间模型程序化生成的双耳 IR(3 秒)	本项目 reverb/

• hrir/ 的 12 条 = H4 的 6 个方向 × 左右耳(BL / BR / FC / FL / FR / LFE); 链路实际用前左 + 前右共 4 条(FL_L / FL_R / FR_L / FR_R)做双耳化
• SADIE II 为真人受试者测量: 2818 个方向, 仰角 ±90°, 测距 1.2 m

实现要点与踩过的坑

结构

• 每个效果级做成独立实例: 一个接入 sink + 一个输出 target, 靠 node.target 串成链。 可以在任意一级单独 pw-play 推流验证, 不用在主链路上串联调试。
• pipe 插件的 command 只吃「程序 + 一个参数」(shebang 式 exec), 参数全写进 wrapper; 且 wrapper 路径必须是纯 ASCII(中文路径静默失效)。
• 湿量为什么抽成独立 DSP: 混响交给 PipeWire 的 convolver(能跑 3 秒长 IR), 但图里的 mixer 增益是加载时定死的, 改它必须重载 = 断音。所以只把"湿量"抽出来做 DSP 增益级。
• 左右声道各 fork 一个 DSP 进程、命令相同, 靠 flock 抢声道槽位区分(进程死锁自动释放)。

DSP

• 块长不能假设固定: quantum 在 32 ~ 2048 之间浮动, 按实际读到的长度一对一处理。 用 np.resize 补到固定长度会重复填充 → 周期性伪影(听感"沙沙")。
• 增益要块内插值: 整块共用一个增益会在块边界留台阶(zipper 噪声)。改为 「上一块增益 → 本块增益」的逐样本斜坡后, 谐波(相对基频) +0/+6 dB 由 −12.1 / −15.9 dB 降到 −90.1 / −70.6 dB。
• 软限幅阈值要贴近 0: 上限 ceiling=0.99 / knee=0.06(介入点 −0.63 dBFS)。 曾用 −3.9 dBFS, 而音乐的峰值(−4 ~ 0 dBFS)长期落在里面被压 → 中低频谐波。
• 归一化用能量滑窗 + 限速(目标 −14 dBFS, 6 dB/s), 左右进程 flock 共享同一增益 → 声像不漂。

陷阱

• convolver 的 gain 是线性倍数, 不是 dB —— 写 -18.0 会变成"反相 ×18", 电平反而更高。 房间 IR 未归一化(频响在 100~200 Hz 高 20 dB), 所以要标定成 gain = 0.126。
• param_eq 端口名带编号(In 1 / Out 1), 写成 :In 会让整张图加载失败, 模块静默降级成直通。
• 峰值相关的失真, 纯音测不出来 —— 纯音峰值因子仅 3 dB, 音乐是 10~14 dB。 必须用高峰值因子素材测, 见 测试/test_limit.py。
• 改完 watchdog / 常驻脚本要重启巡检 —— 旧定义还在内存里按旧参数拉服务。
• 按命令行找进程要按"后段"匹配 —— 面板若用相对路径起过(.venv/bin/python web/server.py), 只匹配绝对路径会漏杀 → 端口被占、新服务起不来。写 *web/server.py* 这种够特异的后段。
• 清进程时匹配串要够特异: 写 *dsp/eq.py* 会匹配到自己的命令行而自杀, 至少写成 *python*dsp/eq.py*。
• 房间 IR 当混响用之前, 必须清掉里面的直达声 / 传播延迟 —— 否则就是回声。 原 IR 前 20 ms 是静音、主峰在 30 ms(= 声源到麦克风 10.3 m 的声程), 前两次反射还跟 直达声同量级(30 ms 处 0 dB、40 ms 处 −1.6 dB)。干声(HRTF)是零延迟的, 两路一相加 就成了"湿声晚 30 ms 还很响" = 明显的回声。 脉冲取证: 主峰后 120 ms 处一个 −26 dBFS 孤立峰(比周围高 12 dB); 湿量设 0 则完全没有。 修法(工具/重做混响IR.py, 原文件备份为 .orig.wav): 裁掉前 22 ms 纯静音 → 前 55 ms 余弦渐入(直达声段 0 → −23.6 dB) → 只留混响尾; 再把 gain 重标 0.126 → 0.4 (剪掉直达声后湿声整体掉 ~19 dB, 不补就是"回声没了、混响也没了")。
• 房间 IR 必须保持双声道, 并在 conf 里用 channel 分别取左右 —— 2026-09-19 版 工具/重做混响IR.py 里写了 x = x[:, 0], 把立体声 IR 的右声道直接丢掉, 写出去的 IR 成了单声道; 而 20-conf 里 revL / revR 读的是同一个文件 —— 两路湿声完全同源, 混响糊在正中央、没有宽度(原 IR 本身是双声道真立体声, 左右相关 0.884)。 修法: 处理时逐声道做、双声道写回; conf 里 revL 用 channel = 0、revR 用 channel = 1。 PipeWire 的 convolver 支持 channel 参数(libspa-filter-graph-plugin-builtin.so 里的合法配置键: filename / channel / gain / blocksize / delay / latency / length / offset / tailsize / resample_quality), 从多声道 IR 文件里按索引取声道。
• 验证"混响左右是否真的独立", 别用尾巴左右相关系数 —— 混响尾巴能量集中在低频, 而 HRTF 左右耳在低频几乎没有头影差异, 所以 IR 无论单声道还是立体声, 尾巴左右相关 都接近 0.9996, 判据完全不敏感, 会把"已修好"误判成"没生效"(2026-09-20 实测踩过)。 敏感判据 = 通道探针: 把一个声道指向"左声道全零、右声道为真数据"的双声道文件, 再配 channel = 1; 若该声道输出没有塌掉, 就说明真的按索引取到了第 2 声道 (实测左右差仅 1.1 dB; 读错声道会掉 40 dB 以上)。
• HRIR 的频响校正要用"同相合并响应", 不是标准 DF-EQ —— 标准漫反射场均衡按各方向 功率平均取参考(假设各方向互不相关), 这套 HRIR 按它算只需要压 1.5 dB; 但真实内容 (人声/低频居中, L ≈ R)两耳信号是相加的, 同相合并响应实测低频高 7.5 dB, 这才 是用户实际听到的量。按同相合并设计后低频压 7.2 dB, 端到端复测低频落到 0(见下)。
• 参数必须落盘, 不能只活在 /dev/shm 里 —— 共享内存是 tmpfs, 重启即空。如果 open_store() 只是"不存在就零填充创建", 重启后参数全变 0 —— 听感上不是"参数没保存", 而是**"混响突然没了"(湿量 0), 极易被当成链路故障去查(2026-09-20 实测复现)。 修法: 改成"文件是新建的** → 从落盘恢复", 落盘由面板在每次改参数时写(见「参数持久化」)。

IR 校正(2026-09-20)

两处校正都改文件、不改 conf(数据干净、conf 简洁、任何用到这些 IR 的地方都受益), 工具 工具/均衡IR.py 可重跑, 原文件一律备份为 .orig.wav。曲线由 工具/分析均衡曲线.py 量出来。都用一个共用的 lowshelf, 所以 HRTF 的方向线索(ILD/ITD)不受影响。

对象	问题	校正	效果
12 条 HRIR	同相输入时低频比 1 kHz 高 7.5 dB	lowshelf 500 Hz −7.2 dB Q=0.707	端到端低频 +7.5 → −0.1 dB
房间 IR	低频比中频高 24.5 dB, 湿路灌低频	lowshelf 300 Hz −21 dB Q=0.70	低频 +24.5 → +5.8 dB(留一点厚度)

配套改动:

• LN_MAX_BOOST 20 → 12(默认值) —— 20 dB 的提升上限会把任何轻内容顶穿满刻度, 是"软限幅常年介入"的直接原因。
• 房间 IR 被压低频后峰值掉 3.7 dB, 湿路 gain 相应 0.4 → 0.61 补偿, 这样听感差异 纯粹来自"低频变干净"而不是"混响变小"。

参数持久化(2026-09-20)

面板上拖出来的 32 段 EQ / 总音量 / 湿量, 现在会落盘; 共享内存被清空后(开机、重启、 systemctl restart pipewire)由 DSP 自动恢复。

为什么需要: /dev/shm 是 tmpfs, 重启就没了。修之前 dsp/common.py 的 open_store() 是"文件不存在就零填充创建" —— 参数全变 0, 听感上就是混响直接消失(湿量 0), 得重新调一遍。

机制:

环节	做什么
面板改参数	POST /api/eq /api/volume /api/wet → common.save_params() 落盘(值没变不写)
DSP 启动	common.open_store() 判断文件是新建的 → restore_params() 从落盘恢复(带上下限夹取)
落盘缺失/损坏	退回 defaults()(全平直 / 0 dB / 0.3)

落盘在 ~/.local/state/cinema-spatial/params.json(与响度归一化的 loudness.json 同目录):

{"eq": [2.5, 2.5, "... 32 段 ..."], "volume_db": 2.0, "wet": 0.6}

实测(rm /dev/shm/collaplex-eq* 后重启 pipewire): 参数自动恢复, 与落盘逐值一致 —— 总音量 +2.0 / 湿量 0.600 / EQ 非零 30 段 ✓

注意: 落盘是"最后一次改动的快照", 不是"出厂默认"。要回到出厂默认就删掉 params.json 并清掉共享内存(rm /dev/shm/collaplex-eq*), 再重启链路。

实测(2026-09-19)

指标	数据
响度归一化	输入差 20.00 dB → 输出端差 0.00 dB
HRTF 双耳化	出口左右相关系数 0.679(直通 = 1.000)
混响	湿量 0 → 无尾巴; 湿量 1 → 3 秒平滑衰减尾巴(−11 → −129 dBFS 实测序列)
总音量线性	+0/+6/+12 dB → RMS 提升 +0.00 / +5.99 / +11.20 dB
软限幅	+12 dB 输出峰值 −1.11 dBFS, 贴顶样本 0%
面板刷新	62 Hz(SSE 推送, 2 秒实测 124 帧)
失真	纯音谐波(相对基频) +0/+6 dB: −91.1 / −91.1 dB
混响回声	修前: 脉冲后 120 ms 有 −26 dBFS 孤立峰(比周围高 12 dB); 修后: 包络单调衰减 −14 −21 −28 −33 −31 −32 −35 −36, 无孤立峰
白噪底噪	旁路整条链 vs 经链路: 均为 −240 dBFS(链路不自造噪声)

实测(2026-09-20) —— 低频脏 / 沙沙诊断

结论: 链路的线性部分干净(无驻波、失真 −116 dB); 脏与沙沙都来自 电平被顶穿之后软限幅常年介入 —— 宽频内容一削, 互调产物堆在低频(= 脏), 高频碎屑(= 沙沙)。

条件(同一粉噪素材, 只改电平)	峰值	RMS	峰值因子	超软限幅阈值样本
直通(不过链, 参考)	−17.3	−31.4	14.1 dB	0%
绕归一化 湿 0	−14.8	−28.3	13.5 dB	0%
绕归一化 湿 0.3	−0.1	−9.4	9.3 dB	0.05%
经归一化 湿 0.3	−0.1	−2.1	2.0 dB	50.49%

低频量(20~200 Hz 相对 1 kHz, 线性条件)	值
HRTF + EQ(湿 0)	+7.5 dB
再加混响(湿 0.3)	+13.6 dB

• 驻波: 无。对数扫频 + Farina 反卷积(扣掉播放/录音通路)实测 20~330 Hz 峰谷仅 2.1 dB。
• 低频抬升的构成: HRTF 对侧耳 IR 低频比自身 1 kHz 高 +7.7 / +8.3 dB(同侧耳只有 −0.5 / +1.4 dB, 即这套 HRIR 未做漫反射场均衡) + EQ 微笑曲线(20~63 Hz 各 +2.5 dB)
  • 混响湿路(其 IR 低频比中高频高 20~25 dB)。
• 元凶参数: bin/collaplex-loudness-norm 里 LN_MAX_BOOST=20(默认 12), 且归一化在 混响之前, 管不到后面 HRTF/混响再叠的那 ~13 dB。
• ★ 测量方法上的两个坑(都实际踩到并作废了对应数据):
  1. 反卷积后不能加 hanning 窗 —— 它在起点为 0, 而 IR 的直达峰正好在起点, 主峰被抹掉 后算出来的是窗函数的谱(表现为一条 +130 dB 的假斜线)。用矩形窗 + 尾部线性渐出。
  2. 别用粉噪做比值谱求传递函数 —— 随机信号 + 链路延迟 = 相位抵消, 会得到 −179 dB 的 假深谷、以及一堆假的"窄峰"。确定性信号(扫频)才能拿真频响。
• 取证脚本: 测试/扫频测频响.py(扫频 + Farina 反卷积)、测试/电平与失真诊断.py (只改电平的对照实验)、测试/验证混响声道.py(混响声道配置检查)、 测试/诊断低频沙沙.py(逐级旁路, 注: 其频响口径受电平影响, 已由前两个脚本取代)。

修复后复测(同素材同脚本)

指标	修复前	修复后
HRTF + EQ 的低频(20~200 Hz 相对 1 kHz)	+7.5 dB	−0.1 dB
再加混响	+13.6 dB	+0.2 dB
整链(经归一化)低频	+12.7 dB	+0.1 dB
整链峰值因子	2.0 dB	12.2 dB
超软限幅阈值样本	50.49%	0.00%
整链峰值 / RMS	−0.1 / −2.1 dBFS	−6.2 / −18.4 dBFS

做完的四件事(全部落地): ① LN_MAX_BOOST 20 → 12; ② HRIR 同相合并响应均衡 −7.2 dB; ③ 房间 IR 低频校平 −21 dB + 湿路 gain 0.4 → 0.61 补偿; ④ EQ 微笑曲线(20~63 Hz +2.5 dB、 高频 +3 dB)改回平直。低频过量收回 ~13 dB 之后, 响度目标回到 −14 dB 也不会再顶穿。

试听

pw-play --target collaplex_hrtf_in 某个.wav    # 只走 HRTF 核心
pw-play --target collaplex_vsink   某个.wav    # 走整条链

全系统: 默认输出就是 collaplex_vsink, Chrome / 播放器 / 游戏直接出声即走整条链。

开发

uvx pyright --project pyrightconfig.json         # 类型检查(要求 0 errors)
bash 打包deb.sh                                   # 出 deb 到 发布/
uv run --with websocket-client python 测试/cdp_拖动验证.py    # CDP 真鼠标验证

测试/ 里是取证脚本(逐级频谱、谐波、削波、湿度尾巴、预设、拖动), 都用真实数据说话:

脚本	验什么
test_eq.py / test_e2e_eq.py	EQ 端到端(1 kHz +12 dB、总音量 +6 dB)
test_limit.py	软限幅(高峰值因子素材, 常规段增益应精确)
test_thd.py	谐波失真随总音量变化
test_stage_spec.py	逐级旁路频谱(定位是哪一级脏)
test_wet.py	湿度 → 混响尾巴能量
test_echo.py	脉冲测回声(主峰后包络: 有没有孤立峰)
cdp_拖动验证.py / cdp_预设验证.py	前端真点击/真拖动(不看 DOM, 看实际写入)

文件

路径	作用
dsp/common.py	前端 ↔ DSP 共享内存协议(参数区 + 版本号 + 双声道状态区)
dsp/loudness_norm.py	响度归一化 DSP
dsp/eq.py	32 段 EQ + 总音量 + 软限幅 DSP
dsp/wet_gain.py	混响湿量增益级
dsp/初始化.py	写共享内存默认值(安装脚本调用)
dsp/状态.py	命令行看归一化的实时推子/电平
bin/collaplex-audio	主命令(start / stop / web)
bin/*	pipe 插件入口模板(ASCII 路径, 安装时渲染)
pipewire/10,20,30-*.conf	虚拟声卡+归一化 / HRTF+混响+湿量级 / EQ
pipewire/91-collaplex-clock.conf	强制 96 kHz(不然 IR 会被按 48k 降采样)
web/server.py web/index.html	控制面板(纯标准库 + 单页, SSE 推送)
hrir/ reverb/	HRIR(12 条)与房间 IR
脚本/安装.sh 脚本/面板.sh	部署 / 起面板
打包deb.sh	打 deb 到 发布/
systemd/collaplex-audio-panel.service	面板自启模板(start 时装到 ~/.config/systemd/user/)
工具/重做混响IR.py	剪掉房间 IR 的直达声(裁静音 + 渐入), 原文件备份 .orig.wav