2 Commits
Author SHA1 Message Date
TheM14 787984afe5 Write OAMD object render metadata into the ADM BWF
ci / ubuntu-latest (push) Failing after 14s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s
Port the Python reference ADM metadata change.  The ADM export path now parses
the full OAMD frame state, so the same block-0 render state the speaker
renderer consumes is available to the trajectory builder.

adm::ObjectMetadata (gain, width/depth/height size, divergence, snap) is
attached to Keyframe and OamdEvent.  TrajectoryBuilder updates the per-object
state from frame_state, emits an event when position or metadata changes, and
both compact and dense64 expansion modes carry the snapshot into every ADM
block.  The state is held across frames without a payload; inactive objects
write gain 0.  Divergence is taken from the current payload (0 when the
extended element does not carry it), matching the speaker renderer instead of
holding a stale value.

build_axml writes width/height/depth (relative 0..1), gain in linear units and
objectDivergence positionRange, omitting defaults.  The ADM path requests
parse_id11_state() so frame_state is populated.  test_core adds coverage for
the AXML fields and for the trajectory metadata and divergence reset.

Bump JOC_VERSION to 1.3.2.
2026-11-12 02:01:13 +08:00
TheM14 836d68c354 Hold frames without JOC metadata in the middle of a stream
ci / ubuntu-latest (push) Failing after 13s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s
A frame without JOC metadata (status 8) used to select Passthrough in every
state, the middle of a stream included.  Passthrough replaces the object render
with the delayed core planes, and the object synthesis restarts from silence on
the next frame, so every such frame produced a step at the frame boundary and a
second one when the metadata came back.  Encoders that are not careful with the
JOC EMDF container emit exactly those frames.

Status 8 now follows the state machine like the other invalid statuses: state 0
(no valid frame rendered yet, i.e. plain E-AC-3 or before the first JOC frame)
keeps Passthrough, state 3 (mid-stream) selects Hold and reuses the previous
object matrices, so the bed and the objects stay continuous.  The compatibility
note at select_mode records the old and the new state machine and states that
the choice is a concession for non-standard streams, not a normative reading.

Bump JOC_VERSION to 1.3.1.  The new renderer test covers both sides: a
mid-stream frame without metadata holds the previous matrices, while a stream
that has not rendered a valid frame yet still passes the core planes through.
2026-11-10 15:33:56 +08:00
8 changed files with 216 additions and 20 deletions

No files matched your search

+2 -2
View File
@@ -10,7 +10,7 @@
#define JOC_VERSION_MAJOR 1
#define JOC_VERSION_MINOR 3
#define JOC_VERSION_PATCH 0
#define JOC_VERSION_STRING "1.3.0"
#define JOC_VERSION_PATCH 2
#define JOC_VERSION_STRING "1.3.2"
#endif /* JOC_VERSION_H */
+14
View File
@@ -363,6 +363,20 @@ std::string build_axml(const std::vector<Track>& tracks, double duration_sec, st
out += "<position coordinate=\"Z\">" + pynum::format_fixed(block.z, 10) +
"</position>";
}
const ObjectMetadata& meta = block.meta;
if (meta.size[0] > 0.0 || meta.size[1] > 0.0 || meta.size[2] > 0.0) {
out += "<width>" + pynum::format_fixed(meta.size[0], 6) + "</width>";
out += "<height>" + pynum::format_fixed(meta.size[2], 6) + "</height>";
out += "<depth>" + pynum::format_fixed(meta.size[1], 6) + "</depth>";
}
if (std::fabs(meta.gain - 1.0) > 1e-9) {
out += "<gain gainUnit=\"linear\">" + pynum::format_fixed(meta.gain, 6) +
"</gain>";
}
if (meta.divergence > 0.0) {
out += "<objectDivergence positionRange=\"" +
pynum::format_fixed(meta.divergence, 6) + "\"/>";
}
out += "<jumpPosition interpolationLength=\"" +
pynum::format_fixed(static_cast<double>(block.interpolation_samples) / scale,
5) +
+10
View File
@@ -14,6 +14,15 @@ namespace joc::adm {
inline constexpr int kObjectCount = 15;
inline constexpr std::uint32_t kTrackCount = 25;
// Per-block OAMD render metadata the ADM audioBlockFormat can express.
struct ObjectMetadata {
double gain = 1.0;
// OAMD order: width, depth, height (relative units 0..1).
double size[3] = {0.0, 0.0, 0.0};
double divergence = 0.0;
bool snap = false;
};
struct Keyframe {
std::int64_t rtime_samples = 0;
double x = 0.0;
@@ -21,6 +30,7 @@ struct Keyframe {
double z = 0.0;
std::int64_t duration_samples = 0;
std::int64_t interpolation_samples = 0;
ObjectMetadata meta;
};
struct Track {
+61 -13
View File
@@ -16,15 +16,22 @@ struct Point {
double y = 0.0;
double z = 0.0;
std::int64_t interpolation_samples = 0;
ObjectMetadata meta;
};
bool same_meta(const ObjectMetadata& left, const ObjectMetadata& right) {
return left.gain == right.gain && left.size[0] == right.size[0] &&
left.size[1] == right.size[1] && left.size[2] == right.size[2] &&
left.divergence == right.divergence && left.snap == right.snap;
}
// otherwise (the reference drops silently).
void append_point(std::vector<Point>* points, std::int64_t sample, double x, double y, double z,
std::int64_t interpolation_samples) {
std::int64_t interpolation_samples, const ObjectMetadata& meta) {
if (!points->empty() && sample == points->back().sample) {
points->back() = Point{sample, x, y, z, interpolation_samples};
points->back() = Point{sample, x, y, z, interpolation_samples, meta};
} else if (points->empty() || sample > points->back().sample) {
points->push_back(Point{sample, x, y, z, interpolation_samples});
points->push_back(Point{sample, x, y, z, interpolation_samples, meta});
}
}
@@ -52,6 +59,7 @@ void points_to_blocks(const std::vector<Point>& points, std::int64_t total_sampl
keyframe.z = point.z;
keyframe.duration_samples = duration;
keyframe.interpolation_samples = std::min(point.interpolation_samples, duration);
keyframe.meta = point.meta;
out->push_back(keyframe);
}
}
@@ -85,7 +93,8 @@ Status expand_compact(const std::vector<OamdEvent>& events, std::int64_t total_s
std::vector<Point> points;
double current[3] = {events[0].x, events[0].y, events[0].z};
append_point(&points, 0, current[0], current[1], current[2], 0);
ObjectMetadata current_meta = events[0].meta;
append_point(&points, 0, current[0], current[1], current[2], 0, current_meta);
for (std::size_t index = 1; index < events.size(); ++index) {
const OamdEvent& event = events[index];
@@ -131,10 +140,12 @@ Status expand_compact(const std::vector<OamdEvent>& events, std::int64_t total_s
target[2] = z;
interpolation = available;
}
append_point(&points, block_start, target[0], target[1], target[2], interpolation);
append_point(&points, block_start, target[0], target[1], target[2], interpolation,
event.meta);
current[0] = event.x;
current[1] = event.y;
current[2] = event.z;
current_meta = event.meta;
}
points_to_blocks(points, total_samples, out);
@@ -156,7 +167,8 @@ Status expand_dense64(const std::vector<OamdEvent>& events, std::int64_t total_s
std::vector<Point> points;
double current[3] = {events[0].x, events[0].y, events[0].z};
append_point(&points, 0, current[0], current[1], current[2], 0);
ObjectMetadata current_meta = events[0].meta;
append_point(&points, 0, current[0], current[1], current[2], 0, current_meta);
for (std::size_t index = 1; index < events.size(); ++index) {
const OamdEvent& event = events[index];
@@ -171,14 +183,15 @@ Status expand_dense64(const std::vector<OamdEvent>& events, std::int64_t total_s
points.back().sample);
}
if (start > points.back().sample) {
append_point(&points, start, current[0], current[1], current[2], 0);
append_point(&points, start, current[0], current[1], current[2], 0, current_meta);
}
const std::int64_t ramp = std::max<std::int64_t>(0, event.ramp_samples);
if (ramp == 0) {
append_point(&points, start, event.x, event.y, event.z, 0);
append_point(&points, start, event.x, event.y, event.z, 0, event.meta);
current[0] = event.x;
current[1] = event.y;
current[2] = event.z;
current_meta = event.meta;
continue;
}
const std::int64_t steps = (ramp + update_block_samples - 1) / update_block_samples;
@@ -214,12 +227,13 @@ Status expand_dense64(const std::vector<OamdEvent>& events, std::int64_t total_s
break;
}
append_point(&points, sample, position[0], position[1], position[2],
update_block_samples);
update_block_samples, event.meta);
future -= update_block_samples;
}
current[0] = event.x;
current[1] = event.y;
current[2] = event.z;
current_meta = event.meta;
}
points_to_blocks(points, total_samples, out);
@@ -239,18 +253,52 @@ void TrajectoryBuilder::submit_frame(std::int64_t frame_index, const oamd::OamdU
if (fixed_[object - 1]) {
continue; // 固定 bed 声道:位置由布局给出,不跟 OAMD 更新
}
const int slot = object - 1;
// OAMD block 0 对动态对象显式携带 gain/size/snap;divergence 只在扩展
// 元素里出现,缺失时按 0 处理,与 speaker 渲染器的逐 payload 语义一致。
if (update != nullptr && update->has_frame_state &&
static_cast<std::size_t>(object) < update->frame_state.objects.size()) {
const oamd::ObjectElementState& element =
update->frame_state.objects[static_cast<std::size_t>(object)];
if (!element.blocks.empty() && element.kind == oamd::ObjectKind::kDynamic) {
const oamd::ObjectRenderState& render = element.blocks[0].render;
ObjectMetadata& meta = meta_[slot];
if (render.not_active) {
meta.gain = 0.0;
} else {
meta.gain = static_cast<double>(render.gain_q) / 4096.0;
if (render.size_mode == 1u || render.size_mode == 2u) {
for (int axis = 0; axis < 3; ++axis) {
meta.size[axis] = std::min(
std::max(static_cast<double>(render.size_q[axis]) / 32767.0, 0.0),
1.0);
}
} else {
meta.size[0] = 0.0;
meta.size[1] = 0.0;
meta.size[2] = 0.0;
}
meta.divergence = static_cast<double>(render.divergence_q) / 32767.0;
meta.snap = render.snap;
}
}
}
double x = 0.0;
double y = 0.0;
double z = 0.0;
geometry::q_to_adm_xyz(state_.q(object, 0), state_.q(object, 1), state_.q(object, 2), &x,
&y, &z);
const int slot = object - 1;
if (!has_previous_[slot] || previous_[slot][0] != x || previous_[slot][1] != y ||
previous_[slot][2] != z) {
events_[slot].push_back(OamdEvent{event_sample, x, y, z, ramp_samples});
const ObjectMetadata& meta = meta_[slot];
const bool position_changed =
!has_previous_[slot] || previous_[slot][0] != x || previous_[slot][1] != y ||
previous_[slot][2] != z;
const bool meta_changed = !has_previous_[slot] || !same_meta(previous_meta_[slot], meta);
if (position_changed || meta_changed) {
events_[slot].push_back(OamdEvent{event_sample, x, y, z, ramp_samples, meta});
previous_[slot][0] = x;
previous_[slot][1] = y;
previous_[slot][2] = z;
previous_meta_[slot] = meta;
has_previous_[slot] = true;
}
}
+3
View File
@@ -19,6 +19,7 @@ struct OamdEvent {
double y = 0.0;
double z = 0.0;
std::int64_t ramp_samples = 0;
ObjectMetadata meta;
};
enum class TrajectoryMode { Compact, Dense64 };
@@ -62,6 +63,8 @@ private:
std::vector<OamdEvent> events_[kObjectCount];
bool has_previous_[kObjectCount] = {};
double previous_[kObjectCount][3] = {};
ObjectMetadata meta_[kObjectCount];
ObjectMetadata previous_meta_[kObjectCount];
bool fixed_[kObjectCount] = {};
double fixed_xyz_[kObjectCount][3] = {};
};
+27 -1
View File
@@ -800,9 +800,35 @@ private:
return pre_state;
}
// Compatibility note for frames without JOC metadata (status 8).
//
// The state machine used to map status 8 to Passthrough unconditionally,
// including in the middle of a stream. That is only meaningful before the
// first valid JOC frame: a plain E-AC-3 stream (or a stream whose first JOC
// frame comes late) has no object state yet, so the core planes are all
// there is and the delayed core PCM is the right output. In the middle of
// a JOC stream a frame without metadata is a damaged frame, not "no
// objects": the Passthrough output replaces the object render with the core
// planes, and the object synthesis restarts from silence on the next frame.
// Every such frame therefore produced a step at the frame boundary and a
// second one when the metadata came back; encoders that are not careful
// with the JOC EMDF container emit exactly those frames.
//
// After the change status 8 follows the state machine like the other
// invalid statuses: state 0 (no valid frame rendered yet) stays Passthrough,
// and state 3 (mid-stream) selects Hold, which reuses the previous object
// matrices and keeps the bed and object rendering continuous.
//
// This is a compatibility choice, not a claim about the normative reading
// of the specification: a frame without metadata can be argued to be the
// Passthrough case. It exists so that non-standard streams stay click-free;
// if the reference behaviour is preferred, re-add the unconditional
// Passthrough branch here.
FrameMode select_mode(const uint32_t status) const noexcept {
if (status == EJOC_FRAME_STATUS_NO_METADATA) {
return FrameMode::Passthrough;
// See the note above: only a stream that has not rendered a valid
// frame yet has nothing to hold.
return state_ == 0u ? FrameMode::Passthrough : FrameMode::Hold;
}
if (state_ == 4u) {
return FrameMode::HardCut;
+5 -4
View File
@@ -1845,10 +1845,11 @@ Status run(const joc_task_config& raw, const joc_event_sink* sink, joc_task_resu
stream_done = true;
break;
}
// The speaker and binaural renderers consume the full per-object
// block state (multi-block and every declared object); the ADM
// export path keeps the reference's 15-track single-block view.
const bool full_metadata_state = speaker_enabled || binaural_enabled;
// The speaker, binaural and ADM paths consume the full per-object
// block state (multi-block and every declared object); the legacy
// stream/ADM single-block view only needs the slot fields.
const bool full_metadata_state =
speaker_enabled || binaural_enabled || adm_enabled;
const Status oamd =
full_metadata_state
? ::joc::oamd::parse_id11_state(bytes.data(), bytes.size(),
+94
View File
@@ -12,6 +12,7 @@
#include <vector>
#include "adm/adm_metadata.h"
#include "adm/adm_tracks.h"
#include "eac3_transport/eac3_reader.h"
#include "eac3joc_core.h"
#include "foundation/bit_reader.h"
@@ -955,6 +956,60 @@ void test_dbmd_and_axml_trim() {
CHECK(plain_axml.find("<DolbyAtmosMasterFile>") == std::string::npos);
}
void test_adm_object_metadata() {
std::vector<joc::adm::Track> tracks(15);
for (std::size_t i = 0; i < tracks.size(); ++i) {
tracks[i].name = "obj" + std::to_string(i);
}
joc::adm::Keyframe block;
block.duration_samples = 48000;
block.meta.gain = 0.5;
block.meta.size[0] = 0.516155;
block.meta.size[1] = 0.516155;
block.meta.size[2] = 0.516155;
block.meta.divergence = 0.25;
tracks[1].blocks.push_back(block);
const std::string axml = joc::adm::build_axml(tracks, 1.0, 48000);
CHECK(axml.find("<width>0.516155</width><height>0.516155</height><depth>0.516155</depth>") !=
std::string::npos);
CHECK(axml.find("<gain gainUnit=\"linear\">0.500000</gain>") != std::string::npos);
CHECK(axml.find("<objectDivergence positionRange=\"0.250000\"/>") != std::string::npos);
// Default metadata writes no fields.
tracks[1].blocks[0].meta = joc::adm::ObjectMetadata{};
const std::string plain = joc::adm::build_axml(tracks, 1.0, 48000);
CHECK(plain.find("<width>") == std::string::npos);
CHECK(plain.find("<gain ") == std::string::npos);
CHECK(plain.find("<objectDivergence ") == std::string::npos);
// TrajectoryBuilder carries block-0 metadata and drops divergence when the
// next payload does not send it, matching the speaker renderer.
joc::adm::TrajectoryBuilder builder;
joc::oamd::OamdUpdate update;
update.has_frame_state = true;
update.object_count = 3;
update.frame_state.object_count = 3;
update.frame_state.block_count = 1;
update.frame_state.objects.resize(3);
auto& element = update.frame_state.objects[2];
element.kind = joc::oamd::ObjectKind::kDynamic;
element.blocks.resize(1);
auto& render = element.blocks[0].render;
render.gain_q = 2048;
render.size_mode = 1;
render.size_q[0] = render.size_q[1] = render.size_q[2] = 16384;
render.divergence_q = 16384;
builder.submit_frame(0, &update, 0);
joc::oamd::OamdUpdate second = update;
second.frame_state.objects[2].blocks[0].render.divergence_q = 0;
builder.submit_frame(40, &second, 0);
std::vector<joc::adm::Track> trajectory;
CHECK(builder.build(96000, joc::adm::TrajectoryMode::Compact, &trajectory).ok());
CHECK(trajectory[1].blocks.size() >= 2);
CHECK(std::fabs(trajectory[1].blocks.front().meta.gain - 0.5) < 1e-12);
CHECK(trajectory[1].blocks.back().meta.divergence == 0.0);
}
void test_int24_packing() {
// Interleaved (L,R) for two frames: 0.0, +1.0, -1.0, +2.0 (clips).
const float values[4] = {0.0f, 1.0f, -1.0f, 2.0f};
@@ -2138,6 +2193,43 @@ float object_peak(const FrameCase& frame, int object_channel) {
return peak;
}
void test_joc_no_metadata_midstream_holds() {
// A frame without JOC metadata in the middle of a JOC stream is a damaged
// frame, not "no objects": it holds the previous matrices instead of
// publishing the core planes. Before the compatibility change every such
// frame went through Passthrough, which produced a step at the frame
// boundary and a second one when the metadata came back.
{
FrameCase frame;
frame.create();
for (int sample = 0; sample < EJOC_FRAME_SAMPLES; ++sample) {
frame.bed[static_cast<std::size_t>(sample)] =
static_cast<float>(0.2 * std::sin(static_cast<double>(sample) * 0.05));
}
configure_passthrough_object(&frame);
CHECK(frame.render(EJOC_CORE_CHANNELS, EJOC_CORE_CHANNELS, 0u, 0u, true, 1u, 1.0));
CHECK(object_peak(frame, 1) > 1.0e-3f);
CHECK(frame.render(EJOC_CORE_CHANNELS, 0u, EJOC_FRAME_STATUS_NO_METADATA, 0u, false,
0u, 1.0));
// Held: the object slot keeps rendering from the previous matrix.
CHECK(object_peak(frame, 1) > 1.0e-3f);
// The next valid frame resumes normally.
CHECK(frame.render(EJOC_CORE_CHANNELS, EJOC_CORE_CHANNELS, 0u, 1u, true, 1u, 1.0));
CHECK(object_peak(frame, 1) > 1.0e-3f);
}
// A stream that has not rendered a valid frame yet keeps the passthrough:
// the core planes are all there is (plain E-AC-3, or a late first JOC frame).
{
FrameCase frame;
frame.create();
fill_frame_bed(&frame, 0.1f, 0.25f);
CHECK(frame.render(EJOC_CORE_CHANNELS, 0u, EJOC_FRAME_STATUS_NO_METADATA, 0u, false,
0u, 1.0));
CHECK(frame.silent_slots(8, EJOC_OUTPUT_CHANNELS - 1));
CHECK(!frame.silent_slots(0, 7));
}
}
void test_joc_frame_state_machine() {
// seq 0 on the first frame is not a hard cut, and a mismatch later is.
{
@@ -2384,6 +2476,7 @@ int main() {
test_speaker_surround_fold();
test_speaker_step_trim_events();
test_dbmd_and_axml_trim();
test_adm_object_metadata();
test_int24_packing();
test_utf8_paths();
test_process_runner();
@@ -2403,6 +2496,7 @@ int main() {
test_eac3_frame_truncated_joc_payload();
test_joc_lfe_clipgain_ramp();
test_joc_passthrough_8_plane_layout();
test_joc_no_metadata_midstream_holds();
test_joc_frame_state_machine();
test_joc_truncated_frame_holds_previous_matrix();
test_joc_no_previous_interpolation();