Files
JustOneCacophony/src/binaural/jochrtf_runtime.cpp
T
TheM14 0bb82e4115
ci / ubuntu-latest (push) Failing after 19s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s
Port the OAMD metadata rendering and the frame-level JOC core
The JOC bitstream reports a per-frame parse status instead of treating every
anomaly as an exception: an unsupported downmix configuration, a clamped
object count, an unknown parameter-band count, bad offset_ts values and
trailing bytes each get their own status. The raw 5-bit offset_ts values are
kept as coded and validated to be strictly increasing per object, and the
clipgain uses 2^(x-4) * (1 + y/32).

The JOC core gains a frame-level state machine. It keeps the per-object
previous matrix and its presence marker, the seq counter, the 8-plane
passthrough history, the LFE clipgain ramp start and the previous actual
core-channel count. Normal, hold, hard-cut and passthrough frames are
distinguished: a frame without a previous state interpolates per the
data-point rules, an object that disappears keeps publishing a zero matrix,
a frame without metadata passes the 8 core planes through to slots 0..7 with
the 1217-sample delay, and a declared core-channel-count change hard-cuts and
clears the LFE ring while the clipgain ramp state is kept. The core LFE
applies the full clipgain as a sample-wise ramp before its delay.

The OAMD parser exposes the full frame state: every object's state in every
position block, the programme assignment and the trim element, with multiple
blocks and up to 30 declared objects accepted. The speaker renderer applies
this state: per-block gain/inactive, zone/elevation, the size kernel, snap,
divergence, element 5 refinement, the priority size budget, ISF basis
matrices and bed channel distribution, scheduled on the 32-sample metadata
grid with block alignment and gain ramps. The size kernel, ISF basis
assembly, bed routing and compensation are computed in oamd_math from the
speaker layout geometry; bed labels and reference positions derive from the
layout tables. The six ISF configurations and twelve layout descriptors are
compiled in as static tables (oamd/isf_tables.h); the JSON loader and the
configure-time embedding are gone. The layout tables gain 6.0, and the layout
lookup, bed map and trim probe follow.

The binaural position timeline consumes the full frame state as well: every
position block is scheduled at its own offset and ramp, and its track list
grows with the declared object count, so multi-block and over-16-object
programmes are rendered instead of rejected. The JOC binaural input stays one
LFE plus fifteen object sources; the extra tracks are followed but not
panned.

The file task and the stream parse the full state for speaker and binaural,
while the ADM export keeps the 15-track single-block view. The public headers
carry the new status values, the frame-level entry point and the raw offset_ts
description; the internal ABI versions go to 6 (joc_core), 2 (frame params and
EMDF info) and 4 (eac3joc).

ctest covers the frame-level core (clipgain formula and LFE ramp, offset_ts
validation, frame statuses, the 8-plane passthrough, the seq state machine and
the no-previous-state interpolation), the OAMD parser state, the compiled-in
ISF tables and the binaural timeline. The READMEs and the mathematical notes
describe the 6.0 layout, the frame state machine, the metadata application and
the ISF lookup tables.
2026-11-08 14:04:21 +08:00

253 lines
11 KiB
C++

#include "binaural/jochrtf_runtime.h"
#include <algorithm>
#include <cmath>
#include <cstring>
#include <string>
namespace joc::binaural {
namespace {
double max_delay_bound(const hrtf::Field& field) {
double maximum = 0.0;
for (const double value : field.delay_bounds) {
maximum = std::max(maximum, value);
}
return maximum;
}
} // namespace
bool profile_from_name(const char* name, Profile* out) {
if (name == nullptr || out == nullptr) {
return false;
}
if (std::strcmp(name, "near") == 0) { *out = Profile::Near; return true; }
if (std::strcmp(name, "mid") == 0) { *out = Profile::Mid; return true; }
if (std::strcmp(name, "far") == 0) { *out = Profile::Far; return true; }
return false;
}
JochrtfRuntime::~JochrtfRuntime() {
if (handle_ != nullptr) {
ejoc_jochrtf_destroy(handle_);
handle_ = nullptr;
}
}
Status JochrtfRuntime::open(const hrtf::Field& field, const hrtf::Kernels& kernels,
Profile profile, const RoomConstants& room) {
if (handle_ != nullptr) {
return Status::fail(JOC_ERR_STATE, stage::kRender, "binaural runtime already open");
}
if (field.coefficients.size() != static_cast<std::size_t>(hrtf::kShTerms * hrtf::kEars *
hrtf::kHybridBands * 2) ||
field.band_centers_hz.size() != static_cast<std::size_t>(hrtf::kHybridBands)) {
return Status::fail(JOC_ERR_HRTF_FORMAT, stage::kRender,
"compiled HRTF field has unexpected array sizes");
}
handle_ = ejoc_jochrtf_create();
if (handle_ == nullptr) {
return Status::fail(JOC_ERR_OUT_OF_MEMORY, stage::kRender,
"ejoc_jochrtf_create failed");
}
profile_ = profile;
if (ejoc_jochrtf_configure_kernels(
handle_, kernels.qmf_analysis.data(), kernels.hybrid_low.data(),
kernels.hybrid_indices.data(), kernels.hybrid_values.data(), kernels.hybrid_count,
kernels.qmf_basis.data(), kernels.qmf_taps.data()) != 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_HRTF_FORMAT, stage::kRender,
std::string("configure_kernels failed: ") +
(message != nullptr ? message : "unknown"));
}
if (ejoc_jochrtf_configure_field(handle_, field.coefficients.data(),
field.delay_coefficients.data(),
field.delay_bounds.data(), field.band_centers_hz.data(),
field.measurement_radius_m) != 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_HRTF_FORMAT, stage::kRender,
std::string("configure_field failed: ") +
(message != nullptr ? message : "unknown"));
}
if (ejoc_jochrtf_configure_room(
handle_, room.dims, room.listener, room.walls, room.speed_of_sound, room.fdn_delays,
room.fdn_feedback, room.damping, room.fdn_output_gain, room.allpass_delays,
room.allpass_gains, room.enable_early_reflections, room.enable_late_room) != 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_RENDER_FAILED, stage::kRender,
std::string("configure_room failed: ") +
(message != nullptr ? message : "unknown"));
}
maximum_hrtf_delay_ =
static_cast<std::int64_t>(std::ceil(max_delay_bound(field) - 1e-9));
hrtf_history_slots_ = static_cast<std::uint32_t>(std::max<std::int64_t>(1, (maximum_hrtf_delay_ + 63) / 64));
staging_.assign(kBlockSamples * kSourceCount, 0.0);
block_output_.assign(kBlockSamples * 2u, 0.0);
output_.clear();
staged_ = 0;
input_samples_ = 0;
processed_samples_ = 0;
blocks_processed_ = 0;
return Status::success();
}
Status JochrtfRuntime::process_block() {
double positions[timeline::kTimelineObjects][3] = {};
const Status queried = timeline_.positions_at(static_cast<std::int64_t>(processed_samples_),
&positions[0][0],
timeline::kTimelineObjects);
if (!queried.ok()) {
return queried;
}
// The reference adapter calls set_source without a `fade` argument, so the
// backend default (fade enabled) applies - the per-object path crossfade is
// part of the reference behaviour, not an optional extra.
constexpr std::uint32_t kFade = 1u;
if (ejoc_jochrtf_set_source(handle_, 0u, kLfePosition,
static_cast<std::uint32_t>(profile_), 1.0, 1u, 1u,
kFade) != 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_RENDER_FAILED, stage::kRender,
std::string("set_source(LFE) failed: ") +
(message != nullptr ? message : "unknown"));
}
for (std::uint32_t source = 0; source < timeline::kTimelineObjects; ++source) {
if (ejoc_jochrtf_set_source(handle_, source + 1u, positions[source],
static_cast<std::uint32_t>(profile_), 1.0, 1u, 0u,
kFade) != 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_RENDER_FAILED, stage::kRender,
std::string("set_source(object ") + std::to_string(source + 1u) +
") failed: " + (message != nullptr ? message : "unknown"));
}
}
const int trimmed = ejoc_jochrtf_process(handle_, staging_.data(), kBlockSamples, 1.0,
block_output_.data());
if (trimmed < 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_RENDER_FAILED, stage::kRender,
std::string("sofa process failed: ") +
(message != nullptr ? message : "unknown"));
}
if (trimmed > 0) {
output_.insert(output_.end(), block_output_.begin(),
block_output_.begin() + static_cast<std::ptrdiff_t>(trimmed) * 2);
}
staged_ = 0;
processed_samples_ += kBlockSamples;
++blocks_processed_;
return Status::success();
}
Status JochrtfRuntime::submit_frame(const float* objects16_planar,
const oamd::OamdUpdate* update, std::int64_t frame_index,
std::int64_t outer_sample_offset,
std::int64_t object_delay_samples) {
if (handle_ == nullptr) {
return Status::fail(JOC_ERR_STATE, stage::kRender, "binaural runtime is not open");
}
if (objects16_planar == nullptr) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender, "null frame");
}
// A frame without an ID11 payload submits nothing at all (the reference only
if (update != nullptr) {
const Status submitted = timeline_.submit_update(
*update, frame_index * JOC_FRAME_SAMPLES, outer_sample_offset, object_delay_samples,
static_cast<std::int64_t>(input_samples_));
if (!submitted.ok()) {
return submitted;
}
}
std::size_t offset = 0;
while (offset < JOC_FRAME_SAMPLES) {
const std::size_t room = kBlockSamples - staged_;
const std::size_t count = std::min<std::size_t>(room, JOC_FRAME_SAMPLES - offset);
for (std::size_t sample = 0; sample < count; ++sample) {
double* row = staging_.data() + (staged_ + sample) * kSourceCount;
for (std::size_t channel = 0; channel < kSourceCount; ++channel) {
row[channel] = static_cast<double>(
objects16_planar[channel * JOC_FRAME_SAMPLES + offset + sample]);
}
}
staged_ += count;
offset += count;
if (staged_ == kBlockSamples) {
const Status status = process_block();
if (!status.ok()) {
return status;
}
}
}
input_samples_ += JOC_FRAME_SAMPLES;
return Status::success();
}
std::uint32_t JochrtfRuntime::finish_capacity(double tail_seconds) const {
std::int64_t requested = tail_samples_;
if (tail_seconds >= 0.0) {
requested = static_cast<std::int64_t>(std::ceil(tail_seconds * 48000.0 - 1e-9));
}
const std::int64_t hrtf_bound = static_cast<std::int64_t>(hrtf_history_slots_) * 64;
const std::int64_t early_bound = hrtf_bound + 2048 + 256 * 64;
std::int64_t drain = std::max(requested, early_bound) + 961;
drain = ((drain + 63) / 64) * 64;
return static_cast<std::uint32_t>(drain);
}
Status JochrtfRuntime::reset() {
if (handle_ == nullptr) {
return Status::fail(JOC_ERR_STATE, stage::kRender, "binaural runtime is not open");
}
if (ejoc_jochrtf_reset(handle_) != 0) {
return Status::fail(JOC_ERR_RENDER_FAILED, stage::kRender, "sofa reset failed");
}
timeline_.reset();
output_.clear();
staged_ = 0;
input_samples_ = 0;
processed_samples_ = 0;
blocks_processed_ = 0;
return Status::success();
}
Status JochrtfRuntime::finish(std::uint32_t flush_samples, std::vector<double>* out) {
if (handle_ == nullptr) {
return Status::fail(JOC_ERR_STATE, stage::kRender, "binaural runtime is not open");
}
if (out == nullptr) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender, "null output");
}
out->clear();
if (flush_samples == 0u) {
return Status::success();
}
std::vector<double> chunk(static_cast<std::size_t>(kBlockSamples) * 2u, 0.0);
std::uint32_t produced_total = 0;
std::uint32_t remaining = flush_samples;
while (remaining > 0) {
const std::uint32_t request = std::min<std::uint32_t>(remaining, kBlockSamples);
const int produced = ejoc_jochrtf_finish(handle_, request, chunk.data(), request);
if (produced < 0) {
const char* message = ejoc_jochrtf_last_error(handle_);
return Status::fail(JOC_ERR_RENDER_FAILED, stage::kRender,
std::string("sofa finish failed: ") +
(message != nullptr ? message : "unknown"));
}
if (produced == 0) {
break;
}
out->insert(out->end(), chunk.begin(),
chunk.begin() + static_cast<std::ptrdiff_t>(produced) * 2);
produced_total += static_cast<std::uint32_t>(produced);
remaining -= std::min<std::uint32_t>(remaining, static_cast<std::uint32_t>(produced));
}
return Status::success();
}
} // namespace joc::binaural