Apply each frame's own clipgain in the analysis scalar
ci / ubuntu-latest (push) Failing after 12s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s

This commit is contained in:
TheM14 committed 2026-10-28 19:20:57 +08:00
1 parent 55f14667d2
commit 7cd5c660e4
4 files changed
+178 -17

No files matched your search

+12 -6
View File
@@ -150,7 +150,12 @@ G_{\mathrm{clip}}=
1+\frac{y}{32}2^{x-4}. 1+\frac{y}{32}2^{x-4}.
$$ $$
It is applied to object PCM after inverse QMF and does not apply to LFE. It is folded into the analysis-side scalar $S=\frac{1}{16}G_{\mathrm{clip}}$, which multiplies
every core-bed sample before the QMF analysis; the $\times16$ after the object inverse QMF cancels the
$1/16$, so the net effect is a multiply by $G_{\mathrm{clip}}$ and the $[-1,1]$ clamp sits **after** the
gain. The scalar keeps two per-frame slots: the first 256 samples of a frame ramp linearly from the
previous frame's value to this frame's value and the rest stays constant, and the first frame after a
reset takes the new value directly. LFE bypasses this scalar.
## 3. Parameter-band expansion and time interpolation ## 3. Parameter-band expansion and time interpolation
@@ -238,8 +243,9 @@ $$
\qquad c\in\{L,R,C\}. \qquad c\in\{L,R,C\}.
$$ $$
For Ls and Rs the ten-slot delay, the $-j$ rotation for $b>0$ and the band-0 21-tap Ls and Rs take the same delay inside the surround path, whose delay line advances
complex FIR are all gated by the **same switch** $\sigma(k)=1\iff k\in\{3,4\}$: regardless; the $-j$ rotation for $b>0$ and the band-0 21-tap complex FIR are gated by
the **same switch** $\sigma(k)=1\iff k\in\{3,4\}$:
$$ $$
\widehat X_{c,b,t}= \widehat X_{c,b,t}=
@@ -251,9 +257,9 @@ X_{c,b,t-10}, & \text{otherwise}.
$$ $$
For $N=7$ the sixth and seventh core channels (Lb/Rb or Tfl/Tfr) behave like the front For $N=7$ the sixth and seventh core channels (Lb/Rb or Tfl/Tfr) behave like the front
channels and only take the ten-slot delay: channel identity affects metadata and the ADM channels and only take the ten-slot delay: channel identity affects metadata and rendering,
placement, not the DSP. These delays and filter histories are decoder state and cannot be not the DSP. These delays and filter histories are decoder state and cannot be reset
reset independently for every frame. independently for every frame.
## 6. Object matrix ## 6. Object matrix
+7 -4
View File
@@ -150,7 +150,10 @@ G_{\mathrm{clip}}=
1+\frac{y}{32}2^{x-4}. 1+\frac{y}{32}2^{x-4}.
$$ $$
它在对象 inverse QMF 之后作用于对象 PCM,不作用于 LFE。 它并入分析端标量 $S=\frac{1}{16}G_{\mathrm{clip}}$,乘在核心 bed 的每个采样上(QMF 分析之前);
对象 inverse QMF 之后的 $\times16$ 抵消 $1/16$,净效果是乘 $G_{\mathrm{clip}}$,因此钳位 $[-1,1]$
处在增益**之后**。标量按帧保留两个槽,本帧前 256 个采样从上一帧值线性过渡到本帧值、之后为常数,
复位后的第一帧直接取新值。LFE 走旁通通路,不参与该标量。
## 3. 参数带展开与时间插值 ## 3. 参数带展开与时间插值
@@ -239,8 +242,8 @@ $$
\qquad c\in\{L,R,C\}. \qquad c\in\{L,R,C\}.
$$ $$
Ls、Rs 的 10 时槽延迟、$b>0$ 的 $-j$ 旋转与 band-0 的 21-tap 复 FIR 由**同一个开关** Ls、Rs 的 10 时槽延迟在环绕通路内完成,延迟线照常推进;$b>0$ 的 $-j$ 旋转与 band-0 的
$\sigma(k)=1\iff k\in\{3,4\}$ 门控: 21-tap 复 FIR 由**同一个开关** $\sigma(k)=1\iff k\in\{3,4\}$ 门控:
$$ $$
\widehat X_{c,b,t}= \widehat X_{c,b,t}=
@@ -252,7 +255,7 @@ X_{c,b,t-10}, & \text{其他情况}.
$$ $$
$N=7$ 时第 6、7 个核心声道(Lb/Rb 或 Tfl/Tfr)与前级相同,只做 10 时槽延迟: $N=7$ 时第 6、7 个核心声道(Lb/Rb 或 Tfl/Tfr)与前级相同,只做 10 时槽延迟:
通道身份只影响元数据与 ADM 落位,不进入 DSP。这些延迟和滤波历史属于解码状态, 通道身份只影响元数据与渲染,不进入 DSP。这些延迟和滤波历史属于解码状态,
不能按帧独立清零。 不能按帧独立清零。
## 6. 对象矩阵 ## 6. 对象矩阵
+4 -7
View File
@@ -174,10 +174,10 @@ public:
} }
std::memset(output16, 0, sizeof(float) * EJOC_OUTPUT_CHANNELS * EJOC_FRAME_SAMPLES); std::memset(output16, 0, sizeof(float) * EJOC_OUTPUT_CHANNELS * EJOC_FRAME_SAMPLES);
analysis(bed_planar, phase_new); analysis(bed_planar, phase_new, clipgain);
render_lfe(lfe, output_scale, output16); render_lfe(lfe, output_scale, output16);
process_objects(object_mask, n_bands, n_dpoints, slope_idx, offset_ts, process_objects(object_mask, n_bands, n_dpoints, slope_idx, offset_ts,
dq, clipgain, output_scale, output16); dq, output_scale, output16);
return 0; return 0;
} }
@@ -378,13 +378,13 @@ private:
} }
} }
void analysis(const float* bed_planar, const float phase_new) noexcept { void analysis(const float* bed_planar, const float phase_new, const double clipgain) noexcept {
job_bed_ = bed_planar; job_bed_ = bed_planar;
// Analysis-side scalar = the structural 1/16 times this frame's clipgain. // Analysis-side scalar = the structural 1/16 times this frame's clipgain.
// clipgain enters the analysis at this stage and the x16 at the output // clipgain enters the analysis at this stage and the x16 at the output
// cancels the 1/16, so the net effect is a multiply by joc_clipgain; the // cancels the 1/16, so the net effect is a multiply by joc_clipgain; the
// previous frame's scalar is the ramp start. // previous frame's scalar is the ramp start.
const float scalar = static_cast<float>(phase_new * job_clipgain_); const float scalar = static_cast<float>(phase_new * clipgain);
job_phase_old_ = analysis_phase_; job_phase_old_ = analysis_phase_;
if (job_phase_old_ <= 0.0f && job_phase_old_ != 0.0f) { if (job_phase_old_ <= 0.0f && job_phase_old_ != 0.0f) {
job_phase_old_ = scalar; job_phase_old_ = scalar;
@@ -595,7 +595,6 @@ private:
const uint8_t* slope_idx, const uint8_t* slope_idx,
const uint8_t* offset_ts, const uint8_t* offset_ts,
const double* dq, const double* dq,
const double clipgain,
const float output_scale, const float output_scale,
float* output16) noexcept { float* output16) noexcept {
@@ -615,7 +614,6 @@ private:
job_slope_idx_ = slope_idx; job_slope_idx_ = slope_idx;
job_offset_ts_ = offset_ts; job_offset_ts_ = offset_ts;
job_dq_ = dq; job_dq_ = dq;
job_clipgain_ = clipgain;
job_output_scale_ = output_scale; job_output_scale_ = output_scale;
job_output16_ = output16; job_output16_ = output16;
@@ -657,7 +655,6 @@ private:
const uint8_t* job_slope_idx_ = nullptr; const uint8_t* job_slope_idx_ = nullptr;
const uint8_t* job_offset_ts_ = nullptr; const uint8_t* job_offset_ts_ = nullptr;
const double* job_dq_ = nullptr; const double* job_dq_ = nullptr;
double job_clipgain_ = 1.0;
float job_output_scale_ = 1.0f; float job_output_scale_ = 1.0f;
float* job_output16_ = nullptr; float* job_output16_ = nullptr;
+155
View File
@@ -12,6 +12,7 @@
#include "adm/adm_metadata.h" #include "adm/adm_metadata.h"
#include "eac3_transport/eac3_reader.h" #include "eac3_transport/eac3_reader.h"
#include "eac3joc_core.h"
#include "foundation/bit_reader.h" #include "foundation/bit_reader.h"
#include "foundation/fs_utf8.h" #include "foundation/fs_utf8.h"
#include "foundation/geometry.h" #include "foundation/geometry.h"
@@ -889,6 +890,157 @@ void test_stream_render_ahead() {
} // namespace } // namespace
// The JOC clipgain is the analysis-side scalar's per-frame factor: it scales the
// frame that carries it, ramps over that frame's first 256 samples, starts from
// the frame's own value after a reset, and never reaches LFE.
struct ClipGainInputs {
std::vector<float> bed;
std::vector<float> lfe;
std::vector<std::uint8_t> n_bands;
std::vector<std::uint8_t> n_dpoints;
std::vector<std::uint8_t> slope;
std::vector<std::uint8_t> offsets;
std::vector<double> dq;
ClipGainInputs()
: bed(EJOC_CORE_CHANNELS * EJOC_FRAME_SAMPLES, 0.0f),
lfe(EJOC_FRAME_SAMPLES, 0.0f),
n_bands(EJOC_MAX_OBJECTS, 0),
n_dpoints(EJOC_MAX_OBJECTS, 0),
slope(EJOC_MAX_OBJECTS, 0),
offsets(EJOC_MAX_OBJECTS * EJOC_MAX_DPOINTS, 0),
dq(static_cast<std::size_t>(EJOC_MAX_OBJECTS) * EJOC_MAX_DPOINTS *
EJOC_MAX_CORE_CHANNELS * EJOC_MAX_PARAMETER_BANDS,
0.0) {
const double two_pi = 6.283185307179586476925286766559;
for (int sample = 0; sample < EJOC_FRAME_SAMPLES; ++sample) {
const double t = static_cast<double>(sample) / 48000.0;
bed[sample] = static_cast<float>(0.05 * std::sin(two_pi * 440.0 * t));
lfe[sample] = static_cast<float>(0.02 * std::sin(two_pi * 55.0 * t));
}
// Object 0 passes the first core channel through one parameter band.
n_bands[0] = 1;
n_dpoints[0] = 1;
dq[0] = 1.0;
}
};
bool clipgain_process(ejoc_renderer_handle handle, const ClipGainInputs& in, double clipgain,
std::vector<float>* out) {
out->assign(static_cast<std::size_t>(EJOC_OUTPUT_CHANNELS) * EJOC_FRAME_SAMPLES, 0.0f);
return ejoc_renderer_process(handle, in.bed.data(), in.lfe.data(), EJOC_CORE_CHANNELS, 0u, 1u,
in.n_bands.data(), in.n_dpoints.data(), in.slope.data(),
in.offsets.data(), in.dq.data(), clipgain, 0.0625f, 1.0f,
out->data()) == 0;
}
void test_clipgain_first_frame_uses_its_own_gain() {
const ClipGainInputs in;
std::vector<float> unity;
std::vector<float> doubled;
auto render = [&in](double clipgain, std::vector<float>* out) {
ejoc_renderer_handle handle = ejoc_renderer_create();
ejoc_renderer_set_threads(handle, 1);
const bool ok = clipgain_process(handle, in, clipgain, out);
ejoc_renderer_destroy(handle);
return ok;
};
CHECK(render(1.0, &unity));
CHECK(render(2.0, &doubled));
float peak = 0.0f;
bool scaled = true;
for (int sample = 0; sample < EJOC_FRAME_SAMPLES; ++sample) {
const float value = unity[EJOC_FRAME_SAMPLES + sample]; // object 0 is channel 1
peak = std::max(peak, std::fabs(value));
if (doubled[EJOC_FRAME_SAMPLES + sample] != 2.0f * value) {
scaled = false;
}
}
// A fresh handle takes the current gain with no transition.
CHECK(peak > 1.0e-3f);
CHECK(scaled);
// LFE bypasses the scalar, so its samples are bit-identical.
CHECK(std::memcmp(unity.data(), doubled.data(), sizeof(float) * EJOC_FRAME_SAMPLES) == 0);
}
void test_clipgain_change_applies_to_the_current_frame() {
const ClipGainInputs in;
std::vector<float> changed;
std::vector<float> held;
auto run = [&in](double second_gain, std::vector<float>* out) {
ejoc_renderer_handle handle = ejoc_renderer_create();
ejoc_renderer_set_threads(handle, 1);
std::vector<float> first;
const bool ok = clipgain_process(handle, in, 1.0, &first) &&
clipgain_process(handle, in, second_gain, out);
ejoc_renderer_destroy(handle);
return ok;
};
CHECK(run(2.0, &changed));
CHECK(run(1.0, &held));
// The change has to land in the frame carrying it; a one-frame-late gain
// would make these two frames identical.
double difference = 0.0;
double energy = 0.0;
for (int object = 1; object < EJOC_OUTPUT_CHANNELS; ++object) {
for (int sample = 0; sample < EJOC_FRAME_SAMPLES; ++sample) {
const std::size_t index =
static_cast<std::size_t>(object) * EJOC_FRAME_SAMPLES + sample;
difference += std::fabs(static_cast<double>(changed[index]) - held[index]);
energy += std::fabs(static_cast<double>(held[index]));
}
}
CHECK(difference > 0.05 * energy);
// The analysis delay lines and the QMF windows hold the new gain back by
// about 1400 samples, so the start of the frame still carries the old value
// and the end is scaled by the new one.
bool head_intact = true;
for (int sample = 0; sample < 256; ++sample) {
const std::size_t index = static_cast<std::size_t>(EJOC_FRAME_SAMPLES) + sample;
if (changed[index] != held[index]) {
head_intact = false;
}
}
CHECK(head_intact);
double tail = 0.0;
for (int sample = 1504; sample < EJOC_FRAME_SAMPLES; ++sample) {
const std::size_t index = static_cast<std::size_t>(EJOC_FRAME_SAMPLES) + sample;
tail = std::max(tail, std::fabs(static_cast<double>(changed[index]) -
2.0 * static_cast<double>(held[index])));
}
CHECK(tail < 1.0e-4);
}
void test_clipgain_reset_clears_the_previous_gain() {
const ClipGainInputs in;
std::vector<float> scratch;
std::vector<float> after_reset;
std::vector<float> fresh;
ejoc_renderer_handle handle = ejoc_renderer_create();
ejoc_renderer_set_threads(handle, 1);
CHECK(clipgain_process(handle, in, 3.0, &scratch));
CHECK(clipgain_process(handle, in, 3.0, &scratch));
CHECK(ejoc_renderer_reset(handle) == 0);
CHECK(clipgain_process(handle, in, 1.0, &after_reset));
ejoc_renderer_destroy(handle);
ejoc_renderer_handle pristine = ejoc_renderer_create();
ejoc_renderer_set_threads(pristine, 1);
CHECK(clipgain_process(pristine, in, 1.0, &fresh));
ejoc_renderer_destroy(pristine);
// No gain state may survive the reset: the first frame must match a fresh
// renderer instead of ramping down from the previous 3x.
CHECK(after_reset.size() == fresh.size());
CHECK(std::memcmp(after_reset.data(), fresh.data(),
sizeof(float) * after_reset.size()) == 0);
}
int main() { int main() {
test_sha256(); test_sha256();
test_crc32_and_inflate(); test_crc32_and_inflate();
@@ -912,6 +1064,9 @@ int main() {
test_hrtf_cache_policy(); test_hrtf_cache_policy();
test_rosella_model_errors(); test_rosella_model_errors();
test_stream_render_ahead(); test_stream_render_ahead();
test_clipgain_first_frame_uses_its_own_gain();
test_clipgain_change_applies_to_the_current_frame();
test_clipgain_reset_clears_the_previous_gain();
std::printf("%d checks, %d failure(s)\n", g_checks, g_failures); std::printf("%d checks, %d failure(s)\n", g_checks, g_failures);
return g_failures == 0 ? 0 : 1; return g_failures == 0 ? 0 : 1;
} }