membrane.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/signal/decay_envelope.hpp>
#include <pulp/signal/drum/voice.hpp>
#include <pulp/signal/lowpass_gate.hpp>
#include <pulp/signal/modal_bank.hpp>
#include <pulp/signal/noise_source.hpp>
#include <pulp/signal/tpt_filter.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <vector>
 
namespace pulp::signal::drum {

enum class MembraneExciter {
    noise_burst,
    pluck,
};

class MembraneVoice : public Voice {
public:
    static constexpr int mode_count = 6;

    static constexpr double membrane_ratios[mode_count] = {1.0,   1.5933, 2.1355,
                                                            2.2954, 2.6531, 2.9173};
 
    MembraneVoice() {
        VelocityResponse r;
        r.level_db = 16.0f;
        // A harder strike tightens the head slightly and excites more of the
        // high modes -- both are brightness rather than level.
        r.bend_octaves = 0.15f;
        r.brightness_octaves = 1.6f;
        set_velocity_response(r);
    }

    void set_tune_hz(double hz) { tune_hz_ = std::clamp(hz, 20.0, 2000.0); }

    void set_structure(double amount) { structure_ = std::clamp(amount, 0.0, 1.0); }

    void set_stretch(double amount) { stretch_ = std::clamp(amount, 0.0, 1.0); }

    void set_decay_ms(double ms) { decay_ms_ = std::clamp(ms, 20.0, 8000.0); }

    void set_damping(double amount) { damping_ = std::clamp(amount, 0.0, 1.0); }

    void set_brightness(double amount) { brightness_ = std::clamp(amount, 0.0, 1.0); }

    void set_position(double position) { position_ = std::clamp(position, 0.02, 0.5); }

    void set_spread(double amount) { spread_ = std::clamp(amount, 0.0, 1.0); }

    void set_exciter_ms(double ms) { exciter_ms_ = std::clamp(ms, 0.1, 50.0); }
    void set_exciter_cutoff_hz(double hz) {
        exciter_cutoff_hz_ = std::clamp(hz, 100.0, 18000.0);
    }
    void set_exciter(MembraneExciter exciter) { exciter_ = exciter; }

    void set_sub_level(double level) { sub_level_ = std::max(level, 0.0); }
    void set_air_level(double level) { air_level_ = std::max(level, 0.0); }
    void set_air_decay_ms(double ms) { air_decay_ms_ = std::clamp(ms, 1.0, 500.0); }
    void set_click_level(double level) { click_level_ = std::max(level, 0.0); }
    void set_click_decay_ms(double ms) {
        click_decay_ms_ = std::clamp(ms, 0.1, 50.0);
    }

    double mode_gain_energy() const { return mode_gain_energy_; }

    LowpassGate& gate() { return gate_; }
    OutputStage& output() { return output_; }
    const OutputStage& output() const { return output_; }
    OutputStage* output_stage() noexcept override { return &output_; }
    int latency_samples() const noexcept override {
        return output_.latency_samples();
    }
    OutputOversampling output_oversampling() const noexcept override {
        return output_.oversampling();
    }
    void set_output_oversampling(OutputOversampling factor) override {
        output_.set_oversampling(factor);
    }
 
protected:
    void on_prepare(double sample_rate) override {
        noise_.prepare(sample_rate);
        bank_.prepare(sample_rate, mode_count, 1);
        exciter_env_.set_sample_rate(sample_rate);
        gate_env_.set_sample_rate(sample_rate);
        sub_env_.set_sample_rate(sample_rate);
        air_env_.set_sample_rate(sample_rate);
        click_env_.set_sample_rate(sample_rate);
        exciter_filter_.prepare(static_cast<float>(sample_rate));
        air_filter_.prepare(static_cast<float>(sample_rate));
        click_filter_.prepare(static_cast<float>(sample_rate));
        gate_.set_sample_rate(sample_rate);
        output_.prepare(sample_rate);
        scratch_.assign(kBlock, 0.0f);
        modes_.fill(ModalMode{});
    }
 
    void on_reset() override {
        bank_.reset();
        exciter_env_.reset();
        gate_env_.reset();
        sub_env_.reset();
        air_env_.reset();
        click_env_.reset();
        exciter_filter_.reset();
        air_filter_.reset();
        click_filter_.reset();
        gate_.reset();
        output_.reset();
        noise_.reset();
        air_noise_.set_seed(NoiseSource::default_seed ^ 0xA17F32D1u);
        click_noise_.set_seed(NoiseSource::default_seed ^ 0xC11C74E5u);
        air_noise_.reset();
        click_noise_.reset();
        pluck_pending_ = false;
        sub_phase_ = 0.0;
        applied_fundamental_hz_ = tune_hz_;
        level_ = 0.0;
    }
 
    void on_note_on(float velocity) override {
        // The modal bank carries its resonator state across strikes, so the
        // shared output history belongs to the same continuing body.
        output_.trigger();
        const auto& response = velocity_response();
        velocity_gain_ = response.gain(velocity);
        const double tension = std::exp2(response.bend(velocity));
        applied_fundamental_hz_ = tune_hz_ * tension;
        const double exciter_scale = response.brightness_scale(velocity);
 
        noise_.reset();
        air_noise_.reset();
        click_noise_.reset();
        build_modes(tension);
        bank_.set_modes(std::span<const ModalMode>(modes_.data(), mode_count));
 
        exciter_filter_.reset();
        exciter_filter_.set_cutoff(static_cast<float>(
            std::min(exciter_cutoff_hz_ * exciter_scale, 0.49 * sample_rate())));
 
        pluck_pending_ = exciter_ == MembraneExciter::pluck;
        if (exciter_ == MembraneExciter::noise_burst) {
            exciter_env_.set_attack_ms(0.0);
            exciter_env_.set_decay_time_constant_ms(exciter_ms_);
            exciter_env_.trigger();
        } else {
            exciter_env_.reset();
        }
 
        sub_phase_ = 0.0;
        sub_env_.reset();
        sub_env_.set_attack_ms(0.0);
        sub_env_.set_decay_t60_ms(decay_ms_);
        if (sub_level_ > 0.0) sub_env_.trigger();
 
        air_filter_.reset();
        air_filter_.set_cutoff(static_cast<float>(
            std::min(4000.0 * exciter_scale, 0.49 * sample_rate())));
        air_env_.reset();
        air_env_.set_attack_ms(0.0);
        air_env_.set_decay_time_constant_ms(air_decay_ms_);
        if (air_level_ > 0.0) air_env_.trigger();
 
        click_filter_.reset();
        click_filter_.set_cutoff(static_cast<float>(
            std::min(8000.0 * exciter_scale, 0.49 * sample_rate())));
        click_env_.reset();
        click_env_.set_attack_ms(0.0);
        click_env_.set_decay_time_constant_ms(click_decay_ms_);
        if (click_level_ > 0.0) click_env_.trigger();
 
        // The gate's control is a fast one-shot: it opens on the strike and the
        // vactrol's own slow fall does the rest, which is the point of using a
        // gate rather than an envelope.
        gate_env_.set_attack_ms(0.5);
        gate_env_.set_decay_t60_ms(decay_ms_ * 0.5);
        gate_env_.trigger();
        level_ = 1.0;
    }
 
    bool on_is_active() const override {
        return pluck_pending_ || exciter_env_.is_active() || gate_env_.is_active() ||
               sub_env_.is_active() || air_env_.is_active() ||
               click_env_.is_active() ||
               level_ > kSilenceLevel || output_.has_tail();
    }
 
    void render_add(float* out, int num_samples) override {
        int done = 0;
        while (done < num_samples) {
            const int n = std::min<int>(kBlock, num_samples - done);
 
            // The bank renders a block at a time, so the exciter is built into
            // a scratch first rather than sample-interleaved.
            for (int i = 0; i < n; ++i) {
                double burst = 0.0;
                if (pluck_pending_) {
                    burst = 1.0;
                    pluck_pending_ = false;
                } else if (exciter_env_.is_active()) {
                    burst = static_cast<double>(noise_.white()) *
                            exciter_env_.process();
                }
                scratch_[static_cast<std::size_t>(i)] =
                    exciter_filter_.process_lowpass(static_cast<float>(burst));
            }
 
            std::fill(body_.begin(), body_.begin() + n, 0.0f);
            bank_.process_add(scratch_.data(), body_.data(), n);
 
            for (int i = 0; i < n; ++i) {
                const double gated = gate_.process(body_[static_cast<std::size_t>(i)],
                                                   gate_env_.process());
                double layers = 0.0;
                if (sub_env_.is_active()) {
                    sub_phase_ +=
                        0.5 * applied_fundamental_hz_ / sample_rate();
                    if (sub_phase_ >= 1.0) sub_phase_ -= std::floor(sub_phase_);
                    layers += std::sin(2.0 * 3.14159265358979323846 * sub_phase_) *
                              sub_env_.process() * sub_level_;
                }
                if (air_env_.is_active()) {
                    layers += static_cast<double>(air_filter_.process_highpass(
                                  air_noise_.white())) *
                              air_env_.process() * air_level_;
                }
                if (click_env_.is_active()) {
                    layers += static_cast<double>(click_filter_.process_lowpass(
                                  click_noise_.white())) *
                              click_env_.process() * click_level_;
                }
                const double shaped =
                    output_.process(static_cast<float>(gated + layers)) * velocity_gain_;
                out[done + i] += static_cast<float>(shaped);
                level_ = std::max(std::fabs(shaped), level_ * kLevelDecay);
            }
            done += n;
        }
    }
 
private:
    static constexpr int kBlock = 128;
    static constexpr double kSilenceLevel = 1e-5;
    static constexpr double kLevelDecay = 0.9995;
 
    void build_modes(double tension) {
        // A deterministic detune per mode, drawn from the voice's own generator
        // so a hit stays reproducible.
        double raw_gain_energy = 0.0;
        for (int m = 0; m < mode_count; ++m) {
            const double harmonic = static_cast<double>(m + 1);
            const double ratio = harmonic + structure_ * (membrane_ratios[m] - harmonic);
            // Stiffness sharpens the upper modes progressively, which is what
            // separates a plate from an ideal membrane.
            const double stiffened =
                ratio * (1.0 + stretch_ * 0.02 * static_cast<double>(m * m));
            const double detune = 1.0 + spread_ * 0.03 * static_cast<double>(noise_.white());
            const double f = tune_hz_ * tension * stiffened * detune;
 
            // Upper modes die faster. At damping 0 they all ring equally, which
            // is a bell; a drum needs the spread.
            const double decay_scale =
                std::pow(0.55, damping_ * static_cast<double>(m));
 
            // Strike position is a comb: a mode with a node at the strike point
            // simply is not excited.
            const double comb = std::fabs(
                std::sin(3.14159265358979323846 * static_cast<double>(m + 1) * position_));
            const double rolloff =
                std::pow(0.6 + 0.4 * brightness_, static_cast<double>(m));
 
            const double raw_gain = comb * rolloff;
            raw_gain_energy += raw_gain * raw_gain;
            modes_[static_cast<std::size_t>(m)] = ModalMode{
                static_cast<float>(std::min(f, 0.49 * sample_rate())),
                static_cast<float>(0.001 * decay_ms_ * decay_scale),
                static_cast<float>(raw_gain),
            };
        }
 
        // Changing strike position selects modes; it must not also act as a
        // hidden master level. Preserve the energy of six equal 1/N gains.
        const double target_energy = 1.0 / static_cast<double>(mode_count);
        const double scale =
            raw_gain_energy > 0.0 ? std::sqrt(target_energy / raw_gain_energy) : 0.0;
        mode_gain_energy_ = 0.0;
        for (auto& mode : modes_) {
            mode.gain = static_cast<float>(static_cast<double>(mode.gain) * scale);
            mode_gain_energy_ +=
                static_cast<double>(mode.gain) * static_cast<double>(mode.gain);
        }
    }
 
    double tune_hz_ = 90.0;
    double structure_ = 1.0;
    double stretch_ = 0.0;
    double decay_ms_ = 700.0;
    double damping_ = 0.5;
    double brightness_ = 0.5;
    double position_ = 0.28;
    double spread_ = 0.1;
    double exciter_ms_ = 1.5;
    double exciter_cutoff_hz_ = 6000.0;
    MembraneExciter exciter_ = MembraneExciter::noise_burst;
    double sub_level_ = 0.0;
    double air_level_ = 0.0;
    double air_decay_ms_ = 20.0;
    double click_level_ = 0.0;
    double click_decay_ms_ = 2.0;
 
    NoiseSource noise_;
    NoiseSource air_noise_;
    NoiseSource click_noise_;
    ModalBank bank_;
    DecayEnvelope64 exciter_env_;
    DecayEnvelope64 gate_env_;
    DecayEnvelope64 sub_env_;
    DecayEnvelope64 air_env_;
    DecayEnvelope64 click_env_;
    TptFilter exciter_filter_;
    TptFilter air_filter_;
    TptFilter click_filter_;
    LowpassGate gate_;
    OutputStage output_;
 
    std::array<ModalMode, mode_count> modes_{};
    std::vector<float> scratch_;
    std::array<float, kBlock> body_{};
 
    double velocity_gain_ = 1.0;
    double mode_gain_energy_ = 0.0;
    double sub_phase_ = 0.0;
    double applied_fundamental_hz_ = 100.0;
    bool pluck_pending_ = false;
    double level_ = 0.0;
};
 
}  // namespace pulp::signal::drum