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.
506 lines
20 KiB
C
506 lines
20 KiB
C
/*
|
|
* joc_core.h -- JustOneCacophony C++ Core, public ABI. Pure C.
|
|
*
|
|
* This header is the single authoritative definition of the Core's public
|
|
* parameter/error surface. Frontends (thin Python CLI, joc_dump, foobar2000,
|
|
* MPV, FFmpeg) only ever fill these POD structs and read these POD results;
|
|
* no audio data, no internal DSP concept, and no Python type crosses this
|
|
* boundary.
|
|
*
|
|
* Stability tiers
|
|
* ---------------
|
|
* [T1] host tier
|
|
* joc_abi_version / joc_version_string / joc_build_info, joc_error,
|
|
* joc_error_name / joc_error_stage, joc_last_error_detail.
|
|
* Stable, versioned, safe for media hosts.
|
|
*
|
|
* [T2] bitstream / verification tier
|
|
* joc_parse_eac3_frame, joc_parse_id14, joc_frame_params, joc_emdf_info.
|
|
* These deliberately expose the dequantized JOC matrix coefficients so the
|
|
* bitstream front-end can be validated bit-exactly and driven by tooling
|
|
* (joc_dump) and A/B harnesses. Media hosts must NOT use this tier; they
|
|
* use the task/stream API (added in later milestones).
|
|
*
|
|
* Conventions
|
|
* -----------
|
|
* * every struct's first two fields are struct_size / struct_version;
|
|
* * all arrays are fixed size and POD, no pointers, no allocation;
|
|
* * every function returns joc_error (JOC_OK == 0);
|
|
* * joc_last_error_detail() returns a thread-local message that stays valid
|
|
* until the next Core call on the same thread.
|
|
*/
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
|
|
#include "joc_version.h"
|
|
|
|
#define JOC_ABI_VERSION 6u
|
|
#define JOC_FRAME_PARAMS_VERSION 2u
|
|
#define JOC_EMDF_INFO_VERSION 2u
|
|
#define JOC_TASK_CONFIG_VERSION 4u
|
|
#define JOC_TASK_RESULT_VERSION 2u
|
|
#define JOC_EVENT_VERSION 1u
|
|
|
|
/* JOC_STATIC: this branch exists for building the sources directly into an application, where nothing is imported or exported. */
|
|
#if defined(JOC_STATIC)
|
|
#define JOC_API
|
|
#define JOC_CALL __cdecl
|
|
#elif defined(_WIN32)
|
|
#if defined(JOC_BUILD_DLL)
|
|
#define JOC_API __declspec(dllexport)
|
|
#else
|
|
#define JOC_API __declspec(dllimport)
|
|
#endif
|
|
#define JOC_CALL __cdecl
|
|
#else
|
|
#define JOC_API __attribute__((visibility("default")))
|
|
#define JOC_CALL
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ------------------------------------------------------------------ */
|
|
/* Fixed layout constants (single source of truth for every frontend) */
|
|
/* ------------------------------------------------------------------ */
|
|
enum {
|
|
JOC_FRAME_SAMPLES = 1536, /* E-AC-3 frame = 24 * 64 */
|
|
JOC_TIMESLOTS = 24,
|
|
JOC_SUBBANDS = 64,
|
|
JOC_CORE_CHANNELS = 5, /* L R C Ls Rs (JOC order) */
|
|
JOC_MAX_CORE_CHANNELS = 7, /* dmx_config_idx 1/2/4 declare 7 */
|
|
JOC_OUTPUT_CHANNELS = 16, /* ch0 = LFE, ch1..15 = objects */
|
|
JOC_MAX_OBJECTS = 15,
|
|
JOC_MAX_DPOINTS = 2,
|
|
JOC_MAX_PARAMETER_BANDS = 23,
|
|
JOC_MAX_EMDF_PAYLOADS = 16,
|
|
JOC_SPEAKER_BLOCK_SAMPLES = 32,
|
|
JOC_BINAURAL_BLOCK_SAMPLES = 512,
|
|
JOC_BINAURAL_QMF_BANDS = 64,
|
|
JOC_BINAURAL_HYBRID_BANDS = 77,
|
|
JOC_QMF_HOP_SAMPLES = 64,
|
|
JOC_BINAURAL_LATENCY_SAMPLES = 961, /* SOFA/.jochrtf and Rosella bank 1 */
|
|
JOC_LFE_DELAY_SAMPLES = 1217
|
|
};
|
|
|
|
/* ------------------------------------------------------------------ */
|
|
/* [T1] library / error surface */
|
|
/* ------------------------------------------------------------------ */
|
|
typedef enum joc_error {
|
|
JOC_OK = 0,
|
|
JOC_ERR_INVALID_ARGUMENT,
|
|
JOC_ERR_INVALID_CONFIG,
|
|
JOC_ERR_OUT_OF_MEMORY,
|
|
JOC_ERR_IO,
|
|
JOC_ERR_UNSUPPORTED_PLATFORM,
|
|
JOC_ERR_LIBRARY_MISSING,
|
|
/* input / bitstream */
|
|
JOC_ERR_INPUT_NOT_FOUND,
|
|
JOC_ERR_INPUT_FORMAT,
|
|
JOC_ERR_EAC3_SYNCFRAME,
|
|
JOC_ERR_EMDF_TRANSPORT,
|
|
JOC_ERR_EMDF_SYNTAX,
|
|
JOC_ERR_JOC_SYNTAX,
|
|
JOC_ERR_JOC_UNSUPPORTED_VARIANT,
|
|
JOC_ERR_OAMD_SYNTAX,
|
|
JOC_ERR_OAMD_UNSUPPORTED_VARIANT,
|
|
JOC_ERR_BITSTREAM_TRUNCATED,
|
|
JOC_ERR_BITSTREAM_PADDING,
|
|
/* resources */
|
|
JOC_ERR_HRTF_NOT_FOUND,
|
|
JOC_ERR_HRTF_FORMAT,
|
|
JOC_ERR_HRTF_VERSION,
|
|
JOC_ERR_HRTF_HASH,
|
|
JOC_ERR_HRTF_UNSUPPORTED_CONVENTION,
|
|
/* rendering / output */
|
|
JOC_ERR_LAYOUT_UNSUPPORTED,
|
|
JOC_ERR_RENDER_FAILED,
|
|
JOC_ERR_OUTPUT_OPEN,
|
|
JOC_ERR_OUTPUT_WRITE,
|
|
JOC_ERR_OUTPUT_CLIP_ABORT,
|
|
JOC_ERR_ADM_VALIDATION,
|
|
/* task / stream */
|
|
JOC_ERR_CANCELLED,
|
|
JOC_ERR_STATE,
|
|
JOC_ERR_NOT_SUPPORTED,
|
|
JOC_ERR_INTERNAL
|
|
} joc_error;
|
|
|
|
JOC_API uint32_t JOC_CALL joc_abi_version(void);
|
|
JOC_API const char* JOC_CALL joc_version_string(void);
|
|
JOC_API const char* JOC_CALL joc_build_info(void);
|
|
/* Struct sizes, so a binding can assert its layout matches the library instead of
|
|
* assuming (mismatches are otherwise silent memory corruption). */
|
|
JOC_API uint32_t JOC_CALL joc_event_size(void);
|
|
JOC_API uint32_t JOC_CALL joc_task_config_size(void);
|
|
JOC_API uint32_t JOC_CALL joc_task_result_size(void);
|
|
JOC_API const char* JOC_CALL joc_error_name(joc_error code);
|
|
JOC_API const char* JOC_CALL joc_error_stage(joc_error code);
|
|
/* Thread-local structured detail for the most recent failing call. */
|
|
JOC_API const char* JOC_CALL joc_last_error_detail(void);
|
|
|
|
/* ------------------------------------------------------------------ */
|
|
/* [T2] bitstream / verification tier */
|
|
/* ------------------------------------------------------------------ */
|
|
|
|
/* One EMDF payload directory entry. bit_offset is the MSB-first bit
|
|
* position of the payload's first byte inside the syncframe, exactly as the
|
|
* EMDF container syntax defines it (payloads are not byte aligned in general). */
|
|
typedef struct joc_emdf_payload_info {
|
|
uint8_t id;
|
|
uint8_t reserved[3];
|
|
uint32_t sample_offset; /* EMDF outer smpoffst: variable_bits(11) */
|
|
uint32_t bit_offset;
|
|
uint32_t size; /* payload bytes */
|
|
} joc_emdf_payload_info;
|
|
|
|
typedef struct joc_emdf_info {
|
|
uint32_t struct_size;
|
|
uint32_t struct_version;
|
|
uint32_t start_bit; /* container syncword bit position */
|
|
uint32_t container_bytes; /* 4 + declared length */
|
|
uint32_t payload_count;
|
|
uint32_t reserved;
|
|
joc_emdf_payload_info payloads[JOC_MAX_EMDF_PAYLOADS];
|
|
} joc_emdf_info;
|
|
|
|
/* Per-object ID14/JOC descriptor plus its dequantized matrix.
|
|
* dq[dp][ch][pb] is zero filled outside [0,n_dpoints) x [0,n_channels) x
|
|
* [0,n_bands). Absent objects are entirely zero. offset_ts holds the raw
|
|
* 5-bit JOC offsets (legal range 0..23, strictly increasing per object). */
|
|
typedef struct joc_object_params {
|
|
uint8_t present;
|
|
uint8_t num_bands_idx;
|
|
uint8_t n_bands;
|
|
uint8_t sparse; /* 0 = dense (MTX), 1 = sparse (IDX+VEC) */
|
|
uint8_t quant_idx; /* 0 = 96 levels, 1 = 192 levels */
|
|
uint8_t slope_idx; /* 0 = interpolate, 1 = step at offset_ts */
|
|
uint8_t num_dpoints_bits;
|
|
uint8_t n_dpoints;
|
|
uint8_t offset_ts[JOC_MAX_DPOINTS];
|
|
uint8_t reserved[2];
|
|
double dq[JOC_MAX_DPOINTS][JOC_MAX_CORE_CHANNELS][JOC_MAX_PARAMETER_BANDS];
|
|
} joc_object_params;
|
|
|
|
/* Per-frame JOC parse status (joc_frame_params.status). A non-zero status makes
|
|
* the frame invalid for rendering: the renderer holds the previous matrices or
|
|
* passes the core PCM through instead of decoding the matrix. Only status 3
|
|
* still carries a complete object list (object count clamped to 15) for
|
|
* diagnostics; statuses 2 and 4 stop the parse after the failing header field. */
|
|
enum {
|
|
JOC_FRAME_STATUS_OK = 0,
|
|
JOC_FRAME_STATUS_UNSUPPORTED_DMX = 2, /* joc_dmx_config_idx outside 0..4 */
|
|
JOC_FRAME_STATUS_OBJECTS_CLAMPED = 3, /* declared object count above 15 */
|
|
JOC_FRAME_STATUS_BAD_PARAMETER_BAND = 4, /* unknown num_bands index */
|
|
JOC_FRAME_STATUS_BAD_OFFSET_TS = 5, /* offset_ts outside 0..23 or not */
|
|
/* strictly increasing */
|
|
JOC_FRAME_STATUS_TRAILING_DATA = 6 /* bytes after joc_data alignment */
|
|
};
|
|
|
|
typedef struct joc_frame_params {
|
|
uint32_t struct_size;
|
|
uint32_t struct_version;
|
|
uint8_t dmx_config_idx;
|
|
uint8_t num_objects_bits;
|
|
uint8_t ext_config_idx;
|
|
uint8_t n_objects;
|
|
uint8_t n_channels; /* 5 or 7 */
|
|
uint8_t clipgain_x_bits;
|
|
uint8_t clipgain_y_bits;
|
|
uint8_t objects_clamped; /* num_objects_bits+1 exceeded 15 */
|
|
uint32_t seq_count; /* 10-bit JOC sequence counter */
|
|
uint32_t present_mask; /* bit i == object i present */
|
|
uint8_t status; /* JOC_FRAME_STATUS_* */
|
|
uint8_t reserved[3];
|
|
uint32_t data_end_bits; /* bit position just after joc_data */
|
|
uint32_t trailing_bits; /* bits left after joc_data (padding/ext) */
|
|
uint8_t tail_bytes[8]; /* first up to 8 trailing bytes, for A/B */
|
|
double clipgain; /* 2^(x-4) * (1 + y/32), bit-exact */
|
|
joc_object_params objects[JOC_MAX_OBJECTS];
|
|
} joc_frame_params;
|
|
|
|
/* Parse an EMDF ID14 (JOC) payload. */
|
|
JOC_API joc_error JOC_CALL joc_parse_id14(const uint8_t* payload, size_t payload_size,
|
|
joc_frame_params* out_params);
|
|
|
|
/* Locate the contiguous JOC EMDF container inside one E-AC-3 syncframe and
|
|
* parse its ID14 payload. out_emdf may be NULL. */
|
|
JOC_API joc_error JOC_CALL joc_parse_eac3_frame(const uint8_t* frame, size_t frame_size,
|
|
joc_frame_params* out_params,
|
|
joc_emdf_info* out_emdf);
|
|
|
|
/* Copy one payload's bytes out of a syncframe (MSB-first bit extraction, which
|
|
* equals a memcpy for byte-aligned containers). out_size receives the payload
|
|
* byte count; pass out == NULL to query only the size. */
|
|
JOC_API joc_error JOC_CALL joc_extract_payload(const uint8_t* frame, size_t frame_size,
|
|
const joc_emdf_payload_info* payload,
|
|
uint8_t* out, size_t out_capacity,
|
|
size_t* out_size);
|
|
|
|
/* E-AC-3 syncframe traversal: given the offset of a frame start, report its
|
|
* byte length so a host can walk a bare E-AC-3 stream without duplicating
|
|
* frmsiz logic. Rejects resynchronisation (no silent recovery). */
|
|
JOC_API joc_error JOC_CALL joc_eac3_frame_bytes(const uint8_t* data, size_t size,
|
|
size_t offset, size_t* out_frame_bytes);
|
|
|
|
/* Strict trailing-bit check for the JOC payload (A/B robustness corpus).
|
|
* Returns JOC_ERR_BITSTREAM_PADDING when more than 7 bits are left over or the
|
|
* leftover bits are not zero. */
|
|
JOC_API joc_error JOC_CALL joc_check_id14_padding(const uint8_t* payload, size_t payload_size,
|
|
uint32_t* out_trailing_bits);
|
|
|
|
/* ================================================================== */
|
|
/* [T1] host tier: task, telemetry and control */
|
|
/* ================================================================== */
|
|
|
|
/* ---- 1. events ---------------------------------------------------- */
|
|
/*
|
|
* Events carry state only: frame/sample counters, stage, progress, statistics,
|
|
* warnings, errors and paths. Audio never travels through an event; a fixed
|
|
* size POD with no pointers keeps that enforceable (see the static assertion in
|
|
* the implementation).
|
|
*/
|
|
typedef enum joc_event_type {
|
|
JOC_EV_TASK_STARTED = 0x0001,
|
|
JOC_EV_TASK_STATE_CHANGED = 0x0002,
|
|
JOC_EV_TASK_COMPLETED = 0x0003,
|
|
JOC_EV_TASK_FAILED = 0x0004,
|
|
JOC_EV_TASK_CANCELLED = 0x0005,
|
|
JOC_EV_INPUT_OPENED = 0x0101,
|
|
JOC_EV_METADATA_INDEXED = 0x0103,
|
|
JOC_EV_HRTF_LOADED = 0x0110,
|
|
JOC_EV_RENDERER_INITIALIZED = 0x0120,
|
|
JOC_EV_PROGRESS = 0x0201,
|
|
JOC_EV_STAGE_CHANGED = 0x0202,
|
|
JOC_EV_JOC_FRAME_STATS = 0x0301,
|
|
JOC_EV_OAMD_STATS = 0x0302,
|
|
JOC_EV_OUTPUT_STATS = 0x0303,
|
|
JOC_EV_OUTPUT_OPENED = 0x0401,
|
|
JOC_EV_OUTPUT_FORMAT_DECIDED = 0x0402,
|
|
JOC_EV_OUTPUT_FINALIZED = 0x0403,
|
|
JOC_EV_LOG = 0x0501,
|
|
JOC_EV_WARNING = 0x0502,
|
|
JOC_EV_ERROR = 0x0503
|
|
} joc_event_type;
|
|
|
|
typedef enum joc_stage {
|
|
JOC_STAGE_IDLE = 0,
|
|
JOC_STAGE_INPUT = 1,
|
|
JOC_STAGE_METADATA = 2,
|
|
JOC_STAGE_DECODE = 3,
|
|
JOC_STAGE_JOC = 4,
|
|
JOC_STAGE_RENDER = 5,
|
|
JOC_STAGE_OUTPUT = 6,
|
|
JOC_STAGE_DONE = 7
|
|
} joc_stage;
|
|
|
|
enum { JOC_LOG_TRACE = 0, JOC_LOG_DEBUG = 1, JOC_LOG_INFO = 2, JOC_LOG_NOTICE = 3,
|
|
JOC_LOG_WARNING = 4, JOC_LOG_ERROR = 5, JOC_LOG_FATAL = 6 };
|
|
|
|
typedef struct joc_event {
|
|
uint32_t struct_size;
|
|
uint32_t type;
|
|
uint64_t sequence;
|
|
uint64_t timestamp_us;
|
|
uint64_t current_frame;
|
|
uint64_t total_frames;
|
|
uint64_t current_sample;
|
|
uint64_t total_samples;
|
|
uint32_t stage;
|
|
uint32_t backend;
|
|
double progress; /* 0..1, -1 = unknown */
|
|
double elapsed_seconds;
|
|
double realtime_factor;
|
|
uint64_t output_samples;
|
|
uint64_t output_bytes;
|
|
double output_duration_seconds;
|
|
joc_error error_code;
|
|
uint32_t log_level;
|
|
char stage_name[32];
|
|
char message[256];
|
|
} joc_event;
|
|
|
|
typedef void (JOC_CALL *joc_event_fn)(void* user, const joc_event* event);
|
|
|
|
typedef struct joc_event_sink {
|
|
uint32_t struct_size;
|
|
joc_event_fn callback;
|
|
void* user;
|
|
uint32_t min_type; /* 0 = no filter */
|
|
uint32_t max_type; /* 0 = no filter */
|
|
} joc_event_sink;
|
|
|
|
/* ---- 2. cancellation ---------------------------------------------- */
|
|
typedef struct joc_cancel_token joc_cancel_token;
|
|
|
|
JOC_API joc_cancel_token* JOC_CALL joc_cancel_token_create(void);
|
|
JOC_API void JOC_CALL joc_cancel_token_request(joc_cancel_token* token);
|
|
JOC_API int32_t JOC_CALL joc_cancel_token_is_requested(const joc_cancel_token* token);
|
|
JOC_API void JOC_CALL joc_cancel_token_destroy(joc_cancel_token* token);
|
|
|
|
/* ---- 3. task configuration and results ---------------------------- */
|
|
typedef enum joc_operation {
|
|
JOC_OP_ADM_BWF = 0,
|
|
JOC_OP_SPEAKER = 1,
|
|
JOC_OP_BINAURAL = 2
|
|
} joc_operation;
|
|
|
|
typedef enum joc_output_format {
|
|
JOC_FORMAT_FLOAT32 = 0,
|
|
JOC_FORMAT_PCM24 = 1
|
|
} joc_output_format;
|
|
|
|
typedef enum joc_binaural_mode {
|
|
JOC_BINAURAL_OFF = 0,
|
|
JOC_BINAURAL_NEAR = 1,
|
|
JOC_BINAURAL_FAR = 2,
|
|
JOC_BINAURAL_MID = 3
|
|
} joc_binaural_mode;
|
|
|
|
typedef enum joc_trajectory_mode {
|
|
JOC_TRAJECTORY_COMPACT = 0,
|
|
JOC_TRAJECTORY_DENSE64 = 1
|
|
} joc_trajectory_mode;
|
|
|
|
/* What to do when an int24 WAV would clip (peak outside [-1, 1]). Mirrors the
|
|
* reference CLI's --clip-action; ADM BWF output is always int24 and does not
|
|
* consult this because no alternative format exists there. */
|
|
typedef enum joc_clip_action {
|
|
JOC_CLIP_ASK = 0, /* prompt on stdin; an error when stdin is not a terminal */
|
|
JOC_CLIP_CONTINUE = 1, /* write int24, truncating out-of-range values */
|
|
JOC_CLIP_FLOAT32 = 2, /* switch the output to float32 */
|
|
JOC_CLIP_ABORT = 3 /* fail the task */
|
|
} joc_clip_action;
|
|
|
|
/* Which 64-QMF / 77-hybrid filterbank the Rosella .personalized_headphone path
|
|
* renders through. The two banks differ in coefficients, hybrid tap count,
|
|
* high-band slot delay and total latency, so they are not interchangeable; the
|
|
* SOFA and .jochrtf paths always use JOC_ROSELLA_FILTERBANK_PUBLIC. */
|
|
typedef enum joc_rosella_filterbank {
|
|
JOC_ROSELLA_FILTERBANK_PUBLIC = 1, /* 13-tap hybrid, 6-slot delay, 961 samples */
|
|
JOC_ROSELLA_FILTERBANK_CAPTURED = 2 /* 11-tap hybrid, 3-slot delay, 448 samples */
|
|
} joc_rosella_filterbank;
|
|
|
|
enum { JOC_TASK_F_SKIP_SHA256 = 1u, JOC_TASK_F_KEEP_INTERMEDIATE = 2u,
|
|
JOC_TASK_F_QUIET = 4u, JOC_TASK_F_METADATA_ONLY = 8u };
|
|
|
|
typedef struct joc_task_config {
|
|
uint32_t struct_size;
|
|
uint32_t struct_version;
|
|
|
|
/* input */
|
|
const char* input_path; /* .eac3/.ec3/.m4a/... */
|
|
const char* ffmpeg_path; /* NULL = FFMPEG, then "ffmpeg" on PATH */
|
|
const char* bed_path; /* NULL = decode the core PCM with ffmpeg */
|
|
const char* work_dir; /* NULL = a temporary directory */
|
|
double eac3_drc_scale; /* 0 = DRC off (reference default) */
|
|
int32_t eac3_target_level; /* -31..0, 0 = not applied */
|
|
|
|
/* output */
|
|
uint32_t operation;
|
|
const char* output_path;
|
|
uint32_t output_format; /* requested format for speaker/binaural */
|
|
uint32_t flags;
|
|
uint32_t clip_action; /* joc_clip_action; JOC_CLIP_ASK by default */
|
|
|
|
/* rendering */
|
|
const char* speaker_layout_name;
|
|
uint32_t speaker_metadata_offset; /* default 1473 */
|
|
uint32_t binaural_mode;
|
|
const char* hrtf_path; /* .jochrtf */
|
|
const char* kernels_path; /* rosella_kernels.npz */
|
|
double binaural_tail_seconds; /* default 5.0 */
|
|
double binaural_tail_threshold; /* binaural only; 0 disables trimming */
|
|
uint32_t binaural_chunk_frames; /* accepted for CLI parity; no effect */
|
|
|
|
/* ADM */
|
|
uint32_t adm_binaural_mode; /* DBMD segment 10 encoding */
|
|
uint32_t trajectory_mode;
|
|
|
|
/* generic */
|
|
uint32_t object_delay_samples; /* default 1473 */
|
|
double gain_db; /* default 0 */
|
|
uint64_t duration_frames; /* 0 = the whole stream */
|
|
uint32_t progress_interval_frames; /* default 1000 */
|
|
uint32_t native_threads; /* 0 = automatic */
|
|
|
|
/* diagnostics */
|
|
uint32_t print_metadata; /* 0 none, 1 summary, 2 per frame */
|
|
const char* metadata_json_path; /* NULL = no JSON summary */
|
|
|
|
joc_cancel_token* cancel; /* optional */
|
|
|
|
/* Binaural input (config version 2): a compiled .jochrtf field (hrtf_path)
|
|
* or a Rosella .personalized_headphone model. */
|
|
const char* personalized_headphone_path; /* Rosella .personalized_headphone input */
|
|
uint32_t rosella_filterbank; /* joc_rosella_filterbank; 0 = PUBLIC */
|
|
uint32_t jochrtf_room; /* non-zero enables the project room */
|
|
} joc_task_config;
|
|
|
|
typedef enum joc_task_status {
|
|
JOC_TASK_OK = 0,
|
|
JOC_TASK_FAILED = 1,
|
|
JOC_TASK_CANCELLED = 2
|
|
} joc_task_status;
|
|
|
|
typedef struct joc_task_result {
|
|
uint32_t struct_size;
|
|
uint32_t struct_version;
|
|
uint32_t status;
|
|
uint32_t error_code;
|
|
char error_message[512];
|
|
char error_stage[32];
|
|
uint64_t input_frames;
|
|
uint64_t output_samples;
|
|
double duration_sec;
|
|
uint32_t output_format_actual;
|
|
double output_peak;
|
|
uint64_t output_over_unity_values;
|
|
uint64_t output_file_bytes;
|
|
char output_sha256[65]; /* empty when skipped */
|
|
uint64_t oamd_payloads;
|
|
uint64_t oamd_transitions;
|
|
double t_decode_bed;
|
|
double t_render;
|
|
double t_write;
|
|
double t_total;
|
|
double t_render_dsp; /* speaker/binaural DSP calls only; 0 for ADM */
|
|
double t_write_file; /* disk writes including the finalize; >= t_write */
|
|
} joc_task_result;
|
|
|
|
typedef struct joc_validation_issue {
|
|
joc_error code;
|
|
uint32_t severity; /* 0 = info, 1 = warning, 2 = error */
|
|
char field[48];
|
|
char message[256];
|
|
} joc_validation_issue;
|
|
|
|
/* ---- 4. entry points ---------------------------------------------- */
|
|
/* Fills `issues` (up to `capacity`) and reports how many were produced.
|
|
* Returns JOC_OK when no *error*-severity issue was found. */
|
|
JOC_API joc_error JOC_CALL joc_task_validate(const joc_task_config* config,
|
|
joc_validation_issue* issues, uint32_t capacity,
|
|
uint32_t* count);
|
|
|
|
/* Runs the whole task on the calling thread. `sink` may be NULL; `out` may be
|
|
* NULL. On cancellation the partial output is removed and JOC_ERR_CANCELLED is
|
|
* returned with out->status = JOC_TASK_CANCELLED. */
|
|
JOC_API joc_error JOC_CALL joc_task_execute(const joc_task_config* config,
|
|
const joc_event_sink* sink, joc_task_result* out);
|
|
|
|
/* Serialises the stable subset of the result as JSON (no environment fields -
|
|
* those belong to the frontend). `needed` receives the required size including
|
|
* the terminator; a NULL buffer queries only the size. */
|
|
JOC_API joc_error JOC_CALL joc_task_result_to_json(const joc_task_result* result, char* buffer,
|
|
size_t capacity, size_t* needed);
|
|
|
|
/* The streaming (push/pull) tier lives in "joc_stream.h" so an embedder can
|
|
* include the narrow surface without the bitstream/verification tier. */
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|