The JOC bitstream reports a per-frame parse status instead of treating every anomaly as an exception: an unsupported downmix configuration, a clamped object count, an unknown parameter-band count, bad offset_ts values and trailing bytes each get their own status. The raw 5-bit offset_ts values are kept as coded and validated to be strictly increasing per object, and the clipgain uses 2^(x-4) * (1 + y/32). The JOC core gains a frame-level state machine. It keeps the per-object previous matrix and its presence marker, the seq counter, the 8-plane passthrough history, the LFE clipgain ramp start and the previous actual core-channel count. Normal, hold, hard-cut and passthrough frames are distinguished: a frame without a previous state interpolates per the data-point rules, an object that disappears keeps publishing a zero matrix, a frame without metadata passes the 8 core planes through to slots 0..7 with the 1217-sample delay, and a declared core-channel-count change hard-cuts and clears the LFE ring while the clipgain ramp state is kept. The core LFE applies the full clipgain as a sample-wise ramp before its delay. The OAMD parser exposes the full frame state: every object's state in every position block, the programme assignment and the trim element, with multiple blocks and up to 30 declared objects accepted. The speaker renderer applies this state: per-block gain/inactive, zone/elevation, the size kernel, snap, divergence, element 5 refinement, the priority size budget, ISF basis matrices and bed channel distribution, scheduled on the 32-sample metadata grid with block alignment and gain ramps. The size kernel, ISF basis assembly, bed routing and compensation are computed in oamd_math from the speaker layout geometry; bed labels and reference positions derive from the layout tables. The six ISF configurations and twelve layout descriptors are compiled in as static tables (oamd/isf_tables.h); the JSON loader and the configure-time embedding are gone. The layout tables gain 6.0, and the layout lookup, bed map and trim probe follow. The binaural position timeline consumes the full frame state as well: every position block is scheduled at its own offset and ramp, and its track list grows with the declared object count, so multi-block and over-16-object programmes are rendered instead of rejected. The JOC binaural input stays one LFE plus fifteen object sources; the extra tracks are followed but not panned. The file task and the stream parse the full state for speaker and binaural, while the ADM export keeps the 15-track single-block view. The public headers carry the new status values, the frame-level entry point and the raw offset_ts description; the internal ABI versions go to 6 (joc_core), 2 (frame params and EMDF info) and 4 (eac3joc). ctest covers the frame-level core (clipgain formula and LFE ramp, offset_ts validation, frame statuses, the 8-plane passthrough, the seq state machine and the no-previous-state interpolation), the OAMD parser state, the compiled-in ISF tables and the binaural timeline. The READMEs and the mathematical notes describe the 6.0 layout, the frame state machine, the metadata application and the ISF lookup tables.
9.6 KiB
双耳渲染
JustOneCacophony 的双耳后端支持两种 HRTF 来源:杜比官方软件个性化扫描导出的
Rosella .personalized_headphone(JSON 解析由本项目自行实现,不调用杜比软件),以及
离线编译好的 .jochrtf 方向场缓存。.jochrtf 是可删除、可重建的 JOC compiled HRTF
cache,不是交换格式。
.jochrtf
-> 77 带方向场 + 延迟模型
-> 64-QMF / 77-hybrid analysis
-> 逐对象 direct + 可选 early reflections
-> 可选 shared unitary-FDN late room
-> stereo float64
输入接口
双耳后端消费两种输入:已编译的方向场(JOC compiled HRTF cache,.jochrtf)配共享滤波器组表,
或者是 Rosella .personalized_headphone 模型。两者都是只读输入,本库不做测量数据格式的解析:
joc_cli input.m4a --binaural `
--compiled-hrtf-cache path\to\subject.jochrtf `
--kernels path\to\rosella_kernels.npz `
--jochrtf-room on `
--binaural-mode mid --binaural-tail-seconds 5.0
joc_cli input.m4a --binaural --personalized-headphone HRTF\binaural.personalized_headphone
库接口使用同一组字段:文件任务用 joc_task_config,流式用 joc_stream_config,
其中 hrtf_path、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用于显式 关闭双耳元数据提示。
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。
公开 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。
固定表按公开标准化的滤波器组实现并编译进源码,各表可由如下 公式计算。
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\}
固定表在编译期确定,运行时不加载外部 archive,也不参与缓存键。标准可公开
获取不等于获准实施相关专利;来源与权利边界见
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 不会命中,而是直接报错。
删除磁盘 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(与 Rosella 路径共用) |
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_jochrtf_* 内核),对外只消费编译好的方向场与
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。