TransientDesigner.h

Go to the documentation of this file.

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/DspMath.h"
#include "../Core/AudioSpec.h"
#include "../Core/AudioBuffer.h"
#include "../Core/DenormalGuard.h"
#include "../Core/StateBlob.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <vector>
 
namespace dspark {
 
template <FloatType T>
class TransientDesigner
{
public:
    ~TransientDesigner() = default; // non-virtual: leaf class (no virtual dispatch)
 
    // -- Lifecycle -----------------------------------------------------------
 
    void prepare(const AudioSpec& spec) noexcept
    {
        if (!spec.isValid()) return;
        prepare(spec.sampleRate);
    }
 
    void prepare(double sampleRate) noexcept
    {
        if (!std::isfinite(sampleRate) || sampleRate <= 0.0) return;
        sampleRate_ = sampleRate;
        updateCoefficients();
        reset();
    }
 
    void processBlock(AudioBufferView<T> buffer) noexcept
    {
        DenormalGuard guard;
        const int nCh = std::min(buffer.getNumChannels(), kMaxChannels);
        const int nS  = buffer.getNumSamples();
 
        const T attAmt = attackAmount_.load(std::memory_order_relaxed);
        const T susAmt = sustainAmount_.load(std::memory_order_relaxed);
        const bool odr = outputDepRecovery_.load(std::memory_order_relaxed);
 
        // Constants for VCA log-domain emulation
        constexpr T noiseFloor = T(1e-5);     // -100 dB floor avoids log(0) and denormals
        constexpr T maxGainLog = T(2.77258);  // approx +24dB max gain change
 
        // Outer loop: channels (state stays in registers)
        for (int ch = 0; ch < nCh; ++ch)
        {
            T* const channelData = buffer.getChannel(ch);
            T fast = envFast_[ch];
            T slow = envSlow_[ch];
            T lastOut = lastOutput_[ch];
 
            // Inner loop: serial envelope recursion per sample
            for (int i = 0; i < nS; ++i)
            {
                T sample = channelData[i];
                T absSample = std::abs(sample) + noiseFloor;
 
                // 1. Fast envelope (Peak)
                T fastCoeff = (absSample > fast) ? fastAttackCoeff_ : fastReleaseCoeff_;
                fast += fastCoeff * (absSample - fast);
 
                // 2. Slow envelope (Sustain/RMS tracker)
                T currentSlowRelCoeff = slowReleaseCoeff_;
 
                if (odr)
                {
                    // Corrected ODR: Higher output = LARGER coefficient = Faster release
                    T modifier = T(1) + std::abs(lastOut) * T(2.0);
                    currentSlowRelCoeff = std::min(fastReleaseCoeff_, currentSlowRelCoeff * modifier);
                }
 
                T slowCoeff = (absSample > slow) ? slowAttackCoeff_ : currentSlowRelCoeff;
                slow += slowCoeff * (absSample - slow);
 
                // 3. Log-domain VCA computation (fastLog/fastExp: relative
                // error < 2e-7 - far below audibility, ~3x faster than libm)
                T diffLog = fastLog(fast) - fastLog(slow);
 
                // Attack kicks in when fast > slow (diffLog > 0). Sustain when slow > fast (diffLog < 0)
                T gainLog = (diffLog > T(0)) ? (diffLog * attAmt) : (-diffLog * susAmt);
 
                gainLog = std::clamp(gainLog, -maxGainLog, maxGainLog);
 
                T gain = fastExp(gainLog);
 
                lastOut = sample * gain;
                channelData[i] = lastOut;
            }
 
            // Save state
            envFast_[ch] = fast;
            envSlow_[ch] = slow;
            lastOutput_[ch] = lastOut;
        }
    }
 
    // -- Parameters ----------------------------------------------------------
    // All setters ignore non-finite values: a NaN amount used to storm the
    // output for as long as it was published, and under output-dependent
    // recovery the NaN last-output silently switched the slow envelope to the
    // fast release, leaving the envelope history diverged after recovery.
 
    void setAttack(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        attackAmount_.store(std::clamp(amount, T(-100), T(100)) / T(100), std::memory_order_relaxed);
    }
 
    void setSustain(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        sustainAmount_.store(std::clamp(amount, T(-100), T(100)) / T(100), std::memory_order_relaxed);
    }
 
    void setOutputDepRecovery(bool enabled) noexcept
    {
        outputDepRecovery_.store(enabled, std::memory_order_relaxed);
    }
 
    void setCharacter(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        T c = std::clamp(amount, T(-1), T(1));
        attackAmount_.store(c, std::memory_order_relaxed);
        sustainAmount_.store(-c * T(0.5), std::memory_order_relaxed);
    }
 
    void reset() noexcept
    {
        envFast_.fill(T(1e-5)); // Init to noise floor
        envSlow_.fill(T(1e-5));
        lastOutput_.fill(T(0));
    }
 
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        StateWriter w(stateId("TDES"), 1);
        // static_cast<float>: the blob stores float (percent units), and
        // StateWriter's overload set is ambiguous for a double argument.
        w.write("attack", static_cast<float>(attackAmount_.load(std::memory_order_relaxed)) * 100.0f);
        w.write("sustain", static_cast<float>(sustainAmount_.load(std::memory_order_relaxed)) * 100.0f);
        w.write("outputDep", outputDepRecovery_.load(std::memory_order_relaxed));
        return w.blob();
    }
 
    bool setState(const uint8_t* data, size_t size)
    {
        StateReader r(data, size);
        if (!r.isValid() || r.processorId() != stateId("TDES")) return false;
        setAttack(static_cast<T>(r.read("attack", 0.0f)));
        setSustain(static_cast<T>(r.read("sustain", 0.0f)));
        setOutputDepRecovery(r.read("outputDep", false));
        return true;
    }
 
private:
    static constexpr int kMaxChannels = 16;
 
    void updateCoefficients() noexcept
    {
        if (!(sampleRate_ > 0.0)) return;
        T fs = static_cast<T>(sampleRate_);
        fastAttackCoeff_  = T(1) - std::exp(T(-1) / (fs * T(0.0001)));
        fastReleaseCoeff_ = T(1) - std::exp(T(-1) / (fs * T(0.005)));
        slowAttackCoeff_  = T(1) - std::exp(T(-1) / (fs * T(0.020)));
        slowReleaseCoeff_ = T(1) - std::exp(T(-1) / (fs * T(0.200)));
    }
 
    double sampleRate_ = 48000.0;
 
    // Atomic parameters (Lock-free thread safety)
    std::atomic<T> attackAmount_ { T(0) };
    std::atomic<T> sustainAmount_ { T(0) };
    std::atomic<bool> outputDepRecovery_ { false };
 
    // Envelope coefficients (written by prepare/updateCoefficients on the
    // setup thread, read by the audio thread)
    T fastAttackCoeff_ = T(0), fastReleaseCoeff_ = T(0);
    T slowAttackCoeff_ = T(0), slowReleaseCoeff_ = T(0);
 
    // Per-channel state (scalar recursion; no SIMD kernel touches these)
    std::array<T, kMaxChannels> envFast_ {};
    std::array<T, kMaxChannels> envSlow_ {};
    std::array<T, kMaxChannels> lastOutput_ {};
};
 
} // namespace dspark