From 0e98e91762b36e645947c76a37fee1b159fc4b99 Mon Sep 17 00:00:00 2001 From: TheM14 Date: Sat, 31 Oct 2026 02:26:55 +0800 Subject: [PATCH] Add the captured Rosella filterbank and select it per bank The Rosella path now chooses its filterbank. Bank 1 is the public bank the reference implementation has always used (13 taps / 6 slots, 961 samples); bank 2 is the captured bank the reference headphone renderer actually runs (11 taps / 3 slots, 448 samples). - src/rosella_captured_filterbank.py implements the four half-steps in float64/complex128; the captured prototype, rotation and hybrid coefficients live in data/rosella_captured_kernels.npz - src/rosella_bank.py owns the choice: both banks expose the same four stages, each with its own coefficients, history and latency - RosellaBinauralRenderer takes filterbank= and derives the startup skip, the flush capacity and the report fields from it - --rosella-filterbank 1|2 selects the bank, default 1; it is rejected for the SOFA and .jochrtf inputs instead of being ignored - document both banks in docs/rosella_filterbank.{md,en.md}, and point the binaural docs, the data README and the options tables at it Checked: the captured stages reproduce the reference vectors the C++ core checks (within 1e-10), an impulse returns at 961 and 448 samples, and chunking, reset and bank independence hold for both. --- README.en.md | 21 ++- README.md | 18 ++- data/README.en.md | 19 +++ data/README.md | 17 +++ data/rosella_captured_kernels.npz | Bin 0 -> 4284 bytes docs/binaural.en.md | 7 + docs/binaural.md | 6 + docs/rosella_filterbank.en.md | 89 ++++++++++++ docs/rosella_filterbank.md | 71 ++++++++++ main.py | 21 ++- src/rosella_bank.py | 101 +++++++++++++ src/rosella_binaural_renderer.py | 42 +++--- src/rosella_captured_filterbank.py | 218 +++++++++++++++++++++++++++++ 13 files changed, 606 insertions(+), 24 deletions(-) create mode 100644 data/rosella_captured_kernels.npz create mode 100644 docs/rosella_filterbank.en.md create mode 100644 docs/rosella_filterbank.md create mode 100644 src/rosella_bank.py create mode 100644 src/rosella_captured_filterbank.py diff --git a/README.en.md b/README.en.md index a47c121..4611f35 100644 --- a/README.en.md +++ b/README.en.md @@ -22,7 +22,7 @@ This is research code, not a complete, standards-compliant, or production-grade or `9.1.6` (`4.0` is the quad layout, a front and a back pair; see [Speaker layouts and channel order](#speaker-layouts-and-channel-order)). - Run public SOFA binaural rendering directly from `pcm16 + ID11/OAMD`, without a temporary ADM BWF. -- Keep the binaural DSP in float64/complex128, including 961-sample latency compensation, cross-frame state, and the room tail. +- Keep the binaural DSP in float64/complex128, including the selected filterbank's latency compensation (961 or 448 samples), cross-frame state, and the room tail. - Use a shared float32/PCM24 WAV writer and explicit PCM24 clipping policy for direct outputs. - Implement everything in pure Python on NumPy; - Read or write metadata sidecars and produce metadata, timing, and output reports. @@ -105,6 +105,8 @@ python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa ` --binaural-mode near python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa ` --hrtf-cache-policy disk +python main.py input.m4a --binaural --personalized-headphone ` + --rosella-filterbank 2 python main.py input.m4a --binaural --binaural-output output.binaural.wav ``` @@ -223,7 +225,21 @@ sample. ### Binaural calculation -See [Binaural Rendering Mathematics](docs/binaural.en.md) for QMF, hybrid processing, direction fields, distance, ITD, room processing, the 512-sample parameter updates above, and 961-sample latency compensation. +See [Binaural Rendering Mathematics](docs/binaural.en.md) for QMF, hybrid processing, direction fields, distance, ITD, room processing, the 512-sample parameter updates above, and the selected filterbank's latency compensation (961 by default, 448 with `--rosella-filterbank 2`). + +### Rosella filterbank + +`--rosella-filterbank 1|2` selects the filterbank of the `.personalized_headphone` +path: + +- `1` (default): the public bank, 13-tap hybrid / 6-slot high-band delay, + 961 samples of latency; +- `2`: the Rosella bank captured from the reference renderer, 11-tap hybrid / + 3-slot high-band delay, 448 samples of latency. + +The option only applies to the Rosella model; the SOFA and `.jochrtf` paths +reject it. See [Rosella filterbank](docs/rosella_filterbank.en.md) for the +parameters, buffers, latency and validation of both banks. For all options: @@ -321,3 +337,4 @@ See the [mathematical notes](docs/math.en.md) for the equations used by the deco - [Mathematical notes](docs/math.en.md) · [中文](docs/math.md) - [Binaural rendering](docs/binaural.en.md) · [中文](docs/binaural.md) +- [Rosella filterbank](docs/rosella_filterbank.en.md) · [中文](docs/rosella_filterbank.md) diff --git a/README.md b/README.md index 152ced2..218cee1 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ - 直接渲染 `2.0`、`3.1`、`4.0`、`5.1`、`7.1`、`5.1.2`、`5.1.4`、`7.1.2`、`7.1.4`、`9.1.4`、 `9.1.6`(`4.0` 是 Quad 布局,前后各一对;声道排列见[扬声器布局与声道顺序](#扬声器布局与声道顺序)); - 从 `pcm16 + ID11/OAMD` 直接运行公开 SOFA 双耳渲染,不生成临时 ADM BWF; -- 双耳 DSP 全程使用 float64/complex128,并保留 961-sample latency compensation、跨帧状态和 room 尾声; +- 双耳 DSP 全程使用 float64/complex128,并保留所选滤波器组的延迟补偿(公开版 961、捕获版 448 samples)、跨帧状态和 room 尾声; - 直接输出统一支持 float32 或 PCM24 WAV,并在 PCM24 削波前提供明确处理策略; - 全程使用 NumPy 的纯 Python 实现; - 读取或写入 metadata sidecar,并生成元数据、运行时间和输出摘要。 @@ -103,6 +103,8 @@ python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa ` --binaural-mode near python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa ` --hrtf-cache-policy disk +python main.py input.m4a --binaural --personalized-headphone ` + --rosella-filterbank 2 python main.py input.m4a --binaural --binaural-output output.binaural.wav ``` @@ -192,7 +194,18 @@ outer subpayload offset 与 block offset 落到绝对 sample timeline,再加 ### 双耳计算 -双耳路径的 QMF、hybrid、方向场、距离、ITD、room、上述 512-sample 参数更新和 961-sample 延迟补偿见[双耳渲染数学](docs/binaural.md)。 +双耳路径的 QMF、hybrid、方向场、距离、ITD、room、上述 512-sample 参数更新和所选滤波器组的延迟补偿(默认 961,`--rosella-filterbank 2` 为 448 samples)见[双耳渲染数学](docs/binaural.md)。 + +### Rosella 滤波器组 + +`--rosella-filterbank 1|2` 选择 `.personalized_headphone` 路径使用的滤波器组: + +- `1`(默认):公开滤波器组,13-tap hybrid / 6-slot 高频延迟,961 samples 延迟; +- `2`:从参考渲染器捕获的 Rosella 滤波器组,11-tap hybrid / 3-slot 高频延迟, + 448 samples 延迟。 + +该选项只作用于 Rosella 模型;SOFA 与 `.jochrtf` 路径给出时报错。两套实现的参数、 +缓冲、延迟与验证见 [Rosella 滤波器组](docs/rosella_filterbank.md)。 更多参数可查看: @@ -283,3 +296,4 @@ JustOneCacophony/ - [数学说明](docs/math.md) · [English](docs/math.en.md) - [双耳渲染](docs/binaural.md) · [English](docs/binaural.en.md) +- [Rosella 滤波器组](docs/rosella_filterbank.md) · [English](docs/rosella_filterbank.en.md) diff --git a/data/README.en.md b/data/README.en.md index 4703c35..a3612bf 100644 --- a/data/README.en.md +++ b/data/README.en.md @@ -72,6 +72,25 @@ $$Y_p = \sum_{q\in C_p}\Bigl(\operatorname{Re}X_q + j\,s_q\,\operatorname{Im}X_q 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`): + +```text +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. diff --git a/data/README.md b/data/README.md index 14a223a..ecd02d0 100644 --- a/data/README.md +++ b/data/README.md @@ -64,6 +64,23 @@ $$Y_p = \sum_{q\in C_p}\Bigl(\operatorname{Re}X_q + j\,s_q\,\operatorname{Im}X_q 相同数值可在 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 重建的 diff --git a/data/rosella_captured_kernels.npz b/data/rosella_captured_kernels.npz new file mode 100644 index 0000000000000000000000000000000000000000..69dcc8b8cef9a89b3a66f4a419d0001ac43f9271 GIT binary patch literal 4284 zcmbtXdst4{8vnXVr7KZNl2p^hMyV zXH4dC`fAm%C09}Pbs4p5Yef?%D)iv7hPz^pM5g; zi^+AW;Xk*bkgY-Ju)DrA!QTwuiH?FlZoI{n*6AlW zFfx>MT-u{-E8Whk?6eR!_%`C(kgC(fL|Ry!1M!4~dgtL2Nxw!93br*|R0#?cTZ zx86aA^CP(t=S(Hj^CNKhvIWp2w&SfKt4ROj{>mYh`}oklz0it+d&qCkc7A!Zx%Ap` z0$!<#fg0adEM=@CcQ?QEy26(8i(lKIBk2!NTa&q_Fa%X@b)T3(0hH4AzQ@1&4X{*!!!W$Qd1Fh5fx>_&LdgkgGj?QD3RwwtVbAD-N=? zOR>_EBTR!O7k23$AGtLQmDRsPcg68UKdGq@bb&CpxM|+r+sV~6R?^rpr?D_R25k3b;ow}6%u8L({rR0jSZ2HmO?=#q zneay`i9KT}rB>A9X&DP3y2rop>2gB)Ezjn<9%%^cj;=wmN4hiBK7=GT^^ryoYQ)V4 zqakCpO>Y$@q2q1+a{uyQ^$4ob!YB017+e?Ax0 zp(WIx%R<)EdN3=Yg)F0aby=?+FRPdbqZcp44|FQX=*nVl)?#g8Cu~5s8Dqx&*#mOA zpr=%nbRYX|ih{?Tk@(e+BP8G9AUCa8Tj==d2ei`Ol<8sfmW(=MCOO@CiU&`b3%yIG zVO3`txlvWYm8WY9gYRxZZ+nb&p|&v7 zZW}6n)stzuX(H-;V+YPXdMgb{ORdH|iGzDhjF62?uhjHF!FK+43lR}5-LDQ01aA?y|+%rA@6l4goN1R{r;PY-sJO~P|(GP=Cm~+3fJAtAyeHNxEB%6`0Z8uQ0gOFMr(0^SpK?G>{Dz3cFx~`t)3ZP5|~MRQ!a2z zV;=Ikv1N!~Ysa+Tm?#<_cqp#_hZUssp9-NB-LaUnn(Utb8)sa3i{GPp82xTw&%92W zDJC|zi^_5v*rhcYjCN_@=^?3P#^c|(q#4)vL22d4A!Z<#Yj?EnU zPvSYGiQ^;7c(;ScQAdjt^K$umF>S!l;@T@7U{W^<@=QzF>RUs}$gUFdlmLavCya>beYLm_pjA6#|b!TOaslcr%8xfkq@Jd=A8owIOe`sn^7Rv4`n6TeVG z(f7VUDmJj*KiLo+^UGXD-S@mA`ZRK>c4G7!cZvU+xKy-62$YRqK{J=m>Jw8kW_JtM zyg!xy(ybcZb#`J*OZJHO=6xgPA`C6Y7;HnAu&;XRl5G9!+}et8e)p9cWIW7~aag%u zWJ6ie*Tn~XSp*kdXR;Zwox-@tc5YhLDE>|2S>$}nfe8#fB0eA7Ph8Y}I9P`&!LVgC zyKVY4A-C}^mwnHLKcH2Mkmo=q#G4l{oOn&vH2T57grN{LcNiP>rbbv3^O(~gYQ*E+lmfwxYHi3M{= zgXb7nnmib~>zS}}b-qwnsNly6JGou~^~hnpHM8yTS&_FnBs85K2OjaR;O_J%b6G!I z$Zpl)xn(|_&-Mn?U}4E@ORN`P70f|Xhkp%sLY*P!w@b|L2bKx>XAJm;Q{NuTxOD;P zS@mLS1~-fT-d{7dr4u03cMz;IzySuA|UyoVx)+J-S9i}&-_%s7%Nqn1_^Mw{0&rAW&7q(D;FOgYnYa_6n z9k0wU@qV7wj6#}pn4>Rmiv=#O?7>+f(C@T0WElbT>YRo!E$jFZR;G4dz57gE9X z7YlLks#I9y@~t?7F<9uUjoz5{o1L;Q7b3Z&O{mulo>IJ$R$R9pHj)Wsl4GhrEM z^a_@?m?c4KUbJ*7GZBubtdLH(E`|YlS<+R5MUcKTPYN=R2ea%#DWNkK9?d=^Z9KF9 zM%ze|VZeNtz|}~MJQsY1HA)%AkuZM4bt#0I4Z_*`lAYg7ID7qtG{J2;wBJ_9^PWzH z6#=^P%^xPg{5%8Mzt04yyps~s{W=vz3DF#fj$P^Q%*kp-$@j45`Ra)2opGUWtQ zZe+?4rd-LCGfcUYDTkPHDN{}{KeA>3Fn{l<7sW*QZ zY43Ud? int: + """Length of the startup transient the runtime removes for ``filterbank``.""" + try: + return FILTERBANK_LATENCY_SAMPLES[int(filterbank)] + except (KeyError, TypeError, ValueError): + raise ValueError( + f"Rosella filterbank must be 1 (public) or 2 (captured), got {filterbank!r}" + ) from None + + +class RosellaBank: + """The four stages of one bank, each with its own state.""" + + def __init__(self, filterbank: int = DEFAULT_FILTERBANK, *, + source_channels: int, output_channels: int, + kernel_data: str | Path | None = None): + if filterbank not in FILTERBANK_CHOICES: + raise ValueError( + f"Rosella filterbank must be 1 (public) or 2 (captured), got {filterbank!r}") + kind = int(filterbank) + if source_channels <= 0 or output_channels <= 0: + raise ValueError("channel counts must be positive") + self.filterbank = kind + self.name = FILTERBANK_NAMES[kind] + self.latency_samples = latency_samples(kind) + if kind == PUBLIC_FILTERBANK: + self.table_path = Path( + DEFAULT_KERNEL_DATA if kernel_data is None else kernel_data + ).expanduser().resolve() + self.qmf_analysis = PublicQmfAnalysis(source_channels, self.table_path) + self.hybrid_analysis = PublicHybridAnalysis(source_channels, self.table_path) + self.hybrid_synthesis = PublicHybridSynthesis(output_channels, self.table_path) + self.qmf_synthesis = PublicQmfSynthesis(output_channels, self.table_path) + else: + self.table_path = Path( + DEFAULT_CAPTURED_KERNEL_DATA if kernel_data is None else kernel_data + ).expanduser().resolve() + self.qmf_analysis = CapturedQmfAnalysis(source_channels, self.table_path) + self.hybrid_analysis = CapturedHybridAnalysis(source_channels, self.table_path) + self.hybrid_synthesis = CapturedHybridSynthesis(output_channels, self.table_path) + self.qmf_synthesis = CapturedQmfSynthesis(output_channels, self.table_path) + + def reset(self): + self.qmf_analysis.reset() + self.hybrid_analysis.reset() + self.hybrid_synthesis.reset() + self.qmf_synthesis.reset() diff --git a/src/rosella_binaural_renderer.py b/src/rosella_binaural_renderer.py index c1964f2..dd6b668 100644 --- a/src/rosella_binaural_renderer.py +++ b/src/rosella_binaural_renderer.py @@ -16,22 +16,16 @@ import numpy as np from bed_layout import bed_object_positions from binaural_metadata import OamdPositionTimeline +from rosella_bank import (DEFAULT_FILTERBANK, FILTERBANK_CHOICES, FILTERBANK_NAMES, + RosellaBank) from rosella_core import RosellaRenderer from rosella_direct import BINAURAL_PROFILE_NAMES -from rosella_filterbank import ( - DEFAULT_KERNEL_DATA, - HybridAnalysis, - HybridSynthesis, - QmfAnalysis, - QmfSynthesis, -) from rosella_model import RosellaModel, load_personalized_headphone SAMPLE_RATE = 48000 FRAME_SAMPLES = 1536 ROSSELLA_BLOCK_SAMPLES = 512 QMF_HOP_SAMPLES = 64 -ROSSELLA_LATENCY_SAMPLES = 961 SOURCE_CHANNELS = 16 OUTPUT_CHANNELS = 2 PROJECT_DIR = Path(__file__).resolve().parent.parent @@ -67,7 +61,8 @@ class RosellaBinauralRenderer: personalized_headphone: str | Path | RosellaModel, *, mode: str = "mid", - kernel_data: str | Path = DEFAULT_KERNEL_DATA, + filterbank: int = DEFAULT_FILTERBANK, + kernel_data: str | Path | None = None, object_delay_samples: int = 1473, tail_seconds: float = 5.0, output_gain: float = 1.0, @@ -76,6 +71,9 @@ class RosellaBinauralRenderer: bed_channels=None): if mode not in BINAURAL_PROFILE_NAMES: raise ValueError("binaural mode must be near, mid, or far") + if filterbank not in FILTERBANK_CHOICES: + raise ValueError( + f"Rosella filterbank must be 1 (public) or 2 (captured), got {filterbank!r}") if int(object_delay_samples) < 0: raise ValueError("object_delay_samples must be non-negative") if float(tail_seconds) < 0.0: @@ -97,8 +95,6 @@ class RosellaBinauralRenderer: self.mode = mode self.profile_index = BINAURAL_PROFILE_NAMES[mode] - self.kernel_data = Path(kernel_data).expanduser().resolve() - self.kernel_data_sha256 = _sha256_file(self.kernel_data) self.object_delay_samples = int(object_delay_samples) self.tail_seconds = float(tail_seconds) self.output_gain = np.float64(output_gain) @@ -106,13 +102,21 @@ class RosellaBinauralRenderer: self.chunk_samples = self.chunk_frames * FRAME_SAMPLES self.dsp_backend = "python" - self.qmf_analysis = QmfAnalysis(SOURCE_CHANNELS, self.kernel_data) - self.hybrid_analysis = HybridAnalysis(SOURCE_CHANNELS, self.kernel_data) + self.bank = RosellaBank( + filterbank, source_channels=SOURCE_CHANNELS, + output_channels=OUTPUT_CHANNELS, kernel_data=kernel_data) + self.filterbank = self.bank.filterbank + self.filterbank_name = FILTERBANK_NAMES[self.filterbank] + self.latency_samples = self.bank.latency_samples + self.kernel_data = self.bank.table_path + self.kernel_data_sha256 = _sha256_file(self.kernel_data) + self.qmf_analysis = self.bank.qmf_analysis + self.hybrid_analysis = self.bank.hybrid_analysis self.core = RosellaRenderer( self.model, SOURCE_CHANNELS, room_impulse_slots=room_impulse_slots) - self.hybrid_synthesis = HybridSynthesis(OUTPUT_CHANNELS, self.kernel_data) - self.qmf_synthesis = QmfSynthesis(OUTPUT_CHANNELS, self.kernel_data) + self.hybrid_synthesis = self.bank.hybrid_synthesis + self.qmf_synthesis = self.bank.qmf_synthesis self.timeline = OamdPositionTimeline( 15, bed_positions=bed_object_positions(bed_channels or ())) @@ -213,7 +217,7 @@ class RosellaBinauralRenderer: stereo *= self.output_gain skip = max(0, min( - len(stereo), ROSSELLA_LATENCY_SAMPLES - self.raw_output_samples)) + len(stereo), self.latency_samples - self.raw_output_samples)) self.raw_output_samples += len(stereo) self.processed_input_samples += len(values) output = stereo[skip:] @@ -231,7 +235,7 @@ class RosellaBinauralRenderer: self._buffer_used = 0 flush_samples = math.ceil( (self.tail_seconds * SAMPLE_RATE - + ROSSELLA_LATENCY_SAMPLES + ROSSELLA_BLOCK_SAMPLES) + + self.latency_samples + ROSSELLA_BLOCK_SAMPLES) / ROSSELLA_BLOCK_SAMPLES) * ROSSELLA_BLOCK_SAMPLES while flush_samples: count = min(flush_samples, self.chunk_samples) @@ -259,7 +263,9 @@ class RosellaBinauralRenderer: "kernel_data": str(self.kernel_data), "kernel_data_sha256": self.kernel_data_sha256, "mode": self.mode, - "latency_compensated_samples": ROSSELLA_LATENCY_SAMPLES, + "filterbank": self.filterbank, + "filterbank_name": self.filterbank_name, + "latency_compensated_samples": self.latency_samples, "object_delay_samples": self.object_delay_samples, "tail_seconds": self.tail_seconds, "metadata_payloads": self.timeline.payload_count, diff --git a/src/rosella_captured_filterbank.py b/src/rosella_captured_filterbank.py new file mode 100644 index 0000000..590da9b --- /dev/null +++ b/src/rosella_captured_filterbank.py @@ -0,0 +1,218 @@ +"""Captured Rosella 64-QMF / 77-hybrid filterbank. + +The Rosella headphone renderer selects its analysis and synthesis callbacks +during preparation, after initialization. The callbacks it actually runs are +this bank: a 640-coefficient QMF prototype, an 11-tap hybrid analysis with a +3-slot high-band delay, and a 448-sample analysis/synthesis latency. The shared +public bank lives in ``rosella_filterbank.py`` and differs in every one of those +parameters (13-tap hybrid, 6-slot delay, 961-sample latency). + +The tables are the float32 values the C++ core compiles in as +``src/hrtf/rosella_filterbank_tables.h``; ``data/rosella_captured_kernels.npz`` +holds the same numbers. State is float64/complex128, like the rest of the +reference implementation. +""" +from __future__ import annotations + +from functools import lru_cache +from pathlib import Path + +import numpy as np + +PROJECT_DIR = Path(__file__).resolve().parent.parent +DEFAULT_CAPTURED_KERNEL_DATA = PROJECT_DIR / "data" / "rosella_captured_kernels.npz" + +QMF_BANDS = 64 +HYBRID_BANDS = 77 +QMF_TAPS = 10 +HYBRID_TAPS = 11 +HYBRID_DELAY = 3 +HYBRID_LOW_BANDS = 16 +ANALYSIS_SYNTHESIS_LATENCY_SAMPLES = 448 + +# The captured renderer's hybrid band order: destination[k] = low[HYBRID_ORDER[k]]. +HYBRID_ORDER = (0, 7, 1, 6, 2, 9, 3, 4, 10, 5, 11, 15, 8, 12, 13, 14) + +# Bands 1 and 3 are conjugated after the permutation. +_CONJUGATED_BANDS = (1, 3) + + +def _tap_sign(tap: int) -> float: + return 1.0 if (tap // 2) % 2 == 0 else -1.0 + + +@lru_cache(maxsize=4) +def _load_tables(path_string: str) -> dict[str, np.ndarray]: + path = Path(path_string) + if not path.is_file(): + raise FileNotFoundError(f"Rosella captured kernel data not found: {path}") + with np.load(path, allow_pickle=False) as archive: + version = archive["format_version"] + if version.shape != (1,) or int(version[0]) != 1: + raise ValueError( + f"unsupported Rosella captured kernel data version in {path}") + prototype = np.asarray(archive["qmf_prototype"], dtype=np.float64) + rotation = np.asarray(archive["rotation"], dtype=np.complex128) + hybrid = np.asarray(archive["hybrid"], dtype=np.complex128) + if prototype.shape != (QMF_BANDS, QMF_TAPS): + raise ValueError("invalid qmf_prototype shape") + if rotation.shape != (QMF_BANDS,): + raise ValueError("invalid rotation shape") + if hybrid.shape != (2 * HYBRID_TAPS,): + raise ValueError("invalid hybrid shape") + return {"qmf_prototype": prototype, "rotation": rotation, "hybrid": hybrid} + + +def load_kernel_tables(path: str | Path = DEFAULT_CAPTURED_KERNEL_DATA + ) -> dict[str, np.ndarray]: + """Load and cache the captured Rosella kernel tables.""" + return _load_tables(str(Path(path).expanduser().resolve())) + + +class QmfAnalysis: + """64-band analysis: 640-coefficient prototype, 9-slot chronological history.""" + + def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_CAPTURED_KERNEL_DATA): + if channels <= 0: + raise ValueError("channels must be positive") + tables = load_kernel_tables(kernel_data) + self.prototype = tables["qmf_prototype"] + self.rotation = tables["rotation"] + self.channels = int(channels) + self.history = np.zeros((QMF_TAPS - 1, self.channels, QMF_BANDS), + dtype=np.float64) + + def reset(self): + self.history.fill(0.0) + + def process_chunk(self, hops) -> np.ndarray: + values = np.asarray(hops, dtype=np.float64) + if values.ndim != 3 or values.shape[1:] != (self.channels, QMF_BANDS): + raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}") + count = values.shape[0] + joined = np.concatenate((self.history, values), axis=0) + even = np.zeros_like(values) + odd = np.zeros_like(values) + for tap in range(QMF_TAPS): + # The window of output i is joined[i:i+10], oldest tap first. + source = joined[tap:tap + count] + target = even if tap % 2 == 0 else odd + target += source * ( + 0.5 * self.prototype[:, tap] * _tap_sign(tap))[None, None, :] + self.history[:] = joined[-(QMF_TAPS - 1):] if count else self.history + + spectrum = (odd + 1j * even) * self.rotation[None, None, :] + transformed = np.fft.fft(spectrum, axis=-1) + output = np.empty(values.shape, dtype=np.complex128) + output[..., 0::2] = transformed[..., :QMF_BANDS // 2] / QMF_BANDS + output[..., 1::2] = np.conj( + transformed[..., QMF_BANDS // 2:][..., ::-1]) / QMF_BANDS + return output + + +class HybridAnalysis: + """Sparse 64-QMF to 77-hybrid analysis: 11 taps, 3-slot high-band delay.""" + + def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_CAPTURED_KERNEL_DATA): + if channels <= 0: + raise ValueError("channels must be positive") + tables = load_kernel_tables(kernel_data) + self.low_kernel = tables["hybrid"] + self.channels = int(channels) + self.history = np.zeros((HYBRID_TAPS - 1, self.channels, QMF_BANDS), + dtype=np.complex128) + + def reset(self): + self.history.fill(0.0) + + def process_chunk(self, qmf) -> np.ndarray: + values = np.asarray(qmf, dtype=np.complex128) + if values.ndim != 3 or values.shape[1:] != (self.channels, QMF_BANDS): + raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}") + count = values.shape[0] + joined = np.concatenate((self.history, values), axis=0) + output = np.zeros((count, self.channels, HYBRID_BANDS), dtype=np.complex128) + low = np.zeros((count, self.channels, HYBRID_LOW_BANDS), dtype=np.complex128) + for band, size in ((0, 8), (1, 4), (2, 4)): + offset = 0 if band == 0 else HYBRID_TAPS + spectrum = np.zeros((count, self.channels, size), dtype=np.complex128) + for tap in range(HYBRID_TAPS): + source = joined[tap:tap + count, :, band] + spectrum[:, :, (tap + 1) % size] += source * self.low_kernel[offset + tap] + base = 0 if band == 0 else 4 + band * 4 + low[:, :, base:base + size] = np.fft.fft(spectrum, axis=-1) + output[:, :, :HYBRID_LOW_BANDS] = low[:, :, list(HYBRID_ORDER)] + for band in _CONJUGATED_BANDS: + output[:, :, band] = np.conj(output[:, :, band]) + # The high bands pass through unchanged, delayed by HYBRID_DELAY slots. + delayed = joined[HYBRID_TAPS - 1 - HYBRID_DELAY: + HYBRID_TAPS - 1 - HYBRID_DELAY + count, :, 3:] + output[:, :, HYBRID_LOW_BANDS:] = delayed + self.history[:] = joined[-(HYBRID_TAPS - 1):] if count else self.history + return output + + +class HybridSynthesis: + """Instantaneous 77-hybrid to 64-QMF recombination.""" + + def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_CAPTURED_KERNEL_DATA): + if channels <= 0: + raise ValueError("channels must be positive") + self.channels = int(channels) + + def reset(self): + return None + + def process_chunk(self, hybrid) -> np.ndarray: + values = np.asarray(hybrid, dtype=np.complex128) + if values.ndim != 3 or values.shape[1:] != (self.channels, HYBRID_BANDS): + raise ValueError(f"expected [slots,{self.channels},77], got {values.shape}") + output = np.empty((values.shape[0], self.channels, QMF_BANDS), + dtype=np.complex128) + output[..., 0] = (values[..., 0] + values[..., 2] + values[..., 4] + + values[..., 6] + values[..., 7] + values[..., 9] + + np.conj(values[..., 3]) + np.conj(values[..., 1])) + output[..., 1] = (values[..., 12] + values[..., 5] + values[..., 8] + + values[..., 10]) + output[..., 2] = (values[..., 13] + values[..., 14] + values[..., 15] + + values[..., 11]) + output[..., 3:] = values[..., HYBRID_LOW_BANDS:] + return output + + +class QmfSynthesis: + """64-band synthesis: prototype-matched 10-tap overlap with a 9-slot history.""" + + def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_CAPTURED_KERNEL_DATA): + if channels <= 0: + raise ValueError("channels must be positive") + tables = load_kernel_tables(kernel_data) + self.prototype = tables["qmf_prototype"] + self.rotation = tables["rotation"] + self.channels = int(channels) + self.history = np.zeros((QMF_TAPS - 1, self.channels, QMF_BANDS), + dtype=np.complex128) + + def reset(self): + self.history.fill(0.0) + + def process_chunk(self, qmf) -> np.ndarray: + values = np.asarray(qmf, dtype=np.complex128) + if values.ndim != 3 or values.shape[1:] != (self.channels, QMF_BANDS): + raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}") + count = values.shape[0] + spectrum = np.empty((count, self.channels, QMF_BANDS), dtype=np.complex128) + spectrum[..., :QMF_BANDS // 2] = np.conj(values[..., 0::2]) + spectrum[..., QMF_BANDS // 2:] = values[..., QMF_BANDS - 1::-2] + current = np.fft.fft(spectrum, axis=-1) * self.rotation[None, None, :] + joined = np.concatenate((self.history, current), axis=0) + output = np.zeros((count, self.channels, QMF_BANDS), dtype=np.float64) + reversed_bands = QMF_BANDS - 1 - np.arange(QMF_BANDS) + for lag in range(QMF_TAPS): + source = joined[QMF_TAPS - 1 - lag:QMF_TAPS - 1 - lag + count] + coefficient = (self.prototype[reversed_bands, QMF_TAPS - 1 - lag] * + _tap_sign(lag) * 2.0) + component = source.real if lag % 2 == 0 else source.imag + output += component * coefficient[None, None, :] + self.history[:] = joined[-(QMF_TAPS - 1):] if count else self.history + return output