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.
373 lines
15 KiB
C
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
|