# 双耳渲染 [English](binaural.en.md) · [返回 README](../README.md) JustOneCacophony 的双耳后端支持三种 HRTF 来源:`SimpleFreeFieldHRIR` SOFA、 杜比官方软件个性化扫描导出的 Rosella `.personalized_headphone`(JSON 解析由本项目 自行实现,不调用杜比软件),以及 `.jochrtf`(JOC compiled HRTF cache)。 SOFA 默认保留完整 HRIR,按点声源参考直连渲染,不编译成方向场: ```text SOFA 完整 HRIR [M,2,N] -> CanonicalHrtf(48 kHz / 单 radius shell) -> 延迟对齐的复数频谱(200-1500 Hz 相位拟合,含 Data.Delay) -> 球面三角形重心插值(lf_logmag_phase 或 lf_mca_zero) -> 点声源参考尺度(方向 + 档位参考距离,无径向修正) -> 逐对象 partitioned convolution(block 128,FFT = max(2048, ≥2×support)) -> 可选项目房间(六路一阶镜像 + 共享 FDN 晚期 FIR) -> stereo float64(统一扣除 latency) ``` `.jochrtf` 仍是显式输入(`--compiled-hrtf-cache`),走球谐方向场渲染;显式给出 `--hrtf-cache-policy` / `--hrtf-cache-dir` 会回到旧的“SOFA → `.jochrtf`”编译路径。 ## 点声源参考尺度 Near/Mid/Far 的参考距离分别为 1.00000465 / 2.19327927 / 6.40177584 m,可用 `--source-reference-distance-m` 覆盖所选档位。对于 ADM 右/前/上坐标 `p=(x,y,z)`: ```text q_SOFA = (y, -x, z) / ||p|| d_nominal = reference_distance_m * ||p|| H_render = H_selected_shell(q_SOFA) ``` 参考距离只给对象坐标规定标称米制尺度,不会把测量半径为 1.2 m 的 HRIR 合成成 2.193 m 的真值,也不改动 SOFA 测量元数据。默认直达声模式不额外应用 1/r 衰减、球头距离比值、 人工中心响应、房间发送或目标距离传播延迟;节目增益与 SOFA 响应刻度保持不变。 声源与听者重合时方向没有定义,沿用该对象最后一个有效方向;没有历史时取正前方。 有限盒外坐标保留元数据距离因子,不裁回单位盒。 ## 可选项目房间 `--sofa-room` 默认关闭,复用项目原有的房间算法:六个一阶镜像反射,以及四路正交 Hadamard 反馈、两级全通扩散、低通阻尼的共享 FDN 晚期。它是项目自有的听感预设, 不是测量 BRIR 或外部标准房间,也不依赖 Rosella 房间表。 启用后 Near/Mid 默认使用 `compact` 紧凑房间,Far 默认使用 `legacy` 原大房间; `--sofa-room-preset compact|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`。直接声、反射与晚期发送使用项目原有的增益公式。 晚期 FDN 在 48 kHz 下用单位脉冲生成双声道 float64 FIR,长度截到 2×RT60:紧凑版 37,383 点、RT60 参数约 0.3894 s,原版 81,600 点、RT60 参数 0.85 s。FIR 由 `src/binaural/room_tables.cpp` 里的四路 Hadamard 反馈、两级全通扩散与低通阻尼在启动时 现场渲染,不读取任何随包发布的音频资产。运行时按 1536 样本批次在 PCM 域做 FFT 卷积, 早期反射仍使用所选 SOFA;LFE 声道不进房间。房间关闭时既不生成也不保留这些状态, 排空时裁去批处理填充。 指向同一声道的直达声是延迟对齐后的完整 HRIR 插值结果;文件任务的 latency 由 field (FFT/2 与 recording origin)决定,输出前统一扣除。 ## 输入接口 SOFA 输入直接按完整 HRIR 渲染,只需要 SOFA 本身: ```powershell joc_cli input.m4a --binaural ` --sofa-hrtf HRTF\subject.sofa ` --binaural-mode mid --sofa-interpolation lf_logmag_phase joc_cli input.m4a --binaural --sofa-hrtf HRTF\subject.sofa --sofa-room joc_cli input.m4a --binaural --sofa-hrtf HRTF\subject.sofa --sofa-room --sofa-room-preset legacy ``` `.jochrtf` 输入(以及 `.personalized_headphone`)需要共享滤波器组表,两者都是只读输入: ```powershell joc_cli input.m4a --binaural ` --compiled-hrtf-cache path\to\subject.jochrtf ` --kernels data\rosella_kernels.npz ` --binaural-mode mid --binaural-tail-seconds 5.0 ``` 多球壳 SOFA 必须用 `--hrtf-radius-m` 指定球壳(单球壳自动选择);`--hrtf-radius-m` 对已编译的 `.jochrtf` 不再生效。`--sofa-interpolation` 选择完整 HRIR 的局部插值: `lf_logmag_phase`(默认,对数幅度 + 相位)或 `lf_mca_zero`(听觉带幅度修正)。 库接口使用同一组字段:文件任务用 `joc_task_config`,流式用 `joc_stream_config`, 其中 `hrtf_sofa_path`(或 `hrtf_path`)、`sofa_interpolation`、`hrtf_radius_m`、 `source_reference_distance_m`、`sofa_room`、`sofa_room_preset`、`sofa_room_asset_dir`、 `hrtf_compile`、`kernels_path`、`binaural_mode`、`binaural_tail_seconds` 决定双耳通路。 `.jochrtf` 是**输入**而不是本库的产物:从 SOFA 或测量数据编译该缓存属于工具链的职责, 与本仓库解耦。缓存加载时会校验成员集合、dtype 与形状、C 连续性、CRC-32 以及按成员重算的 载荷哈希(见下文 `.jochrtf` 一节)。 `binaural_mode` 取 `near`、`mid`、`far`,选择后端的三组预置参数;`binaural_tail_seconds` 决定 flush 时排空的房间尾音长度(默认 5.0 s)。 ## 双耳渲染模式 `--binaural-mode off|near|mid|far`(默认 `mid`)是**人为指定的渲染提示**,不是 从输入 E-AC-3 JOC 码流提取或还原的原始双耳元数据: - 直接双耳渲染(`--binaural`):near/mid/far 生效,默认 `mid`;`off` 报错; - ADM BWF:DBMD segment 10 中后 15 个 JOC 对象的 binaural render mode 写 `off=0/near=1/far=2/mid=3`,前 10 个 bed 保持不变,默认 `mid`;`off` 用于显式 关闭双耳元数据提示。 ## Canonical SOFA 契约 当前 strict importer 接受: - `Conventions=SOFA`; - `SOFAConventions=SimpleFreeFieldHRIR`,version `0.4`、`1.0` 或 `1.1`; - `DataType=FIR`,`Data.IR[M,2,N]`; - 单一正有限 `Data.SamplingRate`,单位为 hertz/Hz; - spherical 或 Cartesian `SourcePosition`; - 单值或 per-measurement 的 `ListenerPosition/View/Up`; - 两个能由 listener-local lateral 坐标唯一识别左右的 receiver; - 单一且零偏移的 emitter; - causal `Data.Delay[I,2]` 或 `[M,2]`; - 明确的 free-field/anechoic `RoomType`。 receiver 左右顺序由几何决定,不能假定 `Data.IR` 的 receiver index。SOFA listener 坐标为 $+X$ front、 $+Y$ left、 $+Z$ up;ADM 坐标为 $+X$ right、 $+Y$ front、 $+Z$ up,转换为: $$\bigl(x_{\mathrm{SOFA}},\ y_{\mathrm{SOFA}},\ z_{\mathrm{SOFA}}\bigr) = \bigl(y_{\mathrm{ADM}},\ -x_{\mathrm{ADM}},\ z_{\mathrm{ADM}}\bigr)$$ `CanonicalHrtf` 将 `Data.IR` 与 `Data.Delay` 分开保存。只有时域 baseline 才调用 `materialized_measurement()` 将 delay 应用一次;运行时 SH 路径不先 materialize。 非 48 kHz HRIR 使用 float64 `scipy.signal.resample_poly` 规范化,delay samples 按 相同比例缩放。 GeneralFIR、BRIR、TF、多 emitter、多义 receiver 或非 free-field 数据需要单独的 convention adapter,不能只通过 reshape 进入核心 importer。 ## Delay/phase:exactly once 编译器只允许三种互斥语义: 1. 非零 `Data.Delay` 是 `Data.IR` 外部 delay;FIR 不去旋,运行时应用一次。 2. `Data.Delay=0` 且 HRIR 有普通正 onset:以每耳 main peak 分离 arrival,拟合后 在运行时恢复一次;当前阈值为 peak index 大于 2 samples。 3. `Data.Delay=0` 且双耳 FIR 共享 sample-0 起点:不发明外部 delay,原 complex phase 直接进入五阶场。 任何路径都不能再叠加第二套 ear delay 或 phase-group delay。 SOFA 直连路径不走这套编译期语义:它保留完整 IR,用 200-1500 Hz 相位拟合估计到达时间, `Data.Delay` 与拟合出的延迟各应用一次(先去掉 `Data.Delay`,再用插值后的延迟复原)。 ## 公开 filterbank 与方向场 运行时固定为: - 48 kHz; - 64-sample QMF hop; - 64-QMF / 77-hybrid; - analysis/synthesis latency 961 samples; - 五阶、36 项、ACN/N3D real spherical harmonics; - PCM、delay、SH、room state 为 float64;频带传递和频域状态为 complex128。 每个 hybrid band 的 real/imaginary 单位增益都通过同一套 analysis/synthesis 链生成 脉冲字典,共 154 个实参数;编译不是直接读取 77 个 FFT bin。默认 projection ridge 为 `1e-3`,SH ridge 为 `1e-5`。同方向 measurement 先合并,再用球面 Voronoi 面积权重做 ridge fit。 固定表位于 `data/rosella_kernels.npz`,实现公开标准化的滤波器组,各表可由如下 公式计算。 hybrid 分析核定义于 [3GPP TS 26.405 / ETSI TS 126 405](https://www.etsi.org/deliver/etsi_ts/126400_126499/126405/06.00.00_60/ts_126405v060000p.pdf) 第 5.2.2 节(Table 1 的 $Q=8$/ $Q=4$ 系数,delay 6): $$G_q^p[n] = g^p[n]\cdot\exp\Bigl(j\,\frac{2\pi}{Q^p}\bigl(q+\tfrac12\bigr)(n-6)\Bigr),\qquad n=0,\dots,12$$ QMF analysis 表即 MPEG-4 AAC/SBR(ISO/IEC 14496-3/AMD1:2003 第 4.B.18.2 节) 的 64 complex QMF bank;打包的 $64\times10$ 表是公开 640-tap prototype $c_0,\dots,c_{639}$ 的多相重排: $$A_{r,t} = \frac{(-1)^t}{128}\,c_{63-r+64t},\qquad r=0,\dots,63,\ t=0,\dots,9$$ QMF synthesis 表为上述 analysis 多相矩阵 $\mathbf{A}$ 的因果左逆,即求解 $\mathbf{A}\,\mathbf{W}=\mathbf{P}$( $\mathbf{P}$ 为 577-sample 延迟置换; 全链 $961 = 577 + 6\times64$),以 rank-4 分解形式存储: $$W_{b,l} = \sum_{r=1}^{4} t_{b,l,r}\,\mathbf{b}_{b,r}^{\top}$$ hybrid synthesis 表为 77→64 重组:高频带恒等 $Y_{3+b}=X_{16+b}$;低频带( $C_p$ 为 $8+4+4$ 子带划分): $$Y_p = \sum_{q\in C_p}\Bigl(\mathrm{Re}X_q + j\,s_q\,\mathrm{Im}X_q\Bigr),\qquad s_q\in\{\pm1\}$$ loader 校验 archive 和每个数组的 SHA-256;table version、所有数组 hash 与 77 个 band-center 参考值都属于 cache key。标准可公开获取不等于获准实施相关 专利;更多来源信息见 [`data/README.md`](../data/README.md) 与 [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md)。 ## `.jochrtf` `.jochrtf` 是无 pickle 的压缩 NumPy archive,固定包含: | key | dtype / shape | |---|---| | `metadata_json` | 含 JSON 文本的 NumPy Unicode scalar(`dtype.kind == "U"`) | | `band_center_frequencies_hz` | little-endian `float64[77]` | | `coefficients` | little-endian `complex128[36,2,77]` | | `delay_coefficients` | little-endian `float64[36,2]` | | `delay_bounds` | little-endian `float64[2,2]` | metadata magic 固定为 `JOC-HRTF-CACHE`,并记录 schema/compiler/phase-policy、 ACN/N3D、filterbank table hashes、SOFA content SHA-256、采样率、radius、order、 两个 ridge、payload hash 和 fit report。cache key 覆盖所有会改变编译结果的字段。 metadata 不保存本机绝对 `source_path`,仅可保存 source display name。 loader 使用 `allow_pickle=False`,并在构造对象前检查 ZIP 成员集、解压大小、shape、 dtype、端序、连续布局、有限值、delay bounds、band centers、payload hash 和 cache key。writer 使用同目录临时文件、`fsync`、进程持有的 OS 文件锁和原子 `os.replace`;对应的隐藏 `.lock` sidecar 可保留,但不代表仍有 writer 持锁。 旧版本、损坏或配置不匹配的 cache 不能命中;从 SOFA 启动时会重建,显式 cache 入口则直接报错。 删除磁盘 cache 后,从同一 SOFA 和同一编译配置得到的场与渲染结果不得改变。 `.jochrtf` 包含由源 HRIR 变换得到的方向场系数与 delay 数据,因此“可以重建”不表示 它不受数据许可约束。生成 cache 不会扩大源 SOFA/HRTF 数据集授予的权利;cache 的 使用、复制和再分发仍须遵守源数据集条款。不能确认条款时,应把 `.jochrtf` 作为本地 私有 cache,不随程序或构建产物发布。`source_sha256` 只用于内容一致性校验,不是许可 或来源证明。 ## Rosella 个性化模型 `.personalized_headphone` 走独立的 Rosella 渲染器,滤波器组可以二选一, 由 `--rosella-filterbank 1|2`(库接口为 `joc_task_config::rosella_filterbank` / `joc_stream_config::rosella_filterbank`,`0` 表示默认)选择: | 取值 | 滤波器组 | 低频 hybrid | 高频 slot delay | 延迟 | | --- | --- | --- | --- | ---: | | `1`(默认) | `PublicFilterbank`(与 SOFA 路径共用) | 13 taps | 6 slots | 961 samples | | `2` | `RosellaFilterbank`(从参考渲染器捕获) | 11 taps | 3 slots | 448 samples | 两套实现通过同一组四个有状态 half-step 调用,因此切换时系数、高频 delay、历史缓冲 布局、起始延迟跳过量和 flush 容量一起改变,分析与合成两级互不共享状态。其它取值直接 报错;非 Rosella 输入给出该选项也报错,不会静默忽略。详见 [Rosella filterbank](rosella_filterbank.en.md)。 ## JOC 对象与房间 生产适配器继续使用现有 JOC 调度: - 每帧输入 `[1536,16]`; - channel 0 是 special LFE,channel 1..15 是 JOC objects; - ID11/OAMD position 使用 sample-timed timeline; - 每 512 samples 更新方向/profile; - 每个对象拥有独立 direct/early history,late FDN 全局共享; - `finish()` 排空 early/late tail;输出增益显式应用,不隐含 limiter 或节目响度归一化。 Near/Mid/Far、equal-power direct level、六面 shoebox 一阶 image source、late send、 unitary FDN、LFE 120–180 Hz cosine-squared 低通及 room calibration 都是 JOC 项目定义行为,不是 SOFA 或 Dolby 公布常数。 双耳渲染在本库内实现:filterbank、SH 方向场求值、逐对象 early/direct 历史与共享 FDN 全部执行于 `joc_core`(`ejoc_sofa_binaural_*` 内核),对外只消费编译好的方向场与 512-sample 粒度的元数据更新。 ## 技术引用与权利边界 - [SOFA SimpleFreeFieldHRIR convention](https://www.sofaconventions.org/mediawiki/index.php/SimpleFreeFieldHRIR) - [3GPP TS 26.405 / ETSI TS 126 405(64-QMF/77-hybrid 定义)](https://www.etsi.org/deliver/etsi_ts/126400_126499/126405/06.00.00_60/ts_126405v060000p.pdf) - [Dolby binaural render mode workflow](https://professionalsupport.dolby.com/s/article/What-is-Binaural-Render-Mode-and-how-do-the-settings-affect-my-mix) - [EP3090576A1](https://patents.google.com/patent/EP3090576A1/en),仅作 direct/early/late、 subband 与 FDN 架构背景,不证明某个产品使用特定实施例。 规范、源码或专利文献可公开获取,不等于获准复制其内容、再分发派生产物或实施其中的 专利权利要求。本项目的技术引用本身不授予专利许可,也不作不侵权保证;准备发布或集成 到产品的一方应自行审查适用的数据许可、软件许可、专利许可及 freedom-to-operate。 公开标准来源与权利边界见 [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md)。