Files
JustOneCacophony/include/eac3joc_core.h
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

373 lines
15 KiB
C

#pragma once
#include <stdint.h>
/* EJOC_STATIC: this branch exists for building the sources directly into an application, where nothing is imported or exported. */
#if defined(EJOC_STATIC)
#define EJOC_API
#define EJOC_CALL __cdecl
#elif defined(_WIN32)
#if defined(EJOC_BUILD_DLL)
#define EJOC_API __declspec(dllexport)
#else
#define EJOC_API __declspec(dllimport)
#endif
#define EJOC_CALL __cdecl
#else
#define EJOC_API __attribute__((visibility("default")))
#define EJOC_CALL
#endif
#ifdef __cplusplus
extern "C" {
#endif
enum {
EJOC_ABI_VERSION = 4,
EJOC_FRAME_SAMPLES = 1536,
EJOC_TIMESLOTS = 24,
EJOC_SUBBANDS = 64,
EJOC_CORE_CHANNELS = 5, /* downmix configurations 0 and 3 */
EJOC_MAX_CORE_CHANNELS = 7, /* downmix configurations 1, 2 and 4 */
EJOC_OUTPUT_CHANNELS = 16,
EJOC_CORE_OUT_CHANNELS = 8, /* passthrough order: L,R,C,LFE,Ls,Rs,(Lrs,Rrs) */
EJOC_LFE_SLOT = 3, /* LFE slot of the passthrough order */
EJOC_MAX_OBJECTS = 15,
EJOC_MAX_DPOINTS = 2,
EJOC_MAX_PARAMETER_BANDS = 23,
EJOC_SPEAKER_BLOCK_SAMPLES = 32,
EJOC_SPEAKER_COORDINATES = 3,
EJOC_SPEAKER_CONTROLS_VERSION = 1,
EJOC_BINAURAL_BLOCK_SAMPLES = 512,
EJOC_BINAURAL_INPUT_CHANNELS = 16,
EJOC_BINAURAL_OUTPUT_CHANNELS = 2,
EJOC_BINAURAL_QMF_BANDS = 64,
EJOC_BINAURAL_HYBRID_BANDS = 77
};
/* Per-frame status of ejoc_renderer_render_frame(). A status outside 0..6 is
* the renderer's own no-metadata marker; the parse-status values match
* joc_frame_params.status (JOC_FRAME_STATUS_* in joc_core.h). Any non-zero
* status makes the frame invalid for matrix rendering: the renderer holds the
* previous matrices or passes the core PCM through instead of decoding it. */
enum {
EJOC_FRAME_STATUS_OK = 0,
EJOC_FRAME_STATUS_UNSUPPORTED_DMX = 2,
EJOC_FRAME_STATUS_OBJECTS_CLAMPED = 3,
EJOC_FRAME_STATUS_BAD_PARAMETER_BAND = 4,
EJOC_FRAME_STATUS_BAD_OFFSET_TS = 5,
EJOC_FRAME_STATUS_TRAILING_DATA = 6,
EJOC_FRAME_STATUS_NO_METADATA = 8
};
typedef void* ejoc_renderer_handle;
typedef void* ejoc_speaker_renderer_handle;
typedef void* ejoc_binaural_renderer_handle;
/*
Fixed array layouts used by ejoc_renderer_process():
bed_planar [core_channel_count][1536]
lfe [1536] or NULL
n_bands [15]
n_dpoints [15]
slope_idx [15]
offset_ts [15][2]
dq [15][2][7][23]
output16 [16][1536]
core_channel_count comes from ejoc_renderer_set_core_channels() and defaults to
EJOC_CORE_CHANNELS; the dq stride is always EJOC_MAX_CORE_CHANNELS.
Only objects selected by object_mask are read from the descriptor arrays.
dq carries already dequantized matrix coefficients in double precision; the
caller performs the JOC bitstream differential decoding for both dense and
sparse objects, so this ABI is identical for both syntaxes.
*/
EJOC_API uint32_t EJOC_CALL ejoc_abi_version(void);
EJOC_API const char* EJOC_CALL ejoc_build_info(void);
EJOC_API ejoc_renderer_handle EJOC_CALL ejoc_renderer_create(void);
EJOC_API void EJOC_CALL ejoc_renderer_destroy(ejoc_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_renderer_reset(ejoc_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_renderer_set_threads(ejoc_renderer_handle handle, uint32_t total_threads);
/*
core_channel_count comes from joc_dmx_config_idx: 5 for configurations 0 and 3,
7 for 1, 2 and 4. bed_planar is then [core_channel_count][1536] and only channels
below core_channel_count are read from dq, whose stride stays [15][2][7][23].
phase_shift is sigma(k) = (k in {3,4}): it enables the Ls/Rs -j rotation of
subbands above 0 together with the band-0 21-tap DC compensation. With the switch
off, channels 3 and 4 only take the common ten-slot surround delay. The delay
line and DC history advance either way, so the flag may change between frames.
*/
EJOC_API uint32_t EJOC_CALL ejoc_renderer_thread_count(ejoc_renderer_handle handle);
EJOC_API const char* EJOC_CALL ejoc_renderer_last_error(ejoc_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_renderer_process(
ejoc_renderer_handle handle,
const float* bed_planar,
const float* lfe,
uint32_t core_channel_count,
uint32_t phase_shift,
uint32_t object_mask,
const uint8_t* n_bands,
const uint8_t* n_dpoints,
const uint8_t* slope_idx,
const uint8_t* offset_ts,
const double* dq,
double clipgain,
float phase_new,
float output_scale,
float* output16_planar);
/*
Frame-level entry point: one E-AC-3 audio frame per call, with the seq state
machine and the per-object previous-matrix state kept inside the renderer. This
is what produces the 16-channel object result for the ADM, speaker and binaural
backends; ejoc_renderer_process() stays as a single-frame kernel for A/B tests.
Fixed array layouts, identical to ejoc_renderer_process():
bed_planar [core_channel_count][1536] (JOC lane order L,R,C,Ls,Rs,(pair))
lfe [1536] or NULL (zeros; the LFE delay ring still advances)
n_bands, n_dpoints, slope_idx [15]
offset_ts [15][2] (raw 5-bit JOC offsets, 0..23)
dq [15][2][7][23]
output16 [16][1536] (ch0 = LFE, ch1..15 = objects)
frame_status is a JOC_FRAME_STATUS_* / EJOC_FRAME_STATUS_* value. has_metadata
is 0 for an audio frame without a JOC EMDF container (frame_status must then be
EJOC_FRAME_STATUS_NO_METADATA); such a frame always passes the 8 core planes
through to output slots 0..7, delayed by 1217 samples, with slots 8..15 zero.
declared_core_channels is the JOC header's n_channels (0 when unknown); a declared
change against the previous frame's actual count turns the frame into a hard cut
with the LFE ring cleared. phase_shift is sigma(k) = (k in {3,4}) for the frame's
downmix configuration; phase_shift_valid = 0 keeps the previous switch (an
unsupported downmix configuration has no usable one). clipgain is the frame's
joc_clipgain when frame_status == 0. seq is the 10-bit JOC sequence counter.
When has_metadata is 0 the object descriptors are ignored.
Slot 0 of output16 is the LFE, slots 1..15 are the 15 objects; each frame's
values are float32(clamped PCM) * output_scale, exactly like the reference.
*/
typedef struct ejoc_frame_input {
uint32_t struct_size;
uint32_t struct_version;
const float* bed_planar;
const float* lfe;
uint32_t core_channel_count;
uint32_t declared_core_channels;
uint32_t phase_shift;
uint32_t phase_shift_valid;
uint32_t frame_status;
uint32_t seq;
uint32_t has_metadata;
uint32_t object_mask;
const uint8_t* n_bands;
const uint8_t* n_dpoints;
const uint8_t* slope_idx;
const uint8_t* offset_ts;
const double* dq;
double clipgain;
float output_scale;
float* output16_planar;
} ejoc_frame_input;
enum { EJOC_FRAME_INPUT_VERSION = 1 };
EJOC_API int EJOC_CALL ejoc_renderer_render_frame(ejoc_renderer_handle handle,
const ejoc_frame_input* input);
/*
High-precision object-to-speaker renderer.
The renderer consumes interleaved float32 input PCM arranged as:
objects16_interleaved [sample_count][16]
where channel 0 is LFE and channels 1..15 are point objects. All spatial
calculations, gain ramps, and accumulation use double. Output is interleaved:
output_interleaved [sample_count][layout_channel_count]
Each metadata entry is a complete object-state snapshot:
metadata_offsets [metadata_count], relative to this process call
ramp_durations [metadata_count], in samples
positions_q15 [metadata_count][15][3]
region_indices [metadata_count][15] or NULL (all region 0)
height_enabled [metadata_count][15] or NULL (all enabled)
object_gains [metadata_count][15] or NULL (all 1.0)
metadata_offsets must be nondecreasing and <= sample_count. sample_count must
be a multiple of EJOC_SPEAKER_BLOCK_SAMPLES. State and unfinished ramps are
preserved across calls.
*/
/*
Per-object speaker controls taken from OAMD metadata: warp mode, trim mode,
the three trim levels and the two front-back balances. trim_bypass is indexed
by object slot (1..15); slot 0 carries the LFE and is unused.
warp_mode 0 leaves the floor Y coordinate unchanged; mode 1 maps it through
clamp(2Y, 0, 1). Modes 2 and 3 render the 5.1-family and 4.0 layouts through an
expanded surround layout (7.1-family, or a rear pair added to 4.0 without a
centre or LFE) and fold the rear pair into the target surround pair: mode 2
uses the PLIIx coefficients (sqrt(3)/2 and 1/2), mode 3 the Standard (Lo/Ro)
coefficients (1 and 0). Layouts without a single surround pair render directly.
trim_mode selects where the gain comes from: automatic applies the layout
position compensation, disabled applies no trim, and explicit applies the
position-dependent trim from centre_db / surround_db / height_db. A bypassed
object keeps its warp but loses the balance and the trim gain.
Controls may change between calls; each call's metadata events use the
controls passed with that call. A null pointer means warp 0, no trim and no
balance.
*/
typedef enum ejoc_speaker_trim_mode {
EJOC_SPEAKER_TRIM_AUTOMATIC = 0,
EJOC_SPEAKER_TRIM_DISABLED = 1,
EJOC_SPEAKER_TRIM_EXPLICIT = 2
} ejoc_speaker_trim_mode;
typedef struct ejoc_speaker_controls {
uint32_t struct_size;
uint32_t struct_version;
uint32_t warp_mode;
uint32_t trim_mode; /* ejoc_speaker_trim_mode */
double centre_db;
double surround_db; /* positive values are treated as zero */
double height_db; /* positive values are treated as zero */
double listener_balance; /* [-1, 1] */
double overhead_balance; /* [-1, 1] */
uint8_t trim_bypass[EJOC_MAX_OBJECTS + 1]; /* per object slot, slot 0 unused */
} ejoc_speaker_controls;
EJOC_API uint32_t EJOC_CALL ejoc_speaker_layout_channel_count(uint32_t speaker_bitfield);
EJOC_API ejoc_speaker_renderer_handle EJOC_CALL ejoc_speaker_renderer_create(uint32_t speaker_bitfield);
EJOC_API void EJOC_CALL ejoc_speaker_renderer_destroy(ejoc_speaker_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_speaker_renderer_reset(ejoc_speaker_renderer_handle handle);
EJOC_API const char* EJOC_CALL ejoc_speaker_renderer_last_error(ejoc_speaker_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_speaker_renderer_process(
ejoc_speaker_renderer_handle handle,
const float* objects16_interleaved,
uint32_t sample_count,
uint32_t metadata_count,
const uint32_t* metadata_offsets,
const uint32_t* ramp_durations,
const uint16_t* positions_q15,
const uint8_t* region_indices,
const uint8_t* height_enabled,
const double* object_gains,
const ejoc_speaker_controls* controls,
double* output_interleaved);
EJOC_API ejoc_binaural_renderer_handle EJOC_CALL ejoc_binaural_renderer_create(void);
EJOC_API void EJOC_CALL ejoc_binaural_renderer_destroy(ejoc_binaural_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_binaural_renderer_reset(ejoc_binaural_renderer_handle handle);
EJOC_API const char* EJOC_CALL ejoc_binaural_renderer_last_error(
ejoc_binaural_renderer_handle handle);
EJOC_API int EJOC_CALL ejoc_binaural_renderer_configure_kernels(
ejoc_binaural_renderer_handle handle,
const double* qmf_analysis,
const double* hybrid_low,
const int16_t* hybrid_indices,
const double* hybrid_values,
uint32_t hybrid_count,
const double* qmf_basis,
const double* qmf_taps);
EJOC_API int EJOC_CALL ejoc_binaural_renderer_configure_room(
ejoc_binaural_renderer_handle handle,
uint32_t bands,
uint32_t allpass_count,
const uint32_t* allpass_delays,
const double* allpass_gains,
const uint32_t* fdn_delays,
const double* fdn_matrix,
uint32_t output_tap_delay,
const double* feedback_complex,
const double* output_taps,
const double* output_complex,
uint32_t extra_count,
const uint32_t* extra_delays,
const double* extra_fields_complex,
const double* extra_matrices);
EJOC_API int EJOC_CALL ejoc_binaural_renderer_process(
ejoc_binaural_renderer_handle handle,
const double* input16_interleaved,
const double* gains_complex,
const double* room_sends,
double output_gain,
double* output_stereo_interleaved);
/*
Native SOFA binaural renderer.
The handle owns the complete runtime: 64-QMF/77-hybrid analysis and synthesis,
fifth-order ACN/N3D real spherical-harmonic direction-field evaluation,
per-object whole-QMF-slot delay histories, six first-order image-source early
reflections, the shared unitary-FDN late room, the 120-180 Hz LFE low-pass and
the 961-sample latency compensation. The caller configures the filterbank
tables, the compiled HRTF field and the room constants once, then per 512-sample
block updates every source with ejoc_jochrtf_set_source() and calls
ejoc_jochrtf_process(). Process returns the number of trimmed stereo
samples written; the first 961 processed samples across calls are discarded.
*/
typedef void* ejoc_jochrtf_handle;
EJOC_API ejoc_jochrtf_handle EJOC_CALL ejoc_jochrtf_create(void);
EJOC_API void EJOC_CALL ejoc_jochrtf_destroy(ejoc_jochrtf_handle handle);
EJOC_API int EJOC_CALL ejoc_jochrtf_reset(ejoc_jochrtf_handle handle);
EJOC_API const char* EJOC_CALL ejoc_jochrtf_last_error(
ejoc_jochrtf_handle handle);
EJOC_API int EJOC_CALL ejoc_jochrtf_configure_kernels(
ejoc_jochrtf_handle handle,
const double* qmf_analysis,
const double* hybrid_low,
const int16_t* hybrid_indices,
const double* hybrid_values,
uint32_t hybrid_count,
const double* qmf_basis,
const double* qmf_taps);
EJOC_API int EJOC_CALL ejoc_jochrtf_configure_field(
ejoc_jochrtf_handle handle,
const double* coefficients,
const double* delay_coefficients,
const double* delay_bounds,
const double* band_centers,
double measurement_radius_m);
EJOC_API int EJOC_CALL ejoc_jochrtf_configure_room(
ejoc_jochrtf_handle handle,
const double* room_dims,
const double* listener_pos,
const double* wall_gains,
double speed_of_sound,
const uint32_t* fdn_delays,
const double* fdn_feedback,
double damping,
double fdn_output_gain,
const uint32_t* allpass_delays,
const double* allpass_gains,
uint32_t enable_early_reflections,
uint32_t enable_late_room);
EJOC_API int EJOC_CALL ejoc_jochrtf_set_source(
ejoc_jochrtf_handle handle,
uint32_t source,
const double* position_adm,
uint32_t profile,
double gain,
uint32_t enabled,
uint32_t special_lfe,
uint32_t fade);
EJOC_API int EJOC_CALL ejoc_jochrtf_process(
ejoc_jochrtf_handle handle,
const double* input16_interleaved,
uint32_t sample_count,
double output_gain,
double* output_stereo_interleaved);
EJOC_API int EJOC_CALL ejoc_jochrtf_finish(
ejoc_jochrtf_handle handle,
uint32_t flush_samples,
double* output_stereo_interleaved,
uint32_t capacity);
#ifdef __cplusplus
}
#endif