Honor OAMD warp modes and position-dependent speaker trims

Read warp mode from OAMD instead of always scaling the floor Y coordinate.
For eligible layouts, mode 1 uses clamp(2Y, 0, 1), while mode 0 leaves Y
unchanged. Height coordinates are not scaled. Modes 2/3 remain explicitly
unsupported, and the CLI provides no warp override.

Keep separate coordinates for floor panning, height panning and trim
evaluation, with W denoting warp and B denoting front-back balance:

    floor Y  = B(W(Y))
    height Y = B(Y)
    trim Y   = B(Y)

Apply explicit trims as a position-dependent gain for each object before
accumulation, replacing fixed gains applied to output channels after mixing.
Automatic, disabled and explicit trim modes are mutually exclusive.
Per-object bypass disables balance and trim while retaining warp.

Update controls at OAMD metadata events and retain the previous controls
when a payload has no trim element. Keep source trajectories and binaural
rendering unchanged.

Write the OAMD warp code into dbmd segment 9 while preserving the other
packed fields. Update the bilingual mathematical notes, README files and
code comments to describe parameters and rendering behavior.

Checked: warp 0/1, Y clipping, height coordinates, balance/trim ordering,
per-object bypass, metadata updates, bed positions and LFE passthrough.
This commit is contained in:
TheM14 committed 2026-11-03 00:11:23 +08:00
1 parent 8424e6bdfb
commit 0e28cd085c
17 files changed
+335 -191

No files matched your search

+62 -29
View File
@@ -446,14 +446,16 @@ $$
$$
For layouts with one horizontal surround pair rather than separate side and rear pairs (the 5.1
family, and 4.0, which carries one rear pair only), the longitudinal coordinate is
family, and 4.0, which carries one rear pair only), OAMD `warp_mode=1` uses
$$
v_{\mathrm{floor}}=
\mathrm{clamp}(2v,0,1).
$$
Other layouts use $v_{\mathrm{floor}}=v$.
Warp 0 and other layouts use $v_{\mathrm{floor}}=v$. The height layer is not scaled.
An absent warp indication uses 0; no CLI override is provided. Modes 2/3 are
explicitly unsupported rather than mapped to 0/1. Balance follows this scaling.
### 10.3 Height layer
@@ -474,6 +476,9 @@ $$
## 11. Layout-dependent position compensation
This is the per-object gain for automatic trim. Disabled trim uses unity;
explicit trim uses §12.2 instead, without multiplying automatic compensation again.
Let $N_h$ be the number of relevant height speakers and $N_f$ the number of relevant additional horizontal speakers:
$$
@@ -552,35 +557,53 @@ speakers by no / some / many height speakers".
Trim and front-back balance apply to seven layouts only: 2.0, 3.1, 4.0, 5.1,
5.1.2, 5.1.4 and 7.1. Wider layouts (7.1.2, 7.1.4, 9.1.4, 9.1.6) are left
untrimmed, with $G_c=1$ and $b=0$.
untrimmed, with $g_t=1$ and $b=0$.
### 12.2 Group levels
Warp, trim and balance controls are read from OAMD metadata:
Each configuration supplies one level $T_g$ in dB for the centre, surround and
height groups. Only an explicit configuration contributes a static level:
| Parameter | Value or unit | Behavior |
|---|---|---|
| `warp_mode` | 0 / 1 | Selects the floor Y mapping in §10.2; modes 2/3 are unsupported and rejected |
| `global_trim_mode` | 0 / 1 / 2 | Automatic / disabled / per-layout configuration; reserved value 3 is rejected |
| $T_s$, $T_h$ | dB | Explicit surround and height trim, with positive values treated as zero |
| $T_c$ | dB | Signed explicit centre trim |
| $b_{\mathrm{lis}}$, $b_{\mathrm{tb}}$ | $[-1,1]$, step $1/16$ | Listener-plane and overhead front-back balance |
| Per-object trim bypass | Boolean | Disables the object's balance and trim gain while retaining warp |
With global mode 2, the selected configuration's default or disabled flag
chooses automatic or disabled trim. A missing configuration uses automatic;
otherwise its explicit parameters apply. Automatic uses §11, disabled uses
unity, and explicit uses §12.2. These modes are mutually exclusive.
Without an initial trim element, warp is 0 and trim is automatic. A later
payload without that element retains the previous controls; a new element
updates them at the corresponding metadata event boundary. The CLI has no
warp override.
### 12.2 Per-object levels
Centre, surround and height levels parameterize a position-dependent object
gain; they are not fixed gains applied to the output channels after mixing.
For original Y after balance $y_t$ and $z=\max(w,0)$:
$$
T_g=
\begin{cases}
\text{coded value}, & \text{explicit},\
0, & \text{disabled},\
0, & \text{automatic}.
\end{cases}
a_s=\mathrm{clamp}(2y_t,0,1)(1-z),\quad a_h=z,
$$
An automatic configuration carries no static group gain: the attenuation it
describes is already applied per object by the position compensation of §11,
and multiplying it in a second time would count it twice.
The static gain of channel $c$ is
$$
G_c=10^{T_{g(c)}/20},
a_c=1-\mathrm{clamp}\bigl(10\max(|z|-0.05,y_t-0.05,|u-0.5|-0.05),0,1\bigr).
$$
where $g(c)$ follows the channel label: centre maps to centre, side, rear and
wide map to surround, top maps to height, and left, right and LFE stay at
$G_c=1$.
Explicit trim uses
$$
D=a_s\min(T_s,0)+a_h\min(T_h,0)+a_cT_c,\qquad g_t=10^{D/20}.
$$
The scalar multiplies the object's whole panning vector before accumulation.
Automatic trim uses §11; disabled trim or per-object bypass uses unity. LFE
passes through. Gain evaluation, panning interpolation and object accumulation
use float64.
### 12.3 Front-back balance
@@ -618,18 +641,28 @@ $1$ at the back wall; $x$ and $z$ are unchanged.
### 12.4 Where it is applied
The balance acts on the second component of the object position before
panning:
Let $B_z(y)$ denote the balance map of §12.3 and $W(y)$ the warp map of §10.2.
The ordinary point-object path keeps three coordinates:
$$
y_o\longmapsto y_o',
y_f=B_z(W(y)),\qquad y_h=B_z(y),\qquad y_t=B_z(y).
$$
while the group gain multiplies the panning result, that is $g_{o,c}$ in the
mix formula of §14 becomes $G_c\,g_{o,c}$.
Floor and height panning use $y_f,y_h$; trim evaluation uses $y_t$. The final gain is
Warp takes no part in either step: it selects a downmix mode, affects only the
downmix path, and leaves object coordinates untouched.
$$
g_{o,c}=G_{\mathrm{object}}\,g_t(u,y_t,z)\,P_c(u,y_f,y_h,z).
$$
Warp precedes balance, followed by trim/pan gain composition, but not every
stage shares a warped Y. Balance requires explicit trim without object bypass;
warp remains independent of trim state and bypass. Source positions are kept
unchanged for ADM and binaural.
Floor coordinates pass through warp and then balance before floor panning.
Height and trim coordinates pass through balance alone. The trim scalar
multiplies the object's entire panning vector before accumulation into output
channels. LFE passes through.
## 13. OAMD time alignment and gain ramps
+56 -25
View File
@@ -443,14 +443,16 @@ $$
$$
对于只有一对水平环绕、没有独立 side/rear 两对的布局(5.1 系列,以及 4.0 这类
只有一对后置声道的布局),纵向坐标使用
只有一对后置声道的布局),仅在 OAMD `warp_mode=1` 时,纵向坐标使用
$$
v_{\mathrm{floor}}=
\mathrm{clamp}(2v,0,1).
$$
其他布局使用 $v_{\mathrm{floor}}=v$。
`warp_mode=0` 或其他布局使用 $v_{\mathrm{floor}}=v$。高度层不做该缩放。
未携带 warp 元数据时采用 0;命令行不提供覆盖选项。2/3 保留为未实现,报错而不回退。
有 front/back balance 时,先求这里的分支坐标,再应用 §12.3 的 balance。
### 10.3 高度层
@@ -471,6 +473,9 @@ $$
## 11. 布局位置补偿
本节是 trim 为 automatic 时的逐对象增益。disabled 取 1;explicit 改用 §12.2,
不能把 automatic 增益与 explicit trim 再乘一遍。
令 $N_h$ 为相关高度扬声器数,$N_f$ 为相关附加水平扬声器数:
$$
@@ -546,38 +551,54 @@ $$
九个配置依次为“no / some / many 附加水平 × no / some / many 高度”。
trim 与前后平衡只在七种布局下施加:2.0、3.1、4.0、5.1、5.1.2、5.1.4、7.1。
更宽的布局(7.1.2、7.1.4、9.1.4、9.1.6)不施加,取 $G_c=1$、$b=0$。
更宽的布局(7.1.2、7.1.4、9.1.4、9.1.6)取 $g_t=1$、$b=0$。
### 12.2 组电平
warp、trim 和 balance 均从 OAMD 元数据读取。各参数的取值与作用为:
每个配置给 centre、surround、height 三个组各一个电平 $T_g$(dB)。只有显式配置
施加静态电平:
| 参数 | 取值或单位 | 行为 |
|---|---|---|
| `warp_mode` | 0 / 1 | 选择 §10.2 的地面 Y 映射;2/3 暂不支持,遇到时明确报错 |
| `global_trim_mode` | 0 / 1 / 2 | automatic / disabled / 按目标布局配置选择;3 为保留值,明确报错 |
| $T_s$、$T_h$ | dB | 显式 surround、height trim 参数,正值按 0 处理 |
| $T_c$ | dB | 显式 centre trim 参数,保留符号 |
| $b_{\mathrm{lis}}$、$b_{\mathrm{tb}}$ | $[-1,1]$,步长 $1/16$ | 听音平面、顶部的前后 balance |
| 逐对象 trim bypass | 布尔值 | 关闭该对象的 balance 和 trim 增益,保留 warp |
全局模式为 2 时,所选配置的 default 或 disabled 标志分别采用 automatic 或 disabled;
缺失配置采用 automatic,其他配置使用其显式参数。automatic 使用 §11 的位置补偿,
disabled 使用单位增益,explicit 使用 §12.2,三种模式互斥。
初始没有 trim element 时采用 `warp_mode=0`、automatic trim。后续 payload 不含该
element 时保持上一组控制;出现新 element 时,在对应元数据事件边界更新。命令行不提供
warp 覆盖选项。
### 12.2 逐对象电平
centre、surround、height 是位置相关 trim 函数的参数,不是混音后各输出声道的固定增益。
令 $y_t$ 为原始 Y 经 balance 后的坐标,$z=\max(w,0)$:
$$
T_g=
\begin{cases}
\text{记录值}, & \text{显式},\
0, & \text{禁用},\
0, & \text{自动}.
\end{cases}
a_s=\mathrm{clamp}(2y_t,0,1)(1-z),\qquad a_h=z,
$$
自动配置不带静态组增益:它描述的衰减量已由 §11 的位置补偿按对象逐个施加,再乘
一次会重复计算。
声道 $c$ 的静态增益为
$$
G_c=10^{T_{g(c)}/20},
a_c=1-\mathrm{clamp}\bigl(10\max(|z|-0.05,\ y_t-0.05,\ |u-0.5|-0.05),0,1\bigr).
$$
$g(c)$ 由声道标签决定:中置归 centre,侧、后、宽归 surround,顶部归 height,左右
与 LFE 不参与,取 $G_c=1$。
explicit 状态下,surround/height 参数上限为 0 dB,centre 保留有符号电平:
$$
D=a_s\min(T_s,0)+a_h\min(T_h,0)+a_cT_c,\qquad g_t=10^{D/20}.
$$
同一个 $g_t$ 乘该对象的整条声像增益向量,然后才累加不同对象。automatic 使用 §11;
disabled 或逐对象 trim bypass 取 $g_t=1$。LFE 仍直接通过。
增益求值、声像插值和对象累加均使用 float64。
### 12.3 前后平衡
每个配置还携带两个前后平衡量:$b_{\mathrm{lis}}$ 作用于听音平面,
$b_{\mathrm{tb}}$ 作用于顶上层层。二者按 $1/16$ 网格量化,只在显式配置下非零。
$b_{\mathrm{tb}}$ 作用于顶部。二者按 $1/16$ 网格量化,只在显式配置下非零。
记 $n=\mathrm{round}(16\,|b|)$、$s=n/18$,单层映射为
@@ -606,15 +627,25 @@ $$
### 12.4 施加位置
前后平衡在声像之前作用于对象坐标的第二个分量:
记 §12.3 的高度混合 balance 映射为 $B_z(y)$,§10.2 的 warp 映射为 $W(y)$。
普通点对象的实际分支顺序为
$$
y_o\longmapsto y_o',
y_f=B_z(W(y)),\qquad y_h=B_z(y),\qquad y_t=B_z(y).
$$
组增益则乘在声像结果上,即 §14 混音式中的 $g_{o,c}$ 替换为 $G_c\,g_{o,c}$。
地面和高度声像分别使用 $y_f,y_h$,trim 函数使用 $y_t$。最后组合
warp 不参与上述任何一步:它是下混模式的选择位,只影响下混路径,不改变对象坐标。
$$
g_{o,c}=G_{\mathrm{object}}\,g_t(u,y_t,z)\,P_c(u,y_f,y_h,z).
$$
因此可概括为 warp → balance → trim 与声像增益合成,但不能让所有阶段共用一个
已经 warp 的 Y。balance 仅在 explicit 且未逐对象 bypass 时启用;warp 不受 trim
状态或 trim bypass 控制。源坐标保持原值,ADM 与 binaural 不预烘焙此变换。
地面坐标依次经过 warp、balance,再用于地面声像;顶部坐标和 trim 求值坐标只经过
balance。trim 标量乘到该对象的整条声像增益向量后,再累加到输出声道。LFE 直接通过。
## 13. OAMD 时间对齐与增益斜坡
+12 -35
View File
@@ -3,8 +3,8 @@
[中文](rosella_filterbank.md) · [Back to README](../README.en.md)
The Rosella `.personalized_headphone` path can run either of two 64-QMF /
77-hybrid filterbanks: the shared public bank (the default) or the Rosella bank
captured from the reference renderer. The SOFA and `.jochrtf` paths always use
77-hybrid filterbanks: the 13-tap public bank (the default) or the 11-tap Rosella
bank. The SOFA and `.jochrtf` paths always use
the public bank and never consult the selector.
## Which bank runs
@@ -26,30 +26,21 @@ and never share it. Any other value is rejected, and the option is an error when
the binaural input is not a Rosella model: a SOFA or `.jochrtf` render must not
silently ignore it.
## Why the banks differ
## Bank parameters
The reference headphone renderer selects its analysis and synthesis callbacks
during preparation, after initialization. Capturing only the initial callbacks
identified the wrong filterbank variant. Runtime buffer captures gave these
parameters:
| Parameter | Captured Rosella bank | Public bank |
| Parameter | 11-tap Rosella bank | 13-tap public bank |
| --- | --- | --- |
| QMF prototype | 640 asymmetric coefficients | polyphase reorder of the public 640-tap prototype |
| Low-band hybrid filter | 11 taps | 13 taps |
| High-band hybrid delay | 3 slots | 6 slots |
| Analysis/synthesis latency | 448 samples | 961 samples |
The wrong variant produced a frequency-dependent room-tail error. With the
captured room send as input, the existing room recursion already matched the
reference, so the fix changes only the filterbank: not the room coefficients,
the direct HRTF calculation, the phase mapping, or the output EQ. The public
bank stayed as bank `1` so historical renders remain reproducible; the captured
bank is bank `2`.
The selector does not change room coefficients, direct HRTF calculation, phase
mapping or output EQ. Bank `1` is the default.
## Implementation
`rosella_captured_filterbank.py` reproduces the four half-steps of the captured
`rosella_captured_filterbank.py` executes the four half-steps of the 11-tap
bank in float64/complex128:
- QMF analysis keeps a 9-slot ring history, reads `(position + tap + 1) mod 10`,
@@ -60,30 +51,16 @@ bank in float64/complex128:
- QMF synthesis keeps a 9-slot history and accumulates 10 prototype-matched
lags, taking the imaginary part on odd lags.
`data/rosella_captured_kernels.npz` stores the captured prototype
`data/rosella_captured_kernels.npz` stores the 11-tap bank's prototype
(`float32[64,10]`), rotation (`complex64[64]`) and hybrid coefficients
(`complex64[22]`); they are promoted to float64/complex128 on load. The values
are the ones the C++ core compiles in as `src/hrtf/rosella_filterbank_tables.h`
and contain no personalized HRTF or room tuning.
(`complex64[22]`); they are promoted to float64/complex128 on load and contain
no personalized HRTF or room tuning.
The startup skip and the flush capacity both come from the selected bank (961 or
448 samples). `.report.json` records the actual choice in
`binaural_renderer_backend`, as `filterbank`, `filterbank_name` and
`latency_compensated_samples`.
## Validation
The local regression script lives in `tests/`, which this repository does not
track (like the rest of its local checks). It covers:
- reference vectors for the four captured half-steps, the same samples the C++
core checks, generated by an independent NumPy implementation, to within
`1e-10` per sample;
- an impulse roundtrip peak at 961 and 448 samples for the two banks;
- chunk invariance (including zero-length and unequal chunks) and `reset()`;
- independence: processing one bank never changes the other bank's state;
- rejection of out-of-range values.
The public filterbank formulas and `.jochrtf` direction field described in
`docs/binaural.md` are unchanged; the captured bank only affects the Rosella
The public filterbank formulas and `.jochrtf` direction field are described in
`docs/binaural.md`; the 11-tap bank only affects the Rosella
path.
+9 -26
View File
@@ -3,7 +3,7 @@
[English](rosella_filterbank.en.md) · [返回 README](../README.md)
Rosella `.personalized_headphone` 路径可以在两套 64-QMF / 77-hybrid 滤波器组之间选择:
公开滤波器组(默认)与从参考渲染器捕获的 Rosella 滤波器组。SOFA 与 `.jochrtf` 路径
13-tap 公开滤波器组(默认)与 11-tap Rosella 滤波器组。SOFA 与 `.jochrtf` 路径
始终使用公开滤波器组,不经过该选择。
## 选择哪一套
@@ -21,25 +21,20 @@ QMF 合成),因此切换会同时改变系数、高频延迟、历史缓冲
flush 容量;分析与合成两级各自持有状态,互不共享。其它取值直接报错;非 Rosella
输入(SOFA、`.jochrtf`)给出该选项也报错,不会静默忽略。
## 为什么两套不同
## 两套参数
参考头戴渲染器在初始化之后的准备阶段才选定 analysis/synthesis 回调,只捕获初始化
时的回调会拿到错误的滤波器组变体。运行时缓冲捕获得到的参数是:
| 参数 | Rosella 捕获版 | 公开版 |
| 参数 | 11-tap Rosella | 13-tap 公开版 |
| --- | --- | --- |
| QMF prototype | 640 个非对称系数 | 公开 640-tap prototype 的多相重排 |
| 低频 hybrid 滤波 | 11 taps | 13 taps |
| 高频 hybrid delay | 3 slots | 6 slots |
| analysis/synthesis 延迟 | 448 samples | 961 samples |
用错变体会在 room 尾音上引入随频率变化的误差;把捕获到的 room send 作为输入时,
现有 room 递推已经能对上参考,因此修复只更换滤波器组,不改 room 系数、direct HRTF、
相位映射或输出 EQ。公开版是 `1`,捕获版是 `2`;默认保留公开版,便于与历史输出对齐。
该选项不改变 room 系数、direct HRTF、相位映射或输出 EQ。默认选择 `1`。
## 实现
`rosella_captured_filterbank.py` 用 float64/complex128 复现捕获版的四个 half-step:
`rosella_captured_filterbank.py` 用 float64/complex128 执行 11-tap 滤波器组的四个 half-step:
- QMF 分析保留 9 slot 环形历史,按 `(position + tap + 1) mod 10` 读取,输出
`spectrum[2b] = F[b]/64`、`spectrum[2b+1] = conj(F[63-b])/64`;
@@ -47,25 +42,13 @@ flush 容量;分析与合成两级各自持有状态,互不共享。其它
band 1 与 band 3 取共轭;高频带原样延迟 3 slot;
- QMF 合成保留 9 slot 历史,用 10 个 lag 的 prototype 匹配累加,奇数 lag 取虚部。
`data/rosella_captured_kernels.npz` 保存捕获版的 prototype(`float32[64,10]`)、
`data/rosella_captured_kernels.npz` 保存 11-tap 滤波器组的 prototype(`float32[64,10]`)、
rotation(`complex64[64]`)与 hybrid 系数(`complex64[22]`);载入后提升为
float64/complex128。这些数值与 C++ 内核编译进去的
`src/hrtf/rosella_filterbank_tables.h` 相同,不包含个性化 HRTF 或 room 调参。
float64/complex128,不包含个性化 HRTF 或 room 调参。
运行时的起始延迟跳过与 flush 容量都取自所选滤波器组:`961` 或 `448` samples,
`.report.json` 的 `binaural_renderer_backend` 用 `filterbank`、`filterbank_name` 与
`latency_compensated_samples` 记录实际选择。
## 验证
本地回归脚本放在 `tests/`(该目录不随仓库跟踪,与其余本地验证脚本一致),覆盖:
- 捕获版四个 half-step 的参考向量(与 C++ 内核 `tests/rosella_filterbank_vectors.h`
同一组、由独立 NumPy 实现生成),逐样本误差小于 `1e-10`;
- 两套滤波器组的脉冲往返延迟分别落在 `961` 与 `448` samples;
- 分块处理(含 0 长度与不等长切分)与 `reset()` 不变性;
- 两套滤波器组互不干扰:交叉处理一个 bank 不改变另一个 bank 的状态;
- 越界取值被拒绝。
`docs/binaural.md` 描述的公开滤波器组公式与 `.jochrtf` 方向和公开版一致;捕获版只
作用于 Rosella 路径。
`docs/binaural.md` 描述的公开滤波器组公式与 `.jochrtf` 方向和公开版一致;11-tap 版本
只作用于 Rosella 路径。