Read the OAMD trim element into speaker rendering and ADM
ci / ubuntu-latest (push) Failing after 16s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s

The OAMD parser reads the trim element: warp mode, global trim mode, the
nine per-configuration records (centre, surround and height level, the two
front-back balances) and the per-object bypass flags. OamdUpdate carries
it, so the file task and the streaming step see the same state; a payload
without the element keeps the previous controls, and an absent element
starts at warp 0 with automatic trim.

Speaker rendering reads the controls from OAMD only; neither the CLI nor
the frontends offer an override. Eligible layouts leave the floor Y alone
at warp 0 and use clamp(2Y, 0, 1) at warp 1, the height layer is never
scaled, and warp 2/3 is reported as unsupported where the speaker
consumes it. Floor, height and trim evaluation keep separate coordinates:
floor Y is balance(warp(Y)), while height Y and trim Y are balance(Y). An
explicit configuration contributes a position-dependent scalar for each
object, applied before accumulation instead of to the output channels
after the mix; automatic, disabled and explicit are mutually exclusive, and
a bypassed object keeps its warp but loses balance and trim. Automatic
still uses the layout position compensation, disabled uses unity, and
layouts without trim semantics stay disabled. LFE passes through, and ADM
source positions and binaural rendering are unchanged.

The controls travel in ejoc_speaker_controls, a C struct a future decoder
can fill without knowing the layout; the layout table now carries the
surround and height channel counts and the seven layouts that have trim
semantics. The internal ABI goes to version 3 for the new process
parameter.

The ADM writer mirrors the element into both carriers. AXML gains
DolbyAtmosMasterFile with DolbyMasterContentInfo, DolbyTrimModeSetup (one
record per configuration, zero values for a disabled one) and
DolbyWarpMode. dbmd segment 10 carries the nine 15-byte records (automatic
flag, three float32 levels and two sign-magnitude balances), and segment 9
writes the warp code into the low three bits of at[152] while keeping the
other packed fields. The task scans the first 64 audio frames for the
element, as the reference does, so a duration-limited render still writes
it.

The bilingual mathematical notes describe the configuration index, the
balance map, the three coordinates and the evaluation order; the READMEs
state that the controls come from OAMD and that warp 2/3 is refused. ctest
covers the element parse, configuration selection, warp 0/1 with the Q15
clamp, the height coordinate, explicit trim and balance, per-object
bypass, LFE passthrough, the step's metadata updates and the exact
dbmd/AXML bytes. Speaker output over the same objects16 stream is
byte-identical to the reference for the seven trimmed layouts and the
wider ones, and both ADM carriers of a rendered BWF are byte-identical to
the reference writer.

The product version goes to 1.2.0; the public ABI stays at 5.
This commit is contained in:
TheM14 committed 2026-11-03 01:34:15 +08:00
1 parent 20f2e77664
commit 58e3403642
21 files changed
+1597 -48

No files matched your search

+150 -4
View File
@@ -453,7 +453,9 @@ 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:
$$
@@ -519,7 +524,147 @@ G_{\mathrm{pos}}
\mathbf G_{\mathrm{point}}.
$$
## 12. OAMD time alignment and gain ramps
## 12. OAMD trim and front-back balance
### 12.1 Configuration selection
The OAMD trim element splits a programme's calibration data into nine
configurations, chosen by the target layout's additional horizontal speaker
count $N_f$ and height speaker count $N_h$:
$$
\kappa_f(N)=
\begin{cases}
0, & N=0,\\
1, & N\in\{2,3\},\\
2, & \text{otherwise},
\end{cases}
\qquad
\kappa_h(N)=
\begin{cases}
0, & N=0,\\
1, & N=2,\\
2, & \text{otherwise}.
\end{cases}
$$
$$
c_{\mathrm{trim}}=\kappa_f(N_f)+3\,\kappa_h(N_h).
$$
The nine configurations enumerate "no / some / many additional horizontal
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_t=1$ and $b=0$.
Warp, trim and balance controls are read from OAMD metadata:
| 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)$:
$$
a_s=\mathrm{clamp}(2y_t,0,1)(1-z),\quad a_h=z,
$$
$$
a_c=1-\mathrm{clamp}\bigl(10\max(|z|-0.05,y_t-0.05,|u-0.5|-0.05),0,1\bigr).
$$
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
Each configuration also carries two front-back balance values:
$b_{\mathrm{lis}}$ for the listener plane and $b_{\mathrm{tb}}$ for the overhead
layer. Both are quantised to a $1/16$ grid and are non-zero only in an explicit
configuration.
Writing $n=\mathrm{round}(16\,|b|)$ and $s=n/18$, the single-layer map is
$$
B_b(y)=
\begin{cases}
y, & y\le 0.05\ \text{or}\ y\ge 0.95,\\[2pt]
(1+s)y-0.05s, & 0.05<y<0.5,\ b>0,\\[2pt]
(1-s)(y-0.5)+0.5+0.45s, & 0.5\le y<0.95,\ b>0,\\[2pt]
(1-s)y+0.05s, & 0.05<y<0.5,\ b<0,\\[2pt]
(1+s)(y-0.5)+0.5-0.45s, & 0.5\le y<0.95,\ b<0.
\end{cases}
$$
It maps $[0.05,0.95]$ monotonically onto itself: the two walls stay fixed, the
two halves meet at $y=0.5$, and their slopes are $1+s$ and $1-s$. The 5 percent
wall bands and the case $b=0$ pass through unchanged, so the map never leaves
the interval and needs no extra clamp.
The height $w$ blends the two layers:
$$
y'=(1-w)\,B_{b_{\mathrm{lis}}}(y)+w\,B_{b_{\mathrm{tb}}}(y).
$$
The front-back axis $y$ is oriented as in §9, with $0$ at the front wall and
$1$ at the back wall; $x$ and $z$ are unchanged.
### 12.4 Where it is applied
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_f=B_z(W(y)),\qquad y_h=B_z(y),\qquad y_t=B_z(y).
$$
Floor and height panning use $y_f,y_h$; trim evaluation uses $y_t$. The final gain is
$$
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
The coded position of an OAMD update is
@@ -575,7 +720,7 @@ $$
If no new metadata update intervenes, this is equivalent to a sample-wise linear ramp of total length $KB$.
## 13. Final speaker mix
## 14. Final speaker mix
For target output channel $c$:
@@ -607,9 +752,10 @@ y_{24}[n]=
\right).
$$
## 14. Scope of the formulas
## 15. Scope of the formulas
- The JOC matrix section covers both the dense MTX and the sparse IDX/VEC differential syntax.
- The speaker-panning section describes ordinary point objects; extent, spread, divergence, and similar modes require additional models.
- Multiple OAMD position blocks must be scheduled in time order.
- A limiter is separate post-processing and is not included in the mixing equations above.
- Trim and front-back balance affect speaker rendering only; binaural rendering does not read them.
+136 -4
View File
@@ -450,7 +450,9 @@ 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$ 为相关附加水平扬声器数:
$$
@@ -516,7 +521,133 @@ G_{\mathrm{pos}}
\mathbf G_{\mathrm{point}}.
$$
## 12. OAMD 时间对齐与增益斜坡
## 12. OAMD trim 与前后平衡
### 12.1 配置选择
OAMD trim element 把节目的校准数据分成九个配置,由目标布局的附加水平扬声器数
$N_f$ 与高度扬声器数 $N_h$ 选定:
$$
\kappa_f(N)=
\begin{cases}
0, & N=0,\\
1, & N\in\{2,3\},\\
2, & \text{其他},
\end{cases}
\qquad
\kappa_h(N)=
\begin{cases}
0, & N=0,\\
1, & N=2,\\
2, & \text{其他}.
\end{cases}
$$
$$
c_{\mathrm{trim}}=\kappa_f(N_f)+3\,\kappa_h(N_h).
$$
九个配置依次为“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_t=1$、$b=0$。
warp、trim 和 balance 均从 OAMD 元数据读取。各参数的取值与作用为:
| 参数 | 取值或单位 | 行为 |
|---|---|---|
| `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)$:
$$
a_s=\mathrm{clamp}(2y_t,0,1)(1-z),\qquad a_h=z,
$$
$$
a_c=1-\mathrm{clamp}\bigl(10\max(|z|-0.05,\ y_t-0.05,\ |u-0.5|-0.05),0,1\bigr).
$$
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$ 网格量化,只在显式配置下非零。
记 $n=\mathrm{round}(16\,|b|)$、$s=n/18$,单层映射为
$$
B_b(y)=
\begin{cases}
y, & y\le 0.05\ \text{或}\ y\ge 0.95,\\[2pt]
(1+s)y-0.05s, & 0.05<y<0.5,\ b>0,\\[2pt]
(1-s)(y-0.5)+0.5+0.45s, & 0.5\le y<0.95,\ b>0,\\[2pt]
(1-s)y+0.05s, & 0.05<y<0.5,\ b<0,\\[2pt]
(1+s)(y-0.5)+0.5-0.45s, & 0.5\le y<0.95,\ b<0.
\end{cases}
$$
它把 $[0.05,0.95]$ 单调映到自身:两端不动,$y=0.5$ 处两段取值相同,斜率分别为
$1+s$ 与 $1-s$。首尾各 $5\%$ 的墙区以及 $b=0$ 的情形都原样通过,因此映射不会
越界,也无需额外钳位。
高度 $w$ 把两层混合起来:
$$
y'=(1-w)\,B_{b_{\mathrm{lis}}}(y)+w\,B_{b_{\mathrm{tb}}}(y).
$$
前后轴 $y$ 的取向见 §9,$0$ 为前、$1$ 为后;$x$ 与 $z$ 不变。
### 12.4 施加位置
记 §12.3 的高度混合 balance 映射为 $B_z(y)$,§10.2 的 warp 映射为 $W(y)$。
普通点对象的实际分支顺序为
$$
y_f=B_z(W(y)),\qquad y_h=B_z(y),\qquad y_t=B_z(y).
$$
地面和高度声像分别使用 $y_f,y_h$,trim 函数使用 $y_t$。最后组合
$$
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 时间对齐与增益斜坡
OAMD 更新的编码位置为
@@ -572,7 +703,7 @@ $$
如果中途没有新的 metadata 更新,该过程等价于总长度 $KB$ 的逐样本线性斜坡。
## 13. 最终扬声器混音
## 14. 最终扬声器混音
对目标输出声道 $c$:
@@ -604,9 +735,10 @@ y_{24}[n]=
\right).
$$
## 14. 公式适用范围
## 15. 公式适用范围
- JOC 矩阵部分同时描述 dense MTX 与 sparse IDX/VEC 两条差分语法。
- 扬声器声像部分描述普通点对象;extent、spread、divergence 等模式需要额外模型。
- 多个 OAMD position block 必须按其时间顺序调度。
- limiter 属于独立后处理,不包含在上述混音公式中。
- trim 与前后平衡只作用于扬声器渲染;双耳渲染不读取它们。