forge_character_delay_catalog.hpp

Go to the documentation of this file.

#pragma once
 
// Multi-character delay — bake-layer catalog node.
//
// Wraps pulp::signal::CharacterDelayT as a lowerable custom node with
// injectable baked params, following the same shape as the lo-fi kit's
// make_delay_node() / make_filter_node(). That kit's simple feedback delay
// stays exactly as it is; this is a different, larger instrument and complements
// rather than replaces it.
//
// Per-character type ids mirror the per-mode "svf" realization pattern: the
// CHARACTER is a registration-time choice, not an injectable param. A baked
// build authored as tape is tape for the artifact's life, and no control-thread
// write can turn it into a BBD mid-render. The characters differ in buffer
// topology and in which filters exist at all, so making the choice a parameter
// would mean either running all five and crossfading (five times the cost) or
// switching topology under the audio thread (a click at best).
//
// Stereo, two ports in and two out, as ONE logical stereo wire — the same
// convention the lo-fi kit's ping-pong node uses. The module is genuinely
// stereo (crossfeed, per-channel instability decorrelation, per-channel
// segment lengths in reverse), so instancing it dual-mono would silently drop
// half of what it does.
//
// WET ONLY, like the DSP: compose with make_drywet_node() for a mix control.
// This differs from the lo-fi delay node, which outputs dry + wet; it is the
// deliberate choice, because at five characters and 1.1 feedback the useful
// dry/wet balance is a per-patch decision, not a fixed sum.
 
#include <pulp/host/forge_param_descriptor.hpp>
#include <pulp/host/custom_node_type.hpp>
 
#include <pulp/signal/character_delay.hpp>
 
#include <algorithm>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace pulp::host::character_delay {
 
using Character = signal::CharacterDelay::Character;
using TapeTier = signal::CharacterDelay::TapeTier;
 
// ── Stable type ids ───────────────────────────────────────────────────────
inline constexpr const char* kCleanTypeId = "delay.clean";
inline constexpr const char* kVintageTypeId = "delay.vintage";
inline constexpr const char* kTapeTypeId = "delay.tape";
inline constexpr const char* kBbdTypeId = "delay.bbd";
inline constexpr const char* kDiffusionTypeId = "delay.diffusion";
inline constexpr const char* kTapePhysicalTypeId = "delay.tape_physical";
 
// ── Injectable param ids ──────────────────────────────────────────────────
// Node-local; the framework namespaces per node so two nodes never collide.
inline constexpr state::ParamID kTimeMs = 1;       // ms, log-tapered by the host
inline constexpr state::ParamID kTimeOffset = 2;   // × on the right channel's time
inline constexpr state::ParamID kFeedback = 3;     // 0–1.1, displayed 0–110%
inline constexpr state::ParamID kCrossfeed = 4;    // %
inline constexpr state::ParamID kCharacter = 5;    // %
inline constexpr state::ParamID kModRate = 6;      // %, internally log-mapped
inline constexpr state::ParamID kModDepth = 7;     // %
inline constexpr state::ParamID kDuck = 8;         // %
inline constexpr state::ParamID kFreeze = 9;       // stepped 0/1
inline constexpr state::ParamID kReverse = 10;     // stepped 0/1

inline constexpr float kMaxTimeMs = 2000.0f;

namespace detail {
inline bool baked_switch_on(float value) noexcept {
    return std::isfinite(value) && value >= 0.5f;
}
}  // namespace detail
 
struct CharacterDelayInstance {
    signal::CharacterDelay delay;
};

inline const char* character_delay_type_id(Character character,
                                           TapeTier tier = TapeTier::standard) {
    switch (character) {
        case Character::vintage_digital: return kVintageTypeId;
        case Character::tape:
            return tier == TapeTier::physical ? kTapePhysicalTypeId : kTapeTypeId;
        case Character::bbd: return kBbdTypeId;
        case Character::diffusion: return kDiffusionTypeId;
        case Character::clean:
        default: return kCleanTypeId;
    }
}
 
inline const char* character_delay_default_name(Character character, TapeTier tier) {
    switch (character) {
        case Character::vintage_digital: return "Vintage Delay";
        case Character::tape:
            return tier == TapeTier::physical ? "Tape Delay (Physical)" : "Tape Delay";
        case Character::bbd: return "BBD Delay";
        case Character::diffusion: return "Diffusion Delay";
        case Character::clean:
        default: return "Clean Delay";
    }
}

inline CustomNodeType make_character_delay_node(Character character,
                                                TapeTier tier = TapeTier::standard,
                                                float tape_speed_ips = 7.5f) {
    CustomNodeType t;
    t.type_id = character_delay_type_id(character, tier);
    t.version = 1;
    t.num_input_ports = 2;  // 0 = left, 1 = right (ONE logical stereo wire)
    t.num_output_ports = 2;
    t.default_name = character_delay_default_name(character, tier);
    t.lowerable = true;
 
    t.create = []() -> void* { return new CharacterDelayInstance{}; };
    t.destroy = [](void* p) { delete static_cast<CharacterDelayInstance*>(p); };
    t.prepare = [character, tier, tape_speed_ips](void* p, double sr, int /*max_block*/) {
        auto* s = static_cast<CharacterDelayInstance*>(p);
        s->delay.set_character(character);
        s->delay.set_tape_tier(tier);
        s->delay.set_tape_speed_ips(tape_speed_ips);
        s->delay.set_sample_rate(sr);
    };
    t.reset = [](void* p) { static_cast<CharacterDelayInstance*>(p)->delay.reset(); };
 
    // Ranges and defaults are the module's canonical contract; the Forge layer
    // mirrors them and is responsible for the display units and for converting
    // musical divisions to milliseconds (the DSP has no tempo input by design).
    t.baked_params.push_back({kTimeMs, 1.0f, kMaxTimeMs, 350.0f});
    t.baked_params.push_back({kTimeOffset, 0.5f, 1.5f, 1.0f});
    t.baked_params.push_back({kFeedback, 0.0f, 1.1f, 0.35f});
    t.baked_params.push_back({kCrossfeed, 0.0f, 1.0f, 0.0f});
    t.baked_params.push_back({kCharacter, 0.0f, 1.0f, 0.5f});
    t.baked_params.push_back({kModRate, 0.0f, 1.0f, 0.3f});
    t.baked_params.push_back({kModDepth, 0.0f, 1.0f, 0.0f});
    t.baked_params.push_back({kDuck, 0.0f, 1.0f, 0.0f});
    t.baked_params.push_back({kFreeze, 0.0f, 1.0f, 0.0f});
    t.baked_params.push_back({kReverse, 0.0f, 1.0f, 0.0f});
 
    t.process_instance_baked_param = [](void* p, audio::BufferView<float>& out,
                                        const audio::BufferView<const float>& in, int n,
                                        const BakedParamView& params) {
        auto* s = static_cast<CharacterDelayInstance*>(p);
        const float* in_left = in.channel_ptr(0);
        const float* in_right = in.channel_ptr(1);
        float* out_left = out.channel_ptr(0);
        float* out_right = out.channel_ptr(1);
 
        // One sample at a time so every knob is sample-accurate. The setters
        // are a clamp and a store — the module smooths internally and only
        // recomputes coefficients at its own control rate — so this costs an
        // inlined call per param rather than a filter redesign per sample.
        for (int k = 0; k < n; ++k) {
            const auto offset = static_cast<std::int32_t>(k);
            s->delay.set_time_ms(params.value_at(kTimeMs, offset));
            s->delay.set_time_offset(params.value_at(kTimeOffset, offset));
            s->delay.set_feedback(params.value_at(kFeedback, offset));
            s->delay.set_crossfeed(params.value_at(kCrossfeed, offset));
            s->delay.set_character_amount(params.value_at(kCharacter, offset));
            s->delay.set_mod(params.value_at(kModRate, offset),
                             params.value_at(kModDepth, offset));
            s->delay.set_duck(params.value_at(kDuck, offset));
            s->delay.set_freeze(detail::baked_switch_on(params.value_at(kFreeze, offset)));
            s->delay.set_reverse(detail::baked_switch_on(params.value_at(kReverse, offset)));
 
            float left = in_left[static_cast<std::size_t>(k)];
            float right = in_right[static_cast<std::size_t>(k)];
            s->delay.process(&left, &right, 1);
            out_left[static_cast<std::size_t>(k)] = left;
            out_right[static_cast<std::size_t>(k)] = right;
        }
    };
    return t;
}
 
inline ForgeNodeDescriptor character_delay_descriptor() {
    ForgeNodeDescriptor d;
    d.key = "character_delay";
    d.label = "Character Delay";
    d.description = "Stereo wet-only delay spanning clean, vintage digital, tape, bucket-brigade, "
                    "and diffused echoes.";
    d.axes = {{"character",
               "Character",
               "Delay-line and coloration topology fixed when the node is built.",
               {{"clean", "Clean", 0.0f},
                {"vintage", "Vintage Digital", 1.0f},
                {"tape", "Tape", 2.0f},
                {"tape_physical", "Tape (Physical)", 3.0f},
                {"bbd", "BBD", 4.0f},
                {"diffusion", "Diffusion", 5.0f}}}};
    d.realizations = {
        {"clean", kCleanTypeId, {{"character", "clean"}}},
        {"vintage", kVintageTypeId, {{"character", "vintage"}}},
        {"tape", kTapeTypeId, {{"character", "tape"}}},
        {"tape_physical", kTapePhysicalTypeId, {{"character", "tape_physical"}}},
        {"bbd", kBbdTypeId, {{"character", "bbd"}}},
        {"diffusion", kDiffusionTypeId, {{"character", "diffusion"}}},
    };
    d.params = {
        {"time_ms", kTimeMs, "Time", "ms", "Base delay time.", ForgeParamKind::continuous,
         ForgeParamCurve::logarithmic},
        {"time_offset", kTimeOffset, "Time Offset", "x",
         "Right-channel delay-time multiplier for stereo offset.", ForgeParamKind::continuous,
         ForgeParamCurve::linear},
        {"feedback", kFeedback, "Feedback", "%",
         "Amount of delayed signal returned to the delay input.", ForgeParamKind::continuous,
         ForgeParamCurve::linear},
        {"crossfeed", kCrossfeed, "Crossfeed", "%",
         "Amount of each channel fed into the opposite channel's feedback path.",
         ForgeParamKind::continuous, ForgeParamCurve::linear},
        {"character", kCharacter, "Character", "%",
         "Intensity of the selected delay topology's coloration.", ForgeParamKind::continuous,
         ForgeParamCurve::linear},
        {"mod_rate", kModRate, "Modulation Rate", "%",
         "Rate of delay-time instability within the selected character.",
         ForgeParamKind::continuous, ForgeParamCurve::linear},
        {"mod_depth", kModDepth, "Modulation Depth", "%", "Depth of delay-time instability.",
         ForgeParamKind::continuous, ForgeParamCurve::linear},
        {"duck", kDuck, "Duck", "%", "Reduces delayed output while the input is active.",
         ForgeParamKind::continuous, ForgeParamCurve::linear},
        {"freeze",
         kFreeze,
         "Freeze",
         "",
         "Holds the current delay contents in a sustaining feedback loop.",
         ForgeParamKind::stepped,
         ForgeParamCurve::linear,
         {{"off", "Off", 0.0f}, {"on", "On", 1.0f}}},
        {"reverse",
         kReverse,
         "Reverse",
         "",
         "Reads completed delay segments in reverse.",
         ForgeParamKind::stepped,
         ForgeParamCurve::linear,
         {{"off", "Off", 0.0f}, {"on", "On", 1.0f}}},
    };
    return d;
}
 
}  // namespace pulp::host::character_delay