Add --rosella-filterbank and restore the public bank as the default
ci / ubuntu-latest (push) Failing after 16s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s

The Rosella path picks its analysis and synthesis bank instead of
hard-coding one. Bank 1 is the shared public bank the renderer used
before the captured variant landed: 13-tap hybrid filters, the 6-slot
high-band delay and 961 samples of latency. Bank 2 is the captured
Rosella bank: 11-tap filters, the 3-slot delay and 448 samples. Both
keep their own coefficients, histories and flush behaviour.

- Drive either bank through one RosellaBank interface, and derive the
  startup skip and the flush capacity from the selected bank
- Add joc_rosella_filterbank to joc_task_config and joc_stream_config
  by replacing the reserved words (struct sizes unchanged, config
  version 3 -> 4)
- Reject an out-of-range value and bank 2 without a Rosella model
  instead of silently falling back
- Expose --rosella-filterbank 1|2 in the CLI with bank 1 as default,
  and reject it outside the personalized headphone path
- Cover bank identity, chunking, reset and per-bank latency in tests
- Document both banks, the selector and the CLI help

Renders of --rosella-filterbank 1 (and the default) match the pre-merge
reference byte for byte; --rosella-filterbank 2 matches the PR #3
reference byte for byte.
This commit is contained in:
TheM14 committed 2026-10-31 01:11:44 +08:00
1 parent 6674cb5386
commit 34a722f56a
19 files changed
+477 -34

No files matched your search

+4
View File
@@ -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;
}
+21
View File
@@ -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 目录,默认 <exe>/output/hrtf-cache\n"
@@ -238,6 +242,11 @@ void parse_args(const std::vector<std::string>& arguments, Options* options) {
options->personalized_headphone = require_value(arguments, &index);
}
}
else if (arg == "--rosella-filterbank") {
options->rosella_filterbank = static_cast<int>(
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<std::uint32_t>(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<std::uint32_t>(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<std::uint32_t>(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;
+89
View File
@@ -0,0 +1,89 @@
#include "hrtf/rosella_bank.h"
#include <utility>
#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<double>& hops, std::size_t slots,
std::vector<Complex>* qmf) override {
bank_.analyze_qmf(hops, slots, qmf);
}
void analyze_hybrid(const std::vector<Complex>& qmf, std::size_t slots,
std::vector<Complex>* hybrid) override {
bank_.analyze_hybrid(qmf, slots, hybrid);
}
void synthesize_hybrid(const std::vector<Complex>& hybrid, std::size_t slots,
std::vector<Complex>* qmf) override {
bank_.synthesize_hybrid(hybrid, slots, qmf);
}
void synthesize_qmf(const std::vector<Complex>& qmf, std::size_t slots,
std::vector<double>* 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<double>& hops, std::size_t slots,
std::vector<Complex>* qmf) override {
bank_.analyze_qmf(hops, slots, qmf);
}
void analyze_hybrid(const std::vector<Complex>& qmf, std::size_t slots,
std::vector<Complex>* hybrid) override {
bank_.analyze_hybrid(qmf, slots, hybrid);
}
void synthesize_hybrid(const std::vector<Complex>& hybrid, std::size_t slots,
std::vector<Complex>* qmf) override {
bank_.synthesize_hybrid(hybrid, slots, qmf);
}
void synthesize_qmf(const std::vector<Complex>& qmf, std::size_t slots,
std::vector<double>* 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<std::uint32_t>(RosellaFilterbank::kLatencySamples)
: static_cast<std::uint32_t>(kLatencySamples);
}
std::unique_ptr<RosellaBank> RosellaBank::create(RosellaBankKind kind, std::size_t channels) {
if (kind == RosellaBankKind::Captured) {
return std::make_unique<CapturedBank>(channels);
}
return std::make_unique<PublicBank>(channels);
}
} // namespace joc::hrtf
+50
View File
@@ -0,0 +1,50 @@
#pragma once
#include <cstddef>
#include <cstdint>
#include <memory>
#include <vector>
#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<RosellaBank> 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<double>& hops, std::size_t slots,
std::vector<Complex>* qmf) = 0;
virtual void analyze_hybrid(const std::vector<Complex>& qmf, std::size_t slots,
std::vector<Complex>* hybrid) = 0;
virtual void synthesize_hybrid(const std::vector<Complex>& hybrid, std::size_t slots,
std::vector<Complex>* qmf) = 0;
virtual void synthesize_qmf(const std::vector<Complex>& qmf, std::size_t slots,
std::vector<double>* hops) = 0;
};
} // namespace joc::hrtf
+15 -8
View File
@@ -12,7 +12,7 @@
#include <vector>
#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<double> field_left;
std::vector<double> field_right;
Core core;
std::unique_ptr<RosellaFilterbank> analysis_bank;
std::unique_ptr<RosellaFilterbank> synthesis_bank;
std::unique_ptr<RosellaBank> analysis_bank;
std::unique_ptr<RosellaBank> synthesis_bank;
timeline::OamdPositionTimeline timeline{timeline::kTimelineObjects};
std::vector<double> 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<std::int64_t>(RosellaFilterbank::kLatencySamples) -
static_cast<std::int64_t>(raw_output_samples);
const std::int64_t remaining =
static_cast<std::int64_t>(rosella_bank_latency(options.bank)) -
static_cast<std::int64_t>(raw_output_samples);
const std::size_t skip = static_cast<std::size_t>(
std::max<std::int64_t>(0, std::min<std::int64_t>(static_cast<std::int64_t>(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<RosellaFilterbank>(kSourceChannels);
impl_->synthesis_bank = std::make_unique<RosellaFilterbank>(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<double>*
std::uint32_t RosellaRuntime::finish_capacity(double tail_seconds) const {
const double samples = tail_seconds * 48000.0 +
static_cast<double>(RosellaFilterbank::kLatencySamples) +
static_cast<double>(rosella_bank_latency(impl_->options.bank)) +
static_cast<double>(kBlockSamples);
const double blocks = std::ceil(samples / static_cast<double>(kBlockSamples));
return static_cast<std::uint32_t>(blocks) * kBlockSamples;
+4
View File
@@ -6,6 +6,7 @@
#include <vector>
#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;
+3
View File
@@ -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);
}
+2
View File
@@ -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 {
+23 -2
View File
@@ -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<joc_validation_issue>* 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",