Files
JustOneCacophony/data
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
..

Python runtime tables

中文

This directory contains static production tables. It does not contain user HRTFs.

SOFA and compact HRTF inputs render direct sound by default. Optional --sofa-room loads generated FIR assets from the original four-line FDN in public_room.py. It contains no HRTF or external-model coefficients. Early reflections use the same module's six-wall image model and the selected full HRIRs or compact field. Personalized rendering continues to use its model's room parameters.

Both archives use sofa-project-room-v1, 48 kHz and float64. sofa-room-compact.npz contains [2,37383] taps and is the Near/Mid default; sofa-room.npz contains [2,81600] taps for the Far default and explicit original-room selection. JSON records FDN/geometry parameters, coefficient SHA-256 and omitted tail energy.

Compact dimensions follow model 9 in Zahorik 2009, Table 1. Late time scales follow the V/S ratio of the original project preset; this does not reproduce the paper's BRIR algorithm. Regenerate both assets with:

python src\generate_sofa_room.py
python src\generate_sofa_room.py --preset compact

tables.npz contains the JOC core decoding tables:

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 loads the QMF tables, while src/joc_decode.py loads the JOC Huffman trees.

Binaural rendering tables

rosella_kernels.npz contains the fixed 64-QMF/77-hybrid tables used by .jochrtf rendering and personalized bank 1. Full SOFA rendering uses PCM convolution:

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]

The float32 table values are promoted to float64 when loaded. src/public_filterbank.py verifies the archive and every array by SHA-256. Those hashes, the table version, and the 77 reference band-center values all participate in the .jochrtf cache key. The full analysis/synthesis latency is 961 samples.

The packaged tables implement publicly standardized filter banks, computable from the following formulas.

The 64-QMF → 77-hybrid structure, the 13-tap low-band prototypes, and their half-bin complex modulation are defined in 3GPP TS 26.405 / ETSI TS 126 405, Section 5.2.2 (Table 1 $Q=8$/Q=4 coefficients, 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

The 64-band QMF analysis is the MPEG-4 AAC/SBR 64 complex QMF analysis bank of ISO/IEC 14496-3/AMD1:2003, subclause 4.B.18.2; the packaged 64\times10 table is the polyphase reordering of the public 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

The QMF synthesis table is the causal left inverse of the analysis polyphase matrix \mathbf{A}, i.e. the solution of \mathbf{A}\,\mathbf{W}=\mathbf{P} (\mathbf{P} is the 577-sample delay permutation; total latency 961 = 577 + 6\times64), stored as a rank-4 factorization:

W_{b,l} = \sum_{r=1}^{4} t_{b,l,r}\,\mathbf{b}_{b,r}^{\top}

The hybrid synthesis table is the 77→64 recombination: identity for the high bands, Y_{3+b}=X_{16+b}, and for the low bands (C_p is the 8+4+4 child partition):

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\}

The same values also appear in other public implementations of these standards (for example FFmpeg's aacps_tablegen.h and aacsbrdata.h).

Captured Rosella filterbank

rosella_captured_kernels.npz holds the bank the reference headphone renderer actually runs (--rosella-filterbank 2):

format_version                  little-endian int32[1]
qmf_prototype                   float32[64,10]
rotation                        complex64[64]
hybrid                          complex64[22]

The table values are promoted to float64/complex128 on load. The full analysis/synthesis latency is 448 samples (961 for the public bank). These values come from runtime buffer captures of the reference renderer, not from the public standards above; the C++ core compiles the same data in as src/hrtf/rosella_filterbank_tables.h. This file also contains no personalized HRTF or room tuning.

Public availability of a standard does not by itself grant permission to practice related patent claims.

SOFA is the user-visible source of truth. A .jochrtf file is a disposable JOC compiled HRTF cache that can be rebuilt from SOFA. The cache contains transformed source-HRTF data and remains subject to the source SOFA/HRTF dataset's licence and redistribution restrictions.