Carry OAMD object render metadata into the ADM BWF

The ADM writer only exported object positions, so the size, gain and divergence
present in the E-AC-3 JOC metadata never reached the ADM BWF.

build_adm_tracks now keeps the per-object render state that frame_state()
already produces (gain, size, divergence, snap).  The state is carried across
frames without an OAMD payload and a snapshot is attached to every ADM
keyframe; inactive objects write gain 0 so their PCM is muted in the ADM.
Divergence follows the speaker renderer's per-payload behaviour: it is taken
from the current payload and is 0 when the extended element does not carry it,
rather than holding a stale value.

adm_serializer writes the metadata on each audioBlockFormat:
  - size -> width/height/depth (relative units 0..1, OAMD width/depth/height
    order; all three are written together);
  - gain -> gain gainUnit="linear" (only when it is not unity);
  - divergence -> objectDivergence positionRange (only when non-zero).
Defaults (point source, 0 dB, no divergence) omit the elements, so existing
outputs are unchanged.

Verified on a 30 s E-AC-3 JOC excerpt: PCM and the default axml stay
byte-identical to the previous writer, the ADM validator passes, and a
metadata-override ADM carries width/height/depth with unchanged PCM.  The
speaker controls tests still pass.
This commit is contained in:
TheM14 committed 2026-11-12 02:00:12 +08:00
1 parent 5fe0b16c51
commit 7de17a8576
2 files changed
+99 -24

No files matched your search

+32 -2
View File
@@ -85,9 +85,36 @@ def _atmos_master_block(atmos_meta):
return lines return lines
def build_axml(obj_tracks, duration_sec, atmos_meta=None): def _object_meta_lines(meta):
"""obj_tracks: [(name, [(rtime, x, y, z, dur), ...]) ×15] """把 OAMD 的逐对象渲染参数写成 ADM 的 audioBlockFormat 子元素。
只写 ADM 能表达的字段:size → width/height/depth(相对单位 0..1),
gain → gain(线性),divergence → objectDivergence(笛卡尔坐标系用
positionRange)。缺省值(size 0、gain 1.0、divergence 0)省略。
"""
if not meta:
return []
lines = []
size = meta.get("size") or (0.0, 0.0, 0.0)
# OAMD 的 size 三轴顺序为 width, depth, height。
width, depth, height = size
if width > 0.0 or depth > 0.0 or height > 0.0:
lines.append(f'<width>{width:.6f}</width>')
lines.append(f'<height>{height:.6f}</height>')
lines.append(f'<depth>{depth:.6f}</depth>')
gain = meta.get("gain")
if gain is not None and abs(float(gain) - 1.0) > 1e-9:
lines.append(f'<gain gainUnit="linear">{float(gain):.6f}</gain>')
divergence = meta.get("divergence")
if divergence is not None and float(divergence) > 0.0:
lines.append(f'<objectDivergence positionRange="{float(divergence):.6f}"/>')
return lines
def build_axml(obj_tracks, duration_sec, atmos_meta=None):
"""obj_tracks: [(name, [(rtime, x, y, z, dur, interpolation, meta), ...]) ×15]
``meta`` 可省略;给出时写 width/height/depth、gain、objectDivergence。
``atmos_meta`` 为 ``oamd_bits.parse_trim`` 的结果;给出时把 trim 与 warp ``atmos_meta`` 为 ``oamd_bits.parse_trim`` 的结果;给出时把 trim 与 warp
写进 ADM。 写进 ADM。
""" """
@@ -153,6 +180,7 @@ def build_axml(obj_tracks, duration_sec, atmos_meta=None):
for k, keyframe in enumerate(kfs): for k, keyframe in enumerate(kfs):
t, x, y, z, dur = keyframe[:5] t, x, y, z, dur = keyframe[:5]
interpolation = keyframe[5] if len(keyframe) > 5 else 0.0 interpolation = keyframe[5] if len(keyframe) > 5 else 0.0
meta = keyframe[6] if len(keyframe) > 6 else None
a(f'<audioBlockFormat audioBlockFormatID="AB_0003{0x1001 + i:04x}_{k + 1:08x}" ' a(f'<audioBlockFormat audioBlockFormatID="AB_0003{0x1001 + i:04x}_{k + 1:08x}" '
f'rtime="{ts(t)}" duration="{ts(dur)}">') f'rtime="{ts(t)}" duration="{ts(dur)}">')
a('<cartesian>1</cartesian>') a('<cartesian>1</cartesian>')
@@ -160,6 +188,8 @@ def build_axml(obj_tracks, duration_sec, atmos_meta=None):
a(f'<position coordinate="Y">{y:.10f}</position>') a(f'<position coordinate="Y">{y:.10f}</position>')
if z != 0: if z != 0:
a(f'<position coordinate="Z">{z:.10f}</position>') a(f'<position coordinate="Z">{z:.10f}</position>')
for line in _object_meta_lines(meta):
a(line)
a(f'<jumpPosition interpolationLength="{interpolation:.5f}">1</jumpPosition>') a(f'<jumpPosition interpolationLength="{interpolation:.5f}">1</jumpPosition>')
a('</audioBlockFormat>') a('</audioBlockFormat>')
a('</audioChannelFormat>') a('</audioChannelFormat>')
+67 -22
View File
@@ -3,7 +3,7 @@ import math
from adm_atmos import q_to_adm_xyz from adm_atmos import q_to_adm_xyz
from bed_layout import bed_object_positions from bed_layout import bed_object_positions
from oamd_bits import JocFieldState, frame_update, parse_trim from oamd_bits import JocFieldState, frame_state, frame_update, parse_trim
from variant_error import UnsupportedVariantError from variant_error import UnsupportedVariantError
# 元数据更新时刻按渲染器处理块对齐,与 Dolby 的 processing_block_size 及 # 元数据更新时刻按渲染器处理块对齐,与 Dolby 的 processing_block_size 及
@@ -19,12 +19,42 @@ def align_metadata_sample(sample, block_samples=METADATA_BLOCK_SAMPLES):
return block * ((int(sample) + block // 2 - 1) // block) return block * ((int(sample) + block // 2 - 1) // block)
def _default_meta():
"""ADM 缺省渲染参数:点源、0 dB、无 divergence。"""
return {"gain": 1.0, "size": (0.0, 0.0, 0.0), "divergence": 0.0,
"snap": False}
def _apply_state(meta, state):
"""把一帧 OAMD 对象状态合并进跨帧保持的渲染参数。
语义与 ``PythonSpeakerRenderer`` 的 metadata 路径一致:动态对象 block 0
的 gain/size/snap 每帧都显式出现;divergence 只在扩展元素里出现,缺失时
渲染器按 0 处理,因此这里也直接取 0,而不是保持旧值。未激活对象由渲染器
静音,ADM 对象轨本身仍携带 PCM,必须写 gain=0。
"""
if state.get("kind") != "dynamic":
return
if state.get("not_active"):
meta["gain"] = 0.0
return
if state.get("render_status") == 1:
size = (0.0, 0.0, 0.0)
if state.get("size_mode") in (1, 2):
size = tuple(min(max(float(value) / 32767.0, 0.0), 1.0)
for value in state.get("size_q", (0, 0, 0)))
meta["gain"] = float(state.get("gain_q", 4096)) / 4096.0
meta["size"] = size
meta["snap"] = bool(state.get("snap", 0))
meta["divergence"] = float(state.get("divergence_q", 0)) / 32767.0
def _lerp_xyz(start, target, amount): def _lerp_xyz(start, target, amount):
return tuple(a + (b - a) * amount for a, b in zip(start, target)) return tuple(a + (b - a) * amount for a, b in zip(start, target))
def _append_point(points, sample, xyz, interpolation_samples): def _append_point(points, sample, xyz, interpolation_samples, meta):
item = (int(sample), *map(float, xyz), int(interpolation_samples)) item = (int(sample), *map(float, xyz), int(interpolation_samples), dict(meta))
if points and item[0] == points[-1][0]: if points and item[0] == points[-1][0]:
points[-1] = item points[-1] = item
elif not points or item[0] > points[-1][0]: elif not points or item[0] > points[-1][0]:
@@ -34,15 +64,17 @@ def _append_point(points, sample, xyz, interpolation_samples):
def _expand_events_dense64(events, total_samples, rate, update_block_samples, def _expand_events_dense64(events, total_samples, rate, update_block_samples,
object_delay_samples, object_index): object_delay_samples, object_index):
if not events: if not events:
return [(0.0, 0.0, 0.0, 0.0, total_samples / float(rate), 0.0)] return [(0.0, 0.0, 0.0, 0.0, total_samples / float(rate), 0.0,
_default_meta())]
block = int(update_block_samples) block = int(update_block_samples)
# 初始位置从成品 sample 0 起有效;合成延迟只作用于后续位置变化。 # 初始位置从成品 sample 0 起有效;合成延迟只作用于后续位置变化。
current = events[0][1] current = events[0][1]
current_meta = events[0][3]
points = [] points = []
_append_point(points, 0, current, 0) _append_point(points, 0, current, 0, current_meta)
for event_index, (coded_start, target, ramp_samples) in enumerate(events[1:], 1): for event_index, (coded_start, target, ramp_samples, meta) in enumerate(events[1:], 1):
start = align_metadata_sample(coded_start + object_delay_samples, block) start = align_metadata_sample(coded_start + object_delay_samples, block)
if start >= total_samples: if start >= total_samples:
break break
@@ -55,12 +87,13 @@ def _expand_events_dense64(events, total_samples, rate, update_block_samples,
# 在运动起点保留上一位置,避免下游把长时间静止段直接连到首个中间点。 # 在运动起点保留上一位置,避免下游把长时间静止段直接连到首个中间点。
if start > points[-1][0]: if start > points[-1][0]:
_append_point(points, start, current, 0) _append_point(points, start, current, 0, current_meta)
ramp = max(0, int(ramp_samples)) ramp = max(0, int(ramp_samples))
if ramp == 0: if ramp == 0:
_append_point(points, start, target, 0) _append_point(points, start, target, 0, meta)
current = target current = target
current_meta = meta
continue continue
end = start + math.ceil(ramp / block) * block end = start + math.ceil(ramp / block) * block
@@ -91,12 +124,14 @@ def _expand_events_dense64(events, total_samples, rate, update_block_samples,
sample = start + elapsed sample = start + elapsed
if sample >= total_samples: if sample >= total_samples:
break break
_append_point(points, sample, position, block) _append_point(points, sample, position, block, meta)
future -= block future -= block
current = target current = target
current_meta = meta
blocks = [] blocks = []
for point_index, (sample, x, y, z, interpolation_samples) in enumerate(points): for point_index, point in enumerate(points):
sample, x, y, z, interpolation_samples, meta = point
end = points[point_index + 1][0] if point_index + 1 < len(points) else total_samples end = points[point_index + 1][0] if point_index + 1 < len(points) else total_samples
duration_samples = max(0, end - sample) duration_samples = max(0, end - sample)
if duration_samples == 0: if duration_samples == 0:
@@ -104,7 +139,7 @@ def _expand_events_dense64(events, total_samples, rate, update_block_samples,
interpolation_samples = min(interpolation_samples, duration_samples) interpolation_samples = min(interpolation_samples, duration_samples)
blocks.append((sample / float(rate), x, y, z, blocks.append((sample / float(rate), x, y, z,
duration_samples / float(rate), duration_samples / float(rate),
interpolation_samples / float(rate))) interpolation_samples / float(rate), meta))
return blocks return blocks
@@ -119,14 +154,16 @@ def _compact_events(events, total_samples, rate, update_block_samples,
``[align(start), align(start) + ramp_duration]``. ``[align(start), align(start) + ramp_duration]``.
""" """
if not events: if not events:
return [(0.0, 0.0, 0.0, 0.0, total_samples / float(rate), 0.0)] return [(0.0, 0.0, 0.0, 0.0, total_samples / float(rate), 0.0,
_default_meta())]
points = [] points = []
current = events[0][1] current = events[0][1]
_append_point(points, 0, current, 0) current_meta = events[0][3]
_append_point(points, 0, current, 0, current_meta)
block = int(update_block_samples) block = int(update_block_samples)
for event_index, (coded_start, target, ramp_samples) in enumerate(events[1:], 1): for event_index, (coded_start, target, ramp_samples, meta) in enumerate(events[1:], 1):
event_start = align_metadata_sample(coded_start + object_delay_samples, block) event_start = align_metadata_sample(coded_start + object_delay_samples, block)
if event_start >= total_samples: if event_start >= total_samples:
break break
@@ -144,7 +181,7 @@ def _compact_events(events, total_samples, rate, update_block_samples,
"previous_sample": points[-1][0]}) "previous_sample": points[-1][0]})
if event_index + 1 < len(events): if event_index + 1 < len(events):
next_coded_start, _, next_ramp_samples = events[event_index + 1] next_coded_start, _, next_ramp_samples = events[event_index + 1][:3]
next_event_start = align_metadata_sample( next_event_start = align_metadata_sample(
next_coded_start + object_delay_samples, block) next_coded_start + object_delay_samples, block)
next_block_start = next_event_start next_block_start = next_event_start
@@ -166,11 +203,13 @@ def _compact_events(events, total_samples, rate, update_block_samples,
if ramp > available: if ramp > available:
block_target = _lerp_xyz(current, target, available / float(ramp)) block_target = _lerp_xyz(current, target, available / float(ramp))
block_interpolation = available block_interpolation = available
_append_point(points, block_start, block_target, block_interpolation) _append_point(points, block_start, block_target, block_interpolation, meta)
current = target current = target
current_meta = meta
blocks = [] blocks = []
for point_index, (sample, x, y, z, interpolation_samples) in enumerate(points): for point_index, point in enumerate(points):
sample, x, y, z, interpolation_samples, meta = point
end = points[point_index + 1][0] if point_index + 1 < len(points) else total_samples end = points[point_index + 1][0] if point_index + 1 < len(points) else total_samples
duration_samples = max(0, end - sample) duration_samples = max(0, end - sample)
if duration_samples == 0: if duration_samples == 0:
@@ -178,7 +217,7 @@ def _compact_events(events, total_samples, rate, update_block_samples,
interpolation_samples = min(interpolation_samples, duration_samples) interpolation_samples = min(interpolation_samples, duration_samples)
blocks.append((sample / float(rate), x, y, z, blocks.append((sample / float(rate), x, y, z,
duration_samples / float(rate), duration_samples / float(rate),
interpolation_samples / float(rate))) interpolation_samples / float(rate), meta))
return blocks return blocks
@@ -226,13 +265,16 @@ def build_adm_tracks(index, frames=None, rate=48000, frame_samples=1536,
state = JocFieldState() state = JocFieldState()
events = [[] for _ in range(15)] events = [[] for _ in range(15)]
previous = [None] * 15 previous = [None] * 15
meta_state = [_default_meta() for _ in range(15)]
for seq, row in enumerate(frames): for seq, row in enumerate(frames):
subs = index.subpayloads(row) subs = index.subpayloads(row)
timing = None timing = None
full = None
if subs is not None and 11 in subs: if subs is not None and 11 in subs:
timing = frame_update(subs[11]) timing = frame_update(subs[11])
state.apply(timing["values"]) state.apply(timing["values"])
full = frame_state(subs[11])
event_sample = seq * frame_samples event_sample = seq * frame_samples
ramp_samples = 0 ramp_samples = 0
@@ -245,9 +287,12 @@ def build_adm_tracks(index, frames=None, rate=48000, frame_samples=1536,
q = state.q q = state.q
for obj in range(1, 16): for obj in range(1, 16):
xyz = q_to_adm_xyz(q[(obj, "q1")], q[(obj, "q2")], q[(obj, "q3")]) xyz = q_to_adm_xyz(q[(obj, "q1")], q[(obj, "q2")], q[(obj, "q3")])
if previous[obj - 1] != xyz: if full is not None and obj < len(full["objects"]):
events[obj - 1].append((event_sample, xyz, ramp_samples)) _apply_state(meta_state[obj - 1], full["objects"][obj])
previous[obj - 1] = xyz meta = dict(meta_state[obj - 1])
if previous[obj - 1] != (xyz, meta):
events[obj - 1].append((event_sample, xyz, ramp_samples, meta))
previous[obj - 1] = (xyz, meta)
total_samples = len(frames) * frame_samples total_samples = len(frames) * frame_samples
# bed 对象在 OAMD 里没有位置字段:位置由声明的 bed 布局决定,整片静止在该方位。 # bed 对象在 OAMD 里没有位置字段:位置由声明的 bed 布局决定,整片静止在该方位。
@@ -258,7 +303,7 @@ def build_adm_tracks(index, frames=None, rate=48000, frame_samples=1536,
if fixed is not None: if fixed is not None:
tracks.append((f"JOC_Object_{obj}", tracks.append((f"JOC_Object_{obj}",
[(0.0, fixed[0], fixed[1], fixed[2], [(0.0, fixed[0], fixed[1], fixed[2],
total_samples / float(rate), 0.0)])) total_samples / float(rate), 0.0, _default_meta())]))
continue continue
tracks.append( tracks.append(
(f"JOC_Object_{obj}", (f"JOC_Object_{obj}",