diff --git a/CMakeLists.txt b/CMakeLists.txt index e11b93f..4782523 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -104,6 +104,7 @@ set(JOC_INTERNAL_SOURCES src/foundation/status.cpp src/hrtf/jochrtf.cpp src/hrtf/public_filterbank.cpp + src/hrtf/rosella_bank.cpp src/hrtf/rosella_filterbank.cpp src/hrtf/rosella_model.cpp src/hrtf/rosella_renderer.cpp diff --git a/README.en.md b/README.en.md index 66dbb05..7ae9eaa 100644 --- a/README.en.md +++ b/README.en.md @@ -82,6 +82,7 @@ joc_cli input.m4a --binaural joc_cli input.m4a --binaural --sofa-hrtf HRTF/other.sofa # another SOFA joc_cli input.m4a --binaural --personalized-headphone # Rosella personalisation # -> output/.binaural.wav +joc_cli input.m4a --binaural --personalized-headphone --rosella-filterbank 2 # captured bank # Other common switches joc_cli input.m4a --duration 30 --gain-db -3 --trajectory-mode dense64 @@ -95,12 +96,19 @@ pass `continue`, `float32` or `abort`). `--duration` is in **seconds**, and `--binaural-tail-threshold` (1e-8, the binaural tail trim) keep the reference defaults. A run always writes `.report.json` (`--report-json` overrides it). -**Differences from the reference:** `--sofa-hrtf`, `--personalized-headphone`, -`--backend python` and the metadata sidecars (`--metadata-dir`, `--metadata-cache`, -`--metadata-backend sidecar`) are unavailable in this build and fail immediately -with an explanation instead of being ignored. This build adds `--bed` (pre-decoded +`--rosella-filterbank 1|2` picks the filterbank of the Rosella `.personalized_headphone` +path: `1` (default) is the public 13-tap / 6-slot bank, `2` is the captured 11-tap / +3-slot bank. Their latencies are 961 and 448 samples, and each keeps its own +coefficients, history and flush capacity. The option only applies to the Rosella +model; the SOFA and `.jochrtf` paths reject it. See +[Rosella filterbank](docs/rosella_filterbank.en.md). + +**Differences from the reference:** `--backend python` and the metadata sidecars +(`--metadata-dir`, `--metadata-cache`, `--metadata-backend sidecar`) are unavailable +in this build and fail immediately with an explanation instead of being ignored. +This build adds `--bed` (pre-decoded 6-channel float32 PCM, which skips ffmpeg decoding), `--kernels`, `--work-dir`, -`--report-json`, `--dry-run` and `--quiet`. +`--report-json`, `--dry-run`, `--quiet` and `--rosella-filterbank`. ## Speaker layouts and channel order diff --git a/README.md b/README.md index 3defbcc..b193faf 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,7 @@ joc_cli input.m4a --binaural joc_cli input.m4a --binaural --sofa-hrtf HRTF/other.sofa # 换一个 SOFA joc_cli input.m4a --binaural --personalized-headphone # Rosella 个性化模型 # -> output/<名称>.binaural.wav +joc_cli input.m4a --binaural --personalized-headphone --rosella-filterbank 2 # 新版 Rosella 滤波器组 # 其它常用开关 joc_cli input.m4a --duration 30 --gain-db -3 --trajectory-mode dense64 @@ -84,11 +85,16 @@ joc_cli input.eac3 --metadata-only --print-metadata summary # 只解析并打 `--binaural-tail-threshold`(默认 1e-8,双耳尾音裁切阈值)等默认值与上游一致。命令总是写出 `<输出>.report.json`(`--report-json` 可改路径)。 -**与上游参数的差异**:`--sofa-hrtf`、`--personalized-headphone`、`--backend python` 以及 -metadata sidecar(`--metadata-dir`/`--metadata-cache`/`--metadata-backend sidecar`)在本构建中 -不可用,给出时立刻报错并说明原因,而不是静默忽略。本构建额外提供 `--bed`(已解码的 6 通道 -float32 PCM,给出后不调用 ffmpeg 解码)、`--kernels`(滤波器组表路径)、`--work-dir`、 -`--report-json`、`--dry-run`、`--quiet`。 +`--rosella-filterbank 1|2` 选择 Rosella 个性化模型使用的滤波器组:`1`(默认)是 13 taps / +6 slots 的公开滤波器组,`2` 是 11 taps / 3 slots 的捕获版。两者延迟分别为 961 / 448 samples, +系数、历史缓冲与 flush 容量各自独立;该选项只作用于 `.personalized_headphone`,SOFA 与 +`.jochrtf` 路径给出时直接报错。详见 [Rosella 滤波器组](docs/rosella_filterbank.en.md)。 + +**与上游参数的差异**:`--backend python` 与 metadata sidecar(`--metadata-dir`/ +`--metadata-cache`/`--metadata-backend sidecar`)在本构建中不可用,给出时立刻报错并说明原因, +而不是静默忽略。本构建额外提供 `--bed`(已解码的 6 通道 float32 PCM,给出后不调用 ffmpeg +解码)、`--kernels`(滤波器组表路径)、`--work-dir`、`--report-json`、`--dry-run`、 +`--quiet`、`--rosella-filterbank`。 ## 扬声器布局与声道顺序 diff --git a/docs/binaural.en.md b/docs/binaural.en.md index 8bc8b98..a6f43b1 100644 --- a/docs/binaural.en.md +++ b/docs/binaural.en.md @@ -121,9 +121,13 @@ The SOFA and `.jochrtf` runtime is fixed at: - fifth order, 36 terms, ACN/N3D real spherical harmonics; - float64 PCM, delay, SH, and room state; complex128 band transfers and spectra. -The `.personalized_headphone` path uses a separate Rosella filterbank with -448 samples of latency. See [Rosella filterbank](rosella_filterbank.en.md) for -its parameters and validation results. The SOFA bank described here is unchanged. +The `.personalized_headphone` path selects its bank rather than fixing it. The +default is the shared public bank described here (961 samples of latency); bank +2 is the captured Rosella bank (448 samples). Both keep their own coefficients, +history and high-band delay, and the runtime skips the selected bank's latency +and sizes the flush with it. See [Rosella filterbank](rosella_filterbank.en.md) +for the parameters, the CLI switch and the validation results. The SOFA and +`.jochrtf` banks described here are unchanged and never use the selector. Real and imaginary unit gains for every hybrid band pass through the same analysis/synthesis chain to form a 154-real-parameter impulse dictionary. The diff --git a/docs/binaural.md b/docs/binaural.md index f93d193..66f27bc 100644 --- a/docs/binaural.md +++ b/docs/binaural.md @@ -177,6 +177,22 @@ key。writer 使用同目录临时文件、`fsync`、进程持有的 OS 文件 私有 cache,不随程序或构建产物发布。`source_sha256` 只用于内容一致性校验,不是许可 或来源证明。 +## Rosella 个性化模型 + +`.personalized_headphone` 走独立的 Rosella 渲染器,滤波器组可以二选一, +由 `--rosella-filterbank 1|2`(库接口为 `joc_task_config::rosella_filterbank` / +`joc_stream_config::rosella_filterbank`,`0` 表示默认)选择: + +| 取值 | 滤波器组 | 低频 hybrid | 高频 slot delay | 延迟 | +| --- | --- | --- | --- | ---: | +| `1`(默认) | `PublicFilterbank`(与 SOFA 路径共用) | 13 taps | 6 slots | 961 samples | +| `2` | `RosellaFilterbank`(从参考渲染器捕获) | 11 taps | 3 slots | 448 samples | + +两套实现通过同一组四个有状态 half-step 调用,因此切换时系数、高频 delay、历史缓冲 +布局、起始延迟跳过量和 flush 容量一起改变,分析与合成两级互不共享状态。其它取值直接 +报错;非 Rosella 输入给出该选项也报错,不会静默忽略。详见 +[Rosella filterbank](rosella_filterbank.en.md)。 + ## JOC 对象与房间 生产适配器继续使用现有 JOC 调度: diff --git a/docs/rosella_filterbank.en.md b/docs/rosella_filterbank.en.md index f7ea4a4..052e5ae 100644 --- a/docs/rosella_filterbank.en.md +++ b/docs/rosella_filterbank.en.md @@ -1,7 +1,28 @@ # Rosella filterbank -The Rosella renderer uses a separate 64-band QMF and 77-band hybrid filterbank. -The SOFA compiler and renderer continue to use `PublicFilterbank`. +The Rosella renderer runs one of two 64-band QMF / 77-band hybrid filterbanks. +The shared public bank is the default; the captured Rosella bank reproduces the +reference headphone renderer. The SOFA compiler and renderer always use +`PublicFilterbank`. + +## Which bank runs + +`--rosella-filterbank 1|2` selects the bank for the `.personalized_headphone` +path; `joc_task_config::rosella_filterbank` and +`joc_stream_config::rosella_filterbank` carry the same value, with `0` meaning +the default. + +| Value | Bank | Low-band hybrid | High-band delay | Latency | +| --- | --- | --- | --- | ---: | +| `1` (default) | `PublicFilterbank` | 13 taps | 6 slots | 961 samples | +| `2` | `RosellaFilterbank` | 11 taps | 3 slots | 448 samples | + +Both banks are driven through the same four stateful half-steps, so the choice +switches the coefficients, the high-band delay, the history layout, the startup +skip and the flush capacity together; the analysis and synthesis banks never +share state. Any other value is rejected, and the option is an error when the +binaural input is not a Rosella model: the SOFA and `.jochrtf` paths do not use +it and must not silently ignore it. ## Why the banks differ @@ -33,9 +54,9 @@ each channel. QMF data uses `[slot, channel, 64]` order. Hybrid data uses and hybrid coefficients as hexadecimal literals. Processing uses double precision. The tables do not contain the personalized HRTF or room tuning. -The runtime removes 448 startup samples and uses the same latency when it -calculates flush capacity. Its rendered buffer is resized to the current block -length, including a short final block. +The runtime removes the selected bank's startup samples and uses the same +latency when it calculates flush capacity. Its rendered buffer is resized to the +current block length, including a short final block. ## Validation @@ -49,8 +70,11 @@ ctest --test-dir build --output-on-failure `rosella_filterbank` checks deterministic analysis, hybrid, folding, and synthesis vectors from an independent NumPy implementation. It also checks empty and -unequal chunks, reset, channel isolation, and impulse latency. The tests need no -reference binary, audio fixture, or personalized headphone file. +unequal chunks, reset, channel isolation, and impulse latency. A second group +checks the bank selector: each kind reproduces exactly what its own class +computes, the two produce different hybrid data, chunking and reset are +invariant for both, and each reports its own latency (961 or 448 samples). The +tests need no reference binary, audio fixture, or personalized headphone file. Before integration with the upstream bed-layout changes, four captured-input tests gave the following room PCM residuals. No gain fitting was used for this diff --git a/include/joc_core.h b/include/joc_core.h index 40d6a96..1369317 100644 --- a/include/joc_core.h +++ b/include/joc_core.h @@ -39,7 +39,7 @@ #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_CONFIG_VERSION 4u #define JOC_TASK_RESULT_VERSION 2u #define JOC_EVENT_VERSION 1u @@ -82,7 +82,7 @@ enum { JOC_BINAURAL_QMF_BANDS = 64, JOC_BINAURAL_HYBRID_BANDS = 77, JOC_QMF_HOP_SAMPLES = 64, - JOC_BINAURAL_LATENCY_SAMPLES = 961, + JOC_BINAURAL_LATENCY_SAMPLES = 961, /* SOFA/.jochrtf and Rosella bank 1 */ JOC_LFE_DELAY_SAMPLES = 1217 }; @@ -366,6 +366,15 @@ typedef enum joc_hrtf_cache_policy { JOC_HRTF_CACHE_DISK = 2 /* compile, reuse and write /.jochrtf */ } joc_hrtf_cache_policy; +/* 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 }; @@ -423,7 +432,7 @@ typedef struct joc_task_config { 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; + uint32_t rosella_filterbank; /* joc_rosella_filterbank; 0 = PUBLIC */ double hrtf_radius_m; /* SOFA measurement-radius shell */ } joc_task_config; diff --git a/include/joc_stream.h b/include/joc_stream.h index 5c2076b..b942f4f 100644 --- a/include/joc_stream.h +++ b/include/joc_stream.h @@ -63,7 +63,7 @@ typedef struct joc_stream_config { uint32_t object_delay_samples; /* default 1473 */ double gain_db; /* default 0 */ uint32_t native_threads; - uint32_t reserved; + uint32_t rosella_filterbank; /* joc_rosella_filterbank; Rosella input, 0 = PUBLIC */ /* 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 diff --git a/src/api/joc_stream_api.cpp b/src/api/joc_stream_api.cpp index d509ac0..bca9fa7 100644 --- a/src/api/joc_stream_api.cpp +++ b/src/api/joc_stream_api.cpp @@ -46,6 +46,10 @@ joc::stream::Config to_config(const joc_stream_config& config) { if (config.hrtf_cache_dir != nullptr) { out.hrtf_cache_dir = config.hrtf_cache_dir; } out.hrtf_cache_policy = config.hrtf_cache_policy; if (config.hrtf_radius_m > 0.0) { out.hrtf_radius_m = config.hrtf_radius_m; } + // 0 is "unset" here as well: the Rosella path defaults to the public bank. + if (config.rosella_filterbank != 0u) { + out.rosella_filterbank = config.rosella_filterbank; + } return out; } diff --git a/src/cli/joc_cli.cpp b/src/cli/joc_cli.cpp index 8ea71d0..98441f1 100644 --- a/src/cli/joc_cli.cpp +++ b/src/cli/joc_cli.cpp @@ -44,6 +44,8 @@ struct Options { std::string compiled_hrtf_cache; std::string personalized_headphone; bool personalized_headphone_used = false; + int rosella_filterbank = 1; + bool rosella_filterbank_set = false; std::string hrtf_cache_policy; std::string hrtf_cache_dir; double hrtf_radius_m = 1.0; @@ -118,6 +120,8 @@ void print_usage() { " --sofa-hrtf PATH SOFA SimpleFreeFieldHRIR 输入;.jochrtf 由本工具内部编译\n" " --personalized-headphone [PATH] Rosella 个性化模型,默认 " "HRTF/binaural.personalized_headphone\n" + " --rosella-filterbank N Rosella 模型滤波器组:1=13 taps/6 slots(默认),\n" + " 2=11 taps/3 slots;仅作用于个性化模型\n" " --compiled-hrtf-cache PATH 直接读取 .jochrtf(高级用法,跳过 SOFA 编译)\n" " --hrtf-cache-policy P SOFA 编译缓存策略 none|memory|disk,默认 memory\n" " --hrtf-cache-dir DIR disk cache 目录,默认 /output/hrtf-cache\n" @@ -238,6 +242,11 @@ void parse_args(const std::vector& arguments, Options* options) { options->personalized_headphone = require_value(arguments, &index); } } + else if (arg == "--rosella-filterbank") { + options->rosella_filterbank = static_cast( + to_int(require_value(arguments, &index), "--rosella-filterbank")); + options->rosella_filterbank_set = true; + } else if (arg == "--hrtf-cache-policy") { options->hrtf_cache_policy = require_value(arguments, &index); } else if (arg == "--hrtf-cache-dir") { options->hrtf_cache_dir = require_value(arguments, &index); } else if (arg == "--hrtf-radius-m") { options->hrtf_radius_m = to_double(require_value(arguments, &index), "--hrtf-radius-m"); } @@ -562,6 +571,10 @@ int main(int argc, char** argv) { check_choice(options.hrtf_cache_policy, "--hrtf-cache-policy", {"none", "memory", "disk"}); } + if (options.rosella_filterbank != 1 && options.rosella_filterbank != 2) { + fail("--rosella-filterbank: invalid choice: " + + std::to_string(options.rosella_filterbank) + " (choose from 1, 2)"); + } const bool speaker_mode = !options.speaker_layout.empty(); const bool binaural_mode = options.binaural; @@ -596,6 +609,9 @@ int main(int argc, char** argv) { if (hrtf_options_used && !binaural_mode) { fail("SOFA/HRTF 选项仅与 --binaural 一起使用"); } + if (options.rosella_filterbank_set && !binaural_mode) { + fail("--rosella-filterbank 仅与 --binaural 一起使用"); + } if (!std::isfinite(options.binaural_tail_seconds) || options.binaural_tail_seconds < 0.0) { fail("binaural-tail-seconds 必须是非负有限值"); @@ -670,6 +686,7 @@ int main(int argc, char** argv) { config.speaker_metadata_offset = static_cast(options.speaker_metadata_offset); config.binaural_mode = binaural_mode_value(options.binaural_mode); config.adm_binaural_mode = binaural_mode_value(options.binaural_mode); + config.rosella_filterbank = static_cast(options.rosella_filterbank); config.binaural_tail_seconds = options.binaural_tail_seconds; config.binaural_tail_threshold = options.binaural_tail_threshold; config.binaural_chunk_frames = static_cast(options.binaural_chunk_frames); @@ -710,6 +727,10 @@ int main(int argc, char** argv) { personalized_path = input.personalized_path; kernels_path = find_kernels(options, arguments.empty() ? std::string() : arguments.front()); + if (options.rosella_filterbank_set && personalized_path.empty()) { + fail("--rosella-filterbank 只作用于 Rosella .personalized_headphone 输入;" + "当前 SOFA/.jochrtf 路径不使用该滤波器组"); + } } catch (const std::exception& error) { std::fprintf(stderr, "joc_cli: error: %s\n", error.what()); return 2; diff --git a/src/hrtf/rosella_bank.cpp b/src/hrtf/rosella_bank.cpp new file mode 100644 index 0000000..5db6cc2 --- /dev/null +++ b/src/hrtf/rosella_bank.cpp @@ -0,0 +1,89 @@ +#include "hrtf/rosella_bank.h" + +#include + +#include "hrtf/rosella_filterbank.h" + +namespace joc::hrtf { +namespace { + +// The shared public bank. It is also what the SOFA field compiler runs, and it +// is the bank the Rosella renderer used before the Rosella-specific one was +// captured. +class PublicBank final : public RosellaBank { +public: + explicit PublicBank(std::size_t channels) : bank_(builtin_kernels(), channels) {} + + void reset() override { bank_.reset(); } + + void analyze_qmf(const std::vector& hops, std::size_t slots, + std::vector* qmf) override { + bank_.analyze_qmf(hops, slots, qmf); + } + + void analyze_hybrid(const std::vector& qmf, std::size_t slots, + std::vector* hybrid) override { + bank_.analyze_hybrid(qmf, slots, hybrid); + } + + void synthesize_hybrid(const std::vector& hybrid, std::size_t slots, + std::vector* qmf) override { + bank_.synthesize_hybrid(hybrid, slots, qmf); + } + + void synthesize_qmf(const std::vector& qmf, std::size_t slots, + std::vector* hops) override { + bank_.synthesize_qmf(qmf, slots, hops); + } + +private: + PublicFilterbank bank_; +}; + +// The bank captured from the Rosella headphone renderer. +class CapturedBank final : public RosellaBank { +public: + explicit CapturedBank(std::size_t channels) : bank_(channels) {} + + void reset() override { bank_.reset(); } + + void analyze_qmf(const std::vector& hops, std::size_t slots, + std::vector* qmf) override { + bank_.analyze_qmf(hops, slots, qmf); + } + + void analyze_hybrid(const std::vector& qmf, std::size_t slots, + std::vector* hybrid) override { + bank_.analyze_hybrid(qmf, slots, hybrid); + } + + void synthesize_hybrid(const std::vector& hybrid, std::size_t slots, + std::vector* qmf) override { + bank_.synthesize_hybrid(hybrid, slots, qmf); + } + + void synthesize_qmf(const std::vector& qmf, std::size_t slots, + std::vector* hops) override { + bank_.synthesize_qmf(qmf, slots, hops); + } + +private: + RosellaFilterbank bank_; +}; + +} // namespace + +std::uint32_t rosella_bank_latency(RosellaBankKind kind) { + return kind == RosellaBankKind::Captured + ? static_cast(RosellaFilterbank::kLatencySamples) + : static_cast(kLatencySamples); +} + +std::unique_ptr RosellaBank::create(RosellaBankKind kind, std::size_t channels) { + if (kind == RosellaBankKind::Captured) { + return std::make_unique(channels); + } + return std::make_unique(channels); +} + +} // namespace joc::hrtf diff --git a/src/hrtf/rosella_bank.h b/src/hrtf/rosella_bank.h new file mode 100644 index 0000000..fbd4bba --- /dev/null +++ b/src/hrtf/rosella_bank.h @@ -0,0 +1,50 @@ +#pragma once + +#include +#include +#include +#include + +#include "hrtf/public_filterbank.h" + +namespace joc::hrtf { + +// Which 64-QMF / 77-hybrid bank the Rosella renderer runs. The two are not +// interchangeable: the QMF prototype, the hybrid tap count, the high-band slot +// delay and the analysis/synthesis latency all differ, so each bank keeps its own +// tables and its own state. +enum class RosellaBankKind : std::int32_t { + Public = 1, // shared bank: 13-tap hybrid, 6-slot delay, 961 samples + Captured = 2, // Rosella bank: 11-tap hybrid, 3-slot delay, 448 samples +}; + +// Analysis/synthesis latency of `kind` at 48 kHz, in samples. +std::uint32_t rosella_bank_latency(RosellaBankKind kind); + +// The four stateful half-steps of either bank, in the order the reference runs +// them. Hops and QMF data are [slots, channels, 64], hybrid data is +// [slots, channels, 77]. State is per instance, so the analysis bank of a +// runtime and its synthesis bank never share buffers. +class RosellaBank { +public: + // `kind` must name one of the enumerators; anything else selects Public. + static std::unique_ptr create(RosellaBankKind kind, std::size_t channels); + + RosellaBank() = default; + RosellaBank(const RosellaBank&) = delete; + RosellaBank& operator=(const RosellaBank&) = delete; + virtual ~RosellaBank() = default; + + virtual void reset() = 0; + + virtual void analyze_qmf(const std::vector& hops, std::size_t slots, + std::vector* qmf) = 0; + virtual void analyze_hybrid(const std::vector& qmf, std::size_t slots, + std::vector* hybrid) = 0; + virtual void synthesize_hybrid(const std::vector& hybrid, std::size_t slots, + std::vector* qmf) = 0; + virtual void synthesize_qmf(const std::vector& qmf, std::size_t slots, + std::vector* hops) = 0; +}; + +} // namespace joc::hrtf diff --git a/src/hrtf/rosella_renderer.cpp b/src/hrtf/rosella_renderer.cpp index 72f9085..488df9e 100644 --- a/src/hrtf/rosella_renderer.cpp +++ b/src/hrtf/rosella_renderer.cpp @@ -12,7 +12,7 @@ #include #include "foundation/fft.h" -#include "hrtf/rosella_filterbank.h" +#include "hrtf/rosella_bank.h" namespace joc::hrtf { @@ -1003,8 +1003,8 @@ struct RosellaRuntime::Impl { std::vector field_left; std::vector field_right; Core core; - std::unique_ptr analysis_bank; - std::unique_ptr synthesis_bank; + std::unique_ptr analysis_bank; + std::unique_ptr synthesis_bank; timeline::OamdPositionTimeline timeline{timeline::kTimelineObjects}; std::vector buffer; // [chunk_samples][16] @@ -1139,9 +1139,13 @@ struct RosellaRuntime::Impl { return Status::success(); } + // The reference drops the first `latency` samples of the raw stream (the + // filterbank's own delay) and returns everything after that; the latency is + // the selected bank's, so the two banks start at different sample offsets. void append_output(const double* stereo, std::size_t count) { - const std::int64_t remaining = static_cast(RosellaFilterbank::kLatencySamples) - - static_cast(raw_output_samples); + const std::int64_t remaining = + static_cast(rosella_bank_latency(options.bank)) - + static_cast(raw_output_samples); const std::size_t skip = static_cast( std::max(0, std::min(static_cast(count), remaining))); @@ -1187,6 +1191,9 @@ Status RosellaRuntime::open(const RosellaModel& model, const RosellaRenderOption if (options.object_delay_samples < 0) { return render_fail(JOC_ERR_INVALID_ARGUMENT, "object_delay_samples must be non-negative"); } + if (options.bank != RosellaBankKind::Public && options.bank != RosellaBankKind::Captured) { + return render_fail(JOC_ERR_INVALID_ARGUMENT, "unknown Rosella filterbank"); + } impl_->model = model; impl_->options = options; logical_field(impl_->model.field_left_padded, &impl_->field_left); @@ -1199,8 +1206,8 @@ Status RosellaRuntime::open(const RosellaModel& model, const RosellaRenderOption return status; } // The analysis bank runs sixteen sources, the synthesis bank two output ears. - impl_->analysis_bank = std::make_unique(kSourceChannels); - impl_->synthesis_bank = std::make_unique(kOutputChannels); + impl_->analysis_bank = RosellaBank::create(options.bank, kSourceChannels); + impl_->synthesis_bank = RosellaBank::create(options.bank, kOutputChannels); impl_->buffer.assign(impl_->chunk_samples() * kSourceChannels, 0.0); impl_->room_sends_buffer_.assign( (impl_->chunk_samples() / kQmfHop) * kHybridBands, Complex(0.0, 0.0)); @@ -1306,7 +1313,7 @@ Status RosellaRuntime::finish(std::uint32_t flush_samples, std::vector* std::uint32_t RosellaRuntime::finish_capacity(double tail_seconds) const { const double samples = tail_seconds * 48000.0 + - static_cast(RosellaFilterbank::kLatencySamples) + + static_cast(rosella_bank_latency(impl_->options.bank)) + static_cast(kBlockSamples); const double blocks = std::ceil(samples / static_cast(kBlockSamples)); return static_cast(blocks) * kBlockSamples; diff --git a/src/hrtf/rosella_renderer.h b/src/hrtf/rosella_renderer.h index c822e3a..b829f56 100644 --- a/src/hrtf/rosella_renderer.h +++ b/src/hrtf/rosella_renderer.h @@ -6,6 +6,7 @@ #include #include "foundation/status.h" +#include "hrtf/rosella_bank.h" #include "hrtf/rosella_model.h" #include "oamd/oamd_parser.h" #include "timeline/position_timeline.h" @@ -21,6 +22,9 @@ enum class RosellaProfile : std::int32_t { Near = 1, Far = 2, Mid = 3 }; struct RosellaRenderOptions { RosellaProfile profile = RosellaProfile::Mid; + // The analysis and synthesis banks both come from this one choice, so the + // latency skip, the flush capacity and the state histories stay consistent. + RosellaBankKind bank = RosellaBankKind::Public; std::int64_t object_delay_samples = 1473; double tail_seconds = 5.0; double output_gain = 1.0; diff --git a/src/stream/stream.cpp b/src/stream/stream.cpp index f2a468a..de00edd 100644 --- a/src/stream/stream.cpp +++ b/src/stream/stream.cpp @@ -127,6 +127,9 @@ Status Stream::create(const Config& config) { } render_options.object_delay_samples = config_.object_delay_samples; render_options.tail_seconds = config_.tail_seconds; + render_options.bank = config_.rosella_filterbank == JOC_ROSELLA_FILTERBANK_CAPTURED + ? hrtf::RosellaBankKind::Captured + : hrtf::RosellaBankKind::Public; if (status.ok()) { status = rosella_.open(model, render_options); } diff --git a/src/stream/stream.h b/src/stream/stream.h index 7d7e168..80030b3 100644 --- a/src/stream/stream.h +++ b/src/stream/stream.h @@ -37,6 +37,8 @@ struct Config { std::string hrtf_cache_dir; std::uint32_t hrtf_cache_policy = JOC_HRTF_CACHE_MEMORY; double hrtf_radius_m = 1.0; + // Filterbank of the Rosella path; the other binaural inputs ignore it. + std::uint32_t rosella_filterbank = JOC_ROSELLA_FILTERBANK_PUBLIC; }; struct Info { diff --git a/src/task/task.cpp b/src/task/task.cpp index 6ec5210..21cdaec 100644 --- a/src/task/task.cpp +++ b/src/task/task.cpp @@ -34,6 +34,7 @@ #include "foundation/mini_json.h" #include "foundation/sha256.h" #include "hrtf/jochrtf.h" +#include "hrtf/rosella_bank.h" #include "hrtf/rosella_model.h" #include "hrtf/rosella_renderer.h" #include "hrtf/sofa_cache.h" @@ -98,6 +99,7 @@ struct Settings { std::string hrtf_cache_dir; std::uint32_t hrtf_cache_policy = JOC_HRTF_CACHE_MEMORY; double hrtf_radius_m = 1.0; + std::uint32_t rosella_filterbank = JOC_ROSELLA_FILTERBANK_PUBLIC; std::uint32_t operation = JOC_OP_ADM_BWF; std::uint32_t output_format = JOC_FORMAT_FLOAT32; std::uint32_t adm_binaural_mode = JOC_BINAURAL_MID; @@ -149,6 +151,9 @@ Settings normalise(const joc_task_config& raw) { if (raw.hrtf_cache_dir != nullptr) { cfg.hrtf_cache_dir = raw.hrtf_cache_dir; } cfg.hrtf_cache_policy = raw.hrtf_cache_policy; cfg.hrtf_radius_m = raw.hrtf_radius_m; + // Kept verbatim so validate() can reject an out-of-range value; 0 is the + // documented "unset" spelling of the public bank. + cfg.rosella_filterbank = raw.rosella_filterbank; if (raw.kernels_path != nullptr) { cfg.kernels_path = raw.kernels_path; } cfg.operation = raw.operation; cfg.output_format = raw.output_format; @@ -1108,6 +1113,14 @@ Status validate(const joc_task_config& raw, std::vector* i fail(JOC_ERR_INVALID_CONFIG, "binaural_mode", "binaural_mode off is only meaningful for ADM output"); } + if (cfg.rosella_filterbank > JOC_ROSELLA_FILTERBANK_CAPTURED) { + fail(JOC_ERR_INVALID_CONFIG, "rosella_filterbank", + "rosella_filterbank must be 1 (public) or 2 (captured)"); + } else if (cfg.rosella_filterbank == JOC_ROSELLA_FILTERBANK_CAPTURED && + cfg.personalized_headphone_path.empty()) { + fail(JOC_ERR_INVALID_CONFIG, "rosella_filterbank", + "rosella_filterbank 2 only applies to a Rosella .personalized_headphone input"); + } } if (cfg.operation == JOC_OP_ADM_BWF) { if (cfg.adm_binaural_mode > 4u) { @@ -1358,14 +1371,22 @@ Status run(const joc_task_config& raw, const joc_event_sink* sink, joc_task_resu } render_options.object_delay_samples = cfg.object_delay_samples; render_options.tail_seconds = cfg.tail_seconds; + render_options.bank = + cfg.rosella_filterbank == JOC_ROSELLA_FILTERBANK_CAPTURED + ? ::joc::hrtf::RosellaBankKind::Captured + : ::joc::hrtf::RosellaBankKind::Public; if (status.ok()) { status = rosella.open(model, render_options); } if (status.ok()) { bus.emit(JOC_EV_HRTF_LOADED, JOC_STAGE_RENDER, JOC_LOG_INFO, model.summary()); bus.emit(JOC_EV_RENDERER_INITIALIZED, JOC_STAGE_RENDER, JOC_LOG_INFO, - "Rosella binaural runtime ready (the first 961 samples are the " - "filterbank latency)"); + fmt("Rosella binaural runtime ready (%s filterbank, the first %u " + "samples are the filterbank latency)", + render_options.bank == ::joc::hrtf::RosellaBankKind::Captured + ? "captured" + : "public", + ::joc::hrtf::rosella_bank_latency(render_options.bank))); } if (!status.ok()) { return finalize_with_error(status.code(), "render", diff --git a/tests/test_core.cpp b/tests/test_core.cpp index d1e74eb..fee2bd1 100644 --- a/tests/test_core.cpp +++ b/tests/test_core.cpp @@ -927,6 +927,36 @@ std::vector drive_objects16_stream(const std::vector& block, std:: return rendered; } +void test_rosella_filterbank_config() { + // validate() reports a selector it cannot honour instead of ignoring it: the + // captured bank needs the Rosella model, and any other value is out of range. + const auto reported = [](std::uint32_t selector, const char* personalized) { + joc_task_config config{}; + config.struct_size = sizeof(config); + config.struct_version = JOC_TASK_CONFIG_VERSION; + config.input_path = "input.eac3"; + config.output_path = "output.wav"; + config.operation = JOC_OP_BINAURAL; + config.binaural_mode = JOC_BINAURAL_MID; + config.personalized_headphone_path = personalized; + config.hrtf_path = personalized == nullptr ? "cache.jochrtf" : nullptr; + config.rosella_filterbank = selector; + std::vector issues; + std::uint32_t errors = 0; + joc::task::validate(config, &issues, &errors); + for (const joc_validation_issue& issue : issues) { + if (std::string(issue.field) == "rosella_filterbank") { + return true; + } + } + return false; + }; + CHECK(!reported(JOC_ROSELLA_FILTERBANK_PUBLIC, "model.personalized_headphone")); + CHECK(!reported(JOC_ROSELLA_FILTERBANK_CAPTURED, "model.personalized_headphone")); + CHECK(reported(3u, "model.personalized_headphone")); + CHECK(reported(JOC_ROSELLA_FILTERBANK_CAPTURED, nullptr)); +} + // A push renders every frame it makes ready, so the stream bounds how far ahead of // the caller it renders. A batch pushed at once must therefore leave a bounded // backlog, and it must render the same samples as pushing one frame at a time. @@ -1126,6 +1156,7 @@ int main() { test_sofa_reader_errors(); test_hrtf_cache_policy(); test_rosella_model_errors(); + test_rosella_filterbank_config(); test_stream_render_ahead(); test_clipgain_first_frame_uses_its_own_gain(); test_clipgain_change_applies_to_the_current_frame(); diff --git a/tests/test_rosella_filterbank.cpp b/tests/test_rosella_filterbank.cpp index 31ac906..2c3e8f6 100644 --- a/tests/test_rosella_filterbank.cpp +++ b/tests/test_rosella_filterbank.cpp @@ -1,8 +1,12 @@ #include #include +#include #include +#include #include +#include "hrtf/public_filterbank.h" +#include "hrtf/rosella_bank.h" #include "hrtf/rosella_filterbank.h" #include "rosella_filterbank_vectors.h" @@ -18,6 +22,9 @@ void check(bool passed, const char* name) { } using joc::hrtf::Complex; +using joc::hrtf::PublicFilterbank; +using joc::hrtf::RosellaBank; +using joc::hrtf::RosellaBankKind; using joc::hrtf::RosellaFilterbank; template @@ -116,11 +123,147 @@ void test_latency() { check(std::abs(*peak - 0.999989847495873) < 1e-10, "roundtrip gain"); } +// One pass of the four half-steps, split into the given slot counts; the +// concatenation is what a single call with the total count produces. +struct BankTrace { + std::vector qmf; + std::vector hybrid; + std::vector folded; + std::vector time; +}; + +BankTrace run_bank(RosellaBank& bank, const std::vector& hops, + const std::vector& synthetic, const std::vector& chunks, + std::size_t channels) { + BankTrace trace; + std::size_t first = 0; + for (const std::size_t count : chunks) { + const std::vector part_hops(hops.begin() + first * channels * 64, + hops.begin() + (first + count) * channels * 64); + const std::vector part_synthetic( + synthetic.begin() + first * channels * 77, + synthetic.begin() + (first + count) * channels * 77); + std::vector qmf, hybrid, folded; + std::vector time; + bank.analyze_qmf(part_hops, count, &qmf); + bank.analyze_hybrid(qmf, count, &hybrid); + bank.synthesize_hybrid(part_synthetic, count, &folded); + bank.synthesize_qmf(folded, count, &time); + trace.qmf.insert(trace.qmf.end(), qmf.begin(), qmf.end()); + trace.hybrid.insert(trace.hybrid.end(), hybrid.begin(), hybrid.end()); + trace.folded.insert(trace.folded.end(), folded.begin(), folded.end()); + trace.time.insert(trace.time.end(), time.begin(), time.end()); + first += count; + } + return trace; +} + +bool same_trace(const BankTrace& left, const BankTrace& right) { + return left.qmf == right.qmf && left.hybrid == right.hybrid && + left.folded == right.folded && left.time == right.time; +} + +void test_bank_selection() { + constexpr std::size_t slots = 24; + constexpr std::size_t channels = 2; + std::vector hops(slots * channels * 64); + for (std::size_t index = 0; index < hops.size(); ++index) { + hops[index] = (static_cast((index * 37 + 11) % 257) - 128) / 128.0; + } + std::vector synthetic(slots * channels * 77); + for (std::size_t index = 0; index < synthetic.size(); ++index) { + synthetic[index] = Complex((static_cast((index * 17 + 3) % 101) - 50) / 64.0, + (static_cast((index * 13 + 7) % 97) - 48) / 64.0); + } + + // The selector is only a choice of implementation: each kind must reproduce + // exactly what its own class computes, and the two banks must stay separate. + std::vector public_hybrid; + std::vector captured_hybrid; + for (const RosellaBankKind kind : {RosellaBankKind::Public, RosellaBankKind::Captured}) { + std::vector direct_qmf, direct_hybrid; + if (kind == RosellaBankKind::Public) { + PublicFilterbank bank(joc::hrtf::builtin_kernels(), channels); + bank.analyze_qmf(hops, slots, &direct_qmf); + bank.analyze_hybrid(direct_qmf, slots, &direct_hybrid); + } else { + RosellaFilterbank bank(channels); + bank.analyze_qmf(hops, slots, &direct_qmf); + bank.analyze_hybrid(direct_qmf, slots, &direct_hybrid); + } + std::unique_ptr selected = RosellaBank::create(kind, channels); + std::vector selected_qmf, selected_hybrid; + selected->analyze_qmf(hops, slots, &selected_qmf); + selected->analyze_hybrid(selected_qmf, slots, &selected_hybrid); + check(selected_qmf == direct_qmf, "selector analysis matches the bank"); + check(selected_hybrid == direct_hybrid, "selector hybrid matches the bank"); + if (kind == RosellaBankKind::Public) { + public_hybrid = selected_hybrid; + } else { + captured_hybrid = selected_hybrid; + } + + BankTrace whole; + { + std::unique_ptr fresh = RosellaBank::create(kind, channels); + whole = run_bank(*fresh, hops, synthetic, {slots}, channels); + } + check(whole.qmf == selected_qmf, "whole chunk analysis"); + check(whole.hybrid == selected_hybrid, "whole chunk hybrid"); + for (int repeat = 0; repeat < 2; ++repeat) { + std::unique_ptr split = RosellaBank::create(kind, channels); + const BankTrace parts = + run_bank(*split, hops, synthetic, {0u, 5u, 0u, 7u, 12u}, channels); + check(same_trace(whole, parts), "chunk/reset invariance"); + } + } + check(public_hybrid != captured_hybrid, "the two banks produce different hybrid data"); +} + +// Distance from the impulse to the absolute peak of the analysis/synthesis +// roundtrip, which is the latency the runtime skips at the head of the stream. +std::size_t roundtrip_peak(RosellaBank& bank, std::size_t slots) { + std::vector impulse(slots * 64, 0.0); + impulse[0] = 1.0; + std::vector qmf, hybrid; + std::vector output; + bank.analyze_qmf(impulse, slots, &qmf); + bank.analyze_hybrid(qmf, slots, &hybrid); + bank.synthesize_hybrid(hybrid, slots, &qmf); + bank.synthesize_qmf(qmf, slots, &output); + const auto peak = std::max_element(output.begin(), output.end(), [](double left, double right) { + return std::abs(left) < std::abs(right); + }); + return static_cast(peak - output.begin()); +} + +void test_bank_latency_and_reset() { + check(joc::hrtf::rosella_bank_latency(RosellaBankKind::Public) == + static_cast(joc::hrtf::kLatencySamples), + "public latency is the public filterbank latency"); + check(joc::hrtf::rosella_bank_latency(RosellaBankKind::Captured) == + static_cast(RosellaFilterbank::kLatencySamples), + "captured latency is the Rosella filterbank latency"); + check(joc::hrtf::rosella_bank_latency(RosellaBankKind::Public) == 961u, + "public latency is 961 samples"); + check(joc::hrtf::rosella_bank_latency(RosellaBankKind::Captured) == 448u, + "captured latency is 448 samples"); + for (const RosellaBankKind kind : {RosellaBankKind::Public, RosellaBankKind::Captured}) { + std::unique_ptr bank = RosellaBank::create(kind, 1); + const std::size_t first = roundtrip_peak(*bank, 64); + check(first == joc::hrtf::rosella_bank_latency(kind), "bank roundtrip latency"); + bank->reset(); + check(roundtrip_peak(*bank, 64) == first, "bank reset restores the startup delay"); + } +} + } int main() { test_reference_and_streaming(); test_latency(); + test_bank_selection(); + test_bank_latency_and_reset(); std::printf("Rosella filterbank: %d failures\n", failures); return failures == 0 ? 0 : 1; }