/* * joc_stream.h -- streaming (push/pull) interface of the JustOneCacophony core. * * This is the narrow, embedder-facing surface: a player or decoder component * includes only this header. It is the same shared library as joc_core.h, split * so an integrator never has to see the bitstream/verification tier. * * A stream is a stateful instance for hosts that cannot wait for a whole file: * the caller feeds E-AC-3 bytes and the core PCM of the same frames (or already * rebuilt objects16) and pulls rendered PCM as soon as it is available. It * mirrors the two library shapes a decoder library normally offers: this * push/pull form for host-owned I/O, and joc_task_execute() in joc_core.h for * library-owned file I/O. * * Contract: * - all state is instance-private, so several streams coexist; * - a stream is NOT thread safe: push and pull must come from one thread; * - rendering is stateful (matrix interpolation, gain ramps, room tail), so a * new position on the timeline requires decoding to continue from the start * of the stream; there is no seek in this version; * - the kernel latency is 961 samples for speaker/binaural output: the first * pull after two 512-sample blocks, and flush() drains the binaural tail. */ #pragma once #include "joc_core.h" /* JOC_STATIC (building the sources directly into an application): joc_core.h above already installs the empty JOC_API. */ #if defined(JOC_STATIC) && !defined(JOC_API) #define JOC_API #define JOC_CALL __cdecl #endif #ifdef __cplusplus extern "C" { #endif typedef struct joc_stream joc_stream; typedef enum joc_stream_input { JOC_STREAM_IN_EAC3 = 0, /* bare E-AC-3 syncframes (the metadata stream) */ JOC_STREAM_IN_PCM_OBJECTS16 = 1, /* objects16 frames, planar [16][1536] each */ JOC_STREAM_IN_CORE_PCM = 3 /* the 5.1 core PCM of the pushed E-AC-3 frames */ } joc_stream_input; typedef enum joc_stream_output { JOC_STREAM_OUT_PCM_OBJECTS16 = 0, /* objects16 frames, planar [16][1536] each */ JOC_STREAM_OUT_SPEAKER = 1, /* interleaved [samples][channels] f32 */ JOC_STREAM_OUT_BINAURAL = 2 /* interleaved [samples][2] f32 */ } joc_stream_output; typedef struct joc_stream_config { uint32_t struct_size; uint32_t struct_version; uint32_t input; uint32_t output; const char* speaker_layout_name; uint32_t speaker_metadata_offset; /* default 1473 */ uint32_t binaural_mode; /* near|mid|far; 0 means mid */ const char* hrtf_path; /* binaural only */ const char* kernels_path; /* binaural only */ double binaural_tail_seconds; /* default 5.0 */ uint32_t object_delay_samples; /* default 1473 */ double gain_db; /* default 0 */ uint32_t native_threads; uint32_t rosella_filterbank; /* joc_rosella_filterbank; Rosella input, 0 = PUBLIC */ /* Binaural input, the same shapes joc_task_config accepts: a compiled * .jochrtf field (hrtf_path) or a Rosella .personalized_headphone model. */ const char* personalized_headphone_path; /* Rosella .personalized_headphone input */ uint32_t jochrtf_room; /* non-zero enables the project room */ } joc_stream_config; typedef struct joc_stream_buffer { uint32_t struct_size; uint32_t struct_version; uint32_t kind; /* which joc_stream_input/output this buffer carries */ uint32_t channels; uint32_t sample_rate; uint32_t sample_count; /* in: capacity / out: produced (per channel) */ uint32_t byte_count; /* in: capacity / out: consumed or produced bytes */ uint32_t reserved; const uint8_t* bytes; /* EAC3 input */ const float* pcm; /* PCM input */ uint8_t* out_bytes; /* reserved for encoded outputs */ float* out_pcm; /* PCM output */ } joc_stream_buffer; typedef struct joc_stream_status_info { uint32_t struct_size; uint32_t struct_version; uint64_t frames_in; uint64_t frames_out; uint64_t samples_in; uint64_t samples_out; uint64_t bytes_in; uint64_t buffered_samples; /* rendered but not yet pulled, per channel */ uint64_t oamd_payloads; uint64_t oamd_transitions; /* Metadata the renderer had to work around, per audio frame: no JOC payload at * all, an ID14 payload that ends inside joc_data (that frame holds the previous * matrices), a declared object count clamped to 15, and a syncframe carrying a * second EMDF container that is not this frame's JOC metadata. */ uint64_t missing_joc_frames; uint64_t objects_clamped_frames; uint64_t extra_container_frames; /* Extra-pair identity disagreements across layers (spec 11.2 checks 1 and 2). * The identity is metadata only, so those frames still render. */ uint64_t chanmap_pair_mismatch_frames; uint64_t bed_mask_mismatch_frames; uint32_t output_channels; uint32_t ended; /* 1 after flush() */ /* Appended field: joc_stream_status() accepts the size that ends at `ended` * as well, so a caller built against the previous header keeps working. */ uint64_t truncated_joc_frames; } joc_stream_status_info; JOC_API joc_error JOC_CALL joc_stream_create(const joc_stream_config* config, joc_stream** out); /* Feeds one buffer. Kind selects the path: EAC3 bytes, the core PCM of those * frames, or objects16. Consumed counts are reported so a caller can resume * from a partial push. */ JOC_API joc_error JOC_CALL joc_stream_push(joc_stream* stream, const joc_stream_buffer* input, uint32_t* consumed_samples, uint32_t* consumed_bytes); /* Copies as many rendered samples as fit into `output` (interleaved, or planar * for PCM_OBJECTS16) and reports how many were produced; 0 means "push more". */ JOC_API joc_error JOC_CALL joc_stream_pull(joc_stream* stream, joc_stream_buffer* output, uint32_t* produced_samples); /* Marks the end of input and drains whatever the renderer still holds (the * binaural room tail); pull the remaining samples afterwards. */ JOC_API joc_error JOC_CALL joc_stream_flush(joc_stream* stream); /* Returns the instance to its initial state (kernel, ramps, timeline, room, * parser, counters) so the same stream can be reused for another pass. */ JOC_API joc_error JOC_CALL joc_stream_reset(joc_stream* stream); JOC_API joc_error JOC_CALL joc_stream_status(const joc_stream* stream, joc_stream_status_info* out); JOC_API joc_error JOC_CALL joc_stream_destroy(joc_stream* stream); #ifdef __cplusplus } /* extern "C" */ #endif