vocoder.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/ballistics_filter.hpp>
#include <pulp/signal/dc_blocker.hpp>
#include <pulp/signal/osc/va.hpp>
#include <pulp/signal/rng.hpp>
#include <pulp/signal/svf.hpp>
#include <pulp/signal/tpt_filter.hpp>
#include <pulp/signal/units.hpp>
#include <pulp/signal/vca.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace pulp::signal {

enum class VocoderCarrier : std::uint8_t {
    external,  
    internal,  
};

enum class VocoderWave : std::uint8_t { saw, pulse };

template <typename SampleType = float>
class VocoderT {
public:
    using CarrierSource = VocoderCarrier;
    using InternalWave = VocoderWave;
 
    // ── Structural constants ──────────────────────────────────────────────

    static constexpr int kMaxBands = 20;
    static constexpr int kMinBands = 10;
    static constexpr std::size_t kBandSlots = static_cast<std::size_t>(kMaxBands);

    static constexpr double kDcBlockHz = 10.0;

    static constexpr double kMaxSampleRate = 192000.0;
 
    // ── Band splitting ────────────────────────────────────────────────────

    static constexpr double kCascadeBWFactor = 0.6435942529055827;

    static constexpr double kPreEmphasis = 0.95;
 
    // ── Follower floors ───────────────────────────────────────────────────

    static constexpr double kRippleCycles = 2.0;

    static constexpr double kAttackCycles = 0.5;
 
    // ── Voiced / unvoiced detection ───────────────────────────────────────

    static constexpr double kZcrLo = 1500.0;
    static constexpr double kZcrHi = 4500.0;
    static constexpr double kZcrWindowMs = 20.0;

    static constexpr double kSibilanceCornerHz = 3500.0;

    static constexpr double kUvEnter = 0.6;
    static constexpr double kUvLeave = 0.4;

    static constexpr double kSensSpan = 0.5;

    static constexpr double kUvSmoothMs = 8.0;

    static constexpr double kEnergyEpsilon = 1e-12;
 
    // ── Carrier ───────────────────────────────────────────────────────────

    static constexpr double kUnvoicedNoise = 0.9;

    static constexpr std::uint32_t kNoiseSeed = 0x9E3779B9u;

    static constexpr double kDefaultPitchHz = 110.0;
    static constexpr double kMinPitchHz = 20.0;
    static constexpr double kMaxPitchHz = 2000.0;
 
    // ── Output ────────────────────────────────────────────────────────────

    static constexpr double kOutputHeadroomTrim = 0.5;

    static constexpr double kWorstCaseGain = 2.0;
 
    // ── Parameter bounds (the baked-params table, in one place) ───────────
 
    static constexpr double kFreqLoMinHz = 60.0;
    static constexpr double kFreqLoMaxHz = 400.0;
    static constexpr double kFreqHiMinHz = 3000.0;
    static constexpr double kFreqHiMaxHz = 12000.0;
    static constexpr double kAttackMinMs = 0.1;
    static constexpr double kAttackMaxMs = 50.0;
    static constexpr double kReleaseMinMs = 2.0;
    static constexpr double kReleaseMaxMs = 200.0;
    static constexpr double kPulseWidthMin = 0.05;
    static constexpr double kPulseWidthMax = 0.95;
    static constexpr double kFormantShiftMinSt = -24.0;
    static constexpr double kFormantShiftMaxSt = 24.0;
    static constexpr double kOutputTrimMinDb = -24.0;
    static constexpr double kOutputTrimMaxDb = 12.0;
 
    // ── Lifecycle ─────────────────────────────────────────────────────────
 
    VocoderT() { rebuild(); }

    void prepare(double sample_rate) {
        sample_rate_ = (std::isfinite(sample_rate) && sample_rate > 0.0) ? sample_rate : 48000.0;
        rebuild();
        reset();
    }
 
    void reset() {
        modulator_dc_.reset();
        carrier_dc_low_.reset();
        carrier_dc_high_.reset();
        sibilance_hp_.reset();
        pre_emphasis_state_ = 0.0;
        oscillator_.reset(0.0);
        rng_.reset();
 
        zcr_bits_.fill(0u);
        zcr_position_ = 0;
        zcr_count_ = 0;
        zcr_hz_ = 0.0;
        previous_sign_ = true;
 
        unvoiced_ = 0.0;
        unvoiced_latched_ = false;
        freeze_edge_ = false;
 
        for (std::size_t k = 0; k < kBandSlots; ++k) {
            bands_[k].analysis_a.reset();
            bands_[k].analysis_b.reset();
            bands_[k].synthesis_a.reset();
            bands_[k].synthesis_b.reset();
            bands_[k].follower.reset();
            bands_[k].analysis_out = 0.0;
            bands_[k].envelope = 0.0;
            bands_[k].held = 0.0;
            bands_[k].gain = 0.0;
        }
    }

    int latency_samples() const { return 0; }
 
    // ── Configuration ─────────────────────────────────────────────────────

    void set_band_count(int n) {
        band_count_ = std::clamp(n, kMinBands, kMaxBands);
        rebuild();
    }

    void set_band_range_hz(double f_lo, double f_hi) {
        if (!std::isfinite(f_lo) || !std::isfinite(f_hi)) return;
        freq_lo_ = std::clamp(f_lo, kFreqLoMinHz, kFreqLoMaxHz);
        freq_hi_ = std::clamp(f_hi, kFreqHiMinHz, kFreqHiMaxHz);
        if (freq_hi_ <= freq_lo_ * 2.0) freq_hi_ = freq_lo_ * 2.0;
        rebuild();
    }
 
    void set_carrier_source(CarrierSource source) { carrier_source_ = source; }
    CarrierSource carrier_source() const { return carrier_source_; }
 
    void set_internal_wave(InternalWave wave) {
        internal_wave_ = wave;
        oscillator_.set_shape(wave == InternalWave::saw ? osc::VaShape::saw
                                                        : osc::VaShape::square);
    }
 
    void set_internal_pulse_width(SampleType w01) {
        if (!std::isfinite(static_cast<double>(w01))) return;
        pulse_width_ = std::clamp(static_cast<double>(w01), kPulseWidthMin, kPulseWidthMax);
        oscillator_.set_pulse_width(pulse_width_);
    }

    void set_internal_pitch_hz(SampleType hz) {
        if (!std::isfinite(static_cast<double>(hz))) return;
        pitch_hz_ = std::clamp(static_cast<double>(hz), kMinPitchHz, kMaxPitchHz);
    }
 
    double internal_pitch_hz() const { return pitch_hz_; }
 
    void set_noise_mix(SampleType m01) { noise_mix_ = clamp_unit(m01, noise_mix_); }

    void set_attack_ms(SampleType ms) {
        if (!std::isfinite(static_cast<double>(ms))) return;
        attack_ms_ = std::clamp(static_cast<double>(ms), kAttackMinMs, kAttackMaxMs);
        apply_ballistics();
    }

    void set_release_ms(SampleType ms) {
        if (!std::isfinite(static_cast<double>(ms))) return;
        release_ms_ = std::clamp(static_cast<double>(ms), kReleaseMinMs, kReleaseMaxMs);
        apply_ballistics();
    }
 
    void set_unvoiced_sensitivity(SampleType s01) {
        unvoiced_sensitivity_ = clamp_unit(s01, unvoiced_sensitivity_);
    }
 
    void set_sibilance_mix(SampleType m01) { sibilance_mix_ = clamp_unit(m01, sibilance_mix_); }

    void set_formant_shift_semitones(SampleType st) {
        if (!std::isfinite(static_cast<double>(st))) return;
        formant_shift_st_ =
            std::clamp(static_cast<double>(st), kFormantShiftMinSt, kFormantShiftMaxSt);
        update_shift();
    }

    void set_formant_freeze(bool on) { freeze_ = on; }
    bool formant_freeze() const { return freeze_; }
 
    void set_output_trim_db(SampleType db) {
        if (!std::isfinite(static_cast<double>(db))) return;
        output_trim_db_ =
            std::clamp(static_cast<double>(db), kOutputTrimMinDb, kOutputTrimMaxDb);
        output_trim_ = units::db_to_linear(output_trim_db_);
    }

    void set_dry_wet(SampleType w01) { dry_wet_ = clamp_unit(w01, dry_wet_); }
 
    // ── Audio ─────────────────────────────────────────────────────────────
 
    void process(SampleType modulator, SampleType carrier_ext, SampleType& out_dry) {
        // Both inputs feed recursive filters. A non-finite sample is a recovery
        // boundary: reject it before it can latch the filterbank, oscillator,
        // voicing detector, or freeze state.
        if (!std::isfinite(static_cast<double>(modulator)) ||
            !std::isfinite(static_cast<double>(carrier_ext))) {
            reset();
            out_dry = SampleType{0};
            return;
        }
        const double modulator_in = static_cast<double>(modulator);
        const double blocked = modulator_dc_.process(modulator_in);
 
        // Pre-emphasis lifts the upper bands so consonants earn a fair envelope
        // level. Modulator only — never the carrier, never the output.
        const double emphasised = blocked - kPreEmphasis * pre_emphasis_state_;
        pre_emphasis_state_ = blocked;
 
        update_zero_crossings(blocked);
 
        // ── Analysis bank ─────────────────────────────────────────────────
        double energy_total = 0.0;
        double energy_high = 0.0;
        for (std::size_t k = 0; k < active_; ++k) {
            Band& band = bands_[k];
            const double filtered =
                band.analysis_b.process(band.analysis_a.process(emphasised)) * band.normalisation;
            band.analysis_out = filtered;
            band.envelope = band.follower.process(filtered);
            energy_total += band.envelope;
            if (band.center_hz > kSibilanceCornerHz) energy_high += band.envelope;
        }
 
        // ── Voiced / unvoiced ─────────────────────────────────────────────
        const double zcr_norm =
            std::clamp((zcr_hz_ - kZcrLo) / (kZcrHi - kZcrLo), 0.0, 1.0);
        const double hf_ratio = energy_high / (energy_total + kEnergyEpsilon);
        const double raw = std::clamp(0.5 * zcr_norm + 0.5 * hf_ratio -
                                          (0.5 - unvoiced_sensitivity_) * kSensSpan,
                                      0.0, 1.0);
        // Schmitt on the raw decision, then a one-pole on the latched result.
        // That order is what lets `u` actually reach 0 and 1: the raw cue tops
        // out well below 1 even for full-band noise (its high-frequency energy
        // ratio is bounded by how much of the bank sits above the sibilance
        // corner), so smoothing the raw value would leave `u` permanently
        // mid-scale. The hysteresis decides, and the one-pole keeps the
        // decision from arriving as a click.
        if (raw > kUvEnter) unvoiced_latched_ = true;
        else if (raw < kUvLeave) unvoiced_latched_ = false;
        unvoiced_ += unvoiced_coefficient_ * ((unvoiced_latched_ ? 1.0 : 0.0) - unvoiced_);
 
        // ── Freeze, then shift ────────────────────────────────────────────
        // Freeze first so a frozen vowel can still be swept with the formant
        // control — the "hold a vowel and morph ooh→aah" gesture needs the
        // shift to act on held levels, not to be locked out by them.
        if (freeze_ && !freeze_edge_)
            for (std::size_t k = 0; k < active_; ++k) bands_[k].held = bands_[k].envelope;
        freeze_edge_ = freeze_;
 
        for (std::size_t k = 0; k < active_; ++k)
            source_[k] = freeze_ ? bands_[k].held : bands_[k].envelope;
        for (std::size_t j = 0; j < active_; ++j)
            bands_[j].gain = shifted_level(static_cast<double>(j) - shift_bands_);
 
        // ── Carrier ───────────────────────────────────────────────────────
        // One noise draw per call, unconditionally, so the generator's position
        // does not depend on the carrier source or on the voicing decision.
        // A render is then bit-identical for a given (params, input) no matter
        // which branches ran.
        const double noise = rng_.next_bipolar<double>();
        const double increment = pitch_hz_ / sample_rate_;
        const double oscillator = oscillator_.next(increment);
 
        const double raw_carrier = carrier_source_ == CarrierSource::internal
                                       ? oscillator
                                       : static_cast<double>(carrier_ext);
 
        // Internal: noise blends into the whole carrier. External: the carrier
        // is the user's and stays intact in the lower bands, with noise
        // substituted only above the sibilance corner so consonants read
        // without smearing the pad the caller chose.
        const double unvoiced_noise = unvoiced_ * kUnvoicedNoise;
        const double internal_noise = std::max(noise_mix_, unvoiced_noise);
        const bool internal = carrier_source_ == CarrierSource::internal;
        const double mixed_low =
            internal ? (1.0 - internal_noise) * raw_carrier + internal_noise * noise : raw_carrier;
        const double mixed_high =
            internal ? mixed_low : (1.0 - unvoiced_noise) * raw_carrier + unvoiced_noise * noise;
 
        // DC-block the SUMMED carrier, after the blend rather than before it —
        // a pulse carrier's DC moves with its width, and the noise term needs
        // the same treatment as the oscillator it replaces. Both blockers run
        // every sample whatever the source, so neither one's state depends on
        // which branch was taken.
        const double carrier_low = carrier_dc_low_.process(mixed_low);
        const double carrier_high = carrier_dc_high_.process(mixed_high);
 
        // ── Synthesis bank ────────────────────────────────────────────────
        double sum = 0.0;
        for (std::size_t k = 0; k < active_; ++k) {
            Band& band = bands_[k];
            const double input = band.center_hz > kSibilanceCornerHz ? carrier_high : carrier_low;
            const double filtered =
                band.synthesis_b.process(band.synthesis_a.process(input)) * band.normalisation;
            sum += vca_.process(filtered, band.gain);
        }
 
        double wet = kOutputHeadroomTrim * sum;
        // Gated by `u` as well as by the user control: an ungated sibilance
        // path leaks breath through every sustained vowel.
        wet += sibilance_mix_ * unvoiced_ * sibilance_hp_.process_highpass(blocked);
        wet *= output_trim_;
 
        const double output = (1.0 - dry_wet_) * blocked + dry_wet_ * wet;
        if (!std::isfinite(output)) {
            reset();
            out_dry = SampleType{0};
            return;
        }
        out_dry = static_cast<SampleType>(output);
    }
 
    // ── Observability ─────────────────────────────────────────────────────
    //
    // The quantities this module is judged on — band centres, per-band
    // envelopes, the voicing decision, the gains actually applied — are not
    // visible in the output, so they are exposed. The acceptance suite still
    // proves the bank against audio (it measures both filterbanks with coherent
    // DFTs of the accessor's own output), rather than letting the module agree
    // with itself.
 
    int band_count() const { return band_count_; }
    double band_ratio() const { return ratio_; }
    double band_q() const { return q_band_; }
    double section_q() const { return q_section_; }
    double bands_per_octave() const { return 1.0 / std::log2(ratio_); }
    double shift_bands() const { return shift_bands_; }
 
    double band_center_hz(int k) const { return in_range(k) ? bands_[index(k)].center_hz : 0.0; }
    double attack_eff_ms(int k) const { return in_range(k) ? bands_[index(k)].attack_ms : 0.0; }
    double release_eff_ms(int k) const { return in_range(k) ? bands_[index(k)].release_ms : 0.0; }

    double analysis_band(int k) const { return in_range(k) ? bands_[index(k)].analysis_out : 0.0; }

    double band_envelope(int k) const { return in_range(k) ? bands_[index(k)].envelope : 0.0; }

    double synthesis_gain(int k) const { return in_range(k) ? bands_[index(k)].gain : 0.0; }

    double unvoiced() const { return unvoiced_; }

    double zcr_hz() const { return zcr_hz_; }

    double zcr_window_ms() const {
        return 1000.0 * static_cast<double>(zcr_length_) / sample_rate_;
    }
 
private:
    struct Band {
        SvfT<double> analysis_a;
        SvfT<double> analysis_b;
        SvfT<double> synthesis_a;
        SvfT<double> synthesis_b;
        BallisticsFilterT<double> follower;
        double center_hz = 0.0;
        double normalisation = 1.0;
        double attack_ms = 0.0;
        double release_ms = 0.0;
        double analysis_out = 0.0;
        double envelope = 0.0;
        double held = 0.0;
        double gain = 0.0;
    };
 
    static constexpr std::size_t kZcrMaxSamples =
        static_cast<std::size_t>(40.0 * 0.001 * kMaxSampleRate);  // widest window, highest rate
    static constexpr std::size_t kZcrWords = (kZcrMaxSamples + 63u) / 64u;
 
    bool in_range(int k) const { return k >= 0 && k < band_count_; }
    static std::size_t index(int k) { return static_cast<std::size_t>(k); }
 
    double clamp_unit(SampleType v, double fallback) const {
        const double d = static_cast<double>(v);
        return std::isfinite(d) ? std::clamp(d, 0.0, 1.0) : fallback;
    }

    void rebuild() {
        active_ = static_cast<std::size_t>(band_count_);
        const double span = std::max(freq_hi_ / freq_lo_, 1.0000001);
        ratio_ = std::pow(span, 1.0 / static_cast<double>(band_count_ - 1));
 
        const double root = std::sqrt(ratio_);
        q_band_ = 1.0 / (root - 1.0 / root);
        q_section_ = kCascadeBWFactor * q_band_;
 
        // A centre above Nyquist is not a band, so the span is held below it.
        // At every rate the parameter table allows this is inactive; it exists
        // so a 22.05 kHz render degrades to a narrower bank instead of to
        // garbage coefficients.
        const double ceiling = 0.45 * sample_rate_;
        for (std::size_t k = 0; k < kBandSlots; ++k) {
            Band& band = bands_[k];
            const double nominal = freq_lo_ * std::pow(ratio_, static_cast<double>(k));
            band.center_hz = std::min(nominal, ceiling);
            band.normalisation = 1.0 / (q_section_ * q_section_);
            for (auto* section : {&band.analysis_a, &band.analysis_b, &band.synthesis_a,
                                  &band.synthesis_b}) {
                section->set_mode(SvfT<double>::Mode::bandpass);
                section->set_sample_rate(sample_rate_);
                section->set_resonance(q_section_);
                section->set_frequency(band.center_hz);
            }
            band.follower.set_mode(BallisticsFilterT<double>::Mode::peak);
            band.follower.prepare(sample_rate_);
        }
 
        apply_ballistics();
        update_shift();
 
        sibilance_hp_.prepare(sample_rate_);
        sibilance_hp_.set_cutoff(kSibilanceCornerHz);
 
        const double dc_pole = std::exp(-2.0 * kPiConstant * kDcBlockHz / sample_rate_);
        modulator_dc_.set_pole(dc_pole);
        carrier_dc_low_.set_pole(dc_pole);
        carrier_dc_high_.set_pole(dc_pole);
 
        zcr_length_ = static_cast<std::size_t>(
            std::llround(std::clamp(kZcrWindowMs * 0.001 * sample_rate_, 1.0,
                                    static_cast<double>(kZcrMaxSamples))));
 
        // 10→90 % time on the voicing decision, using the SAME constant the
        // composed follower uses, so both "10→90 % time" figures in this file
        // mean exactly the same thing rather than differing by a rounding.
        unvoiced_coefficient_ =
            1.0 - std::exp(-kTenToNinety / (kUvSmoothMs * 0.001 * sample_rate_));
 
        oscillator_.set_shape(internal_wave_ == InternalWave::saw ? osc::VaShape::saw
                                                                 : osc::VaShape::square);
        oscillator_.set_pulse_width(pulse_width_);
        vca_.set_response(VcaResponse::linear);
        output_trim_ = units::db_to_linear(output_trim_db_);
    }

    void apply_ballistics() {
        for (std::size_t k = 0; k < kBandSlots; ++k) {
            Band& band = bands_[k];
            const double center = std::max(band.center_hz, 1.0);
            band.attack_ms = std::max(attack_ms_, 1000.0 * kAttackCycles / center);
            band.release_ms = std::max(release_ms_, 1000.0 * kRippleCycles / center);
            band.follower.set_attack_ms(band.attack_ms);
            band.follower.set_release_ms(band.release_ms);
        }
    }

    void update_shift() {
        shift_bands_ = formant_shift_st_ / (12.0 * std::log2(ratio_));
    }

    double shifted_level(double x) const {
        const double floor_x = std::floor(x);
        const auto lower = static_cast<long long>(floor_x);
        const double frac = x - floor_x;
        const auto count = static_cast<long long>(active_);
        const double a = (lower >= 0 && lower < count) ? source_[static_cast<std::size_t>(lower)] : 0.0;
        const double b =
            (lower + 1 >= 0 && lower + 1 < count) ? source_[static_cast<std::size_t>(lower + 1)] : 0.0;
        return a + frac * (b - a);
    }

    void update_zero_crossings(double x) {
        const bool sign = x >= 0.0;
        const bool crossing = sign != previous_sign_;
        previous_sign_ = sign;
 
        const std::size_t word = zcr_position_ >> 6;
        const std::uint64_t bit = std::uint64_t{1} << (zcr_position_ & 63u);
        if ((zcr_bits_[word] & bit) != 0u) --zcr_count_;
        if (crossing) {
            zcr_bits_[word] |= bit;
            ++zcr_count_;
        } else {
            zcr_bits_[word] &= ~bit;
        }
        if (++zcr_position_ >= zcr_length_) zcr_position_ = 0;
 
        zcr_hz_ = static_cast<double>(zcr_count_) * sample_rate_ /
                  static_cast<double>(zcr_length_);
    }

    static constexpr double kTenToNinety = 2.2;
 
    static constexpr double kPiConstant = 3.14159265358979323846;
 
    std::array<Band, kBandSlots> bands_{};
    std::array<double, kBandSlots> source_{};
    std::array<std::uint64_t, kZcrWords> zcr_bits_{};
 
    DcBlocker<double> modulator_dc_{};
    DcBlocker<double> carrier_dc_low_{};
    DcBlocker<double> carrier_dc_high_{};
    TptFilterT<double> sibilance_hp_{};
    osc::VaOscillator oscillator_{};
    VcaT<double> vca_{};
    Xorshift32 rng_{kNoiseSeed};
 
    double sample_rate_ = 48000.0;
    double freq_lo_ = 120.0;
    double freq_hi_ = 7000.0;
    double ratio_ = 1.0;
    double q_band_ = 1.0;
    double q_section_ = 1.0;
 
    double attack_ms_ = 1.5;
    double release_ms_ = 15.0;
    double noise_mix_ = 0.15;
    double unvoiced_sensitivity_ = 0.5;
    double sibilance_mix_ = 0.35;
    double formant_shift_st_ = 0.0;
    double shift_bands_ = 0.0;
    double output_trim_db_ = 0.0;
    double output_trim_ = 1.0;
    double dry_wet_ = 1.0;
    double pitch_hz_ = kDefaultPitchHz;
    double pulse_width_ = 0.5;
 
    double pre_emphasis_state_ = 0.0;
    double unvoiced_ = 0.0;
    double unvoiced_coefficient_ = 0.0;
    double zcr_hz_ = 0.0;
 
    std::size_t active_ = 16;
    std::size_t zcr_length_ = 1;
    std::size_t zcr_position_ = 0;
    std::size_t zcr_count_ = 0;
 
    int band_count_ = 16;
    CarrierSource carrier_source_ = CarrierSource::internal;
    InternalWave internal_wave_ = InternalWave::saw;
    bool previous_sign_ = true;
    bool unvoiced_latched_ = false;
    bool freeze_ = false;
    bool freeze_edge_ = false;
};
 
using Vocoder = VocoderT<float>;
using Vocoder64 = VocoderT<double>;
 
}  // namespace pulp::signal