Files
JustOneCacophony/data/README.md
T
TheM14 3ea285e407 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.
2026-11-01 15:26:08 +08:00

105 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Python 运行时表
[English](README.en.md)
本目录保存 Python 生产路径使用的静态表数据,不保存用户 HRTF。
SOFA与压缩HRTF输入默认仅渲染直达声。可选`--sofa-room`读取下列资产,由原项目`public_room.py`中的同一四路FDN独立生成,不包含HRTF或外部模型系数。早反射按资产记录的几何使用同一六面镜像算法计算,随后使用所选完整HRIR或压缩方向场。个性化路线继续读取其模型自身的房间参数。
格式均为`sofa-project-room-v1`,采样率48 kHz。JSON记录FDN及几何参数、系数SHA-256和截断尾能量。
| 文件 | 预设 | `late_fir` |
|---|---|---|
| `sofa-room-compact.npz` | Near/Mid默认紧凑房间 | `float64[2,37383]` |
| `sofa-room.npz` | Far默认/可显式选择的原大房间 | `float64[2,81600]` |
紧凑预设的尺寸取自[Zahorik 2009表1的模型9](https://pmc.ncbi.nlm.nih.gov/articles/PMC2730711/),晚期时间尺度按本项目原预设的`V/S`比例缩放;它不是对论文BRIR的完整复现。可重生成两套资产:
```powershell
python src\generate_sofa_room.py
python src\generate_sofa_room.py --preset compact
```
`tables.npz` 保存 JOC 核心解码表:
```text
analysis_window float64[10,64]
qmf5_window float64[640]
joc_huff_code_coarse_generic int64[95,2]
joc_huff_code_fine_generic int64[191,2]
joc_huff_code_coarse_coeff_sparse int64[95,2]
joc_huff_code_fine_coeff_sparse int64[191,2]
joc_huff_code_5ch_pos_index_sparse int64[4,2]
joc_huff_code_7ch_pos_index_sparse int64[6,2]
```
`src/joc_qmf.py` 读取 QMF 表,`src/joc_decode.py` 读取 JOC Huffman 树。
## 双耳渲染表
`rosella_kernels.npz` 保存`.jochrtf`压缩渲染和个性化bank 1使用的64-QMF/77-hybrid固定表;完整SOFA路线直接在PCM域卷积:
```text
format_version little-endian int32[1]
qmf_analysis_coefficients float32[64,10]
hybrid_analysis_low_kernel float32[3,2,13,16,2]
hybrid_synthesis_indices int16[154,4]
hybrid_synthesis_values float32[154]
qmf_synthesis_basis float64[64,4,128]
qmf_synthesis_taps float64[64,10,4]
```
float32 表值载入后提升为 float64。`src/public_filterbank.py` 在读取时校验 archive
及每个数组的 SHA-256;这些 hash、table version 和 77 个 band-center 参考值共同进入
`.jochrtf` cache key。analysis/synthesis 全链 latency 为 961 samples。
打包表实现的是公开标准化的滤波器组,各表可由如下公式计算。
64-QMF → 77-hybrid 结构、13-tap 低带 prototype 与半 bin 复调制定义于
[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$$
64-band QMF analysis 即 ISO/IEC 14496-3/AMD1:2003 第 4.B.18.2 节的 MPEG-4
AAC/SBR 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(\operatorname{Re}X_q + j\,s_q\,\operatorname{Im}X_q\Bigr),\qquad s_q\in\{\pm1\}$$
相同数值可在 FFmpeg(`aacps_tablegen.h`、`aacsbrdata.h`)等公开实现中查到。
### Rosella 捕获版滤波器组
`rosella_captured_kernels.npz` 保存参考头戴渲染器实际运行的那套滤波器组
(`--rosella-filterbank 2`):
```text
format_version little-endian int32[1]
qmf_prototype float32[64,10]
rotation complex64[64]
hybrid complex64[22]
```
表值载入后提升为 float64/complex128;全链 latency 为 448 samples(公开版为 961)。
这些数值来自参考渲染器的运行时缓冲捕获,不是上述公开标准的推导值;C++ 内核以
`src/hrtf/rosella_filterbank_tables.h` 的形式内置同一组数据。文件同样不含个性化
HRTF 或 room 调参。
标准可公开获取不等于获准实施相关专利。
`.sofa` 是用户可见的 source of truth;`.jochrtf` 是可删除、可从 SOFA 重建的
JOC compiled HRTF cache。cache 含有源 HRTF 的变换数据,仍受源 SOFA/HRTF
数据集的许可与再分发限制约束。