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

+1
View File
@@ -123,6 +123,7 @@ set(JOC_INTERNAL_SOURCES
src/oamd/oamd_parser.cpp
src/speaker/speaker_layout_lookup.cpp
src/speaker/speaker_step.cpp
src/speaker/speaker_trim.cpp
src/stream/stream.cpp
src/task/task.cpp
src/telemetry/event_bus.cpp
+6
View File
@@ -143,6 +143,12 @@ downstream player recognises Dolby speaker positions on its own.
`--speaker-layout` accepts only the eleven names in the table; anything else fails as an unknown
layout.
Speaker rendering reads warp 0/1, trim and front/back balance from the OAMD metadata; the CLI
has no warp override, and warp 2/3 is reported as unsupported at render time. Trim and balance
apply to the 2.0, 3.1, 4.0, 5.1, 5.1.2, 5.1.4 and 7.1 layouts. Source trajectories and binaural
rendering do not pre-apply these controls; see [mathematics §12](docs/math.en.md) for the
parameters and evaluation order.
## Library integration
The engine and the file task are exposed by `joc_core.h`: `joc_task_validate` /
+5
View File
@@ -124,6 +124,11 @@ PCM 声道顺序严格按上表,不按掩码位序重排。播放器、ASIO、
`--speaker-layout` 只接受上表 11 个名字;其它名字按未知布局报错。
扬声器渲染从 OAMD 元数据读取 warp 0/1、trim 和 front/back balance;命令行不提供 warp
覆盖,warp 2/3 在渲染时明确报错。trim 与 balance 只施加于 2.0、3.1、4.0、5.1、5.1.2、
5.1.4 和 7.1 这七种布局。原始对象轨迹与双耳渲染不预先应用这些控制,参数与求值顺序见
[数学说明 §12](docs/math.md)。
## 库集成
引擎与文件任务使用 `joc_core.h`:`joc_task_validate` / `joc_task_execute` 跑一个文件任务并
+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 与前后平衡只作用于扬声器渲染;双耳渲染不读取它们。
+41 -1
View File
@@ -23,7 +23,7 @@ extern "C" {
#endif
enum {
EJOC_ABI_VERSION = 2,
EJOC_ABI_VERSION = 3,
EJOC_FRAME_SAMPLES = 1536,
EJOC_TIMESLOTS = 24,
EJOC_SUBBANDS = 64,
@@ -35,6 +35,7 @@ enum {
EJOC_MAX_PARAMETER_BANDS = 23,
EJOC_SPEAKER_BLOCK_SAMPLES = 32,
EJOC_SPEAKER_COORDINATES = 3,
EJOC_SPEAKER_CONTROLS_VERSION = 1,
EJOC_BINAURAL_BLOCK_SAMPLES = 512,
EJOC_BINAURAL_INPUT_CHANNELS = 16,
EJOC_BINAURAL_OUTPUT_CHANNELS = 2,
@@ -123,6 +124,44 @@ metadata_offsets must be nondecreasing and <= sample_count. sample_count must
be a multiple of EJOC_SPEAKER_BLOCK_SAMPLES. State and unfinished ramps are
preserved across calls.
*/
/*
Per-object speaker controls taken from OAMD metadata: warp mode, trim mode,
the three trim levels and the two front-back balances. trim_bypass is indexed
by object slot (1..15); slot 0 carries the LFE and is unused.
warp_mode 0 leaves the floor Y coordinate unchanged; mode 1 maps it through
clamp(2Y, 0, 1). warp modes 2 and 3 have no speaker implementation and are
rejected by the caller that builds this structure.
trim_mode selects where the gain comes from: automatic applies the layout
position compensation, disabled applies no trim, and explicit applies the
position-dependent trim from centre_db / surround_db / height_db. A bypassed
object keeps its warp but loses the balance and the trim gain.
Controls may change between calls; each call's metadata events use the
controls passed with that call. A null pointer means warp 0, no trim and no
balance.
*/
typedef enum ejoc_speaker_trim_mode {
EJOC_SPEAKER_TRIM_AUTOMATIC = 0,
EJOC_SPEAKER_TRIM_DISABLED = 1,
EJOC_SPEAKER_TRIM_EXPLICIT = 2
} ejoc_speaker_trim_mode;
typedef struct ejoc_speaker_controls {
uint32_t struct_size;
uint32_t struct_version;
uint32_t warp_mode;
uint32_t trim_mode; /* ejoc_speaker_trim_mode */
double centre_db;
double surround_db; /* positive values are treated as zero */
double height_db; /* positive values are treated as zero */
double listener_balance; /* [-1, 1] */
double overhead_balance; /* [-1, 1] */
uint8_t trim_bypass[EJOC_MAX_OBJECTS + 1]; /* per object slot, slot 0 unused */
} ejoc_speaker_controls;
EJOC_API uint32_t EJOC_CALL ejoc_speaker_layout_channel_count(uint32_t speaker_bitfield);
EJOC_API ejoc_speaker_renderer_handle EJOC_CALL ejoc_speaker_renderer_create(uint32_t speaker_bitfield);
EJOC_API void EJOC_CALL ejoc_speaker_renderer_destroy(ejoc_speaker_renderer_handle handle);
@@ -139,6 +178,7 @@ EJOC_API int EJOC_CALL ejoc_speaker_renderer_process(
const uint8_t* region_indices,
const uint8_t* height_enabled,
const double* object_gains,
const ejoc_speaker_controls* controls,
double* output_interleaved);
EJOC_API ejoc_binaural_renderer_handle EJOC_CALL ejoc_binaural_renderer_create(void);
+2 -2
View File
@@ -9,8 +9,8 @@
#define JOC_VERSION_H
#define JOC_VERSION_MAJOR 1
#define JOC_VERSION_MINOR 1
#define JOC_VERSION_MINOR 2
#define JOC_VERSION_PATCH 0
#define JOC_VERSION_STRING "1.1.0"
#define JOC_VERSION_STRING "1.2.0"
#endif /* JOC_VERSION_H */
+101 -8
View File
@@ -54,6 +54,67 @@ std::uint8_t checksum(const std::string& segment) {
return static_cast<std::uint8_t>((~sum + 1) & 0xFF);
}
// OAMD trim element warp mode as the dbmd, DAMF and AXML warp field carry it:
// 0 normal, 1 warping, 2 downmix_pl2x, 3 downmix_loro.
std::uint32_t trim_warp_mode(const oamd::OamdTrim* trim) {
if (trim == nullptr) {
return 0;
}
return std::min<std::uint32_t>(trim->warp_mode, 3u);
}
// Trim records carry the balance as a sign bit plus a 7-bit magnitude on a
// 1/127 grid.
std::uint8_t balance_byte(double value) {
const long long magnitude =
std::min<long long>(pynum::py_round(std::fabs(value) * 127.0), 127);
return static_cast<std::uint8_t>(static_cast<unsigned>(magnitude) |
(value < 0.0 ? 0x80u : 0x00u));
}
void append_trim_records(const oamd::OamdTrim& trim, std::string* out) {
out->append("<DolbyTrimModeSetup>");
for (int index = 0; index < oamd::kTrimConfigs; ++index) {
const oamd::TrimConfig& record = trim.configs[index];
if (record.kind == oamd::TrimConfigKind::kAbsent) {
continue;
}
out->append("<records><type>");
out->append(std::to_string(index));
out->append("</type>");
if (record.kind == oamd::TrimConfigKind::kDefault) {
out->append("</records>");
continue;
}
const bool explicit_record = record.kind == oamd::TrimConfigKind::kExplicit;
const double centre = explicit_record ? record.centre : 0.0;
const double surround = explicit_record ? record.surround : 0.0;
const double height = explicit_record ? record.height : 0.0;
const double overhead = explicit_record ? record.balance_overhead : 0.0;
const double listener = explicit_record ? record.balance_listener : 0.0;
out->append("<centerTrim>" + pynum::format_fixed(centre, 6) + "</centerTrim>");
out->append("<surroundTrim>" + pynum::format_fixed(surround, 6) + "</surroundTrim>");
out->append("<heightTrim>" + pynum::format_fixed(height, 6) + "</heightTrim>");
out->append("<balanceOverhead>" + pynum::format_fixed(overhead, 6) +
"</balanceOverhead>");
out->append("<balanceListener>" + pynum::format_fixed(listener, 6) +
"</balanceListener>");
out->append("</records>");
}
out->append("</DolbyTrimModeSetup>");
}
void append_atmos_master_block(const oamd::OamdTrim& trim, std::string* out) {
const std::string warp = std::to_string(trim_warp_mode(&trim));
out->append("<DolbyAtmosMasterFile><DolbyMasterContentInfo><render_warp_mode>");
out->append(warp);
out->append("</render_warp_mode></DolbyMasterContentInfo>");
append_trim_records(trim, out);
out->append("<DolbyWarpMode>");
out->append(warp);
out->append("</DolbyWarpMode></DolbyAtmosMasterFile>");
}
} // namespace
std::string ts(double seconds) {
@@ -102,7 +163,8 @@ std::string build_chna() {
return out;
}
Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* out) {
Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* out,
const oamd::OamdTrim* trim) {
if (out == nullptr) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kOutput, "null output");
}
@@ -136,6 +198,10 @@ Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* ou
segment9[106] = 0x01;
segment9[111] = 0x22;
segment9[112] = static_cast<char>(0xFF);
// at[152]: the low three bits are the warp code, the other bits belong to
// the template's packed fields.
segment9[152] = static_cast<char>(
(static_cast<unsigned char>(segment9[152]) & 0xF8u) | trim_warp_mode(trim));
out->push_back(9);
put_u16(out, 248);
out->append(segment9);
@@ -152,12 +218,35 @@ Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* ou
segment10[i] = static_cast<char>(0x84);
}
// Nine 15-byte configuration trims start at byte 7; the first byte of each
// carries the auto-trim flag in bit 0 (1 = automatic, 0 = manual). The
// default is automatic, so a freshly rendered master opens with automatic
// trims in the renderer.
for (std::size_t layout = 0; layout < 9; ++layout) {
const std::size_t flag = 7u + 15u * layout;
segment10[flag] = static_cast<char>(static_cast<unsigned char>(segment10[flag]) | 0x01u);
// carries the auto-trim flag in bit 0 (1 = automatic, 0 = manual). A
// configuration without an explicit record stays automatic, so a freshly
// rendered master opens with automatic trims in the renderer.
for (std::size_t layout = 0; layout < static_cast<std::size_t>(oamd::kTrimConfigs);
++layout) {
const std::size_t base = 7u + 15u * layout;
const oamd::TrimConfig* record =
trim != nullptr ? &trim->configs[layout] : nullptr;
const bool manual = record != nullptr &&
(record->kind == oamd::TrimConfigKind::kExplicit ||
record->kind == oamd::TrimConfigKind::kDisabled);
if (!manual) {
segment10[base] =
static_cast<char>(static_cast<unsigned char>(segment10[base]) | 0x01u);
continue;
}
segment10[base] = static_cast<char>(static_cast<unsigned char>(segment10[base]) & 0xFEu);
const bool explicit_record = record->kind == oamd::TrimConfigKind::kExplicit;
const double levels[3] = {explicit_record ? record->centre : 0.0,
explicit_record ? record->surround : 0.0,
explicit_record ? record->height : 0.0};
for (std::size_t index = 0; index < 3; ++index) {
const float stored = static_cast<float>(levels[index]);
std::memcpy(&segment10[base + 1u + 4u * index], &stored, sizeof(stored));
}
const double overhead = explicit_record ? record->balance_overhead : 0.0;
const double listener = explicit_record ? record->balance_listener : 0.0;
segment10[base + 13u] = static_cast<char>(balance_byte(overhead));
segment10[base + 14u] = static_cast<char>(balance_byte(listener));
}
const std::size_t object_modes = 4u + 2u + 1u + 9u * 15u + object_count;
for (std::uint32_t i = 10; i < std::min<std::uint32_t>(object_count, 10u + kObjectCount); ++i) {
@@ -176,7 +265,8 @@ Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* ou
return Status::success();
}
std::string build_axml(const std::vector<Track>& tracks, double duration_sec, std::uint32_t rate) {
std::string build_axml(const std::vector<Track>& tracks, double duration_sec, std::uint32_t rate,
const oamd::OamdTrim* trim) {
const double scale = static_cast<double>(rate);
std::string out;
out.reserve(64u * 1024u);
@@ -333,6 +423,9 @@ std::string build_axml(const std::vector<Track>& tracks, double duration_sec, st
"_01</audioTrackFormatIDRef>";
out += "</audioStreamFormat>";
}
if (trim != nullptr) {
append_atmos_master_block(*trim, &out);
}
out += "</audioFormatExtended></format></coreMetadata>";
out += "</ebuCoreMain>";
return out;
+9 -2
View File
@@ -7,6 +7,7 @@
#include <vector>
#include "foundation/status.h"
#include "oamd/oamd_parser.h"
namespace joc::adm {
@@ -34,10 +35,16 @@ enum class BinauralMode : std::uint32_t { Off = 0, Near = 1, Far = 2, Mid = 3, U
bool binaural_mode_from_name(const char* name, BinauralMode* out);
std::string build_axml(const std::vector<Track>& tracks, double duration_sec, std::uint32_t rate);
// ``trim`` is the OAMD trim element of the programme; when it is present the
// AXML carries the Dolby master-file block (content info, trim records, warp
// mode) and the dbmd chunk carries the per-configuration records and the warp
// code.
std::string build_axml(const std::vector<Track>& tracks, double duration_sec, std::uint32_t rate,
const oamd::OamdTrim* trim = nullptr);
std::string build_chna();
Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* out);
Status build_dbmd(std::uint32_t object_count, BinauralMode mode, std::string* out,
const oamd::OamdTrim* trim = nullptr);
} // namespace joc::adm
+166
View File
@@ -15,6 +15,13 @@ constexpr int kRampDurationIndex[16] = {32, 64, 128, 256, 320, 480,
1000, 1001, 1024, 1600, 1601, 1602,
1920, 2000, 2002, 2048};
constexpr std::uint32_t kObjectElementId = 1;
// ETSI TS 103 420 Table 12 trim levels, 4-bit index, dB; index 15 is the
// minimum (-36 dB), not silence.
constexpr double kTrimLut[16] = {6.0, 3.0, 1.5, 0.75, -0.75, -1.5,
-3.0, -4.5, -6.0, -7.5, -9.0, -10.5,
-12.0, -13.5, -15.0, -36.0};
// bal3d_y is coded as (code + 1) / 16, so the magnitude never reaches 0.
constexpr double kBalanceStep = 16.0;
constexpr int kIsfObjectCounts[6] = {4, 8, 10, 14, 15, 30};
constexpr int kStandardBedChannelCount[10] = {2, 1, 1, 2, 2, 2, 2, 2, 2, 1};
@@ -329,6 +336,72 @@ Status parse_object_element(bits::BitReader& reader, std::uint32_t object_count,
return Status::success();
}
// trim_element(): one programme-wide record per payload. The first bit of each
// configuration is b_default_trim; b_disable_trim and the value record follow
// only when that bit is clear.
Status parse_trim_element(bits::BitReader& reader, std::uint32_t object_count, OamdTrim* out) {
OamdTrim trim;
trim.warp_mode = reader.read(2);
reader.read(2); // reserved
trim.global_trim_mode = reader.read(2);
if (reader.failed()) {
return syntax("OAMD trim element header truncated");
}
if (trim.global_trim_mode == 2u) {
for (int config = 0; config < kTrimConfigs; ++config) {
TrimConfig& record = trim.configs[config];
if (reader.read(1) != 0u) {
record.kind = TrimConfigKind::kDefault;
continue;
}
if (reader.read(1) != 0u) {
record.kind = TrimConfigKind::kDisabled;
continue;
}
record.kind = TrimConfigKind::kExplicit;
const std::uint32_t presence = reader.read(5);
record.presence = static_cast<std::uint8_t>(presence);
if ((presence & 0x01u) != 0u) {
record.centre = kTrimLut[reader.read(4) & 0x0Fu];
}
if ((presence & 0x02u) != 0u) {
record.surround = kTrimLut[reader.read(4) & 0x0Fu];
}
if ((presence & 0x04u) != 0u) {
record.height = kTrimLut[reader.read(4) & 0x0Fu];
}
if ((presence & 0x08u) != 0u) {
const double sign = reader.read(1) != 0u ? 1.0 : -1.0;
record.balance_overhead =
(static_cast<double>(reader.read(4)) + 1.0) / kBalanceStep * sign;
}
if ((presence & 0x10u) != 0u) {
const double sign = reader.read(1) != 0u ? 1.0 : -1.0;
record.balance_listener =
(static_cast<double>(reader.read(4)) + 1.0) / kBalanceStep * sign;
}
if (reader.failed()) {
return syntax("OAMD trim configuration " + std::to_string(config) +
" truncated");
}
}
}
if (reader.read(1) != 0u) {
for (std::uint32_t index = 0; index < object_count; ++index) {
const bool bypass = reader.read(1) != 0u;
if (index < static_cast<std::uint32_t>(kMaxSlots)) {
trim.disable_per_object[index] = bypass;
}
}
}
if (reader.failed()) {
return syntax("OAMD trim bypass table truncated");
}
trim.object_count = object_count;
*out = trim;
return Status::success();
}
} // namespace
int q_of(int k, int n) {
@@ -377,6 +450,85 @@ Status parse_id11_bed_assignments(const std::uint8_t* payload, std::size_t paylo
return Status::success();
}
Status parse_trim(const std::uint8_t* payload, std::size_t payload_size, OamdTrim* out,
bool* present) {
if (payload == nullptr || out == nullptr || present == nullptr) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kOamd, "null payload or output");
}
*present = false;
if (payload_size == 0) {
return variant("header_truncated", "OAMD payload is empty");
}
bits::BitReader reader(payload, payload_size);
std::uint32_t version = reader.read(2);
if (reader.failed()) {
return variant("header_truncated", "OAMD payload cannot hold the 2-bit version");
}
if (version == 3u) {
version += reader.read(3);
if (reader.failed()) {
return syntax("OAMD version extension truncated");
}
}
std::uint32_t object_count_bits = reader.read(5);
if (object_count_bits == 0x1Fu) {
object_count_bits += reader.read(7);
}
if (reader.failed()) {
return syntax("OAMD object count truncated");
}
const std::uint32_t object_count = object_count_bits + 1u;
ProgramInfo program;
const Status program_status = parse_program_assignment(reader, &program);
if (!program_status.ok()) {
return program_status;
}
const std::uint32_t alternate_present = reader.read(1);
std::uint32_t element_count = reader.read(4);
if (element_count == 0xFu) {
element_count += reader.read(5);
}
if (reader.failed()) {
return syntax("OAMD element count truncated");
}
for (std::uint32_t ordinal = 0; ordinal < element_count; ++ordinal) {
const std::uint32_t element_id = reader.read(4);
std::uint32_t size_field = 0;
if (!variable_bits_max(reader, 4, 4, &size_field)) {
return syntax("OAMD element header truncated at ordinal " + std::to_string(ordinal));
}
const std::uint32_t size_bytes = size_field + 1u;
const std::size_t region_start = reader.position();
const std::size_t region_end = region_start + static_cast<std::size_t>(size_bytes) * 8u;
if (region_end > reader.limit()) {
return variant("element_bounds",
"element " + std::to_string(ordinal) + " (id " +
std::to_string(element_id) + ") declares " +
std::to_string(size_bytes) + " bytes, beyond the payload");
}
if (alternate_present != 0u) {
reader.read(4);
}
reader.read(1);
if (reader.failed()) {
return syntax("OAMD element control fields truncated at ordinal " +
std::to_string(ordinal));
}
if (element_id == kTrimElementId) {
const Status parsed = parse_trim_element(reader, object_count, out);
if (!parsed.ok()) {
return parsed;
}
*present = true;
return Status::success();
}
if (!reader.skip(region_end - reader.position())) {
return syntax("OAMD element skip past payload end");
}
}
return Status::success();
}
Status parse_id11_verbose(const std::uint8_t* payload, std::size_t payload_size, OamdUpdate* out,
ParseTrace* trace) {
if (payload == nullptr || out == nullptr) {
@@ -475,6 +627,20 @@ Status parse_id11_verbose(const std::uint8_t* payload, std::size_t payload_size,
reader.set_limit_bits(reader.limit());
reader.skip(region_end - reader.position());
}
} else if (element_id == kTrimElementId) {
OamdTrim trim;
const Status parsed = parse_trim_element(reader, object_count, &trim);
if (!parsed.ok()) {
return parsed;
}
if (!out->has_trim) {
out->trim = trim;
out->has_trim = true;
}
if (reader.position() < region_end) {
reader.set_limit_bits(reader.limit());
reader.skip(region_end - reader.position());
}
} else {
if (!reader.skip(region_end - reader.position())) {
return syntax("OAMD element skip past payload end");
+44
View File
@@ -17,6 +17,38 @@ inline constexpr int kAxes = 3;
inline constexpr int kNQ12 = 62;
inline constexpr int kNQ3 = 15;
inline constexpr int kQ15Scale = 32768;
inline constexpr std::uint32_t kTrimElementId = 2;
inline constexpr int kTrimConfigs = 9;
// One of the nine per-configuration trim records of the OAMD trim element.
// ``kAbsent`` means the configuration carries no data (the element only
// carries explicit records when global_trim_mode is 2).
enum class TrimConfigKind : std::uint8_t {
kAbsent = 0,
kDefault,
kDisabled,
kExplicit,
};
struct TrimConfig {
TrimConfigKind kind = TrimConfigKind::kAbsent;
std::uint8_t presence = 0; // b_*_trim_present bits of an explicit record
double centre = 0.0; // dB
double surround = 0.0; // dB
double height = 0.0; // dB
double balance_overhead = 0.0; // bal3d_y_tb, [-1, 1]
double balance_listener = 0.0; // bal3d_y_lis, [-1, 1]
};
// Programme calibration carried by the OAMD trim element: warp mode, global
// trim mode, the nine configuration records and the per-object bypass flags.
struct OamdTrim {
std::uint32_t warp_mode = 0;
std::uint32_t global_trim_mode = 0;
TrimConfig configs[kTrimConfigs];
std::uint32_t object_count = 0;
bool disable_per_object[kMaxSlots] = {};
};
// (the reference's None), i.e. hold the previous position.
struct SlotUpdate {
@@ -39,6 +71,11 @@ struct OamdUpdate {
bool content_bed = false;
bool content_isf = false;
bool content_dynamic = false;
// Trim element of this payload. The element describes the programme, so
// ``has_trim`` only marks the payloads that carry it; a payload without it
// keeps whatever controls the caller already holds.
OamdTrim trim;
bool has_trim = false;
};
class OamdState {
@@ -84,6 +121,13 @@ int q_of(int k, int n);
Status parse_id11(const std::uint8_t* payload, std::size_t payload_size, OamdUpdate* out);
// Parses only the trim element of a payload. ``out`` receives the first trim
// element found; ``*present`` is false when the payload carries none. decode
// paths that need the OAMD calibration but no object state can use this
// without requiring an object element.
Status parse_trim(const std::uint8_t* payload, std::size_t payload_size, OamdTrim* out,
bool* present);
struct BedAssignment {
bool lfe_only = false;
bool standard = false;
+17 -11
View File
@@ -10,20 +10,23 @@ struct FrozenLayout {
const char* name;
std::uint32_t out_ch_config;
std::uint32_t speaker_bitfield;
std::uint32_t surround_channels;
std::uint32_t height_channels;
bool carries_trim;
};
constexpr FrozenLayout kLayouts[kLayoutCount] = {
{"2.0", 0, 1},
{"3.1", 3, 7},
{"4.0", 0xFF, 9},
{"5.1", 7, 15},
{"7.1", 11, 31},
{"5.1.2", 13, 1039},
{"5.1.4", 14, 2575},
{"7.1.2", 15, 1055},
{"7.1.4", 16, 2591},
{"9.1.4", 19, 2719},
{"9.1.6", 20, 3743},
{"2.0", 0, 1, 0, 0, true},
{"3.1", 3, 7, 0, 0, true},
{"4.0", 0xFF, 9, 2, 0, true},
{"5.1", 7, 15, 2, 0, true},
{"7.1", 11, 31, 4, 0, true},
{"5.1.2", 13, 1039, 2, 2, true},
{"5.1.4", 14, 2575, 2, 4, true},
{"7.1.2", 15, 1055, 4, 2, false},
{"7.1.4", 16, 2591, 4, 4, false},
{"9.1.4", 19, 2719, 4, 4, false},
{"9.1.6", 20, 3743, 4, 6, false},
};
void fill(const FrozenLayout& source, LayoutInfo* out) {
@@ -31,6 +34,9 @@ void fill(const FrozenLayout& source, LayoutInfo* out) {
out->out_ch_config = source.out_ch_config;
out->speaker_bitfield = source.speaker_bitfield;
out->channel_count = ejoc_speaker_layout_channel_count(source.speaker_bitfield);
out->surround_channels = source.surround_channels;
out->height_channels = source.height_channels;
out->carries_trim = source.carries_trim;
}
} // namespace
+7
View File
@@ -15,6 +15,13 @@ struct LayoutInfo {
std::uint32_t out_ch_config = 0;
std::uint32_t speaker_bitfield = 0;
std::uint32_t channel_count = 0;
// Ls/Rs/Lrs/Rrs and Ltf/Rtf/Ltr/Rtr/Ltm/Rtm, the labels the OAMD trim
// configuration index counts.
std::uint32_t surround_channels = 0;
std::uint32_t height_channels = 0;
// One of the seven layouts that carry OAMD trim and front-back balance
// semantics; wider layouts leave the programme untrimmed.
bool carries_trim = false;
};
// All eleven layouts in the reference's order (2.0, 3.1, 4.0, 5.1, 7.1, 5.1.2,
+89 -12
View File
@@ -1,5 +1,6 @@
#define EJOC_BUILD_DLL
#include "eac3joc_core.h"
#include "speaker/speaker_trim.h"
#include "speaker_layouts.h"
#include <algorithm>
@@ -216,6 +217,7 @@ public:
const std::uint8_t* region_indices,
const std::uint8_t* height_enabled,
const double* object_gains,
const ejoc_speaker_controls* controls,
double* output) noexcept {
error_[0] = '\0';
if (!input || !output) {
@@ -227,11 +229,21 @@ public:
if (metadata_count && (!metadata_offsets || !ramp_durations || !positions_q15)) {
return fail("metadata arrays are null while metadata_count is nonzero");
}
if (!validate_controls(controls)) {
return -1;
}
if (!validate_metadata(sample_count, metadata_count, metadata_offsets,
positions_q15, region_indices, object_gains)) {
return -1;
}
// A caller that passes no controls gets warp 0, no trim and no balance.
ejoc_speaker_controls fallback{};
fallback.struct_size = sizeof(fallback);
fallback.struct_version = EJOC_SPEAKER_CONTROLS_VERSION;
fallback.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
const ejoc_speaker_controls& active = controls != nullptr ? *controls : fallback;
std::fill(output, output + static_cast<std::size_t>(sample_count) * layout_->channel_count, 0.0);
const bool has_lfe = (layout_->speaker_bitfield & 0x4u) != 0;
const std::size_t total_blocks = sample_count / kBlock;
@@ -239,14 +251,14 @@ public:
for (std::size_t block = 0; block < total_blocks; ++block) {
while (event < metadata_count && aligned_block(metadata_offsets[event]) == block) {
apply_event(event, ramp_durations, positions_q15, region_indices,
height_enabled, object_gains);
height_enabled, object_gains, active);
++event;
}
mix_block(input, output, block, has_lfe);
}
while (event < metadata_count && aligned_block(metadata_offsets[event]) == total_blocks) {
apply_event(event, ramp_durations, positions_q15, region_indices,
height_enabled, object_gains);
height_enabled, object_gains, active);
++event;
}
if (event != metadata_count) {
@@ -268,6 +280,42 @@ private:
return -1;
}
bool validate_controls(const ejoc_speaker_controls* controls) noexcept {
if (controls == nullptr) {
return true;
}
if (controls->struct_size != sizeof(ejoc_speaker_controls)) {
fail("speaker controls struct_size mismatch");
return false;
}
if (controls->struct_version != EJOC_SPEAKER_CONTROLS_VERSION) {
fail("unknown speaker controls struct_version");
return false;
}
if (controls->warp_mode > 1u) {
fail("speaker rendering implements warp modes 0/1 only");
return false;
}
if (controls->trim_mode > EJOC_SPEAKER_TRIM_EXPLICIT) {
fail("unknown speaker trim mode");
return false;
}
for (const double level :
{controls->centre_db, controls->surround_db, controls->height_db}) {
if (!std::isfinite(level)) {
fail("trim level is not finite");
return false;
}
}
for (const double balance : {controls->listener_balance, controls->overhead_balance}) {
if (!std::isfinite(balance) || balance < -1.0 || balance > 1.0) {
fail("balance is not finite or outside [-1, 1]");
return false;
}
}
return true;
}
bool validate_metadata(const std::uint32_t sample_count,
const std::uint32_t metadata_count,
const std::uint32_t* metadata_offsets,
@@ -318,13 +366,28 @@ private:
const std::uint8_t region_index,
const bool enable_height,
const double object_gain,
const ejoc_speaker_controls& controls,
const bool bypass_trim,
ChannelGains& output) const noexcept {
output.fill(0.0);
const auto& region = layout_->regions[region_index];
const double u = static_cast<double>(position[0]) / kQ15Scale;
const double v = static_cast<double>(position[1]) / kQ15Scale;
const double w = static_cast<double>(position[2]) / kQ15Scale;
const double floor_v = clamp(std::ldexp(v, floor_y_exponent_), 0.0, 1.0);
const double w = std::max(static_cast<double>(position[2]) / kQ15Scale, 0.0);
const int shift = controls.warp_mode == 1u ? floor_y_exponent_ : 0;
double floor_v = clamp(std::ldexp(v, shift), 0.0, 1.0);
double top_v = clamp(v, 0.0, 1.0);
double trim_v = v;
if (controls.trim_mode == EJOC_SPEAKER_TRIM_EXPLICIT && !bypass_trim) {
// Warp feeds the floor coordinate only: the height and trim
// coordinates see the balance map on the original Y.
floor_v = joc::speaker::apply_balance(floor_v, w, controls.listener_balance,
controls.overhead_balance);
top_v = joc::speaker::apply_balance(top_v, w, controls.listener_balance,
controls.overhead_balance);
trim_v = joc::speaker::apply_balance(v, w, controls.listener_balance,
controls.overhead_balance);
}
PointGains floor{};
plane_gains(region, region.axis0_groups, region.axis0_group_count,
u, floor_v, region.mode, floor);
@@ -332,7 +395,7 @@ private:
if (region.mode == 3) {
PointGains height{};
plane_gains(region, region.axis1_groups, region.axis1_group_count,
u, v, 3, height);
u, top_v, 3, height);
const double z = enable_height ? clamp(w, 0.0, kQ15Max) : 0.0;
if (z >= kQ15Max) {
point = height;
@@ -345,21 +408,33 @@ private:
}
}
}
const double y_term = clamp(v / 0.6, 0.0, 1.0);
const double z_term = clamp((w - 0.2) / 0.8, 0.0, 1.0);
const double amount = clamp(y_term + z_term, 0.0, 1.0);
const double gain = std::pow(10.0, attenuation_db_ * amount / 20.0) * object_gain;
double gain = object_gain;
if (!bypass_trim) {
if (controls.trim_mode == EJOC_SPEAKER_TRIM_AUTOMATIC) {
gain *= position_gain(trim_v, w);
} else if (controls.trim_mode == EJOC_SPEAKER_TRIM_EXPLICIT) {
gain *= joc::speaker::explicit_position_gain(controls, u, trim_v, w);
}
}
for (std::size_t index = 0; index < region.point_count; ++index) {
output[region.points[index].speaker_id] = point[index] * gain;
}
}
double position_gain(const double v, const double w) const noexcept {
const double y_term = clamp(v / 0.6, 0.0, 1.0);
const double z_term = clamp((w - 0.2) / 0.8, 0.0, 1.0);
const double amount = clamp(y_term + z_term, 0.0, 1.0);
return std::pow(10.0, attenuation_db_ * amount / 20.0);
}
void apply_event(const std::size_t event,
const std::uint32_t* ramp_durations,
const std::uint16_t* positions_q15,
const std::uint8_t* region_indices,
const std::uint8_t* height_enabled,
const double* object_gains) noexcept {
const double* object_gains,
const ejoc_speaker_controls& controls) noexcept {
const std::uint32_t blocks = ramp_blocks(ramp_durations[event]);
for (std::size_t object = 0; object < kObjects; ++object) {
const std::size_t object_event = event * kObjects + object;
@@ -367,8 +442,9 @@ private:
const std::uint8_t region = region_indices ? region_indices[object_event] : 0;
const bool height = !height_enabled || height_enabled[object_event] != 0;
const double object_gain = object_gains ? object_gains[object_event] : 1.0;
const bool bypass = controls.trim_bypass[object + 1] != 0u;
ChannelGains next{};
render_point(position, region, height, object_gain, next);
render_point(position, region, height, object_gain, controls, bypass, next);
for (std::size_t channel = 0; channel < layout_->channel_count; ++channel) {
const double difference = next[channel] - current_[object][channel];
target_[object][channel] = next[channel];
@@ -482,6 +558,7 @@ int EJOC_CALL ejoc_speaker_renderer_process(
const uint8_t* region_indices,
const uint8_t* height_enabled,
const double* object_gains,
const ejoc_speaker_controls* controls,
double* output_interleaved) {
if (!handle) {
return -1;
@@ -489,7 +566,7 @@ int EJOC_CALL ejoc_speaker_renderer_process(
return static_cast<ejoc::speaker::Renderer*>(handle)->process(
objects16_interleaved, sample_count, metadata_count,
metadata_offsets, ramp_durations, positions_q15,
region_indices, height_enabled, object_gains, output_interleaved);
region_indices, height_enabled, object_gains, controls, output_interleaved);
}
} // extern "C"
+22 -1
View File
@@ -26,8 +26,29 @@ Status step(SpeakerStep* context, const std::vector<float>& objects16_planar,
static_cast<std::size_t>(JOC_FRAME_SAMPLES) * context->layout.channel_count, 0.0);
context->last_had_payload = update != nullptr;
if (!context->controls_ready) {
const Status status =
parameters_from_oamd(nullptr, context->layout, &context->controls);
if (!status.ok()) {
if (error != nullptr) {
*error = status.message();
}
return status;
}
context->controls_ready = true;
}
std::uint32_t ramp = 0;
if (update != nullptr) {
if (update->has_trim) {
const Status status = parameters_from_oamd(&update->trim, context->layout,
&context->controls);
if (!status.ok()) {
if (error != nullptr) {
*error = status.message();
}
return status;
}
}
context->state.apply(*update);
ramp = update->ramp_duration_samples;
context->last_block_offset = update->block_offset_samples;
@@ -53,7 +74,7 @@ Status step(SpeakerStep* context, const std::vector<float>& objects16_planar,
context->handle, context->interleaved.data(), JOC_FRAME_SAMPLES, event_count,
event_count != 0u ? &offset : nullptr, event_count != 0u ? &ramp : nullptr,
event_count != 0u ? &positions[0][0] : nullptr, nullptr, nullptr, nullptr,
context->output.data());
&context->controls, context->output.data());
if (result != 0) {
const char* message = ejoc_speaker_renderer_last_error(context->handle);
const std::string text =
+5
View File
@@ -9,6 +9,7 @@
#include "foundation/status.h"
#include "oamd/oamd_parser.h"
#include "speaker/speaker_layout_lookup.h"
#include "speaker/speaker_trim.h"
namespace joc::speaker {
@@ -23,6 +24,10 @@ struct SpeakerStep {
std::uint32_t last_ramp_duration = 0;
std::uint32_t last_object_count = 0;
bool last_had_payload = false;
// OAMD speaker controls. A payload carrying the trim element replaces
// them; a payload without it keeps the previous set.
ejoc_speaker_controls controls{};
bool controls_ready = false;
// bed 声道是固定通道:OAMD 不给位置,方位由声明的 bed 布局给出。这里存
// 对象槽 → Q15 方位;bed_override 为 false 的槽仍按 OAMD 坐标声像。
std::uint16_t bed_positions[oamd::kObjects][oamd::kAxes] = {};
+155
View File
@@ -0,0 +1,155 @@
#include "speaker/speaker_trim.h"
#include <algorithm>
#include <cmath>
#include <string>
#include "foundation/py_num.h"
namespace joc::speaker {
namespace {
int height_class(std::uint32_t count) {
if (count == 0u) {
return 0;
}
if (count == 2u) {
return 1;
}
return 2;
}
int floor_class(std::uint32_t count) {
if (count == 0u) {
return 0;
}
if (count == 2u || count == 3u) {
return 1;
}
return 2;
}
} // namespace
int trim_config_index(const LayoutInfo& layout) {
return floor_class(layout.surround_channels) + 3 * height_class(layout.height_channels);
}
Status parameters_from_oamd(const oamd::OamdTrim* trim, const LayoutInfo& layout,
ejoc_speaker_controls* out) {
if (out == nullptr) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender,
"null speaker controls");
}
ejoc_speaker_controls controls{};
controls.struct_size = sizeof(controls);
controls.struct_version = EJOC_SPEAKER_CONTROLS_VERSION;
controls.trim_mode = EJOC_SPEAKER_TRIM_AUTOMATIC;
if (trim != nullptr) {
controls.warp_mode = trim->warp_mode;
for (int slot = 0; slot < oamd::kMaxSlots; ++slot) {
controls.trim_bypass[slot] = trim->disable_per_object[slot] ? 1u : 0u;
}
}
if (controls.warp_mode > 1u) {
return Status::fail(JOC_ERR_NOT_SUPPORTED, stage::kRender,
"speaker: warp_mode_not_implemented: speaker rendering "
"implements warp modes 0/1; warp mode " +
std::to_string(controls.warp_mode) + " is reserved");
}
if (!layout.carries_trim) {
controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
*out = controls;
return Status::success();
}
const std::uint32_t mode = trim != nullptr ? trim->global_trim_mode : 0u;
if (mode == 1u) {
controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
*out = controls;
return Status::success();
}
if (mode > 2u) {
return Status::fail(JOC_ERR_NOT_SUPPORTED, stage::kRender,
"speaker: trim_mode_not_implemented: OAMD global trim mode " +
std::to_string(mode) + " is reserved");
}
if (mode == 2u) {
const oamd::TrimConfig& record = trim->configs[trim_config_index(layout)];
if (record.kind == oamd::TrimConfigKind::kDefault ||
record.kind == oamd::TrimConfigKind::kAbsent) {
*out = controls;
return Status::success();
}
if (record.kind == oamd::TrimConfigKind::kDisabled) {
controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
*out = controls;
return Status::success();
}
if (!std::isfinite(record.centre) || !std::isfinite(record.surround) ||
!std::isfinite(record.height)) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender,
"speaker: trim levels must be finite");
}
for (const double balance : {record.balance_listener, record.balance_overhead}) {
if (!std::isfinite(balance) || balance < -1.0 || balance > 1.0) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender,
"speaker: balance must be finite and in [-1,1]");
}
}
// Surround and height are attenuation-only; the centre level keeps its
// sign.
controls.trim_mode = EJOC_SPEAKER_TRIM_EXPLICIT;
controls.centre_db = record.centre;
controls.surround_db = std::min(record.surround, 0.0);
controls.height_db = std::min(record.height, 0.0);
controls.listener_balance = record.balance_listener;
controls.overhead_balance = record.balance_overhead;
}
*out = controls;
return Status::success();
}
double front_back_balance(double position, double balance) {
const long long steps =
pynum::py_round(std::fabs(balance) * static_cast<double>(kBalanceSteps));
if (steps == 0) {
return position;
}
const double slope = static_cast<double>(steps) / 18.0;
if (position <= kBalanceWall || position >= 1.0 - kBalanceWall) {
return position;
}
if (position < 0.5) {
return balance > 0.0 ? (1.0 + slope) * position - kBalanceWall * slope
: (1.0 - slope) * position + kBalanceWall * slope;
}
return balance > 0.0
? (1.0 - slope) * (position - 0.5) + 0.5 + 0.45 * slope
: (1.0 + slope) * (position - 0.5) + 0.5 - 0.45 * slope;
}
double apply_balance(double position, double height, double listener, double overhead) {
if (listener == 0.0 && overhead == 0.0) {
return position;
}
const double low = front_back_balance(position, listener);
const double high = front_back_balance(position, overhead);
return (1.0 - height) * low + height * high;
}
double explicit_position_gain(const ejoc_speaker_controls& controls, double x, double y,
double z) {
const double surround = std::min(std::max(2.0 * y, 0.0), 1.0) * (1.0 - z);
const double centre = 1.0 - std::min(
std::max(10.0 * std::max(std::max(std::fabs(z) - kBalanceWall,
y - kBalanceWall),
std::fabs(x - 0.5) - kBalanceWall),
0.0),
1.0);
const double db = surround * std::min(controls.surround_db, 0.0) +
z * std::min(controls.height_db, 0.0) + centre * controls.centre_db;
return std::pow(10.0, db / 20.0);
}
} // namespace joc::speaker
+49
View File
@@ -0,0 +1,49 @@
// Port of src/trim_balance.py.
#pragma once
#include <cstdint>
#include "eac3joc_core.h"
#include "foundation/status.h"
#include "oamd/oamd_parser.h"
#include "speaker/speaker_layout_lookup.h"
namespace joc::speaker {
// Front-back balance keeps a 5 percent wall band at each end unmapped.
inline constexpr double kBalanceWall = 0.05;
// bal3d_y is coded on a 1/16 grid, so a balance is quantised to that grid.
inline constexpr int kBalanceSteps = 16;
// Trim configuration a layout selects, from its surround and height counts:
//
// cfg = kappa_f(surrounds) + 3 * kappa_h(heights)
// kappa_f: 0 -> 0, 2..3 -> 1, otherwise 2
// kappa_h: 0 -> 0, 2 -> 1, otherwise 2
int trim_config_index(const LayoutInfo& layout);
// Converts OAMD calibration to the speaker controls of one layout. Warp modes
// 2/3 and the reserved global trim mode are reported as unsupported. A null
// trim selects warp 0 and automatic trim, or disabled trim for a layout that
// carries no trim semantics.
Status parameters_from_oamd(const oamd::OamdTrim* trim, const LayoutInfo& layout,
ejoc_speaker_controls* out);
// Reparameterises a front-back coordinate in [0, 1] by ``balance``: 0 is the
// front wall and 1 the back wall, and the two wall bands pass through
// unchanged.
double front_back_balance(double position, double balance);
// Blends the listener-plane and overhead balance by height: 0 at the listener
// plane, 1 at the top layer.
double apply_balance(double position, double height, double listener, double overhead);
// Position-dependent object trim at the balanced original Y. Surround fades
// in with Y and out towards Z=1, height fades in with Z, and the centre trim is
// local to the front-centre region. The scalar multiplies the object's whole
// panning vector before accumulation.
double explicit_position_gain(const ejoc_speaker_controls& controls, double x, double y,
double z);
} // namespace joc::speaker
+2
View File
@@ -59,6 +59,8 @@ void Stream::reset_state() {
speaker_.state.reset();
speaker_.output.clear();
speaker_.last_had_payload = false;
// Back to the initial controls; the next trim element replaces them.
speaker_.controls_ready = false;
}
if (binaural_ready_) {
binaural_.reset();
+113 -3
View File
@@ -313,6 +313,91 @@ int probe_config_idx(const std::string& path) {
return config;
}
// Reads the programme trim element from the leading audio frames, without
// rendering them. The ADM master metadata carries it, and the reference scans
// the first 64 audio frames for it.
Status probe_atmos_trim(const std::string& path, std::uint64_t max_frames,
oamd::OamdTrim* trim, bool* present) {
*present = false;
std::ifstream input = fs_utf8::open_input(path);
if (!input) {
return Status::success();
}
::joc::eac3::FrameReader reader;
std::vector<char> chunk(1u << 16);
std::vector<::joc::eac3::Frame> group;
std::uint64_t frames = 0;
auto scan_group = [&]() -> bool {
for (const ::joc::eac3::Frame& frame : group) {
bool has_joc = false;
::joc::emdf::Container container;
if (!::joc::emdf::find_joc_emdf_optional(
frame.data, frame.size, &has_joc, &container,
&::joc::joc::score_container_as_joc, nullptr)
.ok() ||
!has_joc) {
continue;
}
const ::joc::emdf::Payload* payload = container.find(::joc::emdf::kIdOamd);
if (payload == nullptr) {
continue;
}
std::vector<std::uint8_t> bytes;
if (!::joc::emdf::extract_payload_bytes(frame.data, frame.size, *payload, &bytes)
.ok()) {
continue;
}
oamd::OamdUpdate update;
if (!oamd::parse_id11(bytes.data(), bytes.size(), &update).ok() ||
!update.has_trim) {
continue;
}
*trim = update.trim;
*present = true;
return true;
}
group.clear();
return false;
};
bool done = false;
while (!done) {
input.read(chunk.data(), static_cast<std::streamsize>(chunk.size()));
const std::streamsize got = input.gcount();
if (got > 0) {
reader.push(reinterpret_cast<const std::uint8_t*>(chunk.data()),
static_cast<std::size_t>(got));
} else {
reader.finish();
done = true;
}
for (;;) {
::joc::eac3::Frame frame;
const ::joc::eac3::FrameReader::Next state = reader.next(&frame);
if (state != ::joc::eac3::FrameReader::Next::Ok) {
break;
}
bool repeats = false;
for (const ::joc::eac3::Frame& prior : group) {
if (prior.same_stream(frame)) {
repeats = true;
break;
}
}
if (repeats) {
++frames;
if (scan_group() || frames >= max_frames) {
return Status::success();
}
}
group.push_back(frame);
}
}
if (!group.empty()) {
scan_group();
}
return Status::success();
}
// Rendered PCM is spooled to a float32 file so the output format can be decided
// once the peak is known, which is what makes --clip-action possible; the
// reference CLI spools for the same reason.
@@ -1311,6 +1396,13 @@ Status run(const joc_task_config& raw, const joc_event_sink* sink, joc_task_resu
::joc::speaker::SpeakerStep speaker;
bool bed_positions_ready = false;
// The ADM master metadata carries the programme's trim element, scanned
// from the leading frames before rendering starts.
::joc::oamd::OamdTrim adm_trim;
bool adm_trim_present = false;
if (cfg.operation == JOC_OP_ADM_BWF) {
probe_atmos_trim(eac3_path, 64, &adm_trim, &adm_trim_present);
}
const bool speaker_enabled = cfg.operation == JOC_OP_SPEAKER;
if (speaker_enabled) {
if (!::joc::speaker::layout_by_name(cfg.layout.c_str(), &speaker.layout)) {
@@ -1323,6 +1415,21 @@ Status run(const joc_task_config& raw, const joc_event_sink* sink, joc_task_resu
return finalize_with_error(JOC_ERR_RENDER_FAILED, "render",
"cannot create the speaker renderer");
}
// The reference seeds the initial controls from the leading frames, so
// the first trim element is in effect before its own event arrives.
::joc::oamd::OamdTrim initial_trim;
bool has_initial_trim = false;
probe_atmos_trim(eac3_path, 64, &initial_trim, &has_initial_trim);
if (has_initial_trim) {
const Status seeded = ::joc::speaker::parameters_from_oamd(
&initial_trim, speaker.layout, &speaker.controls);
if (!seeded.ok()) {
ejoc_speaker_renderer_destroy(speaker.handle);
speaker.handle = nullptr;
return finalize_with_error(seeded.code(), "render", seeded.message());
}
speaker.controls_ready = true;
}
bus.emit(JOC_EV_RENDERER_INITIALIZED, JOC_STAGE_RENDER, JOC_LOG_INFO,
fmt("speaker renderer: %s, %u channels", speaker.layout.name,
speaker.layout.channel_count));
@@ -2107,13 +2214,16 @@ Status run(const joc_task_config& raw, const joc_event_sink* sink, joc_task_resu
} else {
const double duration_sec =
static_cast<double>(processed) * static_cast<std::int64_t>(JOC_FRAME_SAMPLES) / 48000.0;
const std::string axml = ::joc::adm::build_axml(tracks, duration_sec, 48000);
const std::string axml =
::joc::adm::build_axml(tracks, duration_sec, 48000,
adm_trim_present ? &adm_trim : nullptr);
const std::string chna = ::joc::adm::build_chna();
std::string dbmd;
const ::joc::adm::BinauralMode mode =
static_cast<::joc::adm::BinauralMode>(cfg.adm_binaural_mode);
const Status dbmd_status =
::joc::adm::build_dbmd(::joc::io::AdmBwfWriter::kChannels, mode, &dbmd);
const Status dbmd_status = ::joc::adm::build_dbmd(
::joc::io::AdmBwfWriter::kChannels, mode, &dbmd,
adm_trim_present ? &adm_trim : nullptr);
if (!dbmd_status.ok()) {
failure = dbmd_status.message();
} else {
+477
View File
@@ -29,6 +29,8 @@
#include "io/wav_writer.h"
#include "io/zip_reader.h"
#include "oamd/oamd_parser.h"
#include "speaker/speaker_layout_lookup.h"
#include "speaker/speaker_trim.h"
#include "stream/stream.h"
#include "task/task.h"
@@ -47,6 +49,86 @@ void check(bool condition, const char* expression, const char* file, int line) {
#define CHECK(expression) check((expression), #expression, __FILE__, __LINE__)
std::vector<std::uint8_t> from_hex(const char* text) {
auto digit = [](char c) {
return static_cast<std::uint8_t>(c <= '9' ? c - '0' : (c | 0x20) - 'a' + 10);
};
std::vector<std::uint8_t> out;
for (std::size_t i = 0; text[i] != '\0' && text[i + 1] != '\0'; i += 2) {
out.push_back(static_cast<std::uint8_t>((digit(text[i]) << 4) | digit(text[i + 1])));
}
return out;
}
std::string bytes_to_string(const std::vector<std::uint8_t>& bytes) {
return std::string(reinterpret_cast<const char*>(bytes.data()), bytes.size());
}
ejoc_speaker_controls speaker_controls(std::uint32_t warp, std::uint32_t trim_mode) {
ejoc_speaker_controls controls{};
controls.struct_size = sizeof(controls);
controls.struct_version = EJOC_SPEAKER_CONTROLS_VERSION;
controls.warp_mode = warp;
controls.trim_mode = trim_mode;
return controls;
}
// Gain vector of one object, in standard output-channel order. The object sits
// at (u, v, z) Q15 and contributes a single unit sample so the value read back
// from sample 0 is the target gain.
std::vector<double> speaker_gains(const joc::speaker::LayoutInfo& layout,
const ejoc_speaker_controls& controls, std::uint16_t u,
std::uint16_t v, std::uint16_t z,
bool bypass_object = false) {
std::vector<double> gains(layout.channel_count, 0.0);
ejoc_speaker_renderer_handle handle =
ejoc_speaker_renderer_create(layout.speaker_bitfield);
CHECK(handle != nullptr);
if (handle == nullptr) {
return gains;
}
std::vector<float> input(static_cast<std::size_t>(EJOC_SPEAKER_BLOCK_SAMPLES) *
JOC_OUTPUT_CHANNELS,
0.0f);
input[1] = 1.0f; // object slot 1, sample 0
std::uint16_t positions[joc::oamd::kObjects][3] = {};
positions[0][0] = u;
positions[0][1] = v;
positions[0][2] = z;
const std::uint32_t offset = 0;
const std::uint32_t ramp = 0;
ejoc_speaker_controls applied = controls;
if (bypass_object) {
applied.trim_bypass[1] = 1;
}
std::vector<double> output(static_cast<std::size_t>(EJOC_SPEAKER_BLOCK_SAMPLES) *
layout.channel_count,
0.0);
const int result = ejoc_speaker_renderer_process(
handle, input.data(), EJOC_SPEAKER_BLOCK_SAMPLES, 1, &offset, &ramp,
&positions[0][0], nullptr, nullptr, nullptr, &applied, output.data());
CHECK(result == 0);
for (std::uint32_t channel = 0; channel < layout.channel_count; ++channel) {
gains[channel] = output[channel];
}
ejoc_speaker_renderer_destroy(handle);
return gains;
}
void check_gains(const std::vector<double>& actual, const std::vector<double>& expected) {
CHECK(actual.size() == expected.size());
if (actual.size() != expected.size()) {
return;
}
for (std::size_t channel = 0; channel < actual.size(); ++channel) {
if (std::fabs(actual[channel] - expected[channel]) > 1e-13) {
std::printf(" channel %zu actual %.17g expected %.17g\n", channel,
actual[channel], expected[channel]);
}
CHECK(std::fabs(actual[channel] - expected[channel]) <= 1e-13);
}
}
void test_sha256() {
CHECK(joc::crypto::sha256_hex("", 0) ==
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
@@ -350,6 +432,396 @@ void test_dbmd_auto_trim() {
}
}
// OAMD trim element parsing: warp mode, global trim mode, the nine
// configuration records and the per-object bypass flags. The payloads are
// generated by the reference parser's own bit layout.
void test_oamd_trim_parse() {
// warp 2, global trim mode 2; config 0 default, 1 disabled, 2 explicit
// (centre 6 dB, surround -15 dB, height -36 dB, balance +1 / -0.5), the
// rest default; objects 1 and 5 bypassed.
const std::vector<std::uint8_t> explicit_payload = from_hex("1f049c8a9f0eff9ffa2000");
joc::oamd::OamdTrim trim;
bool present = false;
CHECK(joc::oamd::parse_trim(explicit_payload.data(), explicit_payload.size(), &trim,
&present)
.ok());
CHECK(present);
CHECK(trim.warp_mode == 2);
CHECK(trim.global_trim_mode == 2);
CHECK(trim.object_count == 16);
CHECK(trim.configs[0].kind == joc::oamd::TrimConfigKind::kDefault);
CHECK(trim.configs[1].kind == joc::oamd::TrimConfigKind::kDisabled);
CHECK(trim.configs[2].kind == joc::oamd::TrimConfigKind::kExplicit);
CHECK(trim.configs[2].presence == 0x1F);
CHECK(trim.configs[2].centre == 6.0);
CHECK(trim.configs[2].surround == -15.0);
CHECK(trim.configs[2].height == -36.0);
CHECK(trim.configs[2].balance_overhead == 1.0);
CHECK(trim.configs[2].balance_listener == -0.5);
CHECK(trim.configs[3].kind == joc::oamd::TrimConfigKind::kDefault);
CHECK(trim.configs[8].kind == joc::oamd::TrimConfigKind::kDefault);
CHECK(trim.disable_per_object[1]);
CHECK(trim.disable_per_object[5]);
CHECK(!trim.disable_per_object[0]);
CHECK(!trim.disable_per_object[2]);
// warp 1, automatic trim, no configuration records and no bypass table.
const std::vector<std::uint8_t> auto_payload = from_hex("1f048040");
CHECK(joc::oamd::parse_trim(auto_payload.data(), auto_payload.size(), &trim, &present)
.ok());
CHECK(present);
CHECK(trim.warp_mode == 1);
CHECK(trim.global_trim_mode == 0);
for (int index = 0; index < joc::oamd::kTrimConfigs; ++index) {
CHECK(trim.configs[index].kind == joc::oamd::TrimConfigKind::kAbsent);
}
for (int slot = 0; slot < joc::oamd::kMaxSlots; ++slot) {
CHECK(!trim.disable_per_object[slot]);
}
}
void test_speaker_trim_parameters() {
joc::speaker::LayoutInfo layout51{};
joc::speaker::LayoutInfo layout71{};
joc::speaker::LayoutInfo layout40{};
joc::speaker::LayoutInfo layout20{};
joc::speaker::LayoutInfo layout512{};
joc::speaker::LayoutInfo layout514{};
joc::speaker::LayoutInfo layout714{};
CHECK(joc::speaker::layout_by_name("5.1", &layout51));
CHECK(joc::speaker::layout_by_name("7.1", &layout71));
CHECK(joc::speaker::layout_by_name("4.0", &layout40));
CHECK(joc::speaker::layout_by_name("2.0", &layout20));
CHECK(joc::speaker::layout_by_name("5.1.2", &layout512));
CHECK(joc::speaker::layout_by_name("5.1.4", &layout514));
CHECK(joc::speaker::layout_by_name("7.1.4", &layout714));
CHECK(joc::speaker::trim_config_index(layout20) == 0);
CHECK(joc::speaker::trim_config_index(layout40) == 1);
CHECK(joc::speaker::trim_config_index(layout51) == 1);
CHECK(joc::speaker::trim_config_index(layout71) == 2);
CHECK(joc::speaker::trim_config_index(layout512) == 4);
CHECK(joc::speaker::trim_config_index(layout514) == 7);
ejoc_speaker_controls controls{};
CHECK(joc::speaker::parameters_from_oamd(nullptr, layout51, &controls).ok());
CHECK(controls.warp_mode == 0);
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_AUTOMATIC);
CHECK(joc::speaker::parameters_from_oamd(nullptr, layout714, &controls).ok());
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_DISABLED);
joc::oamd::OamdTrim trim{};
trim.warp_mode = 1;
trim.global_trim_mode = 1;
CHECK(joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
CHECK(controls.warp_mode == 1);
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_DISABLED);
trim = joc::oamd::OamdTrim{};
trim.global_trim_mode = 2;
trim.configs[1].kind = joc::oamd::TrimConfigKind::kDefault;
CHECK(joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_AUTOMATIC);
trim.configs[1].kind = joc::oamd::TrimConfigKind::kDisabled;
CHECK(joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_DISABLED);
trim.configs[1].kind = joc::oamd::TrimConfigKind::kExplicit;
trim.configs[1].centre = 1.5;
trim.configs[1].surround = 3.0;
trim.configs[1].height = -6.0;
trim.configs[1].balance_listener = -0.5;
trim.configs[1].balance_overhead = 0.25;
trim.disable_per_object[1] = true;
CHECK(joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_EXPLICIT);
CHECK(controls.centre_db == 1.5);
CHECK(controls.surround_db == 0.0);
CHECK(controls.height_db == -6.0);
CHECK(controls.listener_balance == -0.5);
CHECK(controls.overhead_balance == 0.25);
CHECK(controls.trim_bypass[1] == 1);
CHECK(controls.trim_bypass[2] == 0);
trim.configs[1].balance_listener = 1.5;
CHECK(!joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
trim.configs[1].balance_listener = -0.5;
trim.configs[1].centre = std::numeric_limits<double>::quiet_NaN();
CHECK(!joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
trim.configs[1].centre = 1.5;
trim.warp_mode = 2;
const joc::Status warp2 = joc::speaker::parameters_from_oamd(&trim, layout51, &controls);
CHECK(!warp2.ok());
CHECK(warp2.code() == JOC_ERR_NOT_SUPPORTED);
trim.warp_mode = 3;
CHECK(!joc::speaker::parameters_from_oamd(&trim, layout714, &controls).ok());
trim.warp_mode = 0;
trim.global_trim_mode = 3;
CHECK(!joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok());
// A layout without trim semantics settles on disabled before the reserved
// global mode is looked at.
CHECK(joc::speaker::parameters_from_oamd(&trim, layout714, &controls).ok());
CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_DISABLED);
}
void test_speaker_warp_and_trim() {
joc::speaker::LayoutInfo layout51{};
joc::speaker::LayoutInfo layout514{};
CHECK(joc::speaker::layout_by_name("5.1", &layout51));
CHECK(joc::speaker::layout_by_name("5.1.4", &layout514));
ejoc_speaker_controls automatic51{};
CHECK(joc::speaker::parameters_from_oamd(nullptr, layout51, &automatic51).ok());
ejoc_speaker_controls automatic514{};
CHECK(joc::speaker::parameters_from_oamd(nullptr, layout514, &automatic514).ok());
// Warp 0 leaves the floor Y alone; warp 1 doubles it before the clamp.
const std::vector<double> warp0 = {0.9126902722074105, 0, 0, 0, 0.18155106823708969, 0};
const std::vector<double> warp1 = {0.85973219419392444, 0, 0, 0, 0.35612480624995158, 0};
const std::vector<double> clamped = {0, 0, 0, 0, 0.70794578438413791, 0};
check_gains(speaker_gains(layout51, automatic51, 0, 4096, 0), warp0);
ejoc_speaker_controls warped = automatic51;
warped.warp_mode = 1;
check_gains(speaker_gains(layout51, warped, 0, 4096, 0), warp1);
check_gains(speaker_gains(layout51, warped, 0, 24576, 0), clamped);
// The height layer is not warped.
const std::vector<double> height_top = {0, 0, 0, 0, 0, 0, 0.84139514164519513, 0, 0, 0};
const std::vector<double> height_warp0 =
speaker_gains(layout514, automatic514, 0, 4096, 32767);
ejoc_speaker_controls warped514 = automatic514;
warped514.warp_mode = 1;
check_gains(height_warp0, height_top);
check_gains(speaker_gains(layout514, warped514, 0, 4096, 32767), height_top);
// Explicit trim with balance: warp then balance for the floor, balance on
// the original Y for the trim evaluation.
ejoc_speaker_controls explicit_controls = speaker_controls(
1, EJOC_SPEAKER_TRIM_EXPLICIT);
explicit_controls.surround_db = -6.0;
explicit_controls.listener_balance = 9.0 / 16.0;
explicit_controls.overhead_balance = -9.0 / 16.0;
const std::vector<double> trimmed = {0.68117911059016056, 0, 0, 0, 0.41744281702545366, 0};
check_gains(speaker_gains(layout51, explicit_controls, 0, 4096, 0), trimmed);
// Per-object bypass keeps warp but drops balance and trim.
const std::vector<double> bypassed = {0.92387494614065435, 0, 0, 0, 0.38269450465561039, 0};
check_gains(speaker_gains(layout51, explicit_controls, 0, 4096, 0, true), bypassed);
// Centre trim is local to the front-centre region; height trim scales with Z.
ejoc_speaker_controls centre_controls = speaker_controls(0, EJOC_SPEAKER_TRIM_EXPLICIT);
centre_controls.centre_db = -6.0;
const std::vector<double> centre = {3.0688867071757785e-17, 0, 0.50118723362727224, 0, 0, 0};
check_gains(speaker_gains(layout51, centre_controls, 16384, 0, 0), centre);
ejoc_speaker_controls height_controls = speaker_controls(0, EJOC_SPEAKER_TRIM_EXPLICIT);
height_controls.height_db = -6.0;
const std::vector<double> height_half = {0.50059326485045341, 0, 0, 0, 0,
0, 0.50059326485045341, 0, 0, 0};
check_gains(speaker_gains(layout514, height_controls, 0, 0, 16384), height_half);
// LFE passes straight through, untouched by warp, trim or balance.
ejoc_speaker_renderer_handle handle =
ejoc_speaker_renderer_create(layout51.speaker_bitfield);
CHECK(handle != nullptr);
if (handle != nullptr) {
std::vector<float> input(static_cast<std::size_t>(EJOC_SPEAKER_BLOCK_SAMPLES) *
JOC_OUTPUT_CHANNELS,
0.0f);
for (std::uint32_t sample = 0; sample < EJOC_SPEAKER_BLOCK_SAMPLES; ++sample) {
input[sample * JOC_OUTPUT_CHANNELS] = 0.25f;
}
std::vector<double> output(static_cast<std::size_t>(EJOC_SPEAKER_BLOCK_SAMPLES) *
layout51.channel_count,
0.0);
CHECK(ejoc_speaker_renderer_process(handle, input.data(), EJOC_SPEAKER_BLOCK_SAMPLES,
0, nullptr, nullptr, nullptr, nullptr, nullptr,
nullptr, &explicit_controls, output.data()) == 0);
for (std::uint32_t sample = 0; sample < EJOC_SPEAKER_BLOCK_SAMPLES; ++sample) {
for (std::uint32_t channel = 0; channel < layout51.channel_count; ++channel) {
const double value = output[sample * layout51.channel_count + channel];
CHECK(channel == 3 ? std::fabs(value - 0.25) <= 1e-15 : value == 0.0);
}
}
// Reserved warp modes are rejected before any rendering happens.
ejoc_speaker_controls reserved = speaker_controls(2, EJOC_SPEAKER_TRIM_DISABLED);
CHECK(ejoc_speaker_renderer_process(handle, input.data(), EJOC_SPEAKER_BLOCK_SAMPLES,
0, nullptr, nullptr, nullptr, nullptr, nullptr,
nullptr, &reserved, output.data()) != 0);
ejoc_speaker_renderer_destroy(handle);
}
}
// The speaker step takes the OAMD trim element from each payload; a payload
// without it keeps the previous controls.
void test_speaker_step_trim_events() {
joc::speaker::SpeakerStep step;
CHECK(joc::speaker::layout_by_name("5.1", &step.layout));
step.handle = ejoc_speaker_renderer_create(step.layout.speaker_bitfield);
CHECK(step.handle != nullptr);
if (step.handle == nullptr) {
return;
}
std::vector<float> frame(static_cast<std::size_t>(JOC_FRAME_SAMPLES) * JOC_OUTPUT_CHANNELS,
0.0f);
for (std::uint32_t sample = 0; sample < JOC_FRAME_SAMPLES; ++sample) {
frame[1u * JOC_FRAME_SAMPLES + sample] = 1.0f;
}
std::string error;
const std::size_t read = 1472u * step.layout.channel_count;
joc::oamd::OamdUpdate update;
update.slots[1].q2 = 4096;
update.has_trim = true;
update.trim.warp_mode = 1;
update.trim.global_trim_mode = 0;
update.trim.object_count = 16;
CHECK(joc::speaker::step(&step, frame, &update, &error).ok());
const std::vector<double> warp1 = {0.85973219419392444, 0, 0, 0, 0.35612480624995158, 0};
std::vector<double> gains(step.layout.channel_count);
for (std::uint32_t channel = 0; channel < step.layout.channel_count; ++channel) {
gains[channel] = step.output[read + channel];
}
check_gains(gains, warp1);
// No trim element: warp 1 and automatic trim stay in effect.
update = joc::oamd::OamdUpdate{};
update.slots[1].q2 = 2048;
CHECK(joc::speaker::step(&step, frame, &update, &error).ok());
for (std::uint32_t channel = 0; channel < step.layout.channel_count; ++channel) {
gains[channel] = step.output[read + channel];
}
const std::vector<double> half_warp1 = {0.9461247896349676, 0, 0, 0,
0.18820181552760662, 0};
check_gains(gains, half_warp1);
// A new trim element switches the controls back to warp 0.
update = joc::oamd::OamdUpdate{};
update.slots[1].q2 = 2048;
update.has_trim = true;
update.trim.warp_mode = 0;
update.trim.global_trim_mode = 0;
update.trim.object_count = 16;
CHECK(joc::speaker::step(&step, frame, &update, &error).ok());
for (std::uint32_t channel = 0; channel < step.layout.channel_count; ++channel) {
gains[channel] = step.output[read + channel];
}
const std::vector<double> half_warp0 = {0.96001622724230795, 0, 0, 0,
0.094556249720175942, 0};
check_gains(gains, half_warp0);
ejoc_speaker_renderer_destroy(step.handle);
}
void test_dbmd_and_axml_trim() {
joc::oamd::OamdTrim trim{};
trim.warp_mode = 2;
trim.global_trim_mode = 2;
trim.object_count = 16;
trim.configs[0].kind = joc::oamd::TrimConfigKind::kDefault;
trim.configs[1].kind = joc::oamd::TrimConfigKind::kDisabled;
trim.configs[2].kind = joc::oamd::TrimConfigKind::kExplicit;
trim.configs[2].presence = 0x1F;
trim.configs[2].centre = 6.0;
trim.configs[2].surround = -15.0;
trim.configs[2].height = -36.0;
trim.configs[2].balance_overhead = 1.0;
trim.configs[2].balance_listener = -0.5;
for (int index = 3; index < joc::oamd::kTrimConfigs; ++index) {
trim.configs[index].kind = joc::oamd::TrimConfigKind::kDefault;
}
std::string dbmd;
CHECK(joc::adm::build_dbmd(25, joc::adm::BinauralMode::Mid, &dbmd, &trim).ok());
std::string segment9;
std::string segment10;
std::size_t offset = 4;
while (offset + 2 < dbmd.size() && static_cast<unsigned char>(dbmd[offset]) != 0) {
const std::size_t size =
static_cast<std::size_t>(static_cast<unsigned char>(dbmd[offset + 1])) |
(static_cast<std::size_t>(static_cast<unsigned char>(dbmd[offset + 2])) << 8);
const std::size_t start = offset + 3;
unsigned sum = static_cast<unsigned>(size);
for (std::size_t i = 0; i < size; ++i) {
sum += static_cast<unsigned char>(dbmd[start + i]);
}
sum += static_cast<unsigned char>(dbmd[start + size]);
CHECK((sum & 0xFFu) == 0u);
const unsigned id = static_cast<unsigned char>(dbmd[offset]);
if (id == 9u) {
segment9 = dbmd.substr(start, size);
} else if (id == 10u) {
segment10 = dbmd.substr(start, size);
}
offset = start + size + 1;
}
CHECK(segment9.size() == 248);
CHECK(static_cast<unsigned char>(segment9[152]) == 2);
CHECK(segment10.size() == 292);
const std::string expected_configs = bytes_to_string(from_hex(
"010000000000000000000000000000"
"000000000000000000000000000000"
"000000c040000070c1000010c27fc0"
"010000000000000000000000000000"
"010000000000000000000000000000"
"010000000000000000000000000000"
"010000000000000000000000000000"
"010000000000000000000000000000"
"010000000000000000000000000000"));
CHECK(segment10.substr(7, 135) == expected_configs);
// The bypass table and headphone modes stay untouched.
for (std::size_t i = 7 + 9 * 15; i < 7 + 9 * 15 + 2 * 25; ++i) {
const unsigned char expected =
(i >= 7 + 9 * 15 + 25 + 10) ? 0x03u : 0x00u;
CHECK(static_cast<unsigned char>(segment10[i]) == expected);
}
// Without a trim element the warp field keeps the template's zero.
std::string plain;
CHECK(joc::adm::build_dbmd(25, joc::adm::BinauralMode::Mid, &plain).ok());
CHECK(plain.size() > 4);
std::string plain_segment9;
offset = 4;
while (offset + 2 < plain.size() && static_cast<unsigned char>(plain[offset]) != 0) {
const std::size_t size =
static_cast<std::size_t>(static_cast<unsigned char>(plain[offset + 1])) |
(static_cast<std::size_t>(static_cast<unsigned char>(plain[offset + 2])) << 8);
const std::size_t start = offset + 3;
if (static_cast<unsigned char>(plain[offset]) == 9u) {
plain_segment9 = plain.substr(start, size);
}
offset = start + size + 1;
}
CHECK(plain_segment9.size() == 248);
CHECK(static_cast<unsigned char>(plain_segment9[152]) == 0u);
std::vector<joc::adm::Track> tracks(15);
for (std::size_t i = 0; i < tracks.size(); ++i) {
tracks[i].name = "obj" + std::to_string(i);
}
const std::string axml = joc::adm::build_axml(tracks, 1.0, 48000, &trim);
const std::string expected_block =
"<DolbyAtmosMasterFile><DolbyMasterContentInfo><render_warp_mode>2</render_warp_mode>"
"</DolbyMasterContentInfo><DolbyTrimModeSetup>"
"<records><type>0</type></records>"
"<records><type>1</type><centerTrim>0.000000</centerTrim>"
"<surroundTrim>0.000000</surroundTrim><heightTrim>0.000000</heightTrim>"
"<balanceOverhead>0.000000</balanceOverhead>"
"<balanceListener>0.000000</balanceListener></records>"
"<records><type>2</type><centerTrim>6.000000</centerTrim>"
"<surroundTrim>-15.000000</surroundTrim><heightTrim>-36.000000</heightTrim>"
"<balanceOverhead>1.000000</balanceOverhead>"
"<balanceListener>-0.500000</balanceListener></records>"
"<records><type>3</type></records><records><type>4</type></records>"
"<records><type>5</type></records><records><type>6</type></records>"
"<records><type>7</type></records><records><type>8</type></records>"
"</DolbyTrimModeSetup><DolbyWarpMode>2</DolbyWarpMode></DolbyAtmosMasterFile>";
const std::size_t found = axml.find(expected_block);
CHECK(found != std::string::npos);
CHECK(found < axml.find("</audioFormatExtended>"));
const std::string plain_axml = joc::adm::build_axml(tracks, 1.0, 48000);
CHECK(plain_axml.find("<DolbyAtmosMasterFile>") == std::string::npos);
}
void test_int24_packing() {
// Interleaved (L,R) for two frames: 0.0, +1.0, -1.0, +2.0 (clips).
const float values[4] = {0.0f, 1.0f, -1.0f, 2.0f};
@@ -891,6 +1363,11 @@ int main() {
test_npy();
test_oamd_and_adm_helpers();
test_dbmd_auto_trim();
test_oamd_trim_parse();
test_speaker_trim_parameters();
test_speaker_warp_and_trim();
test_speaker_step_trim_events();
test_dbmd_and_axml_trim();
test_int24_packing();
test_utf8_paths();
test_process_runner();