Files
JustOneCacophony/data/README.en.md
T
TheM14 07a26b41fe Keep only the Rosella and .jochrtf binaural paths
The runtime renders two inputs now: the Rosella .personalized_headphone model and
an already compiled .jochrtf field. SOFA import, the full-HRIR direct renderer
and the SOFA -> .jochrtf fitting compiler leave this checkout; they continue as
an offline tool that only produces caches this repository loads.

The .jochrtf renderer goes back to the implementation that predates the direct
SOFA work: 64-QMF analysis, 77 hybrid bands, per-object hybrid path delays and
the project room (six first-order images plus the shared FDN tail) computed in
code. It is restored verbatim under the .jochrtf vocabulary
(SofaBinauralBackend -> JochrtfBackend) and gains one switch:
--jochrtf-room on|off, off by default. With the room off the renderer outputs
only the field's direct binaural sound, and in either mode it reads no audio
assets.

Because the room is computed in code again, the generated sofa-room*.npz assets
and the modules only the SOFA path used are removed (sofa_canonical, sofa_hrir,
sofa_direct_backend, sofa_room, hybrid_paths, partitioned_convolution,
point_source, compile_hrtf, generate_sofa_room). data/ keeps the decode tables
and the Rosella filterbanks.

The CLI drops --sofa-hrtf, --hrtf-radius-m, --sofa-interpolation,
--hrtf-cache-policy, --hrtf-cache-dir, --sofa-room, --sofa-room-preset and
--source-reference-distance-m. A .jochrtf is still explicit through
--compiled-hrtf-cache, and the default binaural input is the personalized model.

Rosella parsing, filterbank, room and timing are untouched and its output stays
bit-identical. The .jochrtf path reproduces the pre-SOFA renderer sample for
sample, with the room on and with it off.
2026-11-01 19:00:40 +08:00

4.2 KiB

Python runtime tables

中文

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

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.