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.
This commit is contained in:
TheM14 committed 2026-10-31 02:26:55 +08:00
1 parent 247e2a90b6
commit 0e98e91762
13 files changed
+606 -24

No files matched your search

+101
View File
@@ -0,0 +1,101 @@
"""Selectable Rosella 64-QMF / 77-hybrid filterbank.
The Rosella renderer can run either bank:
``PUBLIC_FILTERBANK`` (1)
The shared public bank of ``rosella_filterbank.py``: a 13-tap hybrid
analysis, a 6-slot high-band delay and 961 samples of analysis/synthesis
latency. This is the bank the reference implementation has always used.
``CAPTURED_FILTERBANK`` (2)
The bank the reference headphone renderer actually runs, captured from it:
an 11-tap hybrid analysis, a 3-slot high-band delay and 448 samples of
latency.
Both banks expose the same four stateful stages, so the choice changes the
coefficients, the high-band delay, the history layout and the latency together.
Nothing is shared between them.
"""
from __future__ import annotations
from pathlib import Path
from rosella_captured_filterbank import (
DEFAULT_CAPTURED_KERNEL_DATA,
HybridAnalysis as CapturedHybridAnalysis,
HybridSynthesis as CapturedHybridSynthesis,
QmfAnalysis as CapturedQmfAnalysis,
QmfSynthesis as CapturedQmfSynthesis,
)
from rosella_filterbank import (
DEFAULT_KERNEL_DATA,
HybridAnalysis as PublicHybridAnalysis,
HybridSynthesis as PublicHybridSynthesis,
QmfAnalysis as PublicQmfAnalysis,
QmfSynthesis as PublicQmfSynthesis,
)
PUBLIC_FILTERBANK = 1
CAPTURED_FILTERBANK = 2
FILTERBANK_CHOICES = (PUBLIC_FILTERBANK, CAPTURED_FILTERBANK)
DEFAULT_FILTERBANK = PUBLIC_FILTERBANK
FILTERBANK_NAMES = {
PUBLIC_FILTERBANK: "public",
CAPTURED_FILTERBANK: "captured",
}
# analysis/synthesis latency of each bank, in samples at 48 kHz
FILTERBANK_LATENCY_SAMPLES = {
PUBLIC_FILTERBANK: 961,
CAPTURED_FILTERBANK: 448,
}
def latency_samples(filterbank: int) -> 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()
+24 -18
View File
@@ -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,
+218
View File
@@ -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