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
+476 -33

No files matched your search

+1
View File
@@ -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
+13 -5
View File
@@ -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/<name>.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 `<output>.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
+11 -5
View File
@@ -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`。
## 扬声器布局与声道顺序
+7 -3
View File
@@ -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
+16
View File
@@ -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 调度:
+31 -7
View File
@@ -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
+12 -3
View File
@@ -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 <cache_dir>/<name>.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;
+1 -1
View File
@@ -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
+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
+14 -7
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,8 +1139,12 @@ 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) -
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),
@@ -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",
+31
View File
@@ -927,6 +927,36 @@ std::vector<float> drive_objects16_stream(const std::vector<float>& 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<joc_validation_issue> 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();
+143
View File
@@ -1,8 +1,12 @@
#include <algorithm>
#include <cmath>
#include <cstdint>
#include <cstdio>
#include <memory>
#include <vector>
#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 <typename Value, typename Expected>
@@ -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<Complex> qmf;
std::vector<Complex> hybrid;
std::vector<Complex> folded;
std::vector<double> time;
};
BankTrace run_bank(RosellaBank& bank, const std::vector<double>& hops,
const std::vector<Complex>& synthetic, const std::vector<std::size_t>& chunks,
std::size_t channels) {
BankTrace trace;
std::size_t first = 0;
for (const std::size_t count : chunks) {
const std::vector<double> part_hops(hops.begin() + first * channels * 64,
hops.begin() + (first + count) * channels * 64);
const std::vector<Complex> part_synthetic(
synthetic.begin() + first * channels * 77,
synthetic.begin() + (first + count) * channels * 77);
std::vector<Complex> qmf, hybrid, folded;
std::vector<double> 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<double> hops(slots * channels * 64);
for (std::size_t index = 0; index < hops.size(); ++index) {
hops[index] = (static_cast<int>((index * 37 + 11) % 257) - 128) / 128.0;
}
std::vector<Complex> synthetic(slots * channels * 77);
for (std::size_t index = 0; index < synthetic.size(); ++index) {
synthetic[index] = Complex((static_cast<int>((index * 17 + 3) % 101) - 50) / 64.0,
(static_cast<int>((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<Complex> public_hybrid;
std::vector<Complex> captured_hybrid;
for (const RosellaBankKind kind : {RosellaBankKind::Public, RosellaBankKind::Captured}) {
std::vector<Complex> 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<RosellaBank> selected = RosellaBank::create(kind, channels);
std::vector<Complex> 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<RosellaBank> 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<RosellaBank> 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<double> impulse(slots * 64, 0.0);
impulse[0] = 1.0;
std::vector<Complex> qmf, hybrid;
std::vector<double> 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<std::size_t>(peak - output.begin());
}
void test_bank_latency_and_reset() {
check(joc::hrtf::rosella_bank_latency(RosellaBankKind::Public) ==
static_cast<std::uint32_t>(joc::hrtf::kLatencySamples),
"public latency is the public filterbank latency");
check(joc::hrtf::rosella_bank_latency(RosellaBankKind::Captured) ==
static_cast<std::uint32_t>(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<RosellaBank> 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;
}