Init mpv-joc

This commit is contained in:
TheM14 committed 2026-10-18 21:31:38 +08:00
commit 126e2cd233
52 files changed
+11035

No files matched your search

+875
View File
@@ -0,0 +1,875 @@
/*
* MIT License, Copyright (c) 2026 TheM14
*
* This file is compiled into mpv, so the resulting player is distributed under
* mpv's own license (LGPL-2.1-or-later, or GPL-2.0-or-later when built with
* -Dgpl=true). mpv's license text is in LICENSE-mpv.
*/
/*
* ad_joc.c — mpv audio decoder for E-AC-3 JOC, rendered by the
* JustOneCacophony core (joc_core.dll).
*
* Opt in with --ad=joc. The demuxer hands us E-AC-3 access units; we decode
* the bed with libavcodec (drc off, as the reference frontends do), and push
* each whole audio frame plus its bed PCM into joc_stream. What comes back is
* the object-audio rendering (binaural or a speaker layout) as ordinary float
* PCM, so mpv's resampler, filters, A/V sync and audio output apply unchanged.
*
* This is the "native track" integration: no second audio track, no loopback
* endpoint, correct codec information in the track list.
*/
#include <math.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#ifdef _WIN32
#include <windows.h>
#endif
#include <libavcodec/avcodec.h>
#include <libavutil/opt.h>
#include "config.h"
#include "mpv_talloc.h"
#include "osdep/timer.h"
#include "audio/aframe.h"
#include "audio/chmap.h"
#include "audio/format.h"
#include "common/msg.h"
#include "demux/packet.h"
#include "demux/stheader.h"
#include "filters/f_decoder_wrapper.h"
#include "filters/filter_internal.h"
#include "options/m_config.h"
#include "options/options.h"
#include "options/path.h"
#include "osdep/io.h"
#include "common/codecs.h"
#include "common/common.h"
#include "audio/decode/ad_joc.h"
#include "audio/decode/joc_eac3.h"
#include "audio/decode/joc_stream.h"
#define OPT_BASE_STRUCT struct ad_joc_params
const struct m_sub_options ad_joc_conf = {
.opts = (const m_option_t[]) {
{"binaural", OPT_BOOL(binaural)},
{"hrtf", OPT_STRING(hrtf), .flags = M_OPT_FILE},
{"layout", OPT_STRING(layout), .flags = M_OPT_FILE},
{"mode", OPT_CHOICE(binaural_mode,
{"near", 1}, {"far", 2}, {"mid", 3})},
{"gain-db", OPT_DOUBLE(gain_db), M_RANGE(-60.0, 12.0)},
{"int24", OPT_BOOL(int24)},
{0}
},
.size = sizeof(struct ad_joc_params),
.defaults = &(const struct ad_joc_params){
.binaural = true,
.int24 = false,
.hrtf = "",
.layout = "7.1",
.binaural_mode = 3,
.gain_db = 0.0,
},
};
#define JOC_FRAME_SAMPLES 1536
#define PULL_BLOCK 4096
struct priv {
struct mp_decoder public;
AVCodecContext *avctx;
AVFrame *avframe;
AVPacket *avpkt;
joc_stream *stream;
joc_stream_config cfg;
int out_channels;
struct mp_aframe *fmt;
struct mp_aframe_pool *pool;
uint8_t *carry;
int carry_len;
int carry_cap;
float *bed;
size_t bed_cap; /* floats */
int bed_channels;
uint64_t frames_in; /* audio frames pushed to the renderer */
uint64_t samples_out; /* samples handed to mpv */
uint64_t last_report; /* heartbeat bookkeeping */
double last_stall_log; /* rate limits the "no output" warning */
double next_pts;
bool have_pts;
bool eof;
bool binaural;
bool int24;
enum { PATH_UNDECIDED, PATH_JOC, PATH_NATIVE } path;
struct mp_decoder *native;
struct mp_codec_params *codec;
struct mp_frame *probe_packets;
int num_probe_packets;
int probe_packet_pos;
struct mp_frame eof_frame;
bool eof_pending;
};
static int append(struct priv *p, const uint8_t *data, int len)
{
if (len <= 0)
return 0;
if (p->carry_len + len > p->carry_cap) {
int cap = p->carry_cap ? p->carry_cap : 65536;
while (cap < p->carry_len + len)
cap *= 2;
p->carry = talloc_realloc(p, p->carry, uint8_t, cap);
p->carry_cap = cap;
}
memcpy(p->carry + p->carry_len, data, len);
p->carry_len += len;
return len;
}
static void push_bed(struct priv *p, const uint8_t *data, int bytes)
{
av_packet_unref(p->avpkt);
if (av_new_packet(p->avpkt, bytes) < 0)
return;
memcpy(p->avpkt->data, data, bytes);
if (avcodec_send_packet(p->avctx, p->avpkt) < 0)
return;
while (avcodec_receive_frame(p->avctx, p->avframe) == 0) {
int channels = p->avframe->ch_layout.nb_channels;
int samples = p->avframe->nb_samples;
if (channels <= 0 || samples <= 0) {
av_frame_unref(p->avframe);
continue;
}
if (p->bed_channels && p->bed_channels != channels) {
/* The core pairs one audio frame with one bed frame of the channel
* count it derived; a mid-stream change cannot be paired. */
av_frame_unref(p->avframe);
continue;
}
if (!p->bed_channels) {
p->bed_channels = channels;
MP_VERBOSE(p->public.f, "bed: %d channel(s), %d samples/frame\n",
channels, samples);
}
size_t need = (size_t)samples * channels;
if (need > p->bed_cap) {
p->bed = talloc_realloc(p, p->bed, float, need);
p->bed_cap = need;
}
for (int s = 0; s < samples; ++s) {
for (int c = 0; c < channels; ++c) {
const float *plane = (const float *)p->avframe->extended_data[c];
p->bed[(size_t)s * channels + c] = plane[s];
}
}
joc_stream_buffer in;
memset(&in, 0, sizeof(in));
in.struct_size = sizeof(in);
in.struct_version = 1;
in.kind = JOC_STREAM_IN_CORE_PCM;
in.channels = (uint32_t)channels;
in.sample_rate = 48000;
in.sample_count = (uint32_t)samples;
in.pcm = p->bed;
joc_stream_push(p->stream, &in, NULL, NULL);
av_frame_unref(p->avframe);
}
}
static void feed(struct priv *p, int end_of_stream)
{
if (!p->stream)
return;
for (;;) {
size_t bytes = joc_eac3_audio_frame_bytes(p->carry, (size_t)p->carry_len, 0,
end_of_stream);
if (bytes == 0 || (int)bytes > p->carry_len)
break;
joc_stream_buffer in;
memset(&in, 0, sizeof(in));
in.struct_size = sizeof(in);
in.struct_version = 1;
in.kind = JOC_STREAM_IN_EAC3;
in.bytes = p->carry;
in.byte_count = (uint32_t)bytes;
uint32_t consumed = 0;
if (joc_stream_push(p->stream, &in, NULL, &consumed) != JOC_OK) {
MP_ERR(p->public.f, "renderer refused an E-AC-3 frame (%u bytes): %s\n",
bytes, joc_last_error_detail());
break;
}
p->frames_in++;
push_bed(p, p->carry, (int)bytes);
int left = p->carry_len - (int)bytes;
if (left > 0)
memmove(p->carry, p->carry + bytes, (size_t)left);
p->carry_len = left;
}
}
static float quantize_int24(float v);
static bool emit(struct mp_filter *f)
{
struct priv *p = f->priv;
if (!p->stream || !mp_pin_in_needs_data(f->ppins[1]))
return false;
struct mp_aframe *frame = mp_aframe_new_ref(p->fmt);
if (!frame)
return false;
if (mp_aframe_pool_allocate(p->pool, frame, PULL_BLOCK) < 0) {
talloc_free(frame);
return false;
}
uint8_t **data = mp_aframe_get_data_rw(frame);
if (!data) {
talloc_free(frame);
return false;
}
joc_stream_buffer out;
memset(&out, 0, sizeof(out));
out.struct_size = sizeof(out);
out.struct_version = 1;
out.kind = p->binaural ? JOC_STREAM_OUT_BINAURAL : JOC_STREAM_OUT_SPEAKER;
out.channels = (uint32_t)p->out_channels;
out.sample_rate = 48000;
out.sample_count = PULL_BLOCK;
out.out_pcm = (float *)data[0];
uint32_t produced = 0;
joc_error rc = joc_stream_pull(p->stream, &out, &produced);
if (rc != JOC_OK) {
MP_ERR(f, "renderer pull failed: %s\n", joc_last_error_detail());
talloc_free(frame);
return false;
}
if (produced == 0) {
const double now = mp_time_sec();
joc_stream_status_info st = { .struct_size = sizeof(st), .struct_version = 1 };
joc_stream_status(p->stream, &st);
/* A frame still waiting in carry is normal: the renderer pulls only
* what it has already rendered. Only a dry renderer with nothing in
* flight means the pipeline actually stopped. */
if (p->carry_len == 0 && st.buffered_samples == 0 &&
now - p->last_stall_log > 1.0) {
p->last_stall_log = now;
MP_WARN(f, "no output: frames_in=%llu frames_out=%llu samples_out=%llu "
"buffered=%llu carry=%d eof=%d state=%d\n",
(unsigned long long)st.frames_in,
(unsigned long long)st.frames_out,
(unsigned long long)p->samples_out,
(unsigned long long)st.buffered_samples,
p->carry_len, p->eof, (int)p->path);
}
talloc_free(frame);
return false;
}
/* The renderer's room tail is not part of the file: stop at the sample the
* last input frame ends on, exactly as the file frontends do. */
uint64_t total = p->frames_in * JOC_FRAME_SAMPLES;
uint64_t left = (p->samples_out < total) ? total - p->samples_out : 0;
if ((uint64_t)produced > left)
produced = (uint32_t)left;
if (produced == 0) {
talloc_free(frame);
return false;
}
if (p->int24) {
float *s = (float *)data[0];
for (size_t i = 0; i < (size_t)produced * (size_t)p->out_channels; i++)
s[i] = quantize_int24(s[i]);
}
mp_aframe_set_size(frame, (int)produced);
mp_aframe_set_pts(frame, p->next_pts);
p->next_pts += (double)produced / 48000.0;
p->samples_out += produced;
if (p->frames_in != p->last_report && p->frames_in % 128 == 0) {
p->last_report = p->frames_in;
joc_stream_status_info st = { .struct_size = sizeof(st), .struct_version = 1 };
joc_stream_status(p->stream, &st);
MP_VERBOSE(f, "frames_in=%llu samples_out=%llu buffered=%llu\n",
(unsigned long long)p->frames_in,
(unsigned long long)p->samples_out,
(unsigned long long)st.buffered_samples);
}
mp_pin_in_write(f->ppins[1], MAKE_FRAME(MP_FRAME_AUDIO, frame));
return true;
}
static void clear_probe_packets(struct priv *p)
{
for (int i = p->probe_packet_pos; i < p->num_probe_packets; i++)
mp_frame_unref(&p->probe_packets[i]);
p->num_probe_packets = 0;
p->probe_packet_pos = 0;
}
/* The track is not JOC: hand it to mpv's normal E-AC-3 decoder and replay the
* packets that were kept while classifying, so the track still plays (and a
* seek that happened first is transparent). */
static bool switch_to_native(struct mp_filter *f, struct priv *p)
{
if (p->native)
return true;
struct mp_decoder_list *all = talloc_zero(NULL, struct mp_decoder_list);
ad_lavc.add_decoders(all);
struct mp_decoder_list *sel =
mp_select_decoders(f->log, all, p->codec->codec, NULL);
talloc_free(all);
for (int i = 0; i < sel->num_entries && !p->native; i++)
p->native = ad_lavc.create(f, p->codec, sel->entries[i].decoder);
talloc_free(sel);
if (!p->native) {
MP_ERR(f, "no native E-AC-3 decoder to fall back to\n");
return false;
}
MP_WARN(f, "this E-AC-3 stream carries no JOC metadata; decoding it with "
"the default decoder instead\n");
if (p->stream) {
joc_stream_destroy(p->stream);
p->stream = NULL;
}
p->path = PATH_NATIVE;
return true;
}
/* Host mode: pump the native child — packets in, decoded frames out. */
static void process_host(struct mp_filter *f, struct priv *p)
{
if (!switch_to_native(f, p)) {
mp_filter_internal_mark_failed(f);
return;
}
struct mp_pin *child_in = p->native->f->pins[0];
struct mp_pin *child_out = p->native->f->pins[1];
if (mp_pin_can_transfer_data(f->ppins[1], child_out)) {
struct mp_frame frame = mp_pin_out_read(child_out);
mp_pin_in_write(f->ppins[1], frame);
}
if (p->probe_packet_pos < p->num_probe_packets &&
mp_pin_in_needs_data(child_in)) {
struct mp_frame frame = p->probe_packets[p->probe_packet_pos];
p->probe_packets[p->probe_packet_pos++] = MP_NO_FRAME;
mp_pin_in_write(child_in, frame);
if (p->probe_packet_pos == p->num_probe_packets) {
p->num_probe_packets = 0;
p->probe_packet_pos = 0;
}
} else if (mp_pin_can_transfer_data(child_in, f->ppins[0])) {
struct mp_frame frame = mp_pin_out_read(f->ppins[0]);
mp_pin_in_write(child_in, frame);
}
}
/* True when the renderer accepted these frames as JOC. A stream without any
* EMDF metadata never produces output and counts every frame as missing. */
static bool classify_has_joc(struct priv *p)
{
joc_stream_status_info st;
memset(&st, 0, sizeof(st));
st.struct_size = sizeof(st);
st.struct_version = 1;
if (joc_stream_status(p->stream, &st) != JOC_OK)
return true;
return st.frames_out > 0;
}
static void ad_joc_process(struct mp_filter *f)
{
struct priv *p = f->priv;
if (p->path == PATH_NATIVE) {
process_host(f, p);
return;
}
if (!mp_pin_in_needs_data(f->ppins[1]))
return;
/* End of stream: the renderer still holds its tail, and the EOF frame is
* only forwarded once that tail has been handed out. Draining has to
* happen before touching the input pin, which stays empty from here on. */
if (p->eof_pending) {
if (emit(f))
return;
struct mp_frame eof = p->eof_frame;
p->eof_pending = false;
p->eof_frame = MP_NO_FRAME;
mp_pin_in_write(f->ppins[1], eof);
return;
}
struct mp_frame in = mp_pin_out_read(f->ppins[0]);
if (in.type == MP_FRAME_EOF) {
if (p->path == PATH_UNDECIDED && p->frames_in > 0) {
if (classify_has_joc(p)) {
p->path = PATH_JOC;
clear_probe_packets(p);
} else if (switch_to_native(f, p)) {
struct mp_pin *child_in = p->native->f->pins[0];
for (int i = 0; i < p->num_probe_packets; i++) {
if (!mp_pin_in_needs_data(child_in))
break;
struct mp_frame pf = p->probe_packets[i];
p->probe_packets[i] = MP_NO_FRAME;
mp_pin_in_write(child_in, pf);
}
clear_probe_packets(p);
if (mp_pin_in_needs_data(child_in))
mp_pin_in_write(child_in, in);
else
mp_frame_unref(&in);
process_host(f, p);
mp_filter_internal_mark_progress(f);
return;
}
}
if (!p->eof) {
p->eof = true;
if (p->carry_len > 0) {
feed(p, 1);
p->carry_len = 0;
}
joc_stream_flush(p->stream);
}
p->eof_frame = in;
p->eof_pending = true;
if (emit(f))
return;
/* Nothing buffered: forward EOF immediately. */
struct mp_frame eof = p->eof_frame;
p->eof_pending = false;
p->eof_frame = MP_NO_FRAME;
mp_pin_in_write(f->ppins[1], eof);
return;
}
if (in.type != MP_FRAME_PACKET) {
if (in.type)
MP_ERR(f, "unexpected frame type\n");
return;
}
struct demux_packet *pkt = in.data;
if (!p->have_pts && pkt->pts != MP_NOPTS_VALUE) {
p->next_pts = pkt->pts;
p->have_pts = true;
}
/* Keep what was read while classifying the track: if it turns out to have
* no JOC payload, these packets are replayed into the native decoder. */
bool retained = false;
if (p->path == PATH_UNDECIDED && p->num_probe_packets < 16) {
MP_TARRAY_APPEND(p, p->probe_packets, p->num_probe_packets, in);
retained = true;
}
append(p, pkt->buffer, pkt->len);
feed(p, 0);
if (!retained)
talloc_free(pkt);
if (p->path == PATH_UNDECIDED && p->frames_in >= 8) {
if (classify_has_joc(p)) {
p->path = PATH_JOC;
clear_probe_packets(p);
} else {
process_host(f, p);
return;
}
}
if (emit(f))
return;
mp_filter_internal_mark_progress(f);
}
static void ad_joc_reset(struct mp_filter *f)
{
struct priv *p = f->priv;
if (p->path == PATH_UNDECIDED)
clear_probe_packets(p);
/* mpv restarts the packet stream at the seek target without pre-roll, so
* the renderer cannot be carried across the discontinuity: whatever it
* buffered belongs to the old position and would be emitted as if it were
* the new one. Restart it instead; the missing history costs a short
* convergence, the stale tail would be audible for about a second. */
if (p->stream) {
joc_stream_destroy(p->stream);
p->stream = NULL;
if (joc_stream_create(&p->cfg, &p->stream) != JOC_OK) {
MP_ERR(f, "cannot restart the renderer after a seek: %s\n",
joc_last_error_detail());
p->stream = NULL;
}
}
p->frames_in = 0;
p->samples_out = 0;
if (p->avctx)
avcodec_flush_buffers(p->avctx);
if (p->path == PATH_NATIVE)
return;
p->carry_len = 0;
p->have_pts = false;
p->eof = false;
p->bed_channels = 0;
}
static void ad_joc_destroy(struct mp_filter *f)
{
struct priv *p = f->priv;
if (p->stream) {
joc_stream_destroy(p->stream);
p->stream = NULL;
}
if (p->avctx)
avcodec_free_context(&p->avctx);
av_frame_free(&p->avframe);
av_packet_free(&p->avpkt);
}
static const struct mp_filter_info ad_joc_filter = {
.name = "ad_joc",
.priv_size = sizeof(struct priv),
.process = ad_joc_process,
.reset = ad_joc_reset,
.destroy = ad_joc_destroy,
};
/* mpv names layouts up to 7.1 itself; the renderer goes further (it is a Dolby
* Atmos renderer, so 5.1.2 … 9.1.6 follow the usual speaker order). Spell the
* wider ones out as speaker lists so mpv knows which channel is which. */
static const struct {
const char *name;
const char *speakers;
} layout_names[] = {
{"2.0", "fl-fr"},
{"3.0", "fl-fr-fc"},
{"3.1", "fl-fr-fc-lfe"},
{"4.0", "fl-fr-fc-bc"},
{"5.0", "fl-fr-fc-bl-br"},
{"5.1", "fl-fr-fc-lfe-bl-br"},
{"5.1.2", "fl-fr-fc-lfe-bl-br-tfl-tfr"},
{"5.1.4", "fl-fr-fc-lfe-bl-br-tfl-tfr-tbl-tbr"},
{"6.1", "fl-fr-fc-lfe-bc-sl-sr"},
{"7.0", "fl-fr-fc-bl-br-sl-sr"},
{"7.1", "fl-fr-fc-lfe-bl-br-sl-sr"},
{"7.1.2", "fl-fr-fc-lfe-bl-br-sl-sr-tfl-tfr"},
{"7.1.4", "fl-fr-fc-lfe-bl-br-sl-sr-tfl-tfr-tbl-tbr"},
{"9.1.4", "fl-fr-fc-lfe-bl-br-sl-sr-wl-wr-tfl-tfr-tbl-tbr"},
{"9.1.6", "fl-fr-fc-lfe-bl-br-sl-sr-wl-wr-tfl-tfr-tsl-tsr-tbl-tbr"},
};
static bool layout_chmap(struct mp_chmap *chmap, const char *layout, int channels)
{
for (int i = 0; i < MP_ARRAY_SIZE(layout_names); i++) {
if (strcmp(layout, layout_names[i].name) == 0) {
if (mp_chmap_from_str(chmap, bstr0(layout_names[i].speakers)) &&
chmap->num == channels)
return true;
break;
}
}
if (mp_chmap_from_str(chmap, bstr0(layout)) && chmap->num == channels)
return true;
/* Unknown to mpv: keep the channels, just do not name them. */
mp_chmap_from_channels(chmap, channels);
return chmap->num == channels;
}
/* The renderer's int24 rule (the core's wav_writer to_int32):
* clip, scale by 8388607, truncate toward zero, keep the low 24 bits, and read
* back the value the host sees: n / 2^23. */
static float quantize_int24(float v)
{
if (!isfinite(v))
return 0.0f;
if (v > 1.0f)
v = 1.0f;
else if (v < -1.0f)
v = -1.0f;
int32_t scaled = (int32_t)(v * 8388607.0f);
int32_t written = scaled & 0xFFFFFF;
if (written & 0x800000)
written -= 0x1000000;
return (float)written / 8388608.0f;
}
enum hrtf_kind { HRTF_UNKNOWN, HRTF_SOFA, HRTF_ROSELLA, HRTF_KERNELS };
static bool file_exists(const char *path)
{
if (!path || !path[0])
return false;
FILE *fp = fopen(path, "rb");
if (!fp)
return false;
fclose(fp);
return true;
}
static bool ends_with_ci(const char *s, const char *suffix)
{
size_t a = strlen(s), b = strlen(suffix);
if (a < b)
return false;
for (size_t i = 0; i < b; i++) {
char x = s[a - b + i], y = suffix[i];
if (x >= 'A' && x <= 'Z') x += 32;
if (y >= 'A' && y <= 'Z') y += 32;
if (x != y)
return false;
}
return true;
}
static bool contains(const void *hay, size_t n, const char *needle)
{
size_t m = strlen(needle);
if (n < m)
return false;
for (size_t i = 0; i + m <= n; i++) {
if (memcmp((const unsigned char *)hay + i, needle, m) == 0)
return true;
}
return false;
}
/* The renderer takes three kinds of HRTF input and the user should not have to
* say which: SOFA is HDF5, the Rosella model is JSON with a personalized_hrtf
* object, and a compiled kernel is a .jochrtf. Look at the extension first
* (conclusive for kernels), then at the file signature. */
static enum hrtf_kind hrtf_kind_of(const char *path)
{
if (!path || !path[0])
return HRTF_UNKNOWN;
if (ends_with_ci(path, ".jochrtf"))
return HRTF_KERNELS;
unsigned char head[4096];
FILE *fp = fopen(path, "rb");
if (!fp)
return HRTF_UNKNOWN;
size_t n = fread(head, 1, sizeof(head), fp);
fclose(fp);
if (n >= 8 && memcmp(head, "\x89HDF\r\n\x1a\n", 8) == 0)
return HRTF_SOFA;
for (size_t i = 0; i < n; i++) {
if (head[i] == ' ' || head[i] == '\t' || head[i] == '\r' || head[i] == '\n')
continue;
if (head[i] == '{' && contains(head, n, "\"personalized_hrtf\""))
return HRTF_ROSELLA;
break;
}
if (ends_with_ci(path, ".sofa"))
return HRTF_SOFA;
return HRTF_UNKNOWN;
}
static char *exe_dir(void *ta)
{
#ifdef _WIN32
wchar_t wpath[MP_PATH_MAX];
DWORD len = GetModuleFileNameW(NULL, wpath, MP_PATH_MAX);
while (len > 0 && wpath[len - 1] != L'\\' && wpath[len - 1] != L'/')
len--;
if (len > 0)
wpath[len - 1] = 0;
return mp_to_utf8(ta, wpath);
#else
return NULL;
#endif
}
/* Explicit --ad-joc-hrtf wins; otherwise look where the standalone renderer
* looks: HRTF/binaural.sofa or HRTF/binaural.personalized_headphone next to
* mpv.exe, then the same names under the mpv config directory. */
static char *find_hrtf(struct mp_filter *da, struct ad_joc_params *opts)
{
struct priv *p = da->priv;
if (opts->hrtf && opts->hrtf[0]) {
char *path = mp_get_user_path(p, da->global, opts->hrtf);
if (file_exists(path))
return path;
MP_ERR(da, "HRTF file not found: %s\n", path);
return NULL;
}
static const char *const names[] = {
"HRTF/binaural.sofa",
"HRTF/binaural.personalized_headphone",
"HRTF/binaural.jochrtf",
"joc-hrtf/binaural.sofa",
"joc-hrtf/binaural.personalized_headphone",
};
char *dir = exe_dir(p);
for (int i = 0; i < MP_ARRAY_SIZE(names); i++) {
char *cand = dir ? mp_path_join(p, dir, names[i]) : NULL;
if (file_exists(cand))
return cand;
cand = mp_find_config_file(p, da->global, names[i]);
if (file_exists(cand))
return cand;
}
return NULL;
}
static struct mp_decoder *create(struct mp_filter *parent,
struct mp_codec_params *codec,
const char *decoder)
{
if (!codec->codec || strcmp(codec->codec, "eac3") != 0)
return NULL;
struct mp_filter *da = mp_filter_create(parent, &ad_joc_filter);
if (!da)
return NULL;
mp_filter_add_pin(da, MP_PIN_IN, "in");
mp_filter_add_pin(da, MP_PIN_OUT, "out");
da->log = mp_log_new(da, parent->log, NULL);
(void)decoder;
struct priv *p = da->priv;
struct ad_joc_params *opts = mp_get_config_group(p, da->global, &ad_joc_conf);
bool binaural = opts->binaural;
char *hrtf_path = NULL;
enum hrtf_kind hrtf_kind = HRTF_UNKNOWN;
if (binaural) {
hrtf_path = find_hrtf(da, opts);
hrtf_kind = hrtf_kind_of(hrtf_path);
if (hrtf_kind == HRTF_UNKNOWN) {
MP_WARN(da, "no usable HRTF found%s%s; rendering the speaker layout "
"instead (mpv downmixes it to stereo). Place "
"HRTF/binaural.sofa next to mpv.exe or set --ad-joc-hrtf.\n",
hrtf_path ? ": " : "", hrtf_path ? hrtf_path : "");
binaural = false;
}
}
const AVCodec *lavc = avcodec_find_decoder(AV_CODEC_ID_EAC3);
if (!lavc) {
MP_ERR(da, "libavcodec has no E-AC-3 decoder for the bed\n");
talloc_free(da);
return NULL;
}
p->avctx = avcodec_alloc_context3(lavc);
p->avframe = av_frame_alloc();
p->avpkt = av_packet_alloc();
if (!p->avctx || !p->avframe || !p->avpkt) {
talloc_free(da);
return NULL;
}
p->avctx->pkt_timebase = (AVRational){1, 48000};
/* The reference frontends decode the bed without applying the stream's
* dynamic range metadata. */
av_opt_set_double(p->avctx->priv_data, "drc_scale", 0.0, 0);
if (avcodec_open2(p->avctx, lavc, NULL) < 0) {
MP_ERR(da, "cannot open the E-AC-3 bed decoder\n");
talloc_free(da);
return NULL;
}
joc_stream_config cfg;
memset(&cfg, 0, sizeof(cfg));
cfg.struct_size = sizeof(cfg);
cfg.struct_version = 1;
cfg.input = JOC_STREAM_IN_EAC3;
cfg.output = binaural ? JOC_STREAM_OUT_BINAURAL : JOC_STREAM_OUT_SPEAKER;
cfg.binaural_mode = (uint32_t)opts->binaural_mode;
cfg.gain_db = opts->gain_db;
cfg.object_delay_samples = 1473;
if (binaural) {
if (hrtf_kind == HRTF_SOFA)
cfg.hrtf_sofa_path = hrtf_path;
else if (hrtf_kind == HRTF_ROSELLA)
cfg.personalized_headphone_path = hrtf_path;
else if (hrtf_kind == HRTF_KERNELS)
cfg.hrtf_path = hrtf_path;
/* Compiling a SOFA is expensive; keep the kernels between runs. */
char *cache = mp_find_user_file(p, da->global, "cache", "joc-hrtf-cache");
if (!cache) {
char *dir = exe_dir(p);
if (dir)
cache = mp_path_join(p, dir, "joc-hrtf-cache");
}
if (cache) {
mp_mkdirp(cache);
cfg.hrtf_cache_dir = cache;
cfg.hrtf_cache_policy = 2;
} else {
cfg.hrtf_cache_policy = 1;
}
} else {
cfg.speaker_layout_name = opts->layout;
}
p->cfg = cfg;
if (joc_stream_create(&cfg, &p->stream) != JOC_OK) {
MP_ERR(da, "cannot create the renderer stream: %s\n", joc_last_error_detail());
talloc_free(da);
return NULL;
}
joc_stream_status_info status;
memset(&status, 0, sizeof(status));
status.struct_size = sizeof(status);
status.struct_version = 1;
int channels = binaural ? 2 : 0;
if (joc_stream_status(p->stream, &status) == JOC_OK && status.output_channels)
channels = (int)status.output_channels;
if (channels <= 0)
channels = binaural ? 2 : 8;
struct mp_chmap chmap;
if (binaural) {
mp_chmap_from_channels(&chmap, 2);
} else if (!layout_chmap(&chmap, opts->layout, channels)) {
MP_ERR(da, "unknown speaker layout '%s'\n", opts->layout);
talloc_free(da);
return NULL;
}
p->out_channels = channels;
p->fmt = mp_aframe_create();
mp_aframe_set_format(p->fmt, AF_FORMAT_FLOAT);
mp_aframe_set_chmap(p->fmt, &chmap);
mp_aframe_set_rate(p->fmt, 48000);
p->pool = mp_aframe_pool_create(p);
p->public.f = da;
p->binaural = binaural;
p->codec = codec;
p->path = PATH_UNDECIDED;
p->int24 = opts->int24;
codec->codec_desc = "E-AC-3 JOC (joc_core renderer)";
MP_VERBOSE(da, "renderer: %s, %d channel(s)%s%s\n",
binaural ? "binaural" : opts->layout, p->out_channels,
binaural ? ", hrtf: " : "", binaural ? hrtf_path : "");
if (p->int24)
MP_INFO(da, "int24: quantising the output to the renderer's 24-bit rule\n");
return &p->public;
}
static void add_decoders(struct mp_decoder_list *list)
{
mp_add_decoder(list, "eac3", "joc",
"E-AC-3 JOC object renderer (joc_core)");
}
const struct mp_decoder_fns ad_joc = {
.create = create,
.add_decoders = add_decoders,
};
+27
View File
@@ -0,0 +1,27 @@
/*
* MIT License, Copyright (c) 2026 TheM14
*
* This file is compiled into mpv, so the resulting player is distributed under
* mpv's own license (LGPL-2.1-or-later, or GPL-2.0-or-later when built with
* -Dgpl=true). mpv's license text is in LICENSE-mpv.
*/
/* --ad-joc-* options, shared by the decoder (audio/decode/ad_joc.c) and the
* option table (options/options.c). These are ordinary mpv options, so
* mpv.conf carries them: "ad-joc-binaural=yes", "ad-joc-hrtf=...". */
#pragma once
#include <stdbool.h>
#include "options/m_option.h"
struct ad_joc_params {
bool binaural; /* binaural (stereo) output; off uses the speaker layout */
char *hrtf; /* SOFA / Rosella / .jochrtf; the kind is detected */
char *layout; /* speaker layout name, e.g. "7.1" or "9.1.6" */
bool int24; /* quantise the output to the renderer's int24 rule */
int binaural_mode; /* JOC_BINAURAL_NEAR(1) / FAR(2) / MID(3) */
double gain_db;
};
extern const struct m_sub_options ad_joc_conf;
+492
View File
@@ -0,0 +1,492 @@
/*
* 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 5u
#define JOC_FRAME_PARAMS_VERSION 1u
#define JOC_EMDF_INFO_VERSION 1u
#define JOC_TASK_CONFIG_VERSION 3u
#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,
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];
uint16_t sample_offset; /* EMDF outer smpoffst, 11 bits */
uint16_t reserved2;
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. */
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;
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, parsed only */
uint32_t present_mask; /* bit i == object i present */
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; /* 1 + (y/32) * 2^(x-4), 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;
/* Compiled-HRTF cache policy for a SOFA input; the .jochrtf itself is an
* internal artifact of the compile step. */
typedef enum joc_hrtf_cache_policy {
JOC_HRTF_CACHE_NONE = 0, /* compile and discard */
JOC_HRTF_CACHE_MEMORY = 1, /* compile and keep in this process (default) */
JOC_HRTF_CACHE_DISK = 2 /* compile, reuse and write <cache_dir>/<name>.jochrtf */
} joc_hrtf_cache_policy;
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 HRTF input (config version 2): when hrtf_sofa_path is set the
* library compiles it with hrtf_cache_policy / hrtf_cache_dir / hrtf_radius_m
* and hrtf_path is unused. hrtf_path stays the advanced override that reads
* a .jochrtf directly. */
const char* hrtf_sofa_path; /* SOFA SimpleFreeFieldHRIR input */
const char* personalized_headphone_path; /* Rosella .personalized_headphone input */
const char* hrtf_cache_dir; /* disk policy directory */
uint32_t hrtf_cache_policy; /* joc_hrtf_cache_policy */
uint32_t reserved0;
double hrtf_radius_m; /* SOFA measurement-radius shell */
} 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
+100
View File
@@ -0,0 +1,100 @@
/*
* MIT License, Copyright (c) 2026 TheM14
*
* Derived from the upstream project's eac3_scan.cpp (JustOneCacophony),
* rewritten in C.
* See LICENSE-MIT.
*/
#include <string.h>
#include "audio/decode/joc_eac3.h"
#define EAC3_SYNCWORD 0x0B77u
static uint32_t read_bits(const uint8_t *data, size_t start, size_t count)
{
uint32_t value = 0;
for (size_t index = start; index < start + count; ++index)
value = (value << 1) | ((data[index >> 3] >> (7u - (index & 7u))) & 1u);
return value;
}
/* AC-3 syncframe length in 16-bit words, indexed by fscod then frmsizecod. */
static const uint16_t ac3_frame_words[3][38] = {
{64, 64, 80, 80, 96, 96, 112, 112, 128, 128, 160, 160, 192, 192, 224, 224,
256, 256, 320, 320, 384, 384, 448, 448, 512, 512, 640, 640, 768, 768,
896, 896, 1024, 1024, 1152, 1152, 1280, 1280},
{69, 70, 87, 88, 104, 105, 121, 122, 139, 140, 174, 175, 208, 209, 243, 244,
278, 278, 348, 348, 417, 418, 487, 487, 557, 557, 696, 696, 835, 835,
975, 975, 1114, 1114, 1253, 1253, 1393, 1393},
{96, 96, 120, 120, 144, 144, 168, 168, 192, 192, 240, 240, 288, 288, 336, 336,
384, 384, 480, 480, 576, 576, 672, 672, 768, 768, 960, 960, 1152, 1152,
1344, 1344, 1536, 1536, 1728, 1728, 1920, 1920},
};
size_t joc_eac3_frame_header_at(const uint8_t *data, size_t size, size_t offset,
struct joc_eac3_header *out)
{
if (!data || offset + 6u > size)
return 0;
uint16_t syncword = (uint16_t)((data[offset] << 8) | data[offset + 1]);
if (syncword != EAC3_SYNCWORD)
return 0;
size_t base = offset * 8u;
uint32_t bsid = read_bits(data, base + 40u, 5u);
if (bsid <= 8u) {
uint32_t fscod = read_bits(data, base + 32u, 2u);
uint32_t frmsizecod = read_bits(data, base + 34u, 6u);
if (fscod > 2u || frmsizecod >= 38u)
return 0;
size_t bytes = (size_t)ac3_frame_words[fscod][frmsizecod] * 2u;
if (out) {
out->frame_bytes = bytes;
out->offset = offset;
out->codec = 0;
out->strmtyp = 0;
out->substreamid = 0;
}
return bytes;
}
size_t words = ((size_t)(data[offset + 2] & 0x07u) << 8) | data[offset + 3];
size_t bytes = (words + 1u) * 2u;
if (out) {
out->frame_bytes = bytes;
out->offset = offset;
out->codec = 1;
out->strmtyp = (uint8_t)read_bits(data, base + 16u, 2u);
out->substreamid = (uint8_t)read_bits(data, base + 18u, 3u);
}
return bytes;
}
size_t joc_eac3_audio_frame_bytes(const uint8_t *data, size_t size, size_t offset,
int end_of_stream)
{
struct joc_eac3_header seen[8];
size_t count = 0;
size_t consumed = 0;
while (count < 8) {
struct joc_eac3_header header;
size_t bytes = joc_eac3_frame_header_at(data, size, offset + consumed, &header);
if (bytes == 0 || offset + consumed + bytes > size)
break;
int repeats = 0;
for (size_t index = 0; index < count; ++index) {
if (seen[index].codec == header.codec && seen[index].strmtyp == header.strmtyp &&
seen[index].substreamid == header.substreamid) {
repeats = 1;
break;
}
}
if (repeats)
return consumed;
seen[count++] = header;
consumed += bytes;
}
if (count != 0u && consumed != 0u && end_of_stream)
return consumed;
return 0;
}
+40
View File
@@ -0,0 +1,40 @@
/*
* MIT License, Copyright (c) 2026 TheM14
*
* Derived from the upstream project's eac3_scan.cpp (JustOneCacophony),
* rewritten in C.
* See LICENSE-MIT.
*/
/* E-AC-3 syncframe walking, sized for the audio decoder in ad_joc.c.
*
* An E-AC-3 "audio frame" can be more than one syncframe: a 7-channel JOC
* program interleaves an independent and a dependent substream, and the
* renderer pairs one whole audio frame with one 1536-sample bed frame. These
* helpers are a C port of the subset of the upstream eac3_scan.cpp that the
* decoder needs (no EMDF/JOC inspection: the renderer itself validates that).
*/
#pragma once
#include <stddef.h>
#include <stdint.h>
struct joc_eac3_header {
size_t frame_bytes;
size_t offset;
uint8_t codec; /* 0 = AC-3, 1 = E-AC-3 */
uint8_t strmtyp;
uint8_t substreamid;
};
/* Length of the syncframe at data[offset], or 0 when there is no valid header.
* AC-3 and E-AC-3 are told apart by bsid, exactly as the renderer does. */
size_t joc_eac3_frame_header_at(const uint8_t *data, size_t size, size_t offset,
struct joc_eac3_header *out);
/* Length of the whole audio frame at data[offset]: every syncframe up to the
* first repeated (codec, strmtyp, substreamid). Returns 0 while the group is
* still open inside the buffer, unless end_of_stream says no more bytes will
* arrive. */
size_t joc_eac3_audio_frame_bytes(const uint8_t *data, size_t size, size_t offset,
int end_of_stream);
+146
View File
@@ -0,0 +1,146 @@
/*
* 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 reserved;
/* Binaural HRTF input, the same three shapes joc_task_config accepts: when
* hrtf_sofa_path is set the library compiles it with hrtf_cache_policy /
* hrtf_cache_dir / hrtf_radius_m and hrtf_path is unused; when
* personalized_headphone_path is set the Rosella runtime renders instead.
* hrtf_path stays the fallback/advanced input that reads a .jochrtf directly. */
const char* hrtf_sofa_path; /* SOFA SimpleFreeFieldHRIR input */
const char* personalized_headphone_path; /* Rosella .personalized_headphone input */
const char* hrtf_cache_dir; /* disk cache directory for SOFA compilation */
uint32_t hrtf_cache_policy; /* joc_hrtf_cache_policy: 0 none, 1 memory, 2 disk */
double hrtf_radius_m; /* SOFA measurement-radius shell, default 1.0 */
} 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, 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() */
} 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
+16
View File
@@ -0,0 +1,16 @@
/* Product version of joc_core and joc_cli.
*
* This file is the single source of truth: CMakeLists.txt reads these numbers for
* project(VERSION ...), joc_version_string() returns JOC_VERSION_STRING, and the
* release workflow refuses a tag that does not match it. Bump the three numbers
* and the string together, then tag the commit with v<JOC_VERSION_STRING>.
*/
#ifndef JOC_VERSION_H
#define JOC_VERSION_H
#define JOC_VERSION_MAJOR 1
#define JOC_VERSION_MINOR 0
#define JOC_VERSION_PATCH 0
#define JOC_VERSION_STRING "1.0.0"
#endif /* JOC_VERSION_H */