diff --git a/docs/math.en.md b/docs/math.en.md index fb7d1f0..4a13cf5 100644 --- a/docs/math.en.md +++ b/docs/math.en.md @@ -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.050,\\[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.050,\\[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 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 diff --git a/src/trim_balance.py b/src/trim_balance.py new file mode 100644 index 0000000..ade01a4 --- /dev/null +++ b/src/trim_balance.py @@ -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