Apply the OAMD trim and front-back balance in speaker rendering
Select the trim configuration that applies to the output layout from its
surround and height speaker counts:
cfg = kappa_f(surrounds) + 3 * kappa_h(heights)
Trim and balance apply to seven layouts: 2.0, 3.1, 4.0, 5.1, 5.1.2, 5.1.4
and 7.1. Wider layouts are left untrimmed.
An explicit configuration contributes a static level for the centre,
surround and height groups, which multiplies the panning gains per output
channel. Automatic and disabled configurations contribute no static
level: the attenuation an automatic configuration describes is already
applied per object by the layout position compensation.
An explicit configuration also contributes the two front-back balance
values. Writing n = round(16 |b|) and s = n / 18, each balance
reparameterises the OAMD front-back axis in [0, 1]:
y <= 0.05 or y >= 0.95 -> y
y < 0.5, b > 0 -> (1 + s) y - 0.05 s
y >= 0.5, b > 0 -> (1 - s) (y - 0.5) + 0.5 + 0.45 s
y < 0.5, b < 0 -> (1 - s) y + 0.05 s
y >= 0.5, b < 0 -> (1 + s) (y - 0.5) + 0.5 - 0.45 s
The map is monotonic onto [0.05, 0.95], keeps both walls fixed, and needs
no clamping. Height blends the listener-plane and overhead values before
panning; the horizontal and vertical coordinates are untouched.
Warp is not read here: it selects a downmix mode and does not enter the
speaker path.
This commit is contained in:
1 parent
220e791ce9
commit
8424e6bdfb
6 files changed
+420
-12
No files matched your search
+117
-3
@@ -519,7 +519,119 @@ 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_c=1$ and $b=0$.
|
||||
|
||||
### 12.2 Group levels
|
||||
|
||||
Each configuration supplies one level $T_g$ in dB for the centre, surround and
|
||||
height groups. Only an explicit configuration contributes a static level:
|
||||
|
||||
$$
|
||||
T_g=
|
||||
\begin{cases}
|
||||
\text{coded value}, & \text{explicit},\
|
||||
0, & \text{disabled},\
|
||||
0, & \text{automatic}.
|
||||
\end{cases}
|
||||
$$
|
||||
|
||||
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},
|
||||
$$
|
||||
|
||||
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$.
|
||||
|
||||
### 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
|
||||
|
||||
The balance acts on the second component of the object position before
|
||||
panning:
|
||||
|
||||
$$
|
||||
y_o\longmapsto y_o',
|
||||
$$
|
||||
|
||||
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}$.
|
||||
|
||||
Warp takes no part in either step: it selects a downmix mode, affects only the
|
||||
downmix path, and leaves object coordinates untouched.
|
||||
|
||||
## 13. OAMD time alignment and gain ramps
|
||||
|
||||
The coded position of an OAMD update is
|
||||
|
||||
@@ -575,7 +687,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 +719,11 @@ 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 apply to speaker rendering only;
|
||||
binaural rendering reads neither of them.
|
||||
+104
-3
@@ -516,7 +516,107 @@ 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_c=1$、$b=0$。
|
||||
|
||||
### 12.2 组电平
|
||||
|
||||
每个配置给 centre、surround、height 三个组各一个电平 $T_g$(dB)。只有显式配置
|
||||
施加静态电平:
|
||||
|
||||
$$
|
||||
T_g=
|
||||
\begin{cases}
|
||||
\text{记录值}, & \text{显式},\
|
||||
0, & \text{禁用},\
|
||||
0, & \text{自动}.
|
||||
\end{cases}
|
||||
$$
|
||||
|
||||
自动配置不带静态组增益:它描述的衰减量已由 §11 的位置补偿按对象逐个施加,再乘
|
||||
一次会重复计算。
|
||||
|
||||
声道 $c$ 的静态增益为
|
||||
|
||||
$$
|
||||
G_c=10^{T_{g(c)}/20},
|
||||
$$
|
||||
|
||||
$g(c)$ 由声道标签决定:中置归 centre,侧、后、宽归 surround,顶部归 height,左右
|
||||
与 LFE 不参与,取 $G_c=1$。
|
||||
|
||||
### 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 施加位置
|
||||
|
||||
前后平衡在声像之前作用于对象坐标的第二个分量:
|
||||
|
||||
$$
|
||||
y_o\longmapsto y_o',
|
||||
$$
|
||||
|
||||
组增益则乘在声像结果上,即 §14 混音式中的 $g_{o,c}$ 替换为 $G_c\,g_{o,c}$。
|
||||
|
||||
warp 不参与上述任何一步:它是下混模式的选择位,只影响下混路径,不改变对象坐标。
|
||||
|
||||
## 13. OAMD 时间对齐与增益斜坡
|
||||
|
||||
OAMD 更新的编码位置为
|
||||
|
||||
@@ -572,7 +672,7 @@ $$
|
||||
|
||||
如果中途没有新的 metadata 更新,该过程等价于总长度 $KB$ 的逐样本线性斜坡。
|
||||
|
||||
## 13. 最终扬声器混音
|
||||
## 14. 最终扬声器混音
|
||||
|
||||
对目标输出声道 $c$:
|
||||
|
||||
@@ -604,9 +704,10 @@ y_{24}[n]=
|
||||
\right).
|
||||
$$
|
||||
|
||||
## 14. 公式适用范围
|
||||
## 15. 公式适用范围
|
||||
|
||||
- JOC 矩阵部分同时描述 dense MTX 与 sparse IDX/VEC 两条差分语法。
|
||||
- 扬声器声像部分描述普通点对象;extent、spread、divergence 等模式需要额外模型。
|
||||
- 多个 OAMD position block 必须按其时间顺序调度。
|
||||
- limiter 属于独立后处理,不包含在上述混音公式中。
|
||||
- trim 与前后平衡只作用于扬声器渲染;双耳渲染不读取它们。
|
||||
@@ -699,8 +699,10 @@ def main(argv=None):
|
||||
timings["create_binaural_renderer"] = 0.0
|
||||
layout = get_speaker_layout(args.speaker_layout)
|
||||
speaker_name = speaker_layout_display_name(layout)
|
||||
speaker_meta = oamd_tracks.read_atmos_meta(index)
|
||||
speaker_decoder, speaker_backend_info = create_speaker_renderer(
|
||||
layout, bed_channels=getattr(index, "bed_channels", ()))
|
||||
layout, bed_channels=getattr(index, "bed_channels", ()),
|
||||
trim_meta=speaker_meta)
|
||||
print(f"[speaker] layout={speaker_name} backend={speaker_backend_info['name']} "
|
||||
f"channels={layout.channel_count}", flush=True)
|
||||
spool = SpeakerPcmSpool(
|
||||
|
||||
@@ -11,10 +11,12 @@ from speaker_renderer import PythonSpeakerRenderer, payload_events_from_index, r
|
||||
FRAME_SAMPLES = 1536
|
||||
|
||||
|
||||
def create_speaker_renderer(layout: str | SpeakerLayout, bed_channels=None):
|
||||
def create_speaker_renderer(layout: str | SpeakerLayout, bed_channels=None,
|
||||
trim_meta=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)
|
||||
renderer = PythonSpeakerRenderer(target, bed_channels=bed_channels,
|
||||
trim_meta=trim_meta)
|
||||
return renderer, {
|
||||
"name": "python",
|
||||
"layout": target.name,
|
||||
|
||||
+11
-3
@@ -14,6 +14,7 @@ import numpy as np
|
||||
|
||||
from oamd_bits import JocFieldState, frame_update
|
||||
from speaker_layouts import RegionGeometry, SpeakerLayout, get_speaker_layout
|
||||
from trim_balance import apply_balance, balance_layers, channel_gains
|
||||
|
||||
Q15_SCALE = 32768.0
|
||||
Q15_MAX = 32767.0 / Q15_SCALE
|
||||
@@ -34,8 +35,9 @@ def bed_object_targets(bed_channels) -> dict[int, tuple[float, float, float]]:
|
||||
|
||||
|
||||
def _all_object_targets(layout: SpeakerLayout, state: JocFieldState,
|
||||
bed_targets=None) -> np.ndarray:
|
||||
bed_targets=None, balance=(0.0, 0.0)) -> np.ndarray:
|
||||
bed_targets = bed_targets or {}
|
||||
listener, overhead = balance
|
||||
result = np.zeros((15, layout.channel_count), dtype=np.float64)
|
||||
for object_index in range(1, 16):
|
||||
fixed = bed_targets.get(object_index)
|
||||
@@ -45,6 +47,7 @@ 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)
|
||||
return result
|
||||
@@ -210,12 +213,15 @@ class PythonSpeakerRenderer:
|
||||
"""Stateful float64 speaker renderer."""
|
||||
|
||||
def __init__(self, layout: str | SpeakerLayout, block_size: int = 32,
|
||||
bed_channels=None):
|
||||
bed_channels=None, trim_meta=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)
|
||||
self.reset()
|
||||
|
||||
def reset(self):
|
||||
@@ -230,7 +236,8 @@ class PythonSpeakerRenderer:
|
||||
def _apply_payload(self, payload):
|
||||
update = frame_update(payload)
|
||||
self._state.apply(update["values"])
|
||||
new_target = _all_object_targets(self.layout, self._state, self.bed_targets)
|
||||
new_target = _all_object_targets(self.layout, self._state, self.bed_targets,
|
||||
self.balance)
|
||||
blocks = ramp_block_count(update["ramp_duration_samples"], self.block_size)
|
||||
difference = new_target - self._current
|
||||
significant = np.abs(difference) >= GAIN_SNAP_THRESHOLD
|
||||
@@ -299,6 +306,7 @@ 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
|
||||
|
||||
@@ -0,0 +1,181 @@
|
||||
"""Programme trim and front-back balance taken from the OAMD trim element.
|
||||
|
||||
TS 103 420 splits a programme's trim data into nine configurations, selected
|
||||
by a layout's surround and height speaker counts:
|
||||
|
||||
cfg = kappa_f(surrounds) + 3 * kappa_h(heights)
|
||||
|
||||
kappa_f(n) = 0 for n == 0, 1 for n in (2, 3), 2 otherwise
|
||||
kappa_h(n) = 0 for n == 0, 1 for n == 2, 2 otherwise
|
||||
|
||||
Each configuration holds one unit of calibration:
|
||||
|
||||
* a level in dB for the centre, surround and height speaker groups, and
|
||||
* a front-back balance for the listener plane and for the overhead layer.
|
||||
|
||||
Only the layouts listed in ``SUPPORTED_LAYOUTS`` carry these semantics.
|
||||
|
||||
Configurations left at default contribute neither a static level nor a balance:
|
||||
the automatic attenuation is already applied per object by the layout position
|
||||
compensation. Configurations declared as disabled contribute nothing either.
|
||||
|
||||
The balance reparameterises the front-back axis; it does not move objects off
|
||||
the axis and it leaves the two walls untouched. See ``front_back``.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
# 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.
|
||||
SUPPORTED_LAYOUTS = ("20", "31", "40", "51", "512", "514", "71")
|
||||
|
||||
# Channel label -> trim group. Left, right and LFE carry no trim in any
|
||||
# configuration, so they are absent from the table.
|
||||
GROUPS = {
|
||||
"C": "centre",
|
||||
"Ls": "surround", "Rs": "surround",
|
||||
"Lrs": "surround", "Rrs": "surround",
|
||||
"Ltf": "height", "Rtf": "height",
|
||||
"Ltr": "height", "Rtr": "height",
|
||||
"Ltm": "height", "Rtm": "height",
|
||||
}
|
||||
|
||||
FLOOR_LABELS = ("Ls", "Rs", "Lrs", "Rrs")
|
||||
HEIGHT_LABELS = ("Ltf", "Rtf", "Ltr", "Rtr", "Ltm", "Rtm")
|
||||
|
||||
# bal3d_y is coded in steps of 1/16, so a balance is quantised to that grid.
|
||||
BALANCE_STEPS = 16
|
||||
# Front-back balance keeps a 5 percent wall band at each end and leaves it unmapped.
|
||||
WALL = 0.05
|
||||
|
||||
|
||||
def _height_class(count):
|
||||
if count == 0:
|
||||
return 0
|
||||
if count == 2:
|
||||
return 1
|
||||
return 2
|
||||
|
||||
|
||||
def _floor_class(count):
|
||||
if count == 0:
|
||||
return 0
|
||||
if count in (2, 3):
|
||||
return 1
|
||||
return 2
|
||||
|
||||
|
||||
def layout_classes(layout):
|
||||
"""Return ``(config_index, height_count, floor_count)`` for a layout."""
|
||||
channels = tuple(getattr(layout, "channels", ()))
|
||||
heights = sum(1 for c in channels if c in HEIGHT_LABELS)
|
||||
floor = sum(1 for c in channels if c in FLOOR_LABELS)
|
||||
return _floor_class(floor) + 3 * _height_class(heights), heights, floor
|
||||
|
||||
|
||||
def _supported(layout):
|
||||
return getattr(layout, "name", None) in SUPPORTED_LAYOUTS
|
||||
|
||||
|
||||
def _record(atmos_meta, layout):
|
||||
if not atmos_meta or not _supported(layout):
|
||||
return None
|
||||
index, _, _ = layout_classes(layout)
|
||||
configs = atmos_meta.get("configs") or ()
|
||||
if index >= len(configs):
|
||||
return None
|
||||
return configs[index]
|
||||
|
||||
|
||||
def group_levels_db(atmos_meta, layout):
|
||||
"""Trim level in dB for the centre, surround and height speaker groups.
|
||||
|
||||
Only an explicit configuration contributes a static level. An automatic
|
||||
configuration carries no static gain: the attenuation it describes is
|
||||
already applied per object by the layout position compensation, and
|
||||
multiplying it in a second time would count it twice.
|
||||
"""
|
||||
record = _record(atmos_meta, layout)
|
||||
if not isinstance(record, dict) or record.get("default") or record.get("disabled"):
|
||||
return {"centre": 0.0, "surround": 0.0, "height": 0.0}
|
||||
return {
|
||||
"centre": float(record.get("centre", 0.0)),
|
||||
"surround": float(record.get("surround", 0.0)),
|
||||
"height": float(record.get("height", 0.0)),
|
||||
}
|
||||
|
||||
|
||||
def channel_gains(atmos_meta, layout):
|
||||
"""Per-channel linear gain for the layout, in channel order."""
|
||||
levels = group_levels_db(atmos_meta, layout)
|
||||
gains = []
|
||||
for label in getattr(layout, "channels", ()):
|
||||
group = GROUPS.get(label)
|
||||
db = levels[group] if group else 0.0
|
||||
gains.append(10.0 ** (db / 20.0))
|
||||
return gains
|
||||
|
||||
|
||||
def balance_layers(atmos_meta, layout):
|
||||
"""Front-back balance for the listener plane and the overhead layer.
|
||||
|
||||
Both are returned as signed magnitudes in [-1, 1]; zero means no balance.
|
||||
Only an explicit configuration carries a balance.
|
||||
"""
|
||||
record = _record(atmos_meta, layout)
|
||||
if not isinstance(record, dict) or record.get("default") or record.get("disabled"):
|
||||
return 0.0, 0.0
|
||||
listener = float(record.get("bal3d_y_lis", 0.0))
|
||||
overhead = float(record.get("bal3d_y_tb", 0.0))
|
||||
return listener, overhead
|
||||
|
||||
|
||||
def _curve(balance):
|
||||
"""Segment coefficients for one balance value.
|
||||
|
||||
Returns ``(a0, a1, a2, a3)`` for the two halves of the axis, or ``None``
|
||||
when the balance is zero.
|
||||
|
||||
Writing ``s = |n| / 18`` with ``n`` the balance quantised to the coding
|
||||
grid, a positive balance stretches the front half by ``1 + s`` and
|
||||
compresses the back half by ``1 - s``; a negative balance does the
|
||||
reverse. Both halves anchor at the axis midpoint and at the two walls,
|
||||
so the mapped value always stays inside the wall range.
|
||||
"""
|
||||
n = int(round(abs(balance) * BALANCE_STEPS))
|
||||
if n == 0:
|
||||
return None
|
||||
s = n / 18.0
|
||||
if balance > 0:
|
||||
return 1.0 + s, -WALL * s, 1.0 - s, 0.5 + 0.45 * s
|
||||
return 1.0 - s, WALL * s, 1.0 + s, 0.5 - 0.45 * s
|
||||
|
||||
|
||||
def front_back(position, balance):
|
||||
"""Reparameterise a front-back coordinate in [0, 1] by ``balance``.
|
||||
|
||||
``0`` is the front wall and ``1`` the back wall. Positions inside the
|
||||
wall bands are returned unchanged, and so is every position when the
|
||||
balance is zero.
|
||||
"""
|
||||
curve = _curve(balance)
|
||||
if curve is None:
|
||||
return position
|
||||
if position <= WALL or position >= 1.0 - WALL:
|
||||
return position
|
||||
a0, a1, a2, a3 = curve
|
||||
if position < 0.5:
|
||||
return a0 * position + a1
|
||||
return a2 * (position - 0.5) + a3
|
||||
|
||||
|
||||
def apply_balance(position, height, listener, overhead):
|
||||
"""Blend the two balance layers by height and map the coordinate.
|
||||
|
||||
``height`` runs from 0 at the listener plane to 1 at the top layer.
|
||||
"""
|
||||
if not listener and not overhead:
|
||||
return position
|
||||
low = front_back(position, listener)
|
||||
high = front_back(position, overhead)
|
||||
return (1.0 - height) * low + height * high
|
||||
Reference in new issue
Block a user