Honor OAMD warp modes and position-dependent speaker trims

Read warp mode from OAMD instead of always scaling the floor Y coordinate.
For eligible layouts, mode 1 uses clamp(2Y, 0, 1), while mode 0 leaves Y
unchanged. Height coordinates are not scaled. Modes 2/3 remain explicitly
unsupported, and the CLI provides no warp override.

Keep separate coordinates for floor panning, height panning and trim
evaluation, with W denoting warp and B denoting front-back balance:

    floor Y  = B(W(Y))
    height Y = B(Y)
    trim Y   = B(Y)

Apply explicit trims as a position-dependent gain for each object before
accumulation, replacing fixed gains applied to output channels after mixing.
Automatic, disabled and explicit trim modes are mutually exclusive.
Per-object bypass disables balance and trim while retaining warp.

Update controls at OAMD metadata events and retain the previous controls
when a payload has no trim element. Keep source trajectories and binaural
rendering unchanged.

Write the OAMD warp code into dbmd segment 9 while preserving the other
packed fields. Update the bilingual mathematical notes, README files and
code comments to describe parameters and rendering behavior.

Checked: warp 0/1, Y clipping, height coordinates, balance/trim ordering,
per-object bypass, metadata updates, bed positions and LFE passthrough.
This commit is contained in:
TheM14 committed 2026-11-03 00:11:23 +08:00
1 parent 8424e6bdfb
commit 0e28cd085c
17 files changed
+335 -191

No files matched your search

+15
View File
@@ -209,6 +209,18 @@ def _balance_byte(value):
return magnitude | (0x80 if value < 0 else 0)
def warp_mode(atmos_meta):
"""OAMD trim element 的 ``warp_mode`` → 下混模式码。
dbmd 的 warp 字段、ADM 的 ``DolbyWarpMode`` 和 DAMF 的 ``WarpMode`` 共用
一套编号:0 normal、1 warping、2 downmix_pl2x、3 downmix_loro,4 表示未
指定。来源只有 2 bit 的 OAMD 字段,因此取值落在 0..3。
"""
if not atmos_meta:
return 0
return max(0, min(3, int(atmos_meta.get("warp_mode", 0))))
def build_dbmd(object_count=25, joc_binaural_mode=4, atmos_meta=None):
"""segment 10:9 个 trim 配置 + 逐轨 bypass + JOC object slots 10..24 的 mode。
@@ -233,6 +245,9 @@ def build_dbmd(object_count=25, joc_binaural_mode=4, atmos_meta=None):
at[103] = 0x03
at[106] = 0x01
at[111] = 0x22; at[112] = 0xFF
# at[152] 高 2 位是 bed_distribution、低 3 位是 warp;这里只写 warp,
# 其余位保持模板原值。
at[152] = (at[152] & 0xF8) | warp_mode(atmos_meta)
out.append(9); out += struct.pack("<H", 248); out += bytes(at)
out.append(_checksum(at))
ob = bytearray(5 + 262 + object_count)
+2 -2
View File
@@ -173,8 +173,8 @@ def main():
import argparse
ap = argparse.ArgumentParser()
ap.add_argument("files", nargs="+")
ap.add_argument("--axml-file", default=None, help="用该文件内容替换 wav 内 axml(对照实验)")
ap.add_argument("--chna-file", default=None, help="用该文件内容替换 wav 内 chna(对照实验)")
ap.add_argument("--axml-file", default=None, help="用该文件内容替换 wav 内 axml")
ap.add_argument("--chna-file", default=None, help="用该文件内容替换 wav 内 chna")
a = ap.parse_args()
ax_o = open(a.axml_file, "rb").read() if a.axml_file else None
ch_o = open(a.chna_file, "rb").read() if a.chna_file else None
+4 -4
View File
@@ -391,8 +391,8 @@ def _parse_trim_element(reader, object_count, raw_payload):
"configs": [None] * 9,
"disable_per_obj": None,
}
# global_trim_mode == 2 才携带 9 个配置的显式数据;其余取值表示内容
# 把 trim 交给渲染器自行推导(auto)。
# global_trim_mode: 0 自动、1 禁用、2 按配置显式指定、3 保留。
# 只有 2 才携带下面九个配置的显式数据。
if trim["global_trim_mode"] == 2:
for config in range(9):
if reader.read(1): # b_default_trim
@@ -731,7 +731,7 @@ def frame_update(bits_one, *, retain_spatial=False):
x, y, z = position
out[(slot, "q1")] = q_of(x, N_Q12) if 0 <= x <= N_Q12 else None
out[(slot, "q2")] = q_of(y, N_Q12) if 0 <= y <= N_Q12 else None
# Preserve legacy nonnegative height unless signed spatial output is requested.
# Clamp negative height to zero unless signed spatial output is requested.
out[(slot, "q3")] = q_of(z, N_Q3) if (0 <= z <= N_Q3 or retain_spatial and -N_Q3 <= z < 0) else (
0 if z < 0 else None)
@@ -773,7 +773,7 @@ def frame_update_values(bits_one):
class JocFieldState:
"""未更新/非法窗保持旧值;slot0 q1/q2 的 DLL 初值为中心 16384。"""
"""未更新/非法窗保持旧值;slot0 q1/q2 初始为中心 16384。"""
def __init__(self):
self.q = {(obj, field): 0 for obj in range(16)
+3 -5
View File
@@ -16,7 +16,7 @@ class DistanceState:
class ReferenceDistanceProfileV1:
"""Reference behavior, not a claim about any external public standard."""
"""Near/Mid/Far distance presets with energy-normalized dry/room mixing."""
DISTANCE_M = {
"near": 1.00000465,
@@ -24,10 +24,8 @@ class ReferenceDistanceProfileV1:
"far": 6.40177584,
}
MINIMUM_DISTANCE_M = 0.10
# Distance profiles in the reference renderer are presentation presets,
# not an instruction to attenuate already-authored programme PCM by 1/r.
# Use an energy-normalized dry/room crossfade instead. The coefficient is
# an explicit project calibration target.
# Distance presets use an energy-normalized dry/room crossfade without
# applying 1/r attenuation to the programme PCM.
ROOM_ENERGY_COUPLING_PER_M2 = 0.01318359375
PUBLIC_ROOM_CALIBRATION_GAIN = 1.4
# Public, project-owned room coupling; it is not a SOFA or Dolby constant.
+2 -4
View File
@@ -5,12 +5,10 @@ The Rosella renderer can run either bank:
``PUBLIC_FILTERBANK`` (1)
The shared public bank of ``rosella_filterbank.py``: a 13-tap hybrid
analysis, a 6-slot high-band delay and 961 samples of analysis/synthesis
latency. This is the bank the reference implementation has always used.
latency.
``CAPTURED_FILTERBANK`` (2)
The bank the reference headphone renderer actually runs, captured from it:
an 11-tap hybrid analysis, a 3-slot high-band delay and 448 samples of
latency.
An 11-tap hybrid analysis, a 3-slot high-band delay and 448 samples of latency.
Both banks expose the same four stateful stages, so the choice changes the
coefficients, the high-band delay, the history layout and the latency together.
+6 -14
View File
@@ -1,16 +1,8 @@
"""Captured Rosella 64-QMF / 77-hybrid filterbank.
"""Rosella 64-QMF / 77-hybrid filterbank with an 11-tap hybrid analysis.
The Rosella headphone renderer selects its analysis and synthesis callbacks
during preparation, after initialization. The callbacks it actually runs are
this bank: a 640-coefficient QMF prototype, an 11-tap hybrid analysis with a
3-slot high-band delay, and a 448-sample analysis/synthesis latency. The shared
public bank lives in ``rosella_filterbank.py`` and differs in every one of those
parameters (13-tap hybrid, 6-slot delay, 961-sample latency).
The tables are the float32 values the C++ core compiles in as
``src/hrtf/rosella_filterbank_tables.h``; ``data/rosella_captured_kernels.npz``
holds the same numbers. State is float64/complex128, like the rest of the
reference implementation.
Uses a 640-coefficient QMF prototype, a 3-slot high-band delay and a 448-sample
analysis/synthesis latency. Tables in ``data/rosella_captured_kernels.npz`` are
loaded as float64/complex128; processing state uses the same precision.
"""
from __future__ import annotations
@@ -30,7 +22,7 @@ HYBRID_DELAY = 3
HYBRID_LOW_BANDS = 16
ANALYSIS_SYNTHESIS_LATENCY_SAMPLES = 448
# The captured renderer's hybrid band order: destination[k] = low[HYBRID_ORDER[k]].
# Hybrid band order: destination[k] = low[HYBRID_ORDER[k]].
HYBRID_ORDER = (0, 7, 1, 6, 2, 9, 3, 4, 10, 5, 11, 15, 8, 12, 13, 14)
# Bands 1 and 3 are conjugated after the permutation.
@@ -65,7 +57,7 @@ def _load_tables(path_string: str) -> dict[str, np.ndarray]:
def load_kernel_tables(path: str | Path = DEFAULT_CAPTURED_KERNEL_DATA
) -> dict[str, np.ndarray]:
"""Load and cache the captured Rosella kernel tables."""
"""Load and cache the 11-tap Rosella bank's kernel tables."""
return _load_tables(str(Path(path).expanduser().resolve()))
+4 -2
View File
@@ -12,15 +12,17 @@ FRAME_SAMPLES = 1536
def create_speaker_renderer(layout: str | SpeakerLayout, bed_channels=None,
trim_meta=None):
trim_meta=None, *, parameters=None):
"""Create a stateful speaker renderer and return ``(renderer, info)``."""
target = get_speaker_layout(layout) if isinstance(layout, str) else layout
renderer = PythonSpeakerRenderer(target, bed_channels=bed_channels,
trim_meta=trim_meta)
trim_meta=trim_meta, parameters=parameters)
return renderer, {
"name": "python",
"layout": target.name,
"bed_objects": len(getattr(renderer, "bed_targets", {}) or {}),
"initial_warp_mode": renderer.parameters.warp_mode,
"initial_trim_mode": renderer.parameters.trim_mode,
}
+45 -18
View File
@@ -12,9 +12,10 @@ from typing import Iterable
import numpy as np
from oamd_bits import JocFieldState, frame_update
from oamd_bits import JocFieldState, frame_update, parse_trim
from speaker_layouts import RegionGeometry, SpeakerLayout, get_speaker_layout
from trim_balance import apply_balance, balance_layers, channel_gains
from trim_balance import (SpeakerRenderParameters, apply_balance,
explicit_position_gain, parameters_from_oamd)
Q15_SCALE = 32768.0
Q15_MAX = 32767.0 / Q15_SCALE
@@ -35,9 +36,9 @@ def bed_object_targets(bed_channels) -> dict[int, tuple[float, float, float]]:
def _all_object_targets(layout: SpeakerLayout, state: JocFieldState,
bed_targets=None, balance=(0.0, 0.0)) -> np.ndarray:
bed_targets=None, parameters=None) -> np.ndarray:
bed_targets = bed_targets or {}
listener, overhead = balance
parameters = parameters or parameters_from_oamd(None, layout)
result = np.zeros((15, layout.channel_count), dtype=np.float64)
for object_index in range(1, 16):
fixed = bed_targets.get(object_index)
@@ -47,9 +48,9 @@ def _all_object_targets(layout: SpeakerLayout, state: JocFieldState,
u = state.q[(object_index, "q1")] / Q15_SCALE
v = state.q[(object_index, "q2")] / Q15_SCALE
w = state.q[(object_index, "q3")] / Q15_SCALE
v = apply_balance(v, w, listener, overhead)
result[object_index - 1] = render_point_gains(
layout, u, v, w, standard_order=False)
layout, u, v, w, standard_order=False, parameters=parameters,
bypass_trim=parameters.bypasses(object_index))
return result
@@ -175,16 +176,30 @@ def _plane_gains(region: RegionGeometry, coordinates: np.ndarray, groups,
def render_point_gains(layout: str | SpeakerLayout, u: float, v: float, w: float,
*, region_index: int = 0, enable_height: bool = True,
object_gain: float = 1.0, standard_order: bool = True) -> np.ndarray:
object_gain: float = 1.0, standard_order: bool = True,
parameters: SpeakerRenderParameters | None = None,
bypass_trim: bool = False) -> np.ndarray:
"""Render one point object to a target speaker layout using float64."""
target = get_speaker_layout(layout) if isinstance(layout, str) else layout
controls = parameters or parameters_from_oamd(None, target)
region = target.regions[int(region_index)]
coordinates = _coordinates(region)
floor_v = min(max(math.ldexp(float(v), floor_y_exponent(target.speaker_bitfield)), 0.0), 1.0)
v, w = float(v), max(float(w), 0.0)
floor_v = min(max(math.ldexp(v, floor_y_exponent(
target.speaker_bitfield, controls.warp_mode == 1)), 0.0), 1.0)
top_v = min(max(v, 0.0), 1.0)
trim_v = v
if controls.trim_mode == "explicit" and not bypass_trim:
# Apply warp -> balance for floor, balance(original Y) for
# top and trim. These coordinates must not be collapsed into one Y.
listener, overhead = controls.listener_balance, controls.overhead_balance
floor_v = apply_balance(floor_v, w, listener, overhead)
top_v = apply_balance(top_v, w, listener, overhead)
trim_v = apply_balance(v, w, listener, overhead)
floor = _plane_gains(region, coordinates, region.axis0_groups, u, floor_v, region.mode)
point_gains = floor
if region.mode == 3:
top = _plane_gains(region, coordinates, region.axis1_groups, u, float(v), 3)
top = _plane_gains(region, coordinates, region.axis1_groups, u, top_v, 3)
height = min(max(float(w) if enable_height else 0.0, 0.0), Q15_MAX)
if height >= Q15_MAX:
point_gains = top
@@ -192,7 +207,12 @@ def render_point_gains(layout: str | SpeakerLayout, u: float, v: float, w: float
floor_weight, height_weight = equal_power_pair(height)
point_gains = floor * floor_weight + top * height_weight
internal = np.zeros(target.channel_count, dtype=np.float64)
gain = position_gain(target.speaker_bitfield, v, w) * float(object_gain)
gain = float(object_gain)
if not bypass_trim:
if controls.trim_mode == "automatic":
gain *= position_gain(target.speaker_bitfield, trim_v, w)
elif controls.trim_mode == "explicit":
gain *= explicit_position_gain(controls, u, trim_v, w)
for point_gain, speaker_id in zip(point_gains, region.speaker_ids):
internal[speaker_id] = point_gain * gain
if standard_order:
@@ -213,18 +233,20 @@ class PythonSpeakerRenderer:
"""Stateful float64 speaker renderer."""
def __init__(self, layout: str | SpeakerLayout, block_size: int = 32,
bed_channels=None, trim_meta=None):
bed_channels=None, trim_meta=None, *, parameters=None):
self.layout = get_speaker_layout(layout) if isinstance(layout, str) else layout
self.block_size = int(block_size)
if self.block_size <= 0:
raise ValueError("block_size must be positive")
self.bed_targets = bed_object_targets(bed_channels)
self.trim_gains = np.asarray(channel_gains(trim_meta, self.layout),
dtype=np.float64)
self.balance = balance_layers(trim_meta, self.layout)
if parameters is not None and trim_meta is not None:
raise ValueError("pass normalized parameters or OAMD trim_meta, not both")
self._parameters_override = parameters
self._initial_parameters = parameters or parameters_from_oamd(trim_meta, self.layout)
self.reset()
def reset(self):
self.parameters = self._initial_parameters
channels = self.layout.channel_count
self._state = JocFieldState()
self._current = np.zeros((15, channels), dtype=np.float64)
@@ -235,9 +257,13 @@ class PythonSpeakerRenderer:
def _apply_payload(self, payload):
update = frame_update(payload)
if self._parameters_override is None:
trim = parse_trim(payload)
if trim is not None:
self.parameters = parameters_from_oamd(trim, self.layout)
self._state.apply(update["values"])
new_target = _all_object_targets(self.layout, self._state, self.bed_targets,
self.balance)
self.parameters)
blocks = ramp_block_count(update["ramp_duration_samples"], self.block_size)
difference = new_target - self._current
significant = np.abs(difference) >= GAIN_SNAP_THRESHOLD
@@ -306,7 +332,6 @@ class PythonSpeakerRenderer:
for payload in events_by_block.get(total_blocks, ()):
self._apply_payload(payload)
output *= self.trim_gains[None, :]
if standard_order:
return output[:, list(self.layout.internal_to_standard)]
return output
@@ -321,9 +346,11 @@ class PythonSpeakerRenderer:
def render_objects16(objects16: np.ndarray, payload_events: Iterable[tuple[int, bytes]],
layout: str | SpeakerLayout, *, block_size: int = 32,
standard_order: bool = True, output: np.ndarray | None = None) -> np.ndarray:
standard_order: bool = True, output: np.ndarray | None = None,
trim_meta=None, parameters=None) -> np.ndarray:
"""Render a complete interleaved LFE + 15 object stream."""
renderer = PythonSpeakerRenderer(layout, block_size=block_size)
renderer = PythonSpeakerRenderer(layout, block_size=block_size,
trim_meta=trim_meta, parameters=parameters)
return renderer.process(objects16, payload_events, standard_order=standard_order, output=output)
def payload_events_from_index(index, frame_count: int, *, frame_samples: int = 1536,
+96 -1
View File
@@ -24,6 +24,11 @@ the axis and it leaves the two walls untouched. See ``front_back``.
"""
from __future__ import annotations
from dataclasses import dataclass
import math
from variant_error import UnsupportedVariantError
# Layouts that carry trim and front-back balance semantics, by their compact
# names: 2.0, 3.1, 4.0, 5.1, 5.1.2, 5.1.4 and 7.1. Wider layouts leave the
# programme untrimmed.
@@ -49,6 +54,93 @@ BALANCE_STEPS = 16
WALL = 0.05
@dataclass(frozen=True)
class SpeakerRenderParameters:
"""Codec-independent, per-layout speaker controls; balances are in [-1,1].
Warp 2/3 intentionally have no rendering implementation yet. An absent
warp indication uses normal (0); no CLI override is provided.
"""
warp_mode: int = 0
trim_mode: str = "automatic"
surround_db: float = 0.0
height_db: float = 0.0
centre_db: float = 0.0
listener_balance: float = 0.0
overhead_balance: float = 0.0
disable_per_object: tuple[bool, ...] = ()
def __post_init__(self):
if self.warp_mode in (2, 3):
raise UnsupportedVariantError(
"speaker", "warp_mode_not_implemented",
"Speaker rendering implements warp modes 0/1 only; 2/3 are reserved in E-AC-3 JOC",
details={"warp_mode": self.warp_mode})
if self.warp_mode not in (0, 1):
raise ValueError(f"invalid warp mode: {self.warp_mode!r}")
if self.trim_mode not in ("automatic", "disabled", "explicit"):
raise ValueError(f"invalid trim mode: {self.trim_mode!r}")
for value in (self.surround_db, self.height_db, self.centre_db):
if not math.isfinite(value):
raise ValueError("trim levels must be finite")
for value in (self.listener_balance, self.overhead_balance):
if not math.isfinite(value) or not -1.0 <= value <= 1.0:
raise ValueError("balance must be finite and in [-1,1]")
def bypasses(self, object_index):
return (0 <= object_index < len(self.disable_per_object)
and self.disable_per_object[object_index])
def parameters_from_oamd(atmos_meta, layout):
"""Adapt OAMD calibration to one layout, without changing source positions.
A config's default/disabled flag overrides global custom mode. Missing
custom configuration falls back to automatic.
"""
meta = atmos_meta or {}
common = dict(warp_mode=meta.get("warp_mode", 0),
disable_per_object=tuple(meta.get("disable_per_obj") or ()))
if not _supported(layout):
return SpeakerRenderParameters(**common, trim_mode="disabled")
mode = meta.get("global_trim_mode", 0)
if mode == 1:
return SpeakerRenderParameters(**common, trim_mode="disabled")
if mode not in (0, 1, 2):
raise UnsupportedVariantError(
"speaker", "trim_mode_not_implemented", "Reserved OAMD global trim mode",
details={"global_trim_mode": mode})
record = _record(meta, layout) if mode == 2 else None
if not isinstance(record, dict) or record.get("default"):
return SpeakerRenderParameters(**common)
if record.get("disabled"):
return SpeakerRenderParameters(**common, trim_mode="disabled")
# Surround/height are attenuation-only. Centre retains its signed level.
return SpeakerRenderParameters(
**common, trim_mode="explicit",
surround_db=min(float(record.get("surround", 0.0)), 0.0),
height_db=min(float(record.get("height", 0.0)), 0.0),
centre_db=float(record.get("centre", 0.0)),
listener_balance=float(record.get("bal3d_y_lis", 0.0)),
overhead_balance=float(record.get("bal3d_y_tb", 0.0)))
def explicit_position_gain(parameters, x, y, z):
"""Position-dependent *object* trim, evaluated at balance(original Y).
Surround fades in over Y=0..0.5 and out towards Z=1; height fades in
with Z. Centre trim is local to the front-centre region. The resulting
scalar multiplies the object's entire speaker gain vector, before mixing.
"""
surround = min(max(2.0 * y, 0.0), 1.0) * (1.0 - z)
centre = 1.0 - min(max(10.0 * max(
abs(z) - WALL, y - WALL, abs(x - 0.5) - WALL), 0.0), 1.0)
db = (surround * min(parameters.surround_db, 0.0)
+ z * min(parameters.height_db, 0.0)
+ centre * parameters.centre_db)
return 10.0 ** (db / 20.0)
def _height_class(count):
if count == 0:
return 0
@@ -106,7 +198,10 @@ def group_levels_db(atmos_meta, layout):
def channel_gains(atmos_meta, layout):
"""Per-channel linear gain for the layout, in channel order."""
"""Legacy diagnostic group levels, not the speaker rendering operation.
Rendering uses explicit_position_gain per object before accumulation.
"""
levels = group_levels_db(atmos_meta, layout)
gains = []
for label in getattr(layout, "channels", ()):