Source code for audioeffects.chorus

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""`Chorus` - one delayed voice on a clock-modulated bucket-brigade line.

The player's text is the class docstring; the `CLAIMS` table in the class's
test file ties its claim sentences to tests.
"""

# Design notes, from the rebuild.
#
# `Chorus` — one delayed voice on a clock-modulated bucket-brigade line.
#
# Rebuilt from scratch for Phase 3 against a dossier whose trait table was
# frozen at Station A before this file existed. The old `modulation.py:Chorus`
# is consulted only for the six defects that dossier's section 7 names.
#
# What it sounds like. A single wet voice, delayed a few milliseconds,
# swirls because a triangle LFO moves the *clock* of the line, not the delay
# time: delay is N/(2·f_clk), so the pitch offset ramps inside each half-cycle
# instead of holding a square. Rate is how fast that triangle runs (about
# 0.3 Hz to 10 Hz). Depth is how far the clock swings (0 to ±35 %). Mix at
# the vintage summing network is 0.815 wet against unity dry; Mix 0 is a
# wire. Delay is the mean line, 3–20 ms, default 8.8 ms from the vintage
# 100 pF timing capacitor. Tone is the wet voice's reconstruction low-pass,
# default 3 kHz, far darker than anti-aliasing requires.
#
# Portability tier: audiodsp (`REQUIRES = ("audioecho",)`). The stock
# `audiodelays.Chorus` reads whole-sample taps, moves them once per block, and
# with `voices=1` emits no delayed voice at all. On a stock CircuitPython
# board this module imports cleanly and construction raises `ImportError`.
#
# Cost: one node. `audioecho.FeedbackDelay` with a shipped `wow_shape`
# clock-law table, `feedback=0`, Mix ≤ 1 so the dry stays at unity. Palette
# row: FeedbackDelay +options (the 256-point table is borrowed by the node,
# not an extra looping `RawSample` pull). Budget P4 ≤ 9 %, S3 ≤ 15 % of
# a 5.333 ms stereo block (dossier §3). Measured at patch 0: 8.1 % P4 /
# 9.8 % S3. No `" - lean"` patch.
#
# What the default surrenders: the within-half pitch-offset ratio is
# 1.98, not (d_max/d_min)² = 3.60 (T2). Tone 12 kHz is 2.4 dB down at
# 10 kHz, not ≥10 dB (T3). The constructor Tone 3 kHz still meets T3.
#
# Input ceiling: -6 dBFS. The dry stays at unity and the wet voice
# adds to it (Mix 0.815 at the defaults, 1 at the top), so the output peaks at
# up to twice the input: a phrase peaking at -3 dBFS comes out 3 dB over
# full scale at the defaults. Keep the input under -6.03 dBFS and no setting
# reaches a rail; Mix 0 is still a wire at any level.
#
# Latency: zero samples, at every setting and every rate. Nothing looks
# ahead. The 8–13 ms mean delay is the wet path, not latency. No option adds
# latency, so there is none to default off and none to name in milliseconds.
#
# `capabilities = ()`: the LFO is a free-running relaxation oscillator. This
# class never reads `self._transport()`.

VENDOR = "PyDevices"

from array import array
import math

from . import _component

try:
    import audioecho
except ImportError:                     # pragma: no cover - a stock board
    audioecho = None


#: Line length. Delay 20 ms at Depth 0.35 reaches d_max = 20/(1-0.35) ≈
#: 30.8 ms; one frame of headroom sits under the line. 40 ms is the next
#: round number that clears it.
MAX_DELAY_MS = 40.0

#: One period of the clock law, power of two, borrowed by the node.
SHAPE_LEN = 256

#: Depth below this is treated as off: wow_depth_ms = 0, delay = mean.
DEPTH_OFF = 1e-4


def _unit_triangle(index, length):
    """Bipolar unit triangle on `[0, 1)`: 0 → +1 → 0 → −1 → 0."""
    phase = index / float(length)
    if phase < 0.25:
        return 4.0 * phase
    if phase < 0.75:
        return 2.0 - 4.0 * phase
    return 4.0 * phase - 4.0


[docs] def clock_shape(m): """Q15 table for `d = d0/(1 + m·tri)`. Fitted as mid + depth × wow with wow in [−1, 1]: wow(u) = −(m + u)/(1 + m·u). Depth 0 is a silent table; the node is driven with wow_depth_ms = 0 in that case. """ m = float(m) if m < DEPTH_OFF: return array("h", [0] * SHAPE_LEN) values = [] for index in range(SHAPE_LEN): u = _unit_triangle(index, SHAPE_LEN) wow = -(m + u) / (1.0 + m * u) if wow > 1.0: wow = 1.0 elif wow < -1.0: wow = -1.0 values.append(int(round(wow * 32767.0))) return array("h", values)
[docs] def delay_law(mean_ms, m): """Node `delay_ms` and `wow_depth_ms` for mean `mean_ms` and swing `m`. mid = d0/(1 − m²), depth = d0·m/(1 − m²), so d = mid + depth·wow recovers d0/(1 + m·u). """ mean_ms = float(mean_ms) m = float(m) if m < DEPTH_OFF: return mean_ms, 0.0 denom = 1.0 - m * m if denom < 1e-6: denom = 1e-6 return mean_ms / denom, mean_ms * m / denom
[docs] def nominal_damping_hz(corner_hz, sample_rate): """`damping_hz` whose one-pole −3 dB is `corner_hz` at `sample_rate`. The node takes the analog-style coefficient `1 − exp(−2π f/fs)` (`audiodsp_feedback_delay.c:31-38`), so the knob's hertz is not the digital −3 dB. Inverse of |H|² = 1/2 for y += a(x − y). """ fs = float(sample_rate) fc = float(corner_hz) if fc <= 0.0: return 0.0 omega = 2.0 * math.pi * fc / fs k = 1.0 - math.cos(omega) if k <= 1e-12: return fc a = -k + math.sqrt(k * (k + 2.0)) if a >= 0.999999: a = 0.999999 if a <= 1e-12: return fc return -fs * math.log(1.0 - a) / (2.0 * math.pi)
[docs] class Chorus(_component.Component): """A one-voice analog chorus, the way a bucket-brigade pedal does it: one delayed copy of your signal, its pitch swirling because a triangle moves the line's clock rather than its delay. **Controls.** Rate is the sweep's speed, and Depth is how far the clock swings either way. Mix sets the wet voice against your signal, which stays at full level: 0 is a wire, the default 0.815 is the vintage blend, and 1 puts the two level. Delay is the line's average length. Tone is the wet voice's low-pass: at its default 3 kHz the wet voice is at least 10 dB down at 10 kHz, the dark sound of the originals, and at 12 kHz it is less than 6 dB down there. The Effect controls page lists what the knobs span. **One voice.** A hit comes back once, with no repeats: there is no feedback. The sweep runs free and does not follow a host's tempo. **Levels.** The wet voice adds to your signal, so at Mix 1 the output can reach twice the input. Keep the input under -6.03 dBFS and no setting reaches a rail; with the ceiling taken away, a phrase peaking at -3 dBFS rails. Mix 0 is a wire at any level. **Timing.** Latency is zero at every setting: the wet voice's delay is the effect, and your own signal comes through on time. **On a board.** The class needs audiodsp's `audioecho`, and on a board without it construction raises `ImportError`. """ NAME = 'Chorus' DISPLAY_NAME = 'Chorus' CATEGORIES = ('Modulation',) VERSION = '0.1.0' TIER = _component.AUDIODSP REQUIRES = ("audioecho",) CAPABILITIES = () LATENCY_SAMPLES = 0 TAIL_SAMPLES = 0 #: The wet voice is a delayed, low-passed copy of the input, so it never #: passes the input's peak, and the dry is at unity: the sum is at most #: twice the input at Mix 1. -6.03 dBFS is 16 366 against the 32 767 #: rail. INPUT_CEILING_DBFS = -6.03 MACRO_LABELS = ("Rate", "Depth", "Mix", "Delay", "Tone") MACRO_MODES = { 0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", } _MACRO_RANGES = ( (0.3, 10.0, "log"), # 0 Rate, Hz (0.0, 0.35), # 1 Depth, clock swing m (0.0, 1.0), # 2 Mix; 0 wire, 0.815 vintage, 1 equal (3.0, 20.0), # 3 Delay, mean ms (1000.0, 12000.0, "log"), # 4 Tone, wet −3 dB Hz ) _MACRO_UNITS = {0: "Hz", 3: "ms", 4: "Hz"} PATCHES = { 0: ("Near-equal blend", (36, 127, 104, 43, 56)), 1: ("Long line, deep", (19, 127, 104, 76, 56)), 2: ("Short line, shallow", (61, 73, 104, 7, 56)), 3: ("Slow swirl", (6, 127, 104, 43, 56)), 4: ("Fast warble", (108, 127, 104, 22, 56)), 5: ("Dark wet", (36, 127, 76, 43, 21)), 6: ("Equal sum", (36, 127, 127, 43, 56)), } def _build(self, rate=0.8, depth=0.35, mix=0.815, delay_ms=8.8, tone_hz=3000.0, patch=None): self._shape = clock_shape(0.0) #: The mean `delay_ms` last written, so a move can glide from it. self._delay_written = None self._tail = 0 self._delay = self._own(audioecho.FeedbackDelay( sample_rate=self._sample_rate, channel_count=self._channel_count, max_delay_ms=MAX_DELAY_MS, delay_ms=delay_ms, feedback=0.0, mix=mix, damping_hz=0.0, cut_hz=0.0, wow_hz=0.0, wow_depth_ms=0.0, wow_shape=self._shape)) self._delay.play(self._source) self._output = self._delay self._init_macros((rate, depth, mix, delay_ms, tone_hz), patch)
[docs] def reset(self): """A reset is a fresh instance: patch 0's delay lands at once.""" self._check_live() self._delay_written = None self._delay.set(delay_slew=0.0) _component.Component.reset(self)
def _value(self, index): return _component.macro_value(self._MACRO_RANGES[index], self._macros[index]) def _apply_macro(self, index, position): del position self._refresh() def _refresh(self): rate = self._value(0) depth = self._value(1) mix = self._value(2) mean_ms = self._value(3) tone = self._hz(self._value(4)) delay_ms, wow_depth_ms = delay_law(mean_ms, depth) self._shape = clock_shape(depth) damping = nominal_damping_hz(tone, self._sample_rate) # A Depth or Delay move moves the mean line, and written as it was # the read head jumped by the whole change on the next frame. So # the line walks there over 20 ms (the node's `delay_slew`, # delay-seconds per second, set from the size of this move). last = self._delay_written if last is not None and last != delay_ms: self._delay.set( delay_slew=abs(delay_ms - last) / _component.LEVEL_RAMP_MS) self._delay_written = delay_ms self._delay.set( delay_ms=delay_ms, wow_depth_ms=wow_depth_ms, wow_hz=rate, mix=mix, feedback=0.0, damping_hz=damping, cut_hz=0.0, wow_shape=self._shape) d_max = mean_ms / (1.0 - depth) if depth < 1.0 - DEPTH_OFF else mean_ms self._tail = int(math.ceil(d_max * self._sample_rate / 1000.0)) + 64 @property def tail_samples(self): self._check_live() return int(self._tail)