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

+6 -6
View File
@@ -2,11 +2,11 @@
[中文版](README.md)
> JustOneCacophony is an experimental/test implementation of E-AC-3 JOC for studying JOC parsing, reconstruction, rendering, and the associated mathematics.
> JustOneCacophony implements E-AC-3 JOC parsing, object reconstruction and rendering.
The project can extract and parse EMDF, ID14 JOC parameters, and ID11 OAMD metadata from common E-AC-3 JOC streams. It combines those data with the core PCM decoded by FFmpeg (N=5 or 7 full-band channels), reconstructs LFE plus 15 object channels, and writes ADM BWF, a WAV file for a selected speaker layout, or binaural stereo (a Rosella personalized model, or a compiled `.jochrtf`).
This is research code, not a complete, standards-compliant, or production-grade JOC decoder. It covers only the stream forms currently implemented. Unknown variants fail explicitly—because when the math goes wrong, all that may remain is the cacophony.
It covers the currently implemented stream forms. Unknown variants fail explicitly.
## Current features
@@ -225,12 +225,12 @@ 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 /
- `2`: the 11-tap Rosella bank, 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.
parameters, buffers and latency of both banks.
For all options:
@@ -238,7 +238,7 @@ For all options:
python main.py --help
```
Without `-o`, output still goes to `output/` at the repository root. The directory move intentionally preserves this behavior.
Without `-o`, output goes to `output/` at the repository root.
## Speaker layouts and channel order
@@ -312,7 +312,7 @@ See the [mathematical notes](docs/math.en.md) for the equations used by the deco
- The extra pair's identity follows TS 103 420 Table 47/Table 48 ($k=1\to$Lb/Rb, $k\in\{2,4\}\to$Tfl/Tfr, $N=5,7,7,5,7$); Annex E.3 requires a dependent-substream `chanmap`, when present, to indicate one of the Table 47 configurations, so `*_5_1_2top_*` (chanmap says Lts/Rts) does not satisfy that "shall". Such material is tolerated with a diagnostic instead of being refused.
- An audio frame with no JOC EMDF at all (for example when the encoder wrote none for the first frame) emits silent object channels and is recorded in the `[diagnostics]` line and the JSON report's `diagnostics` field.
- The speaker and SOFA binaural paths currently cover ordinary point objects; extent, spread, diffuse, divergence, channel lock, and similar controls are outside the supported scope.
- OAMD trim elements are boundary-checked and skipped; warp, balance, and trim parameters are not applied to raw object trajectories or speaker rendering.
- Speaker rendering reads warp 0/1, trims and front/back balance from OAMD, with no CLI warp override. Modes 2/3 are explicitly unsupported. Source trajectories and binaural remain free of these speaker controls; see [mathematics §12](docs/math.en.md) for parameters and evaluation order.
- Multi-data-point streams, uncommon band configurations, and unusual OAMD scheduling have less coverage than common 12-band, single-data-point material.
- `joc_clipgain` is folded into the **analysis-side scalar** (`scalar = 1/16 x g`, with `g` from the
`x:3 | y:5` field), so the x16 at the output cancels the 1/16 and the clamp sits **after** the gain.
+6 -6
View File
@@ -2,11 +2,11 @@
[English](README.en.md)
> JustOneCacophony 是一个 E-AC-3 JOC 的实验性 / 测试实现,用于研究 JOC 的解析、重建、渲染以及相关数学过程。
> JustOneCacophony 实现 E-AC-3 JOC 的解析、对象重建与渲染。
项目可以从常见 E-AC-3 JOC 码流中提取并解析 EMDF、ID14 JOC 参数和 ID11 OAMD 元数据,结合 FFmpeg 解码出的核心 PCM(N=5 或 7 个全频段通道)重建 LFE 与 15 路对象 PCM,并输出 ADM BWF、指定扬声器布局的 WAV,或输出双耳 WAV(Rosella 个性化模型,或已编译的 `.jochrtf`)。
这是研究代码,不是完整、标准兼容或生产级的 JOC 解码器。它只覆盖当前已实现的码流形态;遇到未知变体时会明确报错,而不是假装一切都很和谐——如果哪里算错了,它可能就真的只剩 cacophony 了。
当前覆盖已实现的码流形态;遇到未知变体时明确报错。
## 当前功能
@@ -193,11 +193,11 @@ outer subpayload offset 与 block offset 落到绝对 sample timeline,再加
`--rosella-filterbank 1|2` 选择 `.personalized_headphone` 路径使用的滤波器组:
- `1`(默认):公开滤波器组,13-tap hybrid / 6-slot 高频延迟,961 samples 延迟;
- `2`:从参考渲染器捕获的 Rosella 滤波器组,11-tap hybrid / 3-slot 高频延迟,
- `2`:11-tap Rosella 滤波器组,11-tap hybrid / 3-slot 高频延迟,
448 samples 延迟。
该选项只作用于 Rosella 模型;SOFA 与 `.jochrtf` 路径给出时报错。两套实现的参数、
缓冲、延迟与验证见 [Rosella 滤波器组](docs/rosella_filterbank.md)。
缓冲与延迟见 [Rosella 滤波器组](docs/rosella_filterbank.md)。
更多参数可查看:
@@ -205,7 +205,7 @@ outer subpayload offset 与 block offset 落到绝对 sample timeline,再加
python main.py --help
```
未指定 `-o` 时,输出仍写入仓库根目录的 `output/`。这是文件移动后特意保持的原有行为。
未指定 `-o` 时,输出写入仓库根目录的 `output/`。
## 扬声器布局与声道顺序
@@ -274,7 +274,7 @@ JustOneCacophony/
- 额外那一对的身份以 TS 103 420 Table 47/Table 48 为准($k=1\to$Lb/Rb,$k\in\{2,4\}\to$Tfl/Tfr,$N=5,7,7,5,7$);Annex E.3 规定依赖子流的 `chanmap`(若存在)**应**指明 Table 47 的某种配置,因此 `*_5_1_2top_*`(chanmap 写 Lts/Rts)属于不满足 "shall" 的素材,我们按"记诊断 + 继续解码"容错处理。
- 音频帧内没有任何 JOC EMDF 时(例如编码器未写首帧元数据),该帧的对象通道静音,并在 stderr 的 `[diagnostics]` 与 JSON 报告的 `diagnostics` 里记一笔。
- 扬声器与 SOFA 双耳路径当前只覆盖普通点对象;extent、spread、diffuse、divergence、channel lock 等对象控制不在支持范围内。
- OAMD trim element 会按声明边界校验并跳过;warp、balance 和 trim 参数不应用于当前原始对象轨迹或扬声器渲染。
- 扬声器渲染从 OAMD 元数据读取 warp 0/1、trim 和 front/back balance;命令行不提供 warp 覆盖。warp 2/3 暂未实现,遇到时明确报错。原始对象轨迹与 binaural 不预烘焙这些扬声器控制,参数和顺序见 [数学说明 §12](docs/math.md)。
- 多数据点、少见参数带配置和特殊 OAMD 调度的覆盖度低于常见 12-band、单数据点素材。
- `joc_clipgain` 在**分析端**并入分析标量:`标量 = 1/16 × g`(`g = 1 + (y/32)·2^(x−4)`),出口的
×16 抵消 1/16,净效果是 `×g`,clamp 因此处在增益**之后**。标量按帧保存两个槽(上一帧值 → 本帧值),
+4 -8
View File
@@ -72,10 +72,9 @@ $$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
### 11-tap Rosella filterbank
`rosella_captured_kernels.npz` holds the bank the reference headphone renderer
actually runs (`--rosella-filterbank 2`):
`rosella_captured_kernels.npz` holds the bank selected by `--rosella-filterbank 2`:
```text
format_version little-endian int32[1]
@@ -85,11 +84,8 @@ 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.
analysis/synthesis latency is 448 samples (961 for the public bank). This file
contains no personalized HRTF or room tuning.
Public availability of a standard does not by itself grant permission to
practice related patent claims.
+3 -6
View File
@@ -64,10 +64,9 @@ $$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 捕获版滤波器组
### 11-tap Rosella 滤波器组
`rosella_captured_kernels.npz` 保存参考头戴渲染器实际运行的那套滤波器组
(`--rosella-filterbank 2`):
`rosella_captured_kernels.npz` 保存 `--rosella-filterbank 2` 使用的滤波器组:
```text
format_version little-endian int32[1]
@@ -77,9 +76,7 @@ hybrid complex64[22]
```
表值载入后提升为 float64/complex128;全链 latency 为 448 samples(公开版为 961)。
这些数值来自参考渲染器的运行时缓冲捕获,不是上述公开标准的推导值;C++ 内核以
`src/hrtf/rosella_filterbank_tables.h` 的形式内置同一组数据。文件同样不含个性化
HRTF 或 room 调参。
文件不含个性化 HRTF 或 room 调参。
标准可公开获取不等于获准实施相关专利。
+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 路径。
+15
View File
@@ -209,6 +209,18 @@ def _balance_byte(value):
return magnitude | (0x80 if value < 0 else 0)
def warp_mode(atmos_meta):
"""OAMD trim element 的 ``warp_mode`` → 下混模式码。
dbmd 的 warp 字段、ADM 的 ``DolbyWarpMode`` 和 DAMF 的 ``WarpMode`` 共用
一套编号:0 normal、1 warping、2 downmix_pl2x、3 downmix_loro,4 表示未
指定。来源只有 2 bit 的 OAMD 字段,因此取值落在 0..3。
"""
if not atmos_meta:
return 0
return max(0, min(3, int(atmos_meta.get("warp_mode", 0))))
def build_dbmd(object_count=25, joc_binaural_mode=4, atmos_meta=None):
"""segment 10:9 个 trim 配置 + 逐轨 bypass + JOC object slots 10..24 的 mode。
@@ -233,6 +245,9 @@ def build_dbmd(object_count=25, joc_binaural_mode=4, atmos_meta=None):
at[103] = 0x03
at[106] = 0x01
at[111] = 0x22; at[112] = 0xFF
# at[152] 高 2 位是 bed_distribution、低 3 位是 warp;这里只写 warp,
# 其余位保持模板原值。
at[152] = (at[152] & 0xF8) | warp_mode(atmos_meta)
out.append(9); out += struct.pack("<H", 248); out += bytes(at)
out.append(_checksum(at))
ob = bytearray(5 + 262 + object_count)
+2 -2
View File
@@ -173,8 +173,8 @@ def main():
import argparse
ap = argparse.ArgumentParser()
ap.add_argument("files", nargs="+")
ap.add_argument("--axml-file", default=None, help="用该文件内容替换 wav 内 axml(对照实验)")
ap.add_argument("--chna-file", default=None, help="用该文件内容替换 wav 内 chna(对照实验)")
ap.add_argument("--axml-file", default=None, help="用该文件内容替换 wav 内 axml")
ap.add_argument("--chna-file", default=None, help="用该文件内容替换 wav 内 chna")
a = ap.parse_args()
ax_o = open(a.axml_file, "rb").read() if a.axml_file else None
ch_o = open(a.chna_file, "rb").read() if a.chna_file else None
+4 -4
View File
@@ -391,8 +391,8 @@ def _parse_trim_element(reader, object_count, raw_payload):
"configs": [None] * 9,
"disable_per_obj": None,
}
# global_trim_mode == 2 才携带 9 个配置的显式数据;其余取值表示内容
# 把 trim 交给渲染器自行推导(auto)。
# global_trim_mode: 0 自动、1 禁用、2 按配置显式指定、3 保留。
# 只有 2 才携带下面九个配置的显式数据。
if trim["global_trim_mode"] == 2:
for config in range(9):
if reader.read(1): # b_default_trim
@@ -731,7 +731,7 @@ def frame_update(bits_one, *, retain_spatial=False):
x, y, z = position
out[(slot, "q1")] = q_of(x, N_Q12) if 0 <= x <= N_Q12 else None
out[(slot, "q2")] = q_of(y, N_Q12) if 0 <= y <= N_Q12 else None
# Preserve legacy nonnegative height unless signed spatial output is requested.
# Clamp negative height to zero unless signed spatial output is requested.
out[(slot, "q3")] = q_of(z, N_Q3) if (0 <= z <= N_Q3 or retain_spatial and -N_Q3 <= z < 0) else (
0 if z < 0 else None)
@@ -773,7 +773,7 @@ def frame_update_values(bits_one):
class JocFieldState:
"""未更新/非法窗保持旧值;slot0 q1/q2 的 DLL 初值为中心 16384。"""
"""未更新/非法窗保持旧值;slot0 q1/q2 初始为中心 16384。"""
def __init__(self):
self.q = {(obj, field): 0 for obj in range(16)
+3 -5
View File
@@ -16,7 +16,7 @@ class DistanceState:
class ReferenceDistanceProfileV1:
"""Reference behavior, not a claim about any external public standard."""
"""Near/Mid/Far distance presets with energy-normalized dry/room mixing."""
DISTANCE_M = {
"near": 1.00000465,
@@ -24,10 +24,8 @@ class ReferenceDistanceProfileV1:
"far": 6.40177584,
}
MINIMUM_DISTANCE_M = 0.10
# Distance profiles in the reference renderer are presentation presets,
# not an instruction to attenuate already-authored programme PCM by 1/r.
# Use an energy-normalized dry/room crossfade instead. The coefficient is
# an explicit project calibration target.
# Distance presets use an energy-normalized dry/room crossfade without
# applying 1/r attenuation to the programme PCM.
ROOM_ENERGY_COUPLING_PER_M2 = 0.01318359375
PUBLIC_ROOM_CALIBRATION_GAIN = 1.4
# Public, project-owned room coupling; it is not a SOFA or Dolby constant.
+2 -4
View File
@@ -5,12 +5,10 @@ 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.
latency.
``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.
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.
+6 -14
View File
@@ -1,16 +1,8 @@
"""Captured Rosella 64-QMF / 77-hybrid filterbank.
"""Rosella 64-QMF / 77-hybrid filterbank with an 11-tap hybrid analysis.
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.
Uses a 640-coefficient QMF prototype, a 3-slot high-band delay and a 448-sample
analysis/synthesis latency. Tables in ``data/rosella_captured_kernels.npz`` are
loaded as float64/complex128; processing state uses the same precision.
"""
from __future__ import annotations
@@ -30,7 +22,7 @@ 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 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.
@@ -65,7 +57,7 @@ def _load_tables(path_string: str) -> dict[str, np.ndarray]:
def load_kernel_tables(path: str | Path = DEFAULT_CAPTURED_KERNEL_DATA
) -> dict[str, np.ndarray]:
"""Load and cache the captured Rosella kernel tables."""
"""Load and cache the 11-tap Rosella bank's kernel tables."""
return _load_tables(str(Path(path).expanduser().resolve()))
+4 -2
View File
@@ -12,15 +12,17 @@ FRAME_SAMPLES = 1536
def create_speaker_renderer(layout: str | SpeakerLayout, bed_channels=None,
trim_meta=None):
trim_meta=None, *, parameters=None):
"""Create a stateful speaker renderer and return ``(renderer, info)``."""
target = get_speaker_layout(layout) if isinstance(layout, str) else layout
renderer = PythonSpeakerRenderer(target, bed_channels=bed_channels,
trim_meta=trim_meta)
trim_meta=trim_meta, parameters=parameters)
return renderer, {
"name": "python",
"layout": target.name,
"bed_objects": len(getattr(renderer, "bed_targets", {}) or {}),
"initial_warp_mode": renderer.parameters.warp_mode,
"initial_trim_mode": renderer.parameters.trim_mode,
}
+45 -18
View File
@@ -12,9 +12,10 @@ from typing import Iterable
import numpy as np
from oamd_bits import JocFieldState, frame_update
from oamd_bits import JocFieldState, frame_update, parse_trim
from speaker_layouts import RegionGeometry, SpeakerLayout, get_speaker_layout
from trim_balance import apply_balance, balance_layers, channel_gains
from trim_balance import (SpeakerRenderParameters, apply_balance,
explicit_position_gain, parameters_from_oamd)
Q15_SCALE = 32768.0
Q15_MAX = 32767.0 / Q15_SCALE
@@ -35,9 +36,9 @@ def bed_object_targets(bed_channels) -> dict[int, tuple[float, float, float]]:
def _all_object_targets(layout: SpeakerLayout, state: JocFieldState,
bed_targets=None, balance=(0.0, 0.0)) -> np.ndarray:
bed_targets=None, parameters=None) -> np.ndarray:
bed_targets = bed_targets or {}
listener, overhead = balance
parameters = parameters or parameters_from_oamd(None, layout)
result = np.zeros((15, layout.channel_count), dtype=np.float64)
for object_index in range(1, 16):
fixed = bed_targets.get(object_index)
@@ -47,9 +48,9 @@ def _all_object_targets(layout: SpeakerLayout, state: JocFieldState,
u = state.q[(object_index, "q1")] / Q15_SCALE
v = state.q[(object_index, "q2")] / Q15_SCALE
w = state.q[(object_index, "q3")] / Q15_SCALE
v = apply_balance(v, w, listener, overhead)
result[object_index - 1] = render_point_gains(
layout, u, v, w, standard_order=False)
layout, u, v, w, standard_order=False, parameters=parameters,
bypass_trim=parameters.bypasses(object_index))
return result
@@ -175,16 +176,30 @@ def _plane_gains(region: RegionGeometry, coordinates: np.ndarray, groups,
def render_point_gains(layout: str | SpeakerLayout, u: float, v: float, w: float,
*, region_index: int = 0, enable_height: bool = True,
object_gain: float = 1.0, standard_order: bool = True) -> np.ndarray:
object_gain: float = 1.0, standard_order: bool = True,
parameters: SpeakerRenderParameters | None = None,
bypass_trim: bool = False) -> np.ndarray:
"""Render one point object to a target speaker layout using float64."""
target = get_speaker_layout(layout) if isinstance(layout, str) else layout
controls = parameters or parameters_from_oamd(None, target)
region = target.regions[int(region_index)]
coordinates = _coordinates(region)
floor_v = min(max(math.ldexp(float(v), floor_y_exponent(target.speaker_bitfield)), 0.0), 1.0)
v, w = float(v), max(float(w), 0.0)
floor_v = min(max(math.ldexp(v, floor_y_exponent(
target.speaker_bitfield, controls.warp_mode == 1)), 0.0), 1.0)
top_v = min(max(v, 0.0), 1.0)
trim_v = v
if controls.trim_mode == "explicit" and not bypass_trim:
# Apply warp -> balance for floor, balance(original Y) for
# top and trim. These coordinates must not be collapsed into one Y.
listener, overhead = controls.listener_balance, controls.overhead_balance
floor_v = apply_balance(floor_v, w, listener, overhead)
top_v = apply_balance(top_v, w, listener, overhead)
trim_v = apply_balance(v, w, listener, overhead)
floor = _plane_gains(region, coordinates, region.axis0_groups, u, floor_v, region.mode)
point_gains = floor
if region.mode == 3:
top = _plane_gains(region, coordinates, region.axis1_groups, u, float(v), 3)
top = _plane_gains(region, coordinates, region.axis1_groups, u, top_v, 3)
height = min(max(float(w) if enable_height else 0.0, 0.0), Q15_MAX)
if height >= Q15_MAX:
point_gains = top
@@ -192,7 +207,12 @@ def render_point_gains(layout: str | SpeakerLayout, u: float, v: float, w: float
floor_weight, height_weight = equal_power_pair(height)
point_gains = floor * floor_weight + top * height_weight
internal = np.zeros(target.channel_count, dtype=np.float64)
gain = position_gain(target.speaker_bitfield, v, w) * float(object_gain)
gain = float(object_gain)
if not bypass_trim:
if controls.trim_mode == "automatic":
gain *= position_gain(target.speaker_bitfield, trim_v, w)
elif controls.trim_mode == "explicit":
gain *= explicit_position_gain(controls, u, trim_v, w)
for point_gain, speaker_id in zip(point_gains, region.speaker_ids):
internal[speaker_id] = point_gain * gain
if standard_order:
@@ -213,18 +233,20 @@ class PythonSpeakerRenderer:
"""Stateful float64 speaker renderer."""
def __init__(self, layout: str | SpeakerLayout, block_size: int = 32,
bed_channels=None, trim_meta=None):
bed_channels=None, trim_meta=None, *, parameters=None):
self.layout = get_speaker_layout(layout) if isinstance(layout, str) else layout
self.block_size = int(block_size)
if self.block_size <= 0:
raise ValueError("block_size must be positive")
self.bed_targets = bed_object_targets(bed_channels)
self.trim_gains = np.asarray(channel_gains(trim_meta, self.layout),
dtype=np.float64)
self.balance = balance_layers(trim_meta, self.layout)
if parameters is not None and trim_meta is not None:
raise ValueError("pass normalized parameters or OAMD trim_meta, not both")
self._parameters_override = parameters
self._initial_parameters = parameters or parameters_from_oamd(trim_meta, self.layout)
self.reset()
def reset(self):
self.parameters = self._initial_parameters
channels = self.layout.channel_count
self._state = JocFieldState()
self._current = np.zeros((15, channels), dtype=np.float64)
@@ -235,9 +257,13 @@ class PythonSpeakerRenderer:
def _apply_payload(self, payload):
update = frame_update(payload)
if self._parameters_override is None:
trim = parse_trim(payload)
if trim is not None:
self.parameters = parameters_from_oamd(trim, self.layout)
self._state.apply(update["values"])
new_target = _all_object_targets(self.layout, self._state, self.bed_targets,
self.balance)
self.parameters)
blocks = ramp_block_count(update["ramp_duration_samples"], self.block_size)
difference = new_target - self._current
significant = np.abs(difference) >= GAIN_SNAP_THRESHOLD
@@ -306,7 +332,6 @@ class PythonSpeakerRenderer:
for payload in events_by_block.get(total_blocks, ()):
self._apply_payload(payload)
output *= self.trim_gains[None, :]
if standard_order:
return output[:, list(self.layout.internal_to_standard)]
return output
@@ -321,9 +346,11 @@ class PythonSpeakerRenderer:
def render_objects16(objects16: np.ndarray, payload_events: Iterable[tuple[int, bytes]],
layout: str | SpeakerLayout, *, block_size: int = 32,
standard_order: bool = True, output: np.ndarray | None = None) -> np.ndarray:
standard_order: bool = True, output: np.ndarray | None = None,
trim_meta=None, parameters=None) -> np.ndarray:
"""Render a complete interleaved LFE + 15 object stream."""
renderer = PythonSpeakerRenderer(layout, block_size=block_size)
renderer = PythonSpeakerRenderer(layout, block_size=block_size,
trim_meta=trim_meta, parameters=parameters)
return renderer.process(objects16, payload_events, standard_order=standard_order, output=output)
def payload_events_from_index(index, frame_count: int, *, frame_samples: int = 1536,
+96 -1
View File
@@ -24,6 +24,11 @@ the axis and it leaves the two walls untouched. See ``front_back``.
"""
from __future__ import annotations
from dataclasses import dataclass
import math
from variant_error import UnsupportedVariantError
# Layouts that carry trim and front-back balance semantics, by their compact
# names: 2.0, 3.1, 4.0, 5.1, 5.1.2, 5.1.4 and 7.1. Wider layouts leave the
# programme untrimmed.
@@ -49,6 +54,93 @@ BALANCE_STEPS = 16
WALL = 0.05
@dataclass(frozen=True)
class SpeakerRenderParameters:
"""Codec-independent, per-layout speaker controls; balances are in [-1,1].
Warp 2/3 intentionally have no rendering implementation yet. An absent
warp indication uses normal (0); no CLI override is provided.
"""
warp_mode: int = 0
trim_mode: str = "automatic"
surround_db: float = 0.0
height_db: float = 0.0
centre_db: float = 0.0
listener_balance: float = 0.0
overhead_balance: float = 0.0
disable_per_object: tuple[bool, ...] = ()
def __post_init__(self):
if self.warp_mode in (2, 3):
raise UnsupportedVariantError(
"speaker", "warp_mode_not_implemented",
"Speaker rendering implements warp modes 0/1 only; 2/3 are reserved in E-AC-3 JOC",
details={"warp_mode": self.warp_mode})
if self.warp_mode not in (0, 1):
raise ValueError(f"invalid warp mode: {self.warp_mode!r}")
if self.trim_mode not in ("automatic", "disabled", "explicit"):
raise ValueError(f"invalid trim mode: {self.trim_mode!r}")
for value in (self.surround_db, self.height_db, self.centre_db):
if not math.isfinite(value):
raise ValueError("trim levels must be finite")
for value in (self.listener_balance, self.overhead_balance):
if not math.isfinite(value) or not -1.0 <= value <= 1.0:
raise ValueError("balance must be finite and in [-1,1]")
def bypasses(self, object_index):
return (0 <= object_index < len(self.disable_per_object)
and self.disable_per_object[object_index])
def parameters_from_oamd(atmos_meta, layout):
"""Adapt OAMD calibration to one layout, without changing source positions.
A config's default/disabled flag overrides global custom mode. Missing
custom configuration falls back to automatic.
"""
meta = atmos_meta or {}
common = dict(warp_mode=meta.get("warp_mode", 0),
disable_per_object=tuple(meta.get("disable_per_obj") or ()))
if not _supported(layout):
return SpeakerRenderParameters(**common, trim_mode="disabled")
mode = meta.get("global_trim_mode", 0)
if mode == 1:
return SpeakerRenderParameters(**common, trim_mode="disabled")
if mode not in (0, 1, 2):
raise UnsupportedVariantError(
"speaker", "trim_mode_not_implemented", "Reserved OAMD global trim mode",
details={"global_trim_mode": mode})
record = _record(meta, layout) if mode == 2 else None
if not isinstance(record, dict) or record.get("default"):
return SpeakerRenderParameters(**common)
if record.get("disabled"):
return SpeakerRenderParameters(**common, trim_mode="disabled")
# Surround/height are attenuation-only. Centre retains its signed level.
return SpeakerRenderParameters(
**common, trim_mode="explicit",
surround_db=min(float(record.get("surround", 0.0)), 0.0),
height_db=min(float(record.get("height", 0.0)), 0.0),
centre_db=float(record.get("centre", 0.0)),
listener_balance=float(record.get("bal3d_y_lis", 0.0)),
overhead_balance=float(record.get("bal3d_y_tb", 0.0)))
def explicit_position_gain(parameters, x, y, z):
"""Position-dependent *object* trim, evaluated at balance(original Y).
Surround fades in over Y=0..0.5 and out towards Z=1; height fades in
with Z. Centre trim is local to the front-centre region. The resulting
scalar multiplies the object's entire speaker gain vector, before mixing.
"""
surround = min(max(2.0 * y, 0.0), 1.0) * (1.0 - z)
centre = 1.0 - min(max(10.0 * max(
abs(z) - WALL, y - WALL, abs(x - 0.5) - WALL), 0.0), 1.0)
db = (surround * min(parameters.surround_db, 0.0)
+ z * min(parameters.height_db, 0.0)
+ centre * parameters.centre_db)
return 10.0 ** (db / 20.0)
def _height_class(count):
if count == 0:
return 0
@@ -106,7 +198,10 @@ def group_levels_db(atmos_meta, layout):
def channel_gains(atmos_meta, layout):
"""Per-channel linear gain for the layout, in channel order."""
"""Legacy diagnostic group levels, not the speaker rendering operation.
Rendering uses explicit_position_gain per object before accumulation.
"""
levels = group_levels_db(atmos_meta, layout)
gains = []
for label in getattr(layout, "channels", ()):