From 7cd5c660e440e1f4054e072a0b02e1f5bf608cd7 Mon Sep 17 00:00:00 2001 From: TheM14 Date: Wed, 28 Oct 2026 19:20:57 +0800 Subject: [PATCH] Apply each frame's own clipgain in the analysis scalar --- docs/math.en.md | 18 ++-- docs/math.md | 11 ++- src/joc_core/eac3joc_core.cpp | 11 +-- tests/test_core.cpp | 155 ++++++++++++++++++++++++++++++++++ 4 files changed, 178 insertions(+), 17 deletions(-) diff --git a/docs/math.en.md b/docs/math.en.md index b39c908..60ded1d 100644 --- a/docs/math.en.md +++ b/docs/math.en.md @@ -150,7 +150,12 @@ G_{\mathrm{clip}}= 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 @@ -238,8 +243,9 @@ $$ \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 -complex FIR are all gated by the **same switch** $\sigma(k)=1\iff k\in\{3,4\}$: +Ls and Rs take the same delay inside the surround path, whose delay line advances +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}= @@ -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 -channels and only take the ten-slot delay: channel identity affects metadata and the ADM -placement, not the DSP. These delays and filter histories are decoder state and cannot be -reset independently for every frame. +channels and only take the ten-slot delay: channel identity affects metadata and rendering, +not the DSP. These delays and filter histories are decoder state and cannot be reset +independently for every frame. ## 6. Object matrix diff --git a/docs/math.md b/docs/math.md index 6d482db..fbf3763 100644 --- a/docs/math.md +++ b/docs/math.md @@ -150,7 +150,10 @@ G_{\mathrm{clip}}= 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. 参数带展开与时间插值 @@ -239,8 +242,8 @@ $$ \qquad c\in\{L,R,C\}. $$ -Ls、Rs 的 10 时槽延迟、$b>0$ 的 $-j$ 旋转与 band-0 的 21-tap 复 FIR 由**同一个开关** -$\sigma(k)=1\iff k\in\{3,4\}$ 门控: +Ls、Rs 的 10 时槽延迟在环绕通路内完成,延迟线照常推进;$b>0$ 的 $-j$ 旋转与 band-0 的 +21-tap 复 FIR 由**同一个开关** $\sigma(k)=1\iff k\in\{3,4\}$ 门控: $$ \widehat X_{c,b,t}= @@ -252,7 +255,7 @@ X_{c,b,t-10}, & \text{其他情况}. $$ $N=7$ 时第 6、7 个核心声道(Lb/Rb 或 Tfl/Tfr)与前级相同,只做 10 时槽延迟: -通道身份只影响元数据与 ADM 落位,不进入 DSP。这些延迟和滤波历史属于解码状态, +通道身份只影响元数据与渲染,不进入 DSP。这些延迟和滤波历史属于解码状态, 不能按帧独立清零。 ## 6. 对象矩阵 diff --git a/src/joc_core/eac3joc_core.cpp b/src/joc_core/eac3joc_core.cpp index dc4d977..b92da56 100644 --- a/src/joc_core/eac3joc_core.cpp +++ b/src/joc_core/eac3joc_core.cpp @@ -174,10 +174,10 @@ public: } 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); process_objects(object_mask, n_bands, n_dpoints, slope_idx, offset_ts, - dq, clipgain, output_scale, output16); + dq, output_scale, output16); 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; // 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 // cancels the 1/16, so the net effect is a multiply by joc_clipgain; the // previous frame's scalar is the ramp start. - const float scalar = static_cast(phase_new * job_clipgain_); + const float scalar = static_cast(phase_new * clipgain); job_phase_old_ = analysis_phase_; if (job_phase_old_ <= 0.0f && job_phase_old_ != 0.0f) { job_phase_old_ = scalar; @@ -595,7 +595,6 @@ private: const uint8_t* slope_idx, const uint8_t* offset_ts, const double* dq, - const double clipgain, const float output_scale, float* output16) noexcept { @@ -615,7 +614,6 @@ private: job_slope_idx_ = slope_idx; job_offset_ts_ = offset_ts; job_dq_ = dq; - job_clipgain_ = clipgain; job_output_scale_ = output_scale; job_output16_ = output16; @@ -657,7 +655,6 @@ private: const uint8_t* job_slope_idx_ = nullptr; const uint8_t* job_offset_ts_ = nullptr; const double* job_dq_ = nullptr; - double job_clipgain_ = 1.0; float job_output_scale_ = 1.0f; float* job_output16_ = nullptr; diff --git a/tests/test_core.cpp b/tests/test_core.cpp index 7e7bc22..7f19d17 100644 --- a/tests/test_core.cpp +++ b/tests/test_core.cpp @@ -12,6 +12,7 @@ #include "adm/adm_metadata.h" #include "eac3_transport/eac3_reader.h" +#include "eac3joc_core.h" #include "foundation/bit_reader.h" #include "foundation/fs_utf8.h" #include "foundation/geometry.h" @@ -889,6 +890,157 @@ void test_stream_render_ahead() { } // 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 bed; + std::vector lfe; + std::vector n_bands; + std::vector n_dpoints; + std::vector slope; + std::vector offsets; + std::vector 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(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(sample) / 48000.0; + bed[sample] = static_cast(0.05 * std::sin(two_pi * 440.0 * t)); + lfe[sample] = static_cast(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* out) { + out->assign(static_cast(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 unity; + std::vector doubled; + auto render = [&in](double clipgain, std::vector* 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 changed; + std::vector held; + auto run = [&in](double second_gain, std::vector* out) { + ejoc_renderer_handle handle = ejoc_renderer_create(); + ejoc_renderer_set_threads(handle, 1); + std::vector 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(object) * EJOC_FRAME_SAMPLES + sample; + difference += std::fabs(static_cast(changed[index]) - held[index]); + energy += std::fabs(static_cast(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(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(EJOC_FRAME_SAMPLES) + sample; + tail = std::max(tail, std::fabs(static_cast(changed[index]) - + 2.0 * static_cast(held[index]))); + } + CHECK(tail < 1.0e-4); +} + +void test_clipgain_reset_clears_the_previous_gain() { + const ClipGainInputs in; + std::vector scratch; + std::vector after_reset; + std::vector 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() { test_sha256(); test_crc32_and_inflate(); @@ -912,6 +1064,9 @@ int main() { test_hrtf_cache_policy(); test_rosella_model_errors(); 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); return g_failures == 0 ? 0 : 1; }