Files
JustOneCacophony/src/speaker_renderer.py
T
TheM14 76074a05ba Put the CBA bed height row on the 62-level grid and render PCM 2.0/5.1/7.1 binaurally
The height row of the bed reference coordinates sits at ADM 62-level steps
15/62 and 47/62, not at the room corners: Tfl/Tfr, Tsl/Tsr and Tbl/Tbr move
from x = -1 / 1 to -0.516113 / 0.516113, which puts their Q15 numerators at
7928 / 24840 so every bed channel lands on its reference position instead of
being snapped to the nearest neighbour. Lw/Rw keep Y = 21/31 (5285). The
ADM-to-Q15 conversion scales by 32768, the full scale the renderer divides
by, so half-step positions such as 16384 and 7928 are no longer one count
low.

5.1, 5.1.2 and 5.1.4 keep their single surround pair at the rear corners
(y = 32767) instead of y = 16384. That family has no side pair, so its Ls/Rs
is the rear pair, which is the same point the multichannel PCM virtual
sources use; 7.1.x and 9.1.x keep Ls/Rs at 0.5 and Lrs/Rrs at 1.

Add the multichannel PCM binaural path. src/multichannel_binaural.py maps the
2.0 / 5.1 / 7.1 WAV channel order to synthetic objects (LFE on slot 0, the
full-band channels on slots 1..N in ffmpeg order, the remaining slots
silent), resamples the input to the native 48 kHz and drives the Rosella or
.jochrtf adapter. FixedPositionTimeline gives those static directions the
positions_at interface the OAMD timeline exposes, and both adapters accept an
optional fixed_positions argument instead of deriving a timeline from bed
labels.

Checked: the fifteen bed labels convert to the reference Q15 triples, the nine
output layouts agree with the layout table region by region, bed routing and
the derived direct bed labels are unchanged for every layout, and the
regression suite passes.
2026-11-18 17:05:30 +08:00

893 lines
42 KiB
Python

"""High-precision object-to-speaker renderer.
All spatial calculations, gain ramps, and object accumulation use float64. Input
PCM may be float32, but precision is reduced only when the caller explicitly
writes a lower-precision output format.
"""
from __future__ import annotations
from collections import defaultdict
from functools import lru_cache
import math
from typing import Iterable
import numpy as np
import oamd_math
from oamd_bits import JocFieldState, frame_update, parse_trim
from oamd_params import metadata_params
from variant_error import UnsupportedVariantError
from speaker_layouts import RegionGeometry, SpeakerLayout, get_speaker_layout
from trim_balance import (SpeakerRenderParameters, apply_balance,
explicit_position_gain, parameters_from_oamd)
Q15_SCALE = 32768.0
Q15_MAX = 32767.0 / Q15_SCALE
GAIN_SNAP_THRESHOLD = 1.0e-4
ZONE_TO_REGION = (0, 1, 2, 3, 4, 5, 6, 0)
LFE_BED_LABELS = ("RC_LFE", "RC_LFE2")
BED_LABEL_INDEX = {label: index + 1 for index, label in
enumerate(("RC_L", "RC_R", "RC_C", "RC_LFE",
"RC_LS", "RC_RS", "RC_LB", "RC_RB",
"RC_TFL", "RC_TFR", "RC_TSL", "RC_TSR",
"RC_TBL", "RC_TBR", "RC_LW", "RC_RW",
"RC_LFE2"))}
def _stable_norm(vector):
"""Reference vector normalization: tiny-norm floor and unit clamp."""
values = np.asarray(vector, dtype=np.float64)
total = float(np.dot(values, values))
if total == 0.0:
return np.zeros_like(values)
result = values / max(math.sqrt(total), 1.0e-5)
return np.minimum(result, 1.0)
def _region_vector(layout, region_index, u, floor_v, top_v, w,
enable_height):
"""Uncompensated point-source vector in ``layout`` internal order."""
region = layout.regions[int(region_index)]
coordinates = _coordinates(region)
floor = _plane_gains(region, coordinates, region.axis0_groups, u,
floor_v, region.mode)
gains = floor
if region.mode == 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:
gains = top
elif height > 0.0:
floor_weight, height_weight = equal_power_pair(height)
gains = floor * floor_weight + top * height_weight
vector = np.zeros(layout.channel_count, dtype=np.float64)
for value, speaker in zip(gains, region.speaker_ids):
vector[speaker] = value
return vector
def _fold_vector(calc, final, warp_mode, vector):
"""Apply the existing warp 2/3 surround fold to a calculation vector."""
if calc is final:
return vector
return (_surround_fold_matrix(calc.speaker_bitfield,
final.speaker_bitfield, warp_mode)
@ vector)
def bed_object_targets(bed_channels) -> dict[int, tuple[float, float, float]]:
"""JOC 对象槽 → 固定方位 ``(u, v, w)``;只包含 bed 声道。
bed 声道的方位由声道标签定义,与目标扬声器布局无关:同一个声道无论输出哪种
布局都落在同一个源位置,再交给与动态对象相同的点声源渲染路径。LFE 不占对象
槽,单独处理。
"""
from bed_layout import adm_xyz_to_render_coordinates, bed_object_positions
return {slot: adm_xyz_to_render_coordinates(*xyz)
for slot, xyz in bed_object_positions(bed_channels or ()).items()}
def _all_object_targets(layout: SpeakerLayout, state: JocFieldState,
bed_targets=None, parameters=None) -> np.ndarray:
bed_targets = bed_targets or {}
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)
if fixed is not None:
u, v, w = fixed
else:
u = state.q[(object_index, "q1")] / Q15_SCALE
v = state.q[(object_index, "q2")] / Q15_SCALE
w = state.q[(object_index, "q3")] / Q15_SCALE
result[object_index - 1] = render_point_gains(
layout, u, v, w, standard_order=False, parameters=parameters,
bypass_trim=parameters.bypasses(object_index))
return result
def expand_speaker_bitfield(compact_mask: int, center_height: bool = False) -> int:
"""Expand the compact target-layout bitfield into individual speakers."""
expansions = (
0x00000003, 0x00000004, 0x00000008, 0x00000030,
0x000000C0, 0x00000100, 0x00000600, 0x00001800,
0x00006000, 0x00018000, 0x00060000, 0x00180000,
0x00600000, 0x01800000, 0x06000000, 0x18000000,
0x60000000, 0x080000000, 0x600000000, 0x800000000,
0x1000000000, 0x2000000000,
)
expanded = 0
for bit, value in enumerate(expansions):
if int(compact_mask) & (1 << bit):
expanded |= value
if center_height:
expanded |= 0x4000000000
return expanded
def layout_attenuation_db(compact_mask: int) -> float:
"""Compute the layout-dependent maximum positional compensation in dB."""
expanded = expand_speaker_bitfield(compact_mask)
height_channels = 2 * sum((expanded >> bit) & 1 for bit in (13, 15, 17, 19, 21))
floor_channels = ((expanded >> 8) & 1) + 2 * sum(
(expanded >> bit) & 1 for bit in (31, 4, 6, 11, 25, 27, 29, 33)
)
height_factor = min(height_channels / 4.0, 1.0)
floor_factor = min(floor_channels / 4.0, 1.0)
return -max(4.5 - 1.5 * height_factor - 3.0 * floor_factor, 0.0)
def floor_y_exponent(compact_mask: int, metadata_scaling_enabled: bool = True) -> int:
if not metadata_scaling_enabled:
return 0
low_mask = expand_speaker_bitfield(compact_mask) & 0xFFFFFFFF
return int(bool(low_mask & 0x130) and not bool(low_mask & 0x18C0))
def position_gain(compact_mask: int, v: float, w: float) -> float:
"""Return the high-precision position-dependent layout compensation."""
y_term = min(max(float(v) / 0.6, 0.0), 1.0)
z_term = min(max((float(w) - 0.2) / 0.8, 0.0), 1.0)
amount = min(max(y_term + z_term, 0.0), 1.0)
return math.pow(10.0, layout_attenuation_db(compact_mask) * amount / 20.0)
def equal_power_pair(position: float) -> tuple[float, float]:
angle = math.pi * 0.5 * float(position)
return math.cos(angle), math.sin(angle)
def _coordinates(region: RegionGeometry) -> np.ndarray:
return np.asarray(region.coordinates_q15, dtype=np.float64) / Q15_SCALE
def _normalized(value: float, lower: float, upper: float) -> float:
return (float(value) - float(lower)) / (float(upper) - float(lower))
def _axis0_gains(region: RegionGeometry, coordinates: np.ndarray, value: float) -> np.ndarray:
result = np.zeros(len(region.speaker_ids), dtype=np.float64)
position = float(value)
for group in region.axis0_groups:
if not group:
continue
first, last = group[0], group[-1]
if position <= coordinates[first, 0]:
result[first] = 1.0
continue
if position >= coordinates[last, 0]:
result[last] = 1.0
continue
for lower_index, upper_index in zip(group, group[1:]):
lower = coordinates[lower_index, 0]
upper = coordinates[upper_index, 0]
if position > lower and position <= upper:
result[lower_index], result[upper_index] = equal_power_pair(
_normalized(position, lower, upper)
)
break
return result
def _axis1_gains(region: RegionGeometry, coordinates: np.ndarray, groups,
value: float) -> np.ndarray:
result = np.zeros(len(region.speaker_ids), dtype=np.float64)
if not groups:
return result
position = float(value)
first_value = coordinates[groups[0][0], 1]
last_value = coordinates[groups[-1][0], 1]
if position <= first_value:
result[list(groups[0])] = 1.0
return result
if position > last_value:
result[list(groups[-1])] = 1.0
return result
for lower_group, upper_group in zip(groups, groups[1:]):
lower = coordinates[lower_group[0], 1]
upper = coordinates[upper_group[0], 1]
if position >= lower and position <= upper:
lower_gain, upper_gain = equal_power_pair(_normalized(position, lower, upper))
result[list(lower_group)] = lower_gain
result[list(upper_group)] = upper_gain
break
return result
def _plane_gains(region: RegionGeometry, coordinates: np.ndarray, groups,
u: float, v: float, mode: int) -> np.ndarray:
gains = _axis0_gains(
RegionGeometry(region.coordinates_q15, region.speaker_ids, tuple(groups), (), region.mode),
coordinates,
u,
)
if mode >= 2:
gains *= _axis1_gains(region, coordinates, groups, v)
return gains
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,
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)
source = _surround_fold_layout(target) if controls.warp_mode in (2, 3) else target
# Geometry may expand to 7.1.x; calibration always uses the final layout.
internal = _render_point_gains(source, u, v, w, region_index=region_index,
enable_height=enable_height, object_gain=object_gain,
parameters=controls, bypass_trim=bypass_trim,
compensation_bitfield=target.speaker_bitfield)
if source is not target:
internal = _surround_fold_matrix(source.speaker_bitfield, target.speaker_bitfield,
controls.warp_mode) @ internal
if standard_order:
return internal[list(target.internal_to_standard)]
return internal
@lru_cache(maxsize=16)
def _surround_fold_layout(target: SpeakerLayout) -> SpeakerLayout:
"""Add a rear pair for one-pair surround layouts, keeping the height layer."""
if not floor_y_exponent(target.speaker_bitfield):
return target
expanded = {"51": "71", "512": "712", "514": "714"}
if target.name in expanded:
return get_speaker_layout(expanded[target.name])
if target.name == "60":
return target
if target.name != "40":
raise ValueError(f"unsupported surround fold layout: {target.name}")
# 4.0 expands to six full-band speakers without adding centre or LFE.
base = get_speaker_layout("71")
regions = []
speaker_ids = {0: 0, 1: 1, 4: 2, 5: 3, 6: 4, 7: 5}
for region in base.regions:
kept = [i for i, speaker in enumerate(region.speaker_ids) if speaker in speaker_ids]
indices = {old: new for new, old in enumerate(kept)}
def groups(items):
return tuple(tuple(indices[i] for i in group if i in indices)
for group in items if any(i in indices for i in group))
regions.append(RegionGeometry(
tuple(region.coordinates_q15[i] for i in kept),
tuple(speaker_ids[region.speaker_ids[i]] for i in kept),
groups(region.axis0_groups), groups(region.axis1_groups), region.mode))
return SpeakerLayout("60", 255, target.speaker_bitfield | 0x10,
("L", "R", "Ls", "Rs", "Lrs", "Rrs"),
tuple(range(6)), tuple(regions))
@lru_cache(maxsize=32)
def _surround_fold_matrix(source_bitfield: int, target_bitfield: int,
warp_mode: int) -> np.ndarray:
"""Copy shared speakers and fold the rear pair into the target surround pair."""
def speakers(bitfield):
mask = expand_speaker_bitfield(bitfield)
return tuple(i for i in range(mask.bit_length()) if mask & (1 << i))
source, target = speakers(source_bitfield), speakers(target_bitfield)
matrix = np.zeros((len(target), len(source)), dtype=np.float64)
same_side, cross_side = (math.sqrt(3.0) / 2.0, 0.5) if warp_mode == 2 else (1.0, 0.0)
# Speaker IDs 4/5 are side surrounds; 6/7 are the rear pair.
for column, speaker in enumerate(source):
if speaker in target:
matrix[target.index(speaker), column] = 1.0
elif speaker in (6, 7):
matrix[target.index(speaker - 2), column] = same_side
matrix[target.index(5 if speaker == 6 else 4), column] = cross_side
matrix.flags.writeable = False
return matrix
def _render_point_gains(target: SpeakerLayout, u: float, v: float, w: float,
*, region_index: int, enable_height: bool, object_gain: float,
parameters: SpeakerRenderParameters, bypass_trim: bool,
compensation_bitfield: int) -> np.ndarray:
"""Evaluate point gains before any surround fold or output-channel reorder."""
controls = parameters
region = target.regions[int(region_index)]
coordinates = _coordinates(region)
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 != 0)), 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, 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
elif height > 0.0:
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 = float(object_gain)
if not bypass_trim:
if controls.trim_mode == "automatic":
gain *= position_gain(compensation_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
return internal
def align_metadata_sample(sample: int, block_size: int = 32) -> int:
return block_size * ((int(sample) + block_size // 2 - 1) // block_size)
def ramp_block_count(duration_samples: int, block_size: int = 32,
rate_scale: int = 1) -> int:
return (int(duration_samples) * int(rate_scale) + block_size // 2 - 1) // block_size
class PythonSpeakerRenderer:
"""Stateful float64 speaker renderer.
Two input shapes are accepted. Payloads that expand to block-level object
state (``frame_update`` with ``object_blocks``) use the metadata path:
object gain/inactive, region/elevation, size/snap/divergence/refinement,
priority budget, ISF and bed distribution. Older payload dictionaries keep
the previous point-position path so existing callers and tests still work.
"""
def __init__(self, layout: str | SpeakerLayout, block_size: int = 32,
bed_channels=None, trim_meta=None, *, parameters=None,
size_budget: int = 0):
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)
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._size_budget = int(size_budget)
if self._size_budget < 0:
raise ValueError("size_budget must be non-negative")
self._raw_trim_mode = (trim_meta or {}).get("global_trim_mode", 0)
self._meta_params = metadata_params()
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)
self._target = np.zeros_like(self._current)
self._step = np.zeros_like(self._current)
self._remaining = np.zeros((15, channels), dtype=np.int32)
self._window = np.arange(self.block_size, dtype=np.float64) / float(self.block_size)
self._meta_mode = False
self._meta_ready = False
self._n_meta = 0
self._meta_slots: list[int | None] = []
self._meta_labels: list[str | None] = []
self._mc = None
self._mt = None
self._ms = None
self._mr = None
# -------------------------------------------------------------- metadata state
def _update_trim(self, payload, update=None):
trim = update.get("trim") if update is not None else None
if trim is None and update is None:
trim = parse_trim(payload)
if trim is not None and self._parameters_override is None:
self.parameters = parameters_from_oamd(trim, self.layout)
if isinstance(trim, dict) and "global_trim_mode" in trim:
self._raw_trim_mode = trim["global_trim_mode"]
def _init_meta(self, update):
self._isf_cache = {}
program = update["program"]
kinds = update["kinds"]
count = int(update["object_count"])
labels = [label for group in program["bed_channels"] for label in group]
num_bed = int(program["num_bed_objects"])
if len(labels) != num_bed:
if program["dynamic_object_only"]:
labels = ["RC_LFE"] if program["lfe_present"] else []
if len(labels) != num_bed:
raise UnsupportedVariantError(
"speaker", "bed_declaration_mismatch",
"OAMD bed 声明数量与节目分区不一致",
details={"declared": len(labels), "num_bed_objects": num_bed})
slots = []
slot = 1
for object_index, kind in enumerate(kinds):
label = labels[object_index] if object_index < len(labels) else None
if kind == "bed" and label in LFE_BED_LABELS:
slots.append(0)
else:
if slot > 15:
raise UnsupportedVariantError(
"speaker", "object_slot_overflow",
"元数据对象数量超出 15 个 JOC 对象槽",
details={"object_count": count})
slots.append(slot)
slot += 1
if not program["dynamic_object_only"]:
declared = program["num_dynamic_objects"]
if (declared is not None
and num_bed + int(program["num_isf_objects"]) + int(declared)
!= count):
raise UnsupportedVariantError(
"speaker", "program_object_count_mismatch",
"OAMD 节目声明的对象分区与对象数不一致",
details={"object_count": count,
"num_bed_objects": num_bed,
"num_isf_objects": program["num_isf_objects"],
"num_dynamic_objects": declared})
if program["num_isf_objects"]:
isf_idx = program["isf_idx"]
config = (self._meta_params["isf"]["configs"][isf_idx]
if isf_idx is not None and isf_idx < 6 else None)
if config is None or config["counts"][4] != program["num_isf_objects"]:
raise UnsupportedVariantError(
"speaker", "isf_configuration_mismatch",
"ISF 配置数量与节目声明不一致",
details={"isf_idx": isf_idx,
"num_isf_objects": program["num_isf_objects"]})
if count != self._n_meta or slots != self._meta_slots:
channels = self.layout.channel_count
self._n_meta = count
self._meta_slots = slots
self._mc = np.zeros((count, channels), dtype=np.float64)
self._mt = np.zeros((count, channels), dtype=np.float64)
self._ms = np.zeros((count, channels), dtype=np.float64)
self._mr = np.zeros((count, channels), dtype=np.int32)
self._meta_labels = [labels[object_index]
if object_index < len(labels) else None
for object_index in range(count)]
self._meta_mode = True
def _block_targets(self, update, block_index):
count = int(update["object_count"])
channels = self.layout.channel_count
targets = np.zeros((count, channels), dtype=np.float64)
blocks = update["object_blocks"]
kinds = update["kinds"]
zero_size = set()
size_objects = []
for object_index in range(count):
state = blocks[object_index][block_index]
if (kinds[object_index] == "dynamic" and not state["not_active"]
and state["size_mode"] in (1, 2)
and not state["snap"] and state["divergence_q"] == 0):
size_objects.append(object_index)
if 0 < self._size_budget < len(size_objects):
ranked = sorted(
size_objects,
key=lambda index: (-((int(blocks[index][block_index]["priority_q"])
+ 512) >> 10), index))
zero_size = set(ranked[self._size_budget:])
for object_index in range(count):
state = blocks[object_index][block_index]
if state["not_active"]:
continue
spatial = self._object_spatial(update, object_index, block_index,
object_index in zero_size)
gain = float(state["gain_q"]) / 4096.0
targets[object_index] = spatial * gain
return targets
def _object_spatial(self, update, object_index, block_index, force_zero_size):
kind = update["kinds"][object_index]
if kind == "dynamic":
return self._dynamic_spatial(update, object_index, block_index,
force_zero_size)
if kind == "bed":
return self._bed_spatial(update, object_index)
if kind == "isf":
return self._isf_spatial(update, object_index)
return np.zeros(self.layout.channel_count, dtype=np.float64)
# -------------------------------------------------------------- dynamic path
def _dynamic_spatial(self, update, object_index, block_index,
force_zero_size):
state = update["object_blocks"][object_index][block_index]
final = self.layout
warp = self.parameters.warp_mode
calc = _surround_fold_layout(final) if warp in (2, 3) else final
region_index = ZONE_TO_REGION[int(state["zone_idx"]) & 7]
u = float(state["qx"]) / Q15_SCALE
v = float(state["qy"]) / Q15_SCALE
w = max(float(state["qz"]) / Q15_SCALE, 0.0)
enable_height = bool(state["enable_elevation"])
if not enable_height:
w = 0.0
bypass = self.parameters.bypasses(object_index)
floor_v = min(max(math.ldexp(v, floor_y_exponent(
calc.speaker_bitfield, warp != 0)), 0.0), 1.0)
top_v = min(max(v, 0.0), 1.0)
trim_v = v
if self.parameters.trim_mode == "explicit" and not bypass:
listener = self.parameters.listener_balance
overhead = self.parameters.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)
region = calc.regions[region_index]
coordinates = _coordinates(region)
if state["snap"]:
point = _region_vector(calc, region_index, u, floor_v, top_v, w,
enable_height)
best = -1.0
chosen = 0
for index, speaker in enumerate(region.speaker_ids):
value = float(point[speaker])
if value > best:
best = value
chosen = index
speaker_u, speaker_v, speaker_w = coordinates[chosen]
scale = 1.0
distance = ((u - speaker_u) ** 2
+ (min(v, scale) - scale * speaker_v) ** 2
+ (w - speaker_w) ** 2)
if distance < 0.04:
vector = np.zeros(calc.channel_count, dtype=np.float64)
vector[region.speaker_ids[chosen]] = 1.0
comp = (float(speaker_u), float(speaker_v), float(speaker_w))
else:
vector = point
comp = (u, trim_v, w)
elif state["divergence_q"] > 0:
spread = min(float(state["divergence_q"]) / Q15_SCALE, u, 1.0 - u)
left = _region_vector(calc, region_index, u - spread, floor_v,
top_v, w, enable_height)
right = _region_vector(calc, region_index, u + spread, floor_v,
top_v, w, enable_height)
vector = _stable_norm(left + right)
comp = (u, trim_v, w)
elif state["size_mode"] in (1, 2) and not force_zero_size:
size_q = state["size_q"]
if size_q[0] == size_q[1] == size_q[2]:
q_size = int(size_q[0])
else:
q_size = (int(size_q[0]) + int(size_q[1]) + int(size_q[2])) // 3
size = q_size / Q15_SCALE
t = oamd_math.size_curve_value(size)
point = _region_vector(calc, region_index, u, floor_v, top_v, w,
enable_height)
if t < 0.000025:
vector = point
else:
query = (u, (1.0 - w) * floor_v + w * top_v, w)
spread = np.asarray(oamd_math.size_targets(
self._meta_params, calc, region_index, query, size,
height=enable_height), dtype=np.float64)
if t > 0.05:
vector = spread
else:
angle = 20.0 * t
if angle >= 0.99996948:
cosine, sine = 0.0, 1.0
else:
cosine = math.cos(angle * math.pi / 2.0)
sine = math.sin(angle * math.pi / 2.0)
vector = _stable_norm(0.5 * cosine * point
+ 0.5 * sine * spread)
comp = (u, trim_v, w)
else:
vector = _region_vector(calc, region_index, u, floor_v, top_v, w,
enable_height)
comp = (u, trim_v, w)
compensation = 1.0
if not bypass:
if self.parameters.trim_mode == "automatic":
compensation = position_gain(final.speaker_bitfield,
comp[1], comp[2])
elif self.parameters.trim_mode == "explicit":
compensation = explicit_position_gain(self.parameters,
comp[0], comp[1], comp[2])
return _fold_vector(calc, final, warp, vector) * compensation
# -------------------------------------------------------------- bed path
def _bed_spatial(self, update, object_index):
final = self.layout
warp = self.parameters.warp_mode
calc = _surround_fold_layout(final) if warp in (2, 3) else final
label = self._meta_labels[object_index]
bed_index = BED_LABEL_INDEX.get(label)
if bed_index is None:
return np.zeros(final.channel_count, dtype=np.float64)
program = update["program"]
route, weights = oamd_math.bed_distribution(
calc.name, bed_index, int(program["bed_mask"]),
bool(program["b_bed_chan_distribute"]))
bypass = self.parameters.bypasses(object_index)
mode = {"automatic": 0, "disabled": 1, "explicit": 2}[
self.parameters.trim_mode]
if route != -1:
position = oamd_math.bed_reference_position(calc.name, route)
qx, qy, qz = (int(value) for value in position)
if qz > 0:
qx = 32767 if qx > 16384 else 0
u, v = qx / Q15_SCALE, qy / Q15_SCALE
w = max(qz, 0) / Q15_SCALE
floor_v = min(max(math.ldexp(v, floor_y_exponent(
calc.speaker_bitfield, warp != 0)), 0.0), 1.0)
top_v = min(max(v, 0.0), 1.0)
vector = _region_vector(calc, 0, u, floor_v, top_v, w, True)
compensation = 1.0
if not bypass and self.parameters.trim_mode != "disabled":
if self.parameters.trim_mode == "automatic":
compensation = position_gain(final.speaker_bitfield, v, w)
else:
compensation = explicit_position_gain(
self.parameters, u, v, w)
else:
vector = np.asarray(weights, dtype=np.float64).copy()
levels = (self.parameters.surround_db,
self.parameters.height_db,
self.parameters.centre_db)
compensation = float(oamd_math.bed_compensation(
final.name, bed_index, mode, bypass, levels))
return _fold_vector(calc, final, warp, vector) * compensation
# -------------------------------------------------------------- ISF path
def _isf_spatial(self, update, object_index):
program = update["program"]
isf_idx = int(program["isf_idx"])
row = object_index - int(program["num_bed_objects"])
final = self.layout
warp = self.parameters.warp_mode
calc = _surround_fold_layout(final) if warp in (2, 3) else final
key = (calc.name, isf_idx)
matrix = self._isf_cache.get(key)
if matrix is None:
matrix = oamd_math.isf_matrix(self._meta_params, calc.name, isf_idx)
self._isf_cache[key] = matrix
vector = np.asarray(matrix[row], dtype=np.float64)
disabled = (int(self._raw_trim_mode) == 1
or self.parameters.bypasses(object_index))
compensation = float(oamd_math.isf_compensation(
self._meta_params, final.name, isf_idx, row, disabled))
return _fold_vector(calc, final, warp, vector) * compensation
# -------------------------------------------------------------- scheduling
def _apply_meta_targets(self, targets, ramp_samples):
channels = self.layout.channel_count
if self._mc is None or self._mc.shape != (len(targets), channels):
self._mc = np.zeros((len(targets), channels), dtype=np.float64)
self._mt = np.zeros_like(self._mc)
self._ms = np.zeros_like(self._mc)
self._mr = np.zeros((len(targets), channels), dtype=np.int32)
difference = np.asarray(targets, dtype=np.float64) - self._mc
significant = np.abs(difference) >= GAIN_SNAP_THRESHOLD
self._mt[...] = targets
self._mc[~significant] = self._mt[~significant]
self._ms[~significant] = 0.0
self._mr[~significant] = 0
blocks = ramp_block_count(int(ramp_samples), self.block_size)
if blocks:
self._ms[significant] = difference[significant] / float(blocks)
self._mr[significant] = blocks
else:
self._mc[significant] = self._mt[significant]
self._ms[significant] = 0.0
self._mr[significant] = 0
self._meta_ready = True
def _schedule_payload(self, update, event_sample):
if "object_blocks" not in update or not update["object_count"]:
return False
if update.get("trim") is not None:
self._update_trim(None, update)
self._init_meta(update)
for block_index, block in enumerate(update["blocks"]):
sample = (int(event_sample) + int(update["sample_offset"])
+ int(block["block_offset_samples"]))
aligned = align_metadata_sample(sample, self.block_size)
targets = self._block_targets(update, block_index)
self._pending.setdefault(aligned // self.block_size, []).append(
(targets, block["ramp_duration_samples"]))
return True
# -------------------------------------------------------------- legacy path
def _apply_legacy(self, update):
trim = parse_trim(self._current_payload)
if trim is not None and self._parameters_override is 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.parameters)
blocks = ramp_block_count(update["ramp_duration_samples"], self.block_size)
difference = new_target - self._current
significant = np.abs(difference) >= GAIN_SNAP_THRESHOLD
self._target[...] = new_target
self._current[~significant] = new_target[~significant]
self._step[~significant] = 0.0
self._remaining[~significant] = 0
if blocks:
self._step[significant] = difference[significant] / float(blocks)
self._remaining[significant] = blocks
else:
self._current[significant] = new_target[significant]
self._step[significant] = 0.0
self._remaining[significant] = 0
def _apply_payload(self, payload):
self._current_payload = payload
update = frame_update(payload)
if "object_blocks" in update and update["object_count"]:
self._update_trim(payload, update)
self._init_meta(update)
targets = self._block_targets(update, 0)
self._apply_meta_targets(targets,
update["blocks"][0]["ramp_duration_samples"])
else:
self._apply_legacy(update)
# -------------------------------------------------------------- process
def _render_meta_block(self, source, start, stop, out_block):
for object_index in range(self._n_meta):
slot = self._meta_slots[object_index]
if slot is None:
continue
active = self._mr[object_index] > 0
gains = np.broadcast_to(self._mt[object_index],
(self.block_size, self.layout.channel_count)).copy()
if np.any(active):
gains[:, active] = (
self._mc[object_index, active][None, :]
+ self._window[:, None] * self._ms[object_index, active][None, :]
)
out_block += source[start:stop, slot, None] * gains
if np.any(active):
self._mc[object_index, active] += self._ms[object_index, active]
self._mr[object_index, active] -= 1
finished = self._mr[object_index] == 0
self._mc[object_index, finished] = self._mt[object_index, finished]
def _render_legacy_block(self, source, start, stop, out_block):
channels = self.layout.channel_count
if "LFE" in self.layout.channels:
out_block[:, 3] = source[start:stop, 0].astype(np.float64, copy=False)
for object_index in range(15):
active = self._remaining[object_index] > 0
gains = np.broadcast_to(self._target[object_index],
(self.block_size, channels)).copy()
if np.any(active):
gains[:, active] = (
self._current[object_index, active][None, :]
+ self._window[:, None] * self._step[object_index, active][None, :]
)
out_block += (
source[start:stop, object_index + 1, None].astype(np.float64, copy=False)
* gains
)
if np.any(active):
self._current[object_index, active] += self._step[object_index, active]
self._remaining[object_index, active] -= 1
finished = self._remaining[object_index] == 0
self._current[object_index, finished] = self._target[object_index, finished]
def process(self, objects16: np.ndarray, events=(), *, standard_order: bool = True,
output: np.ndarray | None = None) -> np.ndarray:
source = np.asarray(objects16)
if source.ndim != 2 or source.shape[1] != 16:
raise ValueError(f"objects16 must have shape [samples,16], got {source.shape}")
if len(source) % self.block_size:
raise ValueError(f"sample count must be divisible by {self.block_size}")
total_samples = len(source)
channels = self.layout.channel_count
if output is None:
output = np.zeros((total_samples, channels), dtype=np.float64)
elif output.shape != (total_samples, channels) or output.dtype != np.float64:
raise ValueError((output.shape, output.dtype))
else:
output[...] = 0.0
events_by_block: dict[int, list[tuple[int, bytes]]] = defaultdict(list)
for sample_offset, payload in events:
if not 0 <= int(sample_offset) <= total_samples:
raise ValueError(f"metadata offset outside process call: {sample_offset}")
block = align_metadata_sample(sample_offset, self.block_size) // self.block_size
events_by_block[block].append((align_metadata_sample(
sample_offset, self.block_size), bytes(payload)))
self._pending: dict[int, list] = {}
total_blocks = total_samples // self.block_size
for block in range(total_blocks):
for event_sample, payload in events_by_block.get(block, ()):
update = frame_update(payload)
if "object_blocks" in update and update["object_count"]:
self._schedule_payload(update, event_sample)
else:
self._current_payload = payload
self._apply_legacy(update)
for targets, ramp_samples in self._pending.pop(block, ()):
self._apply_meta_targets(targets, ramp_samples)
start = block * self.block_size
stop = start + self.block_size
out_block = output[start:stop]
if self._meta_mode and self._meta_ready:
self._render_meta_block(source, start, stop, out_block)
else:
self._render_legacy_block(source, start, stop, out_block)
for event_sample, payload in events_by_block.get(total_blocks, ()):
update = frame_update(payload)
if "object_blocks" in update and update["object_count"]:
self._schedule_payload(update, event_sample)
else:
self._current_payload = payload
self._apply_legacy(update)
for targets, ramp_samples in self._pending.pop(total_blocks, ()):
self._apply_meta_targets(targets, ramp_samples)
for block_index in sorted(self._pending):
for targets, ramp_samples in self._pending[block_index]:
self._apply_meta_targets(targets, ramp_samples)
self._pending.clear()
if standard_order:
return output[:, list(self.layout.internal_to_standard)]
return output
def render_frame(self, objects16, payload=None, metadata_offset=1473):
source = np.asarray(objects16)
if source.shape != (1536, 16):
raise ValueError(f"frame must have shape (1536,16), got {source.shape}")
events = () if payload is None else ((int(metadata_offset), bytes(payload)),)
return self.process(source, events)
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,
trim_meta=None, parameters=None, size_budget: int = 0) -> np.ndarray:
"""Render a complete interleaved LFE + 15 object stream."""
renderer = PythonSpeakerRenderer(layout, block_size=block_size,
trim_meta=trim_meta, parameters=parameters,
size_budget=size_budget)
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,
payload_id: int = 11, outer_offset_samples: int = 1473):
for frame, row in enumerate(index.rows[:frame_count]):
subpayloads = index.subpayloads(row)
if payload_id in subpayloads:
timing = frame_update(subpayloads[payload_id])
yield (
frame * frame_samples + outer_offset_samples
+ int(timing["sample_offset"]),
subpayloads[payload_id],
)