Replace the Rosella table-A reference environment with a point-source reference: the ADM position now selects a listener-frame direction and a distance scaled by the mode's reference distance (near/mid/far 1.00000465/2.19327927/6.40177584 m, overridable with --source-reference-distance-m). The direct level is an equal-power coefficient rather than a 1/r attenuation, and the measured SOFA response stays as measured: no rigid-sphere radial correction and no Voronoi centre spectrum any more. --sofa-room couples the direct path to this project's own room. It is generated in code, not loaded from an asset: room_tables.cpp runs the four-line Hadamard FDN with two all-pass diffusers and low-pass damping into a float64 FIR, and shoebox_room.cpp computes the six first-order image sources, which are rendered through the same HRIR field with fractional delays. The late tail is convolved in 1536-sample batches. Near/Mid default to the compact room and Far to the legacy one; --sofa-room-preset selects explicitly, and the room is off by default. Filter changes are scheduled at the parameter alignment delay instead of being applied on the spot, and the LFE band starts at latency + recording origin - 64, both matching the reference implementation. joc_task_config goes to version 5 and joc_stream_config gains the same fields; the stream API renders a SOFA directly instead of compiling it.
15 KiB
双耳渲染
JustOneCacophony 的双耳后端支持三种 HRTF 来源:SimpleFreeFieldHRIR SOFA、
杜比官方软件个性化扫描导出的 Rosella .personalized_headphone(JSON 解析由本项目
自行实现,不调用杜比软件),以及 .jochrtf(JOC compiled HRTF cache)。
SOFA 默认保留完整 HRIR,按点声源参考直连渲染,不编译成方向场:
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):
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,
保留原镜像/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 本身:
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)需要共享滤波器组表,两者都是只读输入:
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,version0.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
编译器只允许三种互斥语义:
- 非零
Data.Delay是Data.IR外部 delay;FIR 不去旋,运行时应用一次。 Data.Delay=0且 HRIR 有普通正 onset:以每耳 main peak 分离 arrival,拟合后 在运行时恢复一次;当前阈值为 peak index 大于 2 samples。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
第 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 与
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。
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
- 3GPP TS 26.405 / ETSI TS 126 405(64-QMF/77-hybrid 定义)
- Dolby binaural render mode workflow
- EP3090576A1,仅作 direct/early/late、 subband 与 FDN 架构背景,不证明某个产品使用特定实施例。
规范、源码或专利文献可公开获取,不等于获准复制其内容、再分发派生产物或实施其中的
专利权利要求。本项目的技术引用本身不授予专利许可,也不作不侵权保证;准备发布或集成
到产品的一方应自行审查适用的数据许可、软件许可、专利许可及 freedom-to-operate。
公开标准来源与权利边界见
THIRD_PARTY_NOTICES.md。