Make SOFA room processing optional and self-contained
SOFA and explicit .jochrtf inputs now render direct sound by default. --sofa-room enables the project image-source/FDN room, with the compact preset for Near/Mid and the original large room for Far. - preserve native HRIR timing and apply Data.Delay once - remove external reference configuration, radial head synthesis and the artificial centre response - ship both generated float64 room assets and their generator - retain .jochrtf as an explicit lightweight input and offline export - keep personalized headphone processing unchanged and update bilingual documentation Checked: independent direct/reflection convolution, FDN FIR/recursive agreement, fractional delay and metadata timing, chunk invariance, 8 bit-exact personalized regressions, CLI smoke tests, and full-song D1/D2 renders of two tracks.
This commit is contained in:
1 parent
26e84569c2
commit
3ea285e407
19 files changed
+861
-1134
No files matched your search
+46
-38
@@ -4,74 +4,82 @@
|
||||
|
||||
## 三条独立路线
|
||||
|
||||
| 输入 | 直接声 | 距离与环境 |
|
||||
| 输入 | 渲染 | 距离与环境 |
|
||||
|---|---|---|
|
||||
| SOFA | 完整复数HRIR局部插值、自适应长度FIR、128样本分区卷积 | 外部参考配置的Near/Mid/Far |
|
||||
| `.jochrtf` | 保留原77带/五阶方向场及延迟表示 | 与SOFA相同的三档参考合同 |
|
||||
| `.personalized_headphone` | 原DSP及滤波器组 | 原Near/Mid/Far及环境处理 |
|
||||
| SOFA | 完整复数HRIR方向插值、自适应长度FIR、128样本分区卷积 | 默认纯直达声;`--sofa-room`可选项目房间;不做径向人头合成 |
|
||||
| `.jochrtf` | 原77带/五阶方向场及延迟表示 | 同样默认纯直达声,可选相同房间 |
|
||||
| `.personalized_headphone` | 原DSP、滤波器组及模型参数 | 原Near/Mid/Far及房间处理保持不变 |
|
||||
|
||||
SOFA不会调用编译器、生成压缩缓存或自动回退。原压缩格式、校验器和离线编译能力保留。旧 `sofa_binaural_backend.py` 作为已有底层实现仍在,CLI工厂使用新的 `ReferenceSofaBackend`。
|
||||
SOFA不会调用编译器、生成压缩缓存或自动回退。`.jochrtf`格式、校验器和离线编译能力保留。SOFA与压缩输入通过`DirectSofaBackend`接入对象时间线。
|
||||
|
||||
```powershell
|
||||
python main.py input.m4a --binaural
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --reference-config C:\config\reference.json
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --sofa-interpolation lf_mca_zero
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --binaural-mode near
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --binaural-mode far
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --source-reference-distance-m 2.193
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --sofa-room
|
||||
python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa --sofa-room --sofa-room-preset legacy
|
||||
python src\compile_hrtf.py C:\HRTF\subject.sofa C:\HRTF\subject.jochrtf
|
||||
python main.py input.m4a --binaural --compiled-hrtf-cache C:\HRTF\subject.jochrtf
|
||||
python main.py input.m4a --binaural --personalized-headphone --binaural-mode far --rosella-filterbank 2
|
||||
```
|
||||
|
||||
默认SOFA为项目目录下的 `HRTF/binaural.sofa`,路径不依赖当前工作目录;其他位置用 `--sofa-hrtf PATH` 显式指定。单球壳自动选择,多球壳须用 `--hrtf-radius-m` 指定最近的测量球壳。个性化默认路径不变。三条双耳路线都支持 `--binaural-mode near|mid|far`,CLI默认mid;off仅适用于ADM DBMD提示。
|
||||
默认SOFA为项目目录下的`HRTF/binaural.sofa`,不依赖当前工作目录;其他位置用`--sofa-hrtf PATH`指定。单球壳自动选择,多球壳须用`--hrtf-radius-m`选择一个测量球壳,当前不做径向插值。默认个性化路径仍为`HRTF/binaural.personalized_headphone`。
|
||||
|
||||
## 外部参考配置
|
||||
SOFA与压缩输入沿用Near/Mid/Far的点声源参考尺度,默认Mid。个性化的Near/Mid/Far和ADM输出的DBMD提示保持原行为。
|
||||
|
||||
`--reference-config` > `BINAURAL_REFERENCE_CONFIG` > 本地 `local/binaural_reference.json`。缺失、SHA-256不符或不支持的映射明确报错。环境数据与具体身份说明不随源码提供。配置示例:
|
||||
## 点声源参考尺度
|
||||
|
||||
```json
|
||||
{"schema":"binaural-reference-v1","profile_id":"reference-v1",
|
||||
"model_path":"C:/path/to/reference-data.json","model_sha256":"<64 hex digits>",
|
||||
"profile_index":3,"room_impulse_slots":4096,"level_calibration_directions":128,
|
||||
"compiled_receiver_positions_m":[[0,0.09,0],[0,-0.09,0]]}
|
||||
```
|
||||
|
||||
`model_path` 指向受现有参数加载器支持的外部数据,支持相对配置文件的路径;`profile_index` 固定公共电平校准锚点,选择渲染档位使用 `--binaural-mode`,不改校准锚点。压缩格式没有耳位字段,因此压缩输入必须显式配置耳位,且报告其来源。完整SOFA使用文件自身耳位。不同SOFA共用环境尺度,测量半径不定义场景距离或房间大小。
|
||||
|
||||
参考映射执行所选档位的量化、轴缩放、边界与近中心正则规则。有限盒外位置沿边界射线延伸,保留ETSI距离因子,不能再次裁回坐标盒。Near共同直接声系数为1、房间发送为0;Mid/Far为:
|
||||
Near/Mid/Far的参考距离分别为1.00000465/2.19327927/6.40177584 m,可用`--source-reference-distance-m`覆盖所选档位。对于ADM右/前/上坐标`p=(x,y,z)`:
|
||||
|
||||
```text
|
||||
r_eff = h0 * reference_distance_m
|
||||
a = 1 / sqrt(1 + c * r_eff^2)
|
||||
b = r_eff * a
|
||||
q_SOFA = (y, -x, z) / ||p||
|
||||
d_nominal = reference_distance_m * ||p||
|
||||
H_render(ear, f) = H_selected_shell(ear, f, q_SOFA)
|
||||
```
|
||||
|
||||
房间发送乘对象信号后进入独立环境状态。完整SOFA直接声与环境分支分别处理,再对齐实现延迟并求和;没有额外的1/r或绝对飞行时间。输出增益只应用一次,不隐式限幅。
|
||||
参考距离给对象坐标规定标称米制尺度,不会把测量半径为1.2 m的HRIR合成为2.193 m真值,也不会更改SOFA测量元数据。默认直达声模式不额外应用1/r衰减、球头距离比值、人工中心响应、房间发送、direct/room能量耦合或目标距离传播延迟;节目增益和SOFA响应刻度保持不变。开启房间后采用原项目距离耦合,用户指定输出增益仍只应用一次。
|
||||
|
||||
声源与听者重合时方向没有定义,沿用该对象最后一个有效方向;没有历史时取正前方。该规则不合成零ITD响应。有限盒外坐标保留元数据距离因子,不裁回单位盒。
|
||||
|
||||
SOFA输入不需要个性化模型或本机配置;关闭房间时也不读取房间资产。报告记录输入路径、SHA-256、测量半径、插值方法与房间开关。
|
||||
|
||||
## 可选项目房间
|
||||
|
||||
`--sofa-room`默认关闭,复用原`.jochrtf`路线的`public_room.py`和`reference_distance.py`算法,提供原始与紧凑两套参数:六个一阶镜像反射,以及四路正交Hadamard反馈、两级全通扩散、低通阻尼的共享FDN。它是项目自有听感预设,目标是提供接近理想听音环境、以直达声为主的房间感,不是测量BRIR或强制标准房间。它不依赖Rosella房间表。
|
||||
|
||||
启用后Near/Mid默认使用`compact`紧凑房间,Far默认使用`legacy`原大房间,以保留Far单位坐标盒的空间范围。`--sofa-room-preset compact|legacy`可显式选择;`legacy`指原项目大房间。紧凑房间尺寸引用[Zahorik 2009表1模型9](https://pmc.ncbi.nlm.nih.gov/articles/PMC2730711/),保留原镜像/FDN算法,将晚期延迟、扩散时间与RT60参数按`V/S`比例缩短。参数及来源记录在资产元数据中。这仅借用文献几何,不是该论文BRIR算法的复现。
|
||||
|
||||
完整HRIR路线对六个到达方向分别查询HRIR,以完整频率网格上的相位斜坡实现分数采样延迟。反射路径相对直达路径的额外时间为`(L_path-L_direct)/c`,保留原HRIR的`Data.Delay`,不再量化到77带。直接声、反射与晚期发送采用原项目的增益公式。房间几何只覆盖其内部声源;开启房间时不静默裁剪盒外位置。
|
||||
|
||||
晚期FDN在48 kHz下用单位脉冲生成双声道float64 FIR:紧凑版为`data/sofa-room-compact.npz`,37,383点、RT60参数约0.3894秒;原版为`data/sofa-room.npz`,81,600点、RT60参数0.85秒。两者截断后的探测尾能量比均约`2.2e-13`。运行时通过PCM域FFT卷积实现各自同一线性时不变系统。早反射继续使用所选SOFA;晚期输出保持原项目的双声道FDN定义。
|
||||
|
||||
晚期分支补齐卷积实现移位和所选SOFA的共同录音延迟估计后,与直接声及早反射相加。房间关闭时不创建这些状态;开启时按1536样本计算批次处理,参数仍每128样本更新,排空时裁去额外批处理填充。`.jochrtf`的早反射保持其77带表示误差。
|
||||
|
||||
可用`python src\generate_sofa_room.py`重生成两套资产,或以`--preset compact|legacy`只生成一套。原算法来源、参数、系数哈希及尾部精度预算写入NPZ元数据。
|
||||
|
||||
## 完整HRIR数学与时间基准
|
||||
|
||||
严格导入器继续校验 `SimpleFreeFieldHRIR` 0.4/1.0/1.1、FIR、两个可由位置识别左右的耳、零Emitter偏移、自由场、单位和有限数值。重采样时Data.Delay的采样点数同比例变化。当前距离模型要求固定、对称并以听者中心为原点的耳位;不支持的几何明确拒绝。
|
||||
导入器校验`SimpleFreeFieldHRIR` 0.4/1.0/1.1、FIR、两个可由位置识别左右的耳、零Emitter偏移、自由场、单位和有限数值。采样率统一为48 kHz;重采样时`Data.Delay`的采样点数同比例变化。耳位须在测量之间固定;方向插值不再要求用对称耳位拟合球头。
|
||||
|
||||
SOFA为前/左/上,ADM为右/前/上,变换为 `(y,-x,z)`。单位方向三维凸包构建局部三角网格,查询使用射线与平面三角形的非负、和为1的重心权重;不做经纬平面插值或外推。精确节点返回完整复数响应。跨越大测量缺口的面仍是低支持区域,网格包围原点不能证明覆盖精度。
|
||||
当前没有实现`SimpleFreeFieldHRIR`以外的BRIR或其他SOFA Convention。不支持的文件明确拒绝。后端已按响应类型预留BRIR提示及忽略`--sofa-room`的规则;当前验证的是该策略接口,不代表已实现BRIR读取。
|
||||
|
||||
FFT最少2048点,按完整HRIR与Data.Delay自动扩展为满足时间预算的2次幂,自动长度上限16384点;不裁短输入。每耳在200–1500 Hz作线性相位回归,对齐后插值完整剩余复数响应,再恢复加权延迟。Data.Delay恰好施加一次,不能从耳位再加一次ITD。默认 `lf_logmag_phase` 对数幅度与对齐复数插值相位结合;可选 `lf_mca_zero` 使用41个连续Gammatone功率近似带、PCHIP和±12 dB修正限幅。这是独立MCA近似,并非第三方项目逐位复现。
|
||||
测量单位方向的三维凸包构成局部三角网格,查询使用射线与面三角形的非负、和为1的重心权重。不使用经纬平面插值,不外推未覆盖半球。精确节点返回测量复数响应。
|
||||
|
||||
距离补充采用归一化刚性球传递函数 `H_sphere(r)/H_sphere(r_measurement)` 的复数比值。测量半径处严格为1;不叠加第二套耳间延迟。球半径由对称耳位推导。中心使用参考正则半径与零ITD的球面面积加权能量平均响应平滑混合。该模型是人头径向变化的近似,不能把角度插值实验当作任意距离准确性证明。
|
||||
低频对齐延迟在200–1500 Hz拟合。默认`lf_logmag_phase`对对数幅度插值,原相位通过时间对齐的复数残差及插值延迟恢复;备选`lf_mca_zero`使用听觉带幅度校正。两种方法都保留所选FFT长度的完整FIR,不替换为最小相位。
|
||||
|
||||
直接声电平按固定等面积方向及100–16000 Hz对数频率权重,与校准锚点的参考直接声匹配总双耳能量;每份SOFA只得到一个全局系数,三档共用该系数,不逐档、逐方向、逐耳或逐频率归一化。三档共用相同的HRIR插值、距离补充、卷积和时间补偿流程,只切换参考参数与其直接声/发送规则。
|
||||
`Data.Delay`在频域只叠加一次。公共移位为FFT长度的一半,用于保存插值前振铃;输出只补偿卷积/滤波器组的实现延迟。文件提供的共同录音延迟、左右耳相对延迟和频率相关相位关系均保留,不再减去拟合录音原点,也不根据目标距离增加飞行时间。真实序列的DC/Nyquist频点按实数端点处理。
|
||||
|
||||
保留选定FFT长度的全部FIR采样,共同移位FFT长度的一半以存储前振铃。渲染时使用全方向双耳低频延迟平均值的中位数、取整为单一录音时间原点,给环境分支补齐该原点与实现延迟后统一补偿;报告此偏移。查询得到的原始复数HRIR不改时间基准。这个全局时间参考变换不根据目标距离增加传播时间。
|
||||
每对象拥有独立卷积历史。更新时旧/新输出在128样本内线性交叉淡化,两个滤波器均使用完整输入历史。滤波器更新同样延后公共FIR实现移位,避免移除实现延迟后将元数据更新提前。完整HRIR路线直接在PCM域卷积;QMF/hybrid仅用于显式压缩输入。内部精度为float64/complex128,不做隐式限幅。
|
||||
|
||||
每对象独立卷积历史,更新时旧/新输出线性交叉淡化128样本,保持输入历史及独立overlap;环境发送平滑更新。环境计算按1536样本批处理,不改变128样本参数时间线,排空时裁掉额外计算填充。采样率固定48 kHz,内部float64/complex128。
|
||||
## 对象接入
|
||||
|
||||
## 对象接入与支持范围
|
||||
输入为每帧`[1536,16]` PCM:0是LFE,1–15是已经重建的对象/bed槽。直接使用ID11时间线,不重新解码,也不先渲染到扬声器布局。保留1473样本对象时间补偿和32样本元数据对齐,参数每128样本更新。
|
||||
|
||||
输入为每帧 `[1536,16]` PCM:0是LFE,1–15是已经重建的对象/bed槽。直接使用ID11时间线,不重新解码,不先转扬声器布局。保留1473样本内容时间补偿和32样本元数据对齐;新后端每128样本更新参数。
|
||||
|
||||
SOFA专用解析开关保留负高度、边界外因子及锚定字段;旧解析器默认行为与个性化时间线不变。有限盒外更新进入时间插值;当前多位置块、ISF、显式无穷远和需要屏幕校准的锚定明确返回结构化不支持错误。`finish()`只排空一次,并保留配置的尾声预算。
|
||||
LFE继续使用独立低通处理,不发送至可选房间。SOFA专用解析保留负高度、边界外因子及锚定字段;个性化解析与时间线不变。当前多位置块、ISF、显式无穷远以及需要屏幕校准的锚定明确报错。`finish()`仅排空一次,`--binaural-tail-seconds`规定FIR/滤波器组及可选房间尾声的排空预算。
|
||||
|
||||
## 轻量格式
|
||||
|
||||
`.jochrtf` v1仍为无pickle的NumPy ZIP,保存JSON元数据、77个频带中心、`complex128[36,2,77]`方向系数、`float64[36,2]`延迟系数和`float64[2,2]`边界。原格式、cache key、哈希校验、原子写入及源数据许可关系不变。它保留方向压缩的固有误差;与完整SOFA的距离语义一致不代表频响精度相同。滤波器组公开来源见 [data说明](../data/README.md)。
|
||||
`.jochrtf` v1仍为无pickle的NumPy ZIP,保存JSON元数据、77个频带中心、`complex128[36,2,77]`方向系数、`float64[36,2]`延迟系数及`float64[2,2]`边界。原格式、cache key、哈希校验、原子写入及源数据许可关系不变。压缩输入保留自身的方向与频率表示误差,不等同于完整HRIR精度。
|
||||
|
||||
数学依据:[Duda与Martens 1998](https://www.ece.ucdavis.edu/cipic/wp-content/uploads/sites/12/2015/04/cipic_JASA_Nov_1998.pdf),[MCA原论文](https://doi.org/10.1109/TASLP.2023.3313908),[ETSI TS 103 420](https://www.etsi.org/deliver/etsi_ts/103400_103499/103420/01.02.01_60/ts_103420v010201p.pdf)。算法独立实现,不复制第三方HRTF源码;数据许可仍随外部数据适用。
|
||||
滤波器组来源见[data说明](../data/README.md)。方向插值和MCA的参考文献见[研究实现依据](https://doi.org/10.1109/TASLP.2023.3313908);算法独立实现,外部测量数据仍适用其自身许可。
|
||||
Reference in new issue
Block a user