Adds Necessary Delay: BBD delay into spring reverb

Camilo Landau · claude · Camilo Landau · commit a8114f4d825a · 2026-04-09T11:27:13.000+02:00
Bucket-brigade style delay with vibrato modulation and progressive
darkening, feeding into a Schroeder spring reverb. Infinite hold
via footswitch. Dry signal never touches the spring.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ A collection of custom effects for the [Polyend Endless](https://polyend.com/end
 |--------|-------------|
 | [Tremvolope](effects/tremvolope/) | Envelope-controlled stereo tremolo. Dynamics shape the rate, depth, and stereo spread — quiet signals bloom into swirling modulation, or loud attacks drive aggressive throb. |
 | [Preamp](effects/preamp/) | Transparent preamp and clean boost. Soft saturation adds warmth and compression without coloring your tone. Tilt EQ goes from round to airy in a single knob. |
+| [Necessary Delay](effects/necessary-delay/) | BBD-style delay into spring reverb. Vibrato-wobbled, progressively darkening repeats dissolve into dripping, metallic ambience. Infinite hold for drones and layering. |
 
 ## How to Use
 
diff --git a/effects/necessary-delay/PatchImpl.cpp b/effects/necessary-delay/PatchImpl.cpp
@@ -0,0 +1,234 @@
+#include "Patch.h"
+
+#include <cmath>
+
+// BBD-style delay into spring reverb.
+// Dry signal is never reverbed — only the delay trails hit the spring.
+//
+// Left knob:  Time (30 ms to 3000 ms)
+// Mid knob:   Mix (dry/wet)
+// Right knob: Repeats (feedback amount)
+// Footswitch press: bypass
+// Footswitch hold:  toggle infinite repeats (LED turns red)
+
+constexpr float kPi = 3.14159265f;
+constexpr float kTwoPi = 2.0f * kPi;
+
+// Delay
+constexpr int kMaxDelaySamples = 144000; // 3000 ms at 48 kHz
+constexpr int kMinDelaySamples = 1440;   // 30 ms
+
+// BBD vibrato modulation
+constexpr float kVibratoRate = 2.5f;  // Hz
+constexpr float kVibratoDepth = 40.0f; // samples (~0.8 ms)
+constexpr float kBbdDamping = 0.35f;   // LP coefficient per repeat (~3 kHz)
+
+// Spring reverb — allpass diffusers (series)
+constexpr int kAllpassLengths[] = {556, 441, 341, 225};
+constexpr int kNumAllpasses = 4;
+constexpr float kAllpassCoeff = 0.5f;
+
+// Spring reverb — comb filters (parallel)
+constexpr int kCombLengths[] = {1687, 1601, 2053, 2251};
+constexpr int kNumCombs = 4;
+constexpr float kCombDecay = 0.7f;
+constexpr float kCombDamping = 0.3f;
+
+class PatchImpl : public Patch
+{
+  public:
+    void init() override
+    {
+        delayWritePos = 0;
+        lfoPhase = 0.0f;
+        bbdLpState = 0.0f;
+
+        for (int i = 0; i < kNumCombs; ++i)
+        {
+            combPos[i] = 0;
+            combLpState[i] = 0.0f;
+        }
+        for (int i = 0; i < kNumAllpasses; ++i)
+            allpassPos[i] = 0;
+    }
+
+    void setWorkingBuffer(std::span<float, kWorkingBufferSize> buffer) override
+    {
+        // Partition the working buffer into delay line + reverb buffers
+        delayLine = buffer.data();
+        int offset = kMaxDelaySamples;
+
+        for (int i = 0; i < kNumCombs; ++i)
+        {
+            combLines[i] = buffer.data() + offset;
+            offset += kCombLengths[i];
+        }
+        for (int i = 0; i < kNumAllpasses; ++i)
+        {
+            allpassLines[i] = buffer.data() + offset;
+            offset += kAllpassLengths[i];
+        }
+
+        // Zero all buffers
+        for (int i = 0; i < offset; ++i)
+            buffer[i] = 0.0f;
+    }
+
+    void processAudio(std::span<float> audioBufferLeft,
+                      std::span<float> audioBufferRight) override
+    {
+        if (!active)
+            return;
+
+        const int delaySamples = kMinDelaySamples +
+            static_cast<int>(timeParam * static_cast<float>(kMaxDelaySamples - kMinDelaySamples));
+        const float feedback = infiniteHold ? 0.99f : repeatsParam * 0.9f;
+        const float wet = mixParam;
+        const float dry = 1.0f - mixParam;
+
+        for (auto leftIt = audioBufferLeft.begin(), rightIt = audioBufferRight.begin();
+             leftIt != audioBufferLeft.end();
+             ++leftIt, ++rightIt)
+        {
+            float input = (*leftIt + *rightIt) * 0.5f;
+
+            // --- Vibrato LFO ---
+            lfoPhase += kVibratoRate / static_cast<float>(kSampleRate);
+            if (lfoPhase >= 1.0f)
+                lfoPhase -= 1.0f;
+            float mod = std::sin(kTwoPi * lfoPhase) * kVibratoDepth;
+
+            // --- Read from delay with vibrato + linear interpolation ---
+            float readPosF = static_cast<float>(delayWritePos)
+                           - static_cast<float>(delaySamples) + mod;
+            while (readPosF < 0.0f)
+                readPosF += static_cast<float>(kMaxDelaySamples);
+
+            int readIdx = static_cast<int>(readPosF);
+            float frac = readPosF - static_cast<float>(readIdx);
+            int idx0 = readIdx % kMaxDelaySamples;
+            int idx1 = (readIdx + 1) % kMaxDelaySamples;
+
+            float delayed = delayLine[idx0] * (1.0f - frac) + delayLine[idx1] * frac;
+
+            // --- BBD low-pass (darkens with each repeat) ---
+            bbdLpState += kBbdDamping * (delayed - bbdLpState);
+            delayed = bbdLpState;
+
+            // --- Write to delay (input + feedback with soft limit) ---
+            delayLine[delayWritePos] = std::tanh(input + delayed * feedback);
+            delayWritePos = (delayWritePos + 1) % kMaxDelaySamples;
+
+            // --- Spring reverb on delay output only ---
+            float wetSignal = processSpring(delayed);
+
+            // --- Mix (dry signal never hits the spring) ---
+            *leftIt = *leftIt * dry + wetSignal * wet;
+            *rightIt = *rightIt * dry + wetSignal * wet;
+        }
+    }
+
+    ParameterMetadata getParameterMetadata(int paramIdx) override
+    {
+        switch (paramIdx)
+        {
+            case 0: return { 0.0f, 1.0f, 0.3f };  // Time
+            case 1: return { 0.0f, 1.0f, 0.5f };  // Mix
+            case 2: return { 0.0f, 1.0f, 0.4f };  // Repeats
+            default: return { 0.0f, 1.0f, 0.5f };
+        }
+    }
+
+    Color getStateLedColor() override
+    {
+        if (!active)
+            return Color::kDimBlue;
+        return infiniteHold ? Color::kRed : Color::kLightBlueColor;
+    }
+
+    void setParamValue(int idx, float value) override
+    {
+        switch (idx)
+        {
+            case 0: timeParam = value; break;
+            case 1: mixParam = value; break;
+            case 2: repeatsParam = value; break;
+        }
+    }
+
+    void handleAction(int actionIdx) override
+    {
+        if (actionIdx == 0)
+            active = !active;
+        else if (actionIdx == 1)
+            infiniteHold = !infiniteHold;
+    }
+
+  private:
+    float processSpring(float input)
+    {
+        // Allpass diffusion chain (spring dispersion)
+        float signal = input;
+        for (int i = 0; i < kNumAllpasses; ++i)
+        {
+            float* buf = allpassLines[i];
+            int len = kAllpassLengths[i];
+            int& pos = allpassPos[i];
+
+            float delayed = buf[pos];
+            float temp = signal + kAllpassCoeff * delayed;
+            buf[pos] = temp;
+            signal = delayed - kAllpassCoeff * temp;
+            pos = (pos + 1) % len;
+        }
+
+        // Parallel comb filters with damped feedback (resonant tail)
+        float combSum = 0.0f;
+        for (int i = 0; i < kNumCombs; ++i)
+        {
+            float* buf = combLines[i];
+            int len = kCombLengths[i];
+            int& pos = combPos[i];
+            float& lp = combLpState[i];
+
+            float delayed = buf[pos];
+            lp += kCombDamping * (delayed - lp);
+            buf[pos] = signal + kCombDecay * lp;
+            combSum += delayed;
+            pos = (pos + 1) % len;
+        }
+
+        return combSum * 0.25f;
+    }
+
+    // Working buffer partitions
+    float* delayLine = nullptr;
+    float* combLines[kNumCombs] = {};
+    float* allpassLines[kNumAllpasses] = {};
+
+    // Delay state
+    int delayWritePos = 0;
+    float lfoPhase = 0.0f;
+    float bbdLpState = 0.0f;
+
+    // Spring reverb state
+    int combPos[kNumCombs] = {};
+    float combLpState[kNumCombs] = {};
+    int allpassPos[kNumAllpasses] = {};
+
+    // Parameters
+    float timeParam = 0.3f;
+    float mixParam = 0.5f;
+    float repeatsParam = 0.4f;
+
+    // State
+    bool active = true;
+    bool infiniteHold = false;
+};
+
+static PatchImpl patch;
+
+Patch* Patch::getInstance()
+{
+    return &patch;
+}
diff --git a/effects/necessary-delay/README.md b/effects/necessary-delay/README.md
@@ -0,0 +1,60 @@
+# Necessary Delay
+
+**A bucket-brigade delay into spring reverb for the Polyend Endless.**
+
+Your dry signal stays clean. The repeats don't. Necessary Delay runs a BBD-style analog delay — complete with vibrato wobble and progressive high-frequency rolloff — into a spring reverb that only the delay trails ever touch. The result is a delay that starts articulate and dissolves into dripping, metallic ambience as the repeats fade.
+
+The vibrato modulation gives each repeat a slight pitch drift, the way a real bucket-brigade chip would. The one-pole filter in the feedback path darkens every pass, so early repeats are clear and present while later ones smear into warm fog. Then the spring catches all of that and adds its own resonant, boingy tail — diffused through allpass filters for that characteristic drip, sustained by damped comb filters for the decay.
+
+Hold the footswitch and the repeats freeze into infinite sustain, layering new playing on top of a living, breathing loop.
+
+## Controls
+
+| Knob | Parameter | Description |
+|------|-----------|-------------|
+| Left | **Time** | Delay time, 30 ms to 3 seconds. Short for slapback, long for sprawling ambient repeats. |
+| Mid | **Mix** | Dry/wet blend. Full CCW is dry, full CW is wet. The dry signal is always clean — the spring reverb only colors the delay trails. |
+| Right | **Repeats** | Feedback amount. Low for a single echo, high for cascading, darkening trails that wash into the spring. |
+
+**Footswitch press**: Bypass on/off (LED light blue = active, dim blue = bypassed).
+
+**Footswitch hold**: Toggle infinite repeats. The delay loop sustains indefinitely — play over it, layer textures, build drones. LED turns red so you know it's locked.
+
+## How It Works
+
+The signal chain is intentionally asymmetric:
+
+```
+Dry signal ──────────────────────────────────────→ output
+                                                     ↑
+Input → BBD delay → vibrato mod → spring reverb → wet mix
+            ↑              |
+            └── feedback ──┘
+                (LP filtered, soft limited)
+```
+
+- **BBD delay**: Mono delay line with linear-interpolated readout. A 2.5 Hz sine LFO wobbles the read position by ~0.8 ms for that analog pitch drift.
+- **Feedback path**: Each repeat passes through a one-pole low-pass (~3 kHz) that progressively darkens the sound. A `tanh` soft limiter prevents runaway, especially during infinite hold.
+- **Spring reverb**: 4 cascaded Schroeder allpass filters diffuse the signal (modeling spring dispersion), then 4 parallel comb filters with damped feedback create the resonant tail. Only the delay output feeds the spring — your dry tone stays untouched.
+
+## Sweet Spots
+
+- **Analog slapback**: Time at 8 o'clock (~100 ms), Repeats at 9 o'clock, Mix at 10 o'clock. Quick, warm slap with a hint of spring splash.
+- **Tape-echo wash**: Time at noon (~1.5 s), Repeats at 1 o'clock, Mix at noon. Repeats darken and dissolve into reverb. Classic ambient delay.
+- **Drip machine**: Time at 10 o'clock (~500 ms), Repeats at 2 o'clock, Mix at 1 o'clock. Spring-drenched repeats that cascade and drip.
+- **Infinite drone**: Any time setting, hold footswitch. Layer notes and chords over a frozen, evolving delay loop. The spring reverb smears everything into a lush pad.
+- **Lo-fi ghost**: Time at 3 o'clock (~2.5 s), Repeats high, Mix at 9 o'clock. Long, dark, barely-there repeats that haunt the background.
+
+## Build
+
+Requires the [GNU Arm Embedded Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain).
+
+```
+make
+```
+
+Copy the resulting `.endl` file from `build/` to your Endless via USB.
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).
