Files
mpv-joc/src/joc_decode.h
T
TheM14 ecf14d8c32 Sync the Rosella filterbank choice into the plugin and the fork
The kernel can now render the Rosella path through either bank; expose
that choice in both front ends with the same values and the same
default.

- plugin: joc-rosella-filterbank = 1|2 (public|captured); unset means
  the kernel default (the public bank), and it applies only to
  joc-hrtf-source=rosella, logging a warning otherwise
- fork: --ad-joc-rosella-filterbank, the same values and default; it
  sits in the ad_joc option group, so it is read only when ad_joc
  decodes a Rosella model
- log the bank actually selected (public|captured) on both paths
- add a bank-2 case to tools/verify_parity.ps1
- document the key in both READMEs and the example config

Checked: the plugin builds, the option parser covers the numeric and
named spellings plus invalid values, and for both banks the plugin's
PCM is bit-identical to joc_cli with --rosella-filterbank 1|2.
2026-10-31 02:29:23 +08:00

207 lines
9.9 KiB
C++

// Decode engine: E-AC-3 JOC file -> rendered PCM, without any host-specific types.
//
// Kept free of fb2k headers on purpose: the same code is what a headless harness
// drives when the output has to be compared byte for byte against joc_cli.
//
// Two inputs are needed to render, and they come from different places:
// * the E-AC-3 syncframes -- the metadata stream -- read straight from the file;
// * the 5.1 core PCM of those same frames -- the rendering core does not decode
// the core (it has no AC-3 decoder at all), so ffmpeg produces it.
//
// The core is the C++ kernel under kernel/, compiled into this component and called
// through its public C API via the CoreApi table. No DLL is shipped or loaded: the
// table is filled with the linked entry points and start-up only checks the ABI
// version.
#pragma once
#include <cstddef>
#include <cstdint>
#include <functional>
#include <string>
namespace joc_decode {
// Delay of the rendering pipeline itself, in output samples: in a run that began
// at source sample 0, output sample k carries the rendering of source sample
// k - this value. A seek starts the inputs this much earlier and drops the
// samples before the target. Measured as 0: the renderer's own filter-bank
// latency and its metadata delay are inside the renderer, not delays of the
// delivered stream. It stays a named, overridable constant so the measurement can
// be repeated.
constexpr std::uint32_t kJocSeekPipelineDelaySamples = 0;
// Syncframes fed before the frame the target sits in. The renderer's state is
// rebuilt from the frames it is given, so a restart needs a moment to converge and
// the delivered part has to be past that. Two things converge at different rates:
// the metadata state (object positions, matrix interpolation, gain ramps), which
// the measured 3008-sample window covers, and the binaural room tail, which is
// recursive and can only be approached -- two syncframes are enough for the speaker
// path, and the tail keeps improving with more, which is why this is 64.
constexpr std::uint32_t kJocSeekPrerollFrames = 64;
enum class Output {
kBinaural = 0, // 2 channels, HRTF rendering
kSpeaker = 1, // N channels, named layout
};
// Which HRTF to render with. Both inputs are user-facing model/data files; how
// the renderer gets from them to its internal filter field is its own business.
enum class HrtfSource {
kSofa = 0,
kRosella = 1,
};
// Where the E-AC-3 syncframes come from. A bare stream is read straight from the
// file; inside a container the track has to be extracted first (ffmpeg, stream copy).
enum class InputKind {
kBare = 0,
kContainer = 1,
};
struct Settings {
Output output = Output::kBinaural;
InputKind input_kind = InputKind::kBare;
// Which of the container's audio tracks holds the E-AC-3 stream, 0-based.
unsigned audio_index = 0;
std::string speaker_layout = "7.1";
HrtfSource hrtf_source = HrtfSource::kSofa;
// Filterbank of the Rosella path: 0 = the renderer's default (public bank),
// 2 = the captured bank. Only the Rosella input reads it.
std::uint32_t rosella_filterbank = 0;
// Empty means the default file in the default folder, see resolve_hrtf_file().
std::string hrtf_file;
std::string hrtf_cache_dir; // SOFA compile cache (disk policy)
unsigned hrtf_cache_policy = 1; // 0 none, 1 memory, 2 disk
double hrtf_radius_m = 1.0; // SOFA measurement-radius shell
std::uint32_t binaural_mode = 3; // JOC_BINAURAL_MID
double gain_db = 0.0;
double tail_seconds = 5.0;
// Duration of the file, in seconds. The renderer ends a binaural stream with a
// room tail, which would be played as time the file does not have; the delivered
// stream is cut at exactly this much audio instead. Zero means "no limit".
double length_seconds = 0.0;
std::uint32_t object_delay_samples = 1473;
std::uint32_t native_threads = 0;
std::string ffmpeg_path = "ffmpeg";
// Where joc_core.dll lives; empty means the renderer's default lookup
// (the plugin's own directory first).
std::string core_path;
// Bytes in front of the first syncframe -- a leading ID3v2 tag. The renderer
// rejects a stream that does not begin on a syncword, so both the walk and the
// feed start here.
std::uint64_t stream_start_bytes = 0;
// Samples of pipeline delay a seek compensates for, and syncframes it pre-rolls
// before the target: the calibrated constants above, unless the comparison
// harness overrides them to measure those constants.
std::uint32_t pipeline_delay_samples = kJocSeekPipelineDelaySamples;
std::uint32_t seek_preroll_frames = kJocSeekPrerollFrames;
// Stop feeding the renderer after this many input syncframes and flush, which
// is what the reference CLI's --duration does. Zero means "the whole file".
// Only the comparison harness sets it; playback leaves it at zero.
std::uint64_t input_frame_limit = 0;
// Deliver 24-bit fixed-point PCM instead of float32. The renderer itself is
// always float32 and this does not change it: the flag says how the *caller*
// hands the samples on, and the quantisation happens once, where the format is
// decided (see pack_int24 below). It exists because the streaming interface
// has no int24 output -- the core's int24 rule lives in its file-writing path
// (kernel/src/io/wav_writer.cpp), which the component cannot reach, so the
// rule is reproduced here instead. Out-of-range samples follow the core's
// JOC_CLIP_CONTINUE policy: truncated to the edge, and reported.
bool force_int24 = false;
};
// Channel count of a named layout, or 0 when the layout is not one of the
// layouts the core accepts.
unsigned speaker_channels(const std::string& layout);
// Directory this component's DLL was loaded from. The default HRTF folder is
// <that directory>\HRTF, the same place the reference CLI looks next to its exe.
std::string component_directory();
// The HRTF file a configuration will actually use: the configured path, or the
// default file in the default folder when none is configured. Empty when the
// component directory cannot be determined.
std::string resolve_hrtf_file(const Settings& settings);
// Result of examining a file without rendering anything.
struct FileProbe {
bool readable = false;
bool joc = false; // every examined syncframe carries JOC
std::uint32_t sample_rate = 0;
std::uint32_t channels = 0; // core 5.1 layout, i.e. 6 (including LFE)
std::uint64_t frames = 0; // E-AC-3 syncframes in the file
double duration_seconds = 0.0;
std::string detail;
};
// Walks the file's syncframes. Cheap enough for a Media Library scan: it only
// does pointer arithmetic over the stream, no decoding, no HRTF work. The walk
// starts at `start_offset`, which is where the stream begins behind a tag area.
FileProbe probe_file(const std::string& path, std::size_t max_scan_bytes = 0,
std::uint64_t start_offset = 0);
// Decides whether the E-AC-3 track of a container file carries JOC, without
// rendering anything: ffmpeg copies a short prefix of that track out (stream copy,
// so the syncframes are the stored ones) and the same bitstream test is applied.
// The verdict is cached per file, because the information and the decode pass would
// otherwise each launch ffmpeg for it.
bool probe_container_joc(const std::string& ffmpeg_path, const std::string& path,
unsigned audio_index, bool* joc, std::string* detail);
// ---- forced int24 delivery ------------------------------------------------
//
// The core's own int24 rule, reproduced byte for byte from
// kernel/src/io/wav_writer.cpp: clip to [-1, 1], multiply by 8388607, truncate
// toward zero (the core's comment: the int32 conversion is "identical to NumPy's
// float32 -> int32 cast after clipping"), write the low three bytes, little
// endian; a non-finite sample becomes 0, exactly as the core writes it.
//
// Sample values that have been through this are what a 24-bit host import
// gives back, i.e. n / 2^23. That is the scale
// a caller should use when it wants to check what the host received.
constexpr double kInt24ImportScale = 8388608.0;
struct Int24Block {
std::size_t clipped = 0; // samples that were outside [-1, 1]
std::int32_t peak = 0; // largest magnitude actually written
};
// Packs `count` interleaved float32 samples into `out`, which must hold
// count * 3 bytes, and reports what the clip caught.
Int24Block pack_int24(const float* interleaved, std::size_t count, std::uint8_t* out);
class Engine {
public:
Engine();
~Engine();
Engine(const Engine&) = delete;
Engine& operator=(const Engine&) = delete;
bool start(const std::string& input_path, const Settings& settings, std::string* error);
// Interleaved float32; returns frames produced per channel, 0 means end of stream.
std::size_t read(float* destination, std::size_t frames, std::string* error);
unsigned channels() const;
void stop();
// Duration of the file, in seconds, for a caller that learns it after start()
// (reported duration of the track); zero means "no limit".
void set_length(double seconds);
// Repositions so that the next sample read() returns is the rendering of source
// sample round(seconds * 48000): the inputs restart at the syncframe holding
// that sample and the output before it is dropped. Seeking at or past
// `total_seconds` (0 when the duration is unknown) succeeds and makes the next
// read() return 0, as the decoder contract requires. start() must have run.
bool seek(double seconds, double total_seconds, std::string* error);
// Polled while the syncframe index is being walked, so a long seek stays
// interruptible; returning false aborts the seek.
void set_abort_check(std::function<bool()> check);
private:
struct Impl;
Impl* impl_;
};
} // namespace joc_decode