MultibandCompressor.h

Go to the documentation of this file.

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "CrossoverFilter.h"
#include "Compressor.h"
#include "../Core/AudioBuffer.h"
#include "../Core/AudioSpec.h"
#include "../Core/DspMath.h"
#include "../Core/SimdOps.h"
#include "../Core/StateBlob.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cassert>
#include <cstddef>
#include <cstdint>
#include <cstdio>
#include <vector>
 
namespace dspark {
 
template <FloatType T, int MaxBands = 12>
class MultibandCompressor
{
    static_assert(MaxBands >= 2, "MultibandCompressor needs at least 2 bands (one split)");
 
public:
    // -- Lifecycle -----------------------------------------------------------
 
    void prepare(const AudioSpec& spec)
    {
        if (!spec.isValid()) return;
 
        prepared_.store(false, std::memory_order_relaxed);
 
        crossover_.prepare(spec);
        for (int b = 0; b < MaxBands; ++b)
        {
            bandBuffers_[b].resize(spec.numChannels, spec.maxBlockSize);
            compressors_[b].prepare(spec);
        }
        lastNumBands_ = MaxBands; // freshly prepared bands are all clean
 
        prepared_.store(true, std::memory_order_relaxed);
    }
 
    void processBlock(AudioBufferView<T> buffer) noexcept
    {
        if (!prepared_.load(std::memory_order_relaxed)) return;
 
        // Clamp to the per-band buffers' geometry (allocated for the prepared
        // spec): a wider or longer caller buffer must never index the band
        // buffers out of bounds below.
        const int nCh = std::min(buffer.getNumChannels(), bandBuffers_[0].getNumChannels());
        const int nS  = std::min(buffer.getNumSamples(), bandBuffers_[0].getNumSamples());
        if (nCh <= 0 || nS <= 0) return;
 
        // 1. Hand the crossover every band slot, truncated to this block. It
        // returns how many bands it actually wrote THIS block (its band count
        // is an atomic a concurrent setNumBands() may move between our read
        // and its own); summing only what was written keeps stale band
        // buffers out of the output.
        for (int b = 0; b < MaxBands; ++b)
            views_[b] = bandBuffers_[b].toView().getSubView(0, nS);
 
        // 2. Split into bands
        const int nb = crossover_.processBlock(buffer, views_.data(), MaxBands);
        if (nb < 2) return; // crossover inactive: input left untouched
 
        // 3. Bands (re-)enabled by a live band-count increase start clean:
        // their compressors would otherwise replay the gain reduction from
        // when they were last active (arbitrarily stale).
        if (nb > lastNumBands_)
            for (int b = lastNumBands_; b < nb; ++b)
                compressors_[b].reset();
        lastNumBands_ = nb;
 
        // 4. Compress each band independently.
        // IMPORTANT: bands are summed directly, so every band must share the
        // SAME latency. Compressors default to 0 lookahead (latency 0) and a
        // latency-free detector -> coherent sum. If you enable lookahead or
        // the Hilbert detector (feed-forward adds its compensation delay),
        // apply the SAME setting to every band via getBandCompressor(b); a
        // divergent per-band latency would phase-cancel at the crossover
        // regions (this class does not auto-delay-compensate).
        for (int b = 0; b < nb; ++b)
            compressors_[b].processBlock(views_[b]);
 
        // 5. Sum bands back into the output buffer (SIMD add kernels)
        for (int ch = 0; ch < nCh; ++ch)
        {
            T* const __restrict out = buffer.getChannel(ch);
            const T* const __restrict src0 = bandBuffers_[0].getChannel(ch);
 
            // Base copy (band 0)
            std::copy(src0, src0 + nS, out);
 
            // Accumulate remaining active bands
            for (int b = 1; b < nb; ++b)
                simd::add(out, bandBuffers_[b].getChannel(ch), nS);
        }
    }
 
    // -- Configuration -------------------------------------------------------
 
    void setNumBands(int n) noexcept
    {
        crossover_.setNumBands(std::clamp(n, 2, MaxBands));
    }
 
    void setCrossoverFrequency(int index, T freqHz) noexcept
    {
        crossover_.setCrossoverFrequency(index, freqHz);
    }
 
    void setOrder(int order) noexcept
    {
        crossover_.setOrder(order);
    }
 
    void setCrossoverMode(typename CrossoverFilter<T, MaxBands>::FilterMode mode) noexcept
    {
        crossover_.setFilterMode(mode);
    }
 
    // -- Per-band compressor access ------------------------------------------
 
    [[nodiscard]] Compressor<T>& getBandCompressor(int band) noexcept
    {
        assert(band >= 0 && band < MaxBands);
        int safeBand = std::clamp(band, 0, MaxBands - 1);
        return compressors_[safeBand];
    }
 
    [[nodiscard]] const Compressor<T>& getBandCompressor(int band) const noexcept
    {
        assert(band >= 0 && band < MaxBands);
        int safeBand = std::clamp(band, 0, MaxBands - 1);
        return compressors_[safeBand];
    }
 
    // -- Convenience per-band setters ----------------------------------------
 
    void setBandThreshold(int band, T dB) noexcept
    {
        if (band >= 0 && band < MaxBands)
            compressors_[band].setThreshold(dB);
    }
 
    void setBandRatio(int band, T ratio) noexcept
    {
        if (band >= 0 && band < MaxBands)
            compressors_[band].setRatio(ratio);
    }
 
    void setBandAttack(int band, T ms) noexcept
    {
        if (band >= 0 && band < MaxBands)
            compressors_[band].setAttack(ms);
    }
 
    void setBandRelease(int band, T ms) noexcept
    {
        if (band >= 0 && band < MaxBands)
            compressors_[band].setRelease(ms);
    }
 
    // -- Queries -------------------------------------------------------------
 
    [[nodiscard]] T getBandGainReductionDb(int band) const noexcept
    {
        if (band < 0 || band >= MaxBands) return T(0);
        return compressors_[band].getGainReductionDb();
    }
 
    [[nodiscard]] int getNumBands() const noexcept { return crossover_.getNumBands(); }
 
    [[nodiscard]] T getCrossoverFrequency(int index) const noexcept
    {
        return crossover_.getCrossoverFrequency(index);
    }
 
    [[nodiscard]] int getOrder() const noexcept { return crossover_.getOrder(); }
 
    [[nodiscard]] typename CrossoverFilter<T, MaxBands>::FilterMode getCrossoverMode() const noexcept
    {
        return crossover_.getFilterMode();
    }
 
    [[nodiscard]] int getLatency() const noexcept
    {
        // Crossover latency + the largest per-band compressor latency (bands
        // are expected to share the same lookahead/detector; see processBlock()).
        int maxBand = 0;
        const int nb = crossover_.getNumBands();
        for (int b = 0; b < nb && b < MaxBands; ++b)
            maxBand = std::max(maxBand, compressors_[b].getLatency());
        return crossover_.getLatency() + maxBand;
    }
 
    void reset() noexcept
    {
        crossover_.reset();
        for (auto& c : compressors_) c.reset();
        lastNumBands_ = MaxBands;
    }
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        StateWriter w(stateId("MBCP"), 1);
        const int n = crossover_.getNumBands();
        w.write("numBands", n);
        w.write("order", crossover_.getOrder());
        w.write("xoverMode", static_cast<int32_t>(crossover_.getFilterMode()));
        char key[24];
        for (int i = 0; i < n - 1; ++i)
        {
            std::snprintf(key, sizeof(key), "x%d", i);
            w.write(key, static_cast<float>(crossover_.getCrossoverFrequency(i)));
        }
        for (int i = 0; i < n; ++i)
        {
            std::snprintf(key, sizeof(key), "band%d", i);
            w.write(key, getBandCompressor(i).getState());
        }
        return w.blob();
    }
 
    bool setState(const uint8_t* data, size_t size)
    {
        StateReader r(data, size);
        if (!r.isValid() || r.processorId() != stateId("MBCP")) return false;
        const int n = std::clamp(r.read("numBands", 3), 2, MaxBands);
        setNumBands(n);
        setOrder(r.read("order", 24));
        setCrossoverMode(static_cast<typename CrossoverFilter<T, MaxBands>::FilterMode>(
            r.read("xoverMode", 0)));
        char key[24];
        for (int i = 0; i < n - 1; ++i)
        {
            std::snprintf(key, sizeof(key), "x%d", i);
            const float f = r.read(key, -1.0f);
            if (f > 0.0f) setCrossoverFrequency(i, static_cast<T>(f));
        }
        for (int i = 0; i < n; ++i)
        {
            std::snprintf(key, sizeof(key), "band%d", i);
            const auto nested = r.readBlob(key);
            if (!nested.empty())
                getBandCompressor(i).setState(nested.data(), nested.size());
        }
        return true;
    }
 
private:
    std::atomic<bool> prepared_ { false };
    int lastNumBands_ = MaxBands; 
    CrossoverFilter<T, MaxBands> crossover_;
    std::array<Compressor<T>, MaxBands> compressors_ {};
    std::array<AudioBuffer<T>, MaxBands> bandBuffers_ {};
    std::array<AudioBufferView<T>, MaxBands> views_ {}; 
};
 
} // namespace dspark