transient_phase_policy.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/checked_allocation.hpp>
 
#include <algorithm>
#include <cassert>
#include <cmath>
#include <complex>
#include <cstring>
#include <vector>
 
namespace pulp::signal {
 
template <typename SampleType = float>
class TransientPhasePolicyT {
public:
    struct Config {
        int fft_size = 2048;
        float sensitivity = 1.0f;
        float strength = 1.0f;
        int refractory_frames = 3;
    };
 
    static bool checked_retained_bytes(int fft_size, std::uint64_t target_max_bytes,
                                       std::uint64_t& bytes) noexcept {
        CheckedRetainedByteCharge charge(target_max_bytes);
        if (!charge.add<SampleType>(static_cast<std::uint64_t>(fft_size / 2 + 1)))
            return false;
        bytes = charge.total();
        return true;
    }

    void prepare(const Config& config) {
        assert(config.fft_size >= 256 && (config.fft_size & (config.fft_size - 1)) == 0);
        config_ = config;
        num_bins_ = config.fft_size / 2 + 1;
        prev_mag_.assign(static_cast<size_t>(num_bins_), SampleType{0});
        reset();
    }
 
    void reset() {
        std::fill(prev_mag_.begin(), prev_mag_.end(), SampleType{0});
        std::memset(flux_history_, 0, sizeof(flux_history_));
        history_count_ = 0;
        history_pos_ = 0;
        refractory_remaining_ = 0;
    }

    SampleType analyze(const std::complex<SampleType>* const* frames, int channels, int num_bins) {
        assert(num_bins == num_bins_);
        double flux = 0.0;
        double total = 0.0;
        for (int k = 0; k < num_bins_; ++k) {
            std::complex<SampleType> sum(SampleType{0}, SampleType{0});
            for (int ch = 0; ch < channels; ++ch) sum += frames[ch][k];
            const SampleType mag = std::abs(sum);
            const SampleType d = mag - prev_mag_[static_cast<size_t>(k)];
            if (d > SampleType{0}) flux += static_cast<double>(d);
            total += static_cast<double>(mag);
            prev_mag_[static_cast<size_t>(k)] = mag;
        }
 
        flux_history_[history_pos_] = static_cast<SampleType>(flux);
        history_pos_ = (history_pos_ + 1) % kHistory;
        if (history_count_ < kHistory) ++history_count_;
 
        if (history_count_ < 9 || total < 1e-9)
            return SampleType{0};
 
        SampleType sorted[kHistory];
        std::copy(flux_history_, flux_history_ + history_count_, sorted);
        std::nth_element(sorted, sorted + history_count_ / 2, sorted + history_count_);
        const double median = static_cast<double>(sorted[history_count_ / 2]);
 
        // Median-relative AND a significant fraction of frame energy.
        const bool transient =
            flux * static_cast<double>(config_.sensitivity) > 3.0 * median
            && flux > 0.05 * total;
 
        // Refractory gate: count every analyzed frame down, and only let a fresh
        // transient fire once the guard has elapsed. This collapses a hit's
        // multi-frame decay into a SINGLE reset at its onset instead of one reset
        // per ringing frame — the over-firing that bled the synthesis-phase lead.
        if (refractory_remaining_ > 0) --refractory_remaining_;
        if (transient && refractory_remaining_ == 0) {
            refractory_remaining_ = config_.refractory_frames;
            return static_cast<SampleType>(config_.strength);
        }
        return SampleType{0};
    }
 
private:
    static constexpr int kHistory = 32;
 
    Config config_;
    int num_bins_ = 0;
    std::vector<SampleType> prev_mag_;
    SampleType flux_history_[kHistory] = {};
    int history_count_ = 0;
    int history_pos_ = 0;
    int refractory_remaining_ = 0;  // frames left in the post-reset suppression window
};
 
using TransientPhasePolicy = TransientPhasePolicyT<float>;
using TransientPhasePolicy64 = TransientPhasePolicyT<double>;
 
} // namespace pulp::signal