forge_effect_modulation_catalog.hpp

Go to the documentation of this file.

#pragma once
 
// Modulation — bake-layer catalog nodes.
//
// The home for the modulation family: effects whose character comes from
// something moving underneath the signal rather than from a nonlinearity. It
// opens with the single-sideband frequency shifter and is named for the family
// rather than for that one member, because the chorus, phaser and vibrato
// lineages that follow share this file's conventions — a moving delay or phase
// relationship, a rate or offset in real units, a wet path that a mix control
// blends against dry — and differ only in what is moving and how far.
//
// TRUE STEREO, two ports in and two out as ONE logical wire. The shifter is not
// a per-rail memoryless function: `stereo_split` mode drives the left channel
// up and the right down from a SHARED carrier, so the two rails must be
// processed in the same call to stay phase-locked. Instancing it dual-mono
// would silently reduce that mode to two identical up-shifts — which sounds
// fine right up until someone reaches for the stereo control and nothing
// happens.
//
// EVERY CHOICE ON THE SHIFTER IS AN INJECTABLE PARAM, none is a
// registration-time realization, and that is worth stating because it is the
// opposite of the saturator's arrangement. The rule is that anything which
// changes reported latency must be frozen at registration, because a node whose
// latency moves under the audio thread breaks the host's delay compensation.
// The shifter reports zero latency in every mode: the Hilbert network is IIR
// allpass with no bulk delay, the mode switch only changes the sign and scale
// applied to the quadrature term, and the feedback delay lives inside a loop
// rather than in the signal's path to the output. Nothing there can move
// latency, so nothing there has to be baked in.
//
// The three lineages that follow are NOT all like that, and the differences are
// the interesting part of this file:
//
//   - **Chorus** freezes its VOICING, its Juno mode and its BBD colour stage at
//     registration. Latency is zero for all of them, so the latency rule is not
//     what forces it — topology is. The four voicings differ in VOICE COUNT and
//     in the mix matrix that combines them, and `set_voicing` rewinds every LFO
//     phase and overwrites the rate. See `chorus::make_chorus_node`.
//   - **Phaser** freezes its STAGE COUNT, for the same reason the diode-bridge
//     compressor freezes its detector position: the module's own published notch
//     law takes the stage count as an argument, so the measured response is a
//     different function per count, not a different value of one function.
//   - **Vibrato** ships THREE nodes rather than one with a mode knob, because
//     the three engines are different signal-theoretic objects — one modulates a
//     delay (real, frequency-independent pitch modulation) and two modulate
//     allpass corners (frequency-DEPENDENT apparent pitch, plus moving notches).
//     A mode knob would imply they are points on a continuum.
//
// And the delay vibrato is the one member in this file where the LATENCY rule
// bites: its reported latency is `ceil(base_delay + amplitude)` and the
// amplitude scales as `depth / rate`, so it moves by a factor of ~280 across the
// DSP's declared ranges. Its rate FLOOR is therefore a registration-time
// argument, exactly like the VCA compressor's lookahead — see
// `vibrato::make_delay_vibrato_node`.
//
// TWO SETTERS IN THIS FAMILY MUST NOT BE CALLED PER SAMPLE, and both would fail
// silently rather than loudly. `ChorusEnsembleT::set_voicing` /
// `set_juno_mode` rewind every LFO phase, so injecting either every sample
// freezes the modulation at phase zero — a chorus that does not chorus.
// `DelayVibratoT::set_delay_ms` / `set_fade_in_ms` re-arm the onset envelope and
// zero its depth, so injecting them every sample pins the depth envelope at zero
// — a vibrato that does not vibrate. The first pair is handled by making them
// realizations; the second by applying them only when the value actually
// changes. Both are the kind of bug that renders as "the effect is subtle".
//
// The one thing that IS fixed at registration is the feedback line's capacity,
// and it is fixed by the DSP header's `kMaxLoopMs` rather than by a node-local
// ceiling: `prepare()` sizes for it, so the `fb_delay_ms` knob's top is the
// largest delay the node can ever hold without allocating.
//
// WET AND DRY BOTH: unlike a compressor, whose output IS the processed signal,
// a frequency shifter is routinely run as a blend — the classic barberpole
// setting is a wet spiral sitting under a dry source. The DSP block owns the
// mix so that `mix < 100 %` blends dry against the whole wet chain including
// the recirculated tail, which is what makes turning the control down attenuate
// the barberpole rather than disable it.
 
#include <pulp/host/custom_node_type.hpp>
 
#include <vector>
 
#include <pulp/signal/chorus_family.hpp>
#include <pulp/signal/frequency_shifter_ssb.hpp>
#include <pulp/signal/phaser_stages.hpp>
#include <pulp/signal/vibrato.hpp>
 
#include <cmath>
#include <string>
 
namespace pulp::host::modulation {
 
// ── Stable type ids ───────────────────────────────────────────────────────
inline constexpr const char* kSsbFrequencyShifterTypeId = "modulation.frequency_shifter_ssb";
 
// ── Injectable param ids ──────────────────────────────────────────────────
// Node-local; the framework namespaces per node so two nodes never collide.
inline constexpr state::ParamID kShiftHz = 1;       // Hz, signed: + up, − down
inline constexpr state::ParamID kFeedback = 2;      // 0..kMaxFeedback
inline constexpr state::ParamID kFeedbackDelayMs = 3;  // ms
inline constexpr state::ParamID kMix = 4;           // %
inline constexpr state::ParamID kShiftMode = 5;     // stepped 0..3, see below
inline constexpr state::ParamID kStereoSpread = 6;  // %

inline constexpr float kModeUp = 0.0f;
inline constexpr float kModeDown = 1.0f;
inline constexpr float kModeDualMono = 2.0f;
inline constexpr float kModeStereoSplit = 3.0f;

float ssb_frequency_shifter_worst_case_gain();

inline signal::FrequencyShiftMode mode_from_param(float value) {
    const int step = static_cast<int>(std::lround(value));
    switch (step) {
        case 1: return signal::FrequencyShiftMode::down;
        case 2: return signal::FrequencyShiftMode::dual_mono;
        case 3: return signal::FrequencyShiftMode::stereo_split;
        default: return signal::FrequencyShiftMode::up;
    }
}

CustomNodeType make_frequency_shifter_node();
 
// ═══════════════════════════════════════════════════════════════════════════
//  Chorus — four voicings of one ensemble engine
// ═══════════════════════════════════════════════════════════════════════════
 
namespace chorus {
 
using Engine = signal::ChorusEnsemble;
using Voicing = Engine::Voicing;
using JunoMode = Engine::JunoMode;
 
// ── Injectable param ids ──────────────────────────────────────────────────
inline constexpr state::ParamID kRateHz = 1;       // Hz
inline constexpr state::ParamID kDepth = 2;        // %
inline constexpr state::ParamID kMix = 3;          // %
inline constexpr state::ParamID kStereoWidth = 4;  // %

inline constexpr double kRateMinHz = 0.05;
inline constexpr double kRateMaxHz = 10.0;

std::string chorus_type_id(Voicing voicing, JunoMode juno_mode, bool bbd_color);
 
std::string chorus_display_name(Voicing voicing, JunoMode juno_mode, bool bbd_color);
 
struct Instance {
    Engine engine;
};

float chorus_worst_case_gain(Voicing voicing, double sample_rate);

CustomNodeType make_chorus_node(Voicing voicing = Voicing::ce2,
                                JunoMode juno_mode = JunoMode::mode_I, bool bbd_color = false);
 
}  // namespace chorus
 
// ═══════════════════════════════════════════════════════════════════════════
//  Phaser — a swept allpass cascade
// ═══════════════════════════════════════════════════════════════════════════
 
namespace phaser {
 
using Engine = signal::PhaserStages;
 
// ── Injectable param ids ──────────────────────────────────────────────────
inline constexpr state::ParamID kRateHz = 1;         // Hz
inline constexpr state::ParamID kDepth = 2;          // %
inline constexpr state::ParamID kCenterHz = 3;       // Hz
inline constexpr state::ParamID kFeedback = 4;       // −kFeedbackMax .. +kFeedbackMax
inline constexpr state::ParamID kMix = 5;            // %
inline constexpr state::ParamID kStereoSpread = 6;   // cycles, 0 .. 0.5
inline constexpr state::ParamID kStaggerRatio = 7;   // ratio
inline constexpr state::ParamID kWave = 8;           // stepped 0..6

inline constexpr double kRateMinHz = 0.02;
inline constexpr double kRateMaxHz = 10.0;
inline constexpr double kCenterMinHz = 20.0;
inline constexpr double kCenterMaxHz = 5000.0;

inline constexpr float kWaveSine = 0.0f;
inline constexpr float kWaveTriangle = 1.0f;
inline constexpr float kWaveSawUp = 2.0f;
inline constexpr float kWaveSawDown = 3.0f;
inline constexpr float kWaveSquare = 4.0f;
inline constexpr float kWaveSampleHold = 5.0f;
inline constexpr float kWaveSmoothRandom = 6.0f;

inline signal::LfoWave wave_from_param(float value) {
    const int step = static_cast<int>(std::lround(value));
    switch (step) {
        case 1: return signal::LfoWave::triangle;
        case 2: return signal::LfoWave::saw_up;
        case 3: return signal::LfoWave::saw_down;
        case 4: return signal::LfoWave::square;
        case 5: return signal::LfoWave::sample_hold;
        case 6: return signal::LfoWave::smooth_random;
        default: return signal::LfoWave::sine;
    }
}
 
struct Instance {
    Engine engine;
};
 
std::string phaser_type_id(int stages);

float phaser_worst_case_gain();

CustomNodeType make_phaser_node(int stages = Engine::kStageCountDefault);
 
}  // namespace phaser
 
// ═══════════════════════════════════════════════════════════════════════════
//  Vibrato — three lineages, three nodes
// ═══════════════════════════════════════════════════════════════════════════
 
namespace vibrato {
 
// Public for compatibility with the modulation catalog's response tests and
// downstream characterization tools. The implementation remains in the
// catalog translation unit so the public header carries no DSP helper body.
double allpass_cascade_l1(const std::vector<double>& corners_hz, double sample_rate,
                          int length = 200000);
 
// ── Delay vibrato — the only one that really shifts pitch ─────────────────
 
namespace delay_line {
 
using Engine = signal::DelayVibrato;
 
// Injectable parameter ids.
inline constexpr state::ParamID kRateHz = 1;
inline constexpr state::ParamID kDepthCents = 2;
inline constexpr state::ParamID kDelayMs = 3;
inline constexpr state::ParamID kFadeInMs = 4;
 
struct Instance {
    Engine engine;
    // Last values applied to the onset setters. Those setters re-arm the
    // lifecycle envelope, so the process callback updates them only when the
    // injected value changes.
    float applied_delay_ms = -1.0f;
    float applied_fade_in_ms = -1.0f;
};
 
// The floor is part of the realization identity because it changes the
// injectable rate range.
std::string delay_vibrato_type_id(float min_rate_hz);

float delay_vibrato_worst_case_gain();

CustomNodeType make_delay_vibrato_node(float min_rate_hz = 4.0f);
 
}  // namespace delay_line
 
// ── Phase vibrato — the Magnatone varistor lineage ────────────────────────
 
namespace phase {
 
using Engine = signal::PhaseVibrato;
 
// Injectable parameter ids.
inline constexpr state::ParamID kRateHz = 1;
inline constexpr state::ParamID kDepth = 2;
inline constexpr state::ParamID kCenterHz = 3;
inline constexpr state::ParamID kMix = 4;
 
struct Instance {
    Engine engine;
};
 
std::string phase_vibrato_type_id(int stages);

float phase_vibrato_worst_case_gain(int stages, double sample_rate);

CustomNodeType make_phase_vibrato_node(int stages = Engine::kDefaultStageCount);
 
}  // namespace phase
 
// ── Univibe — the lamp-and-photocell lineage ──────────────────────────────
 
namespace univibe {
 
using Engine = signal::UniVibe;
using Mode = Engine::Mode;
 
inline constexpr state::ParamID kRateHz = 1;
inline constexpr state::ParamID kDepth = 2;
inline constexpr state::ParamID kMode = 3;
inline constexpr float kModeVibrato = 0.0f;
inline constexpr float kModeChorus = 1.0f;
inline constexpr const char* kTypeId = "modulation.vibrato.univibe";
 
struct Instance {
    Engine engine;
};

Mode mode_from_param(float value);

float univibe_worst_case_gain(double sample_rate);

CustomNodeType make_univibe_node();
 
}  // namespace univibe
 
}  // namespace vibrato
 
}  // namespace pulp::host::modulation
 
#include <pulp/host/detail/forge_effect_modulation_catalog_descriptor.hpp>
#include <pulp/host/detail/forge_effect_modulation_extended_catalog.hpp>