Source code for audioeffects.pingpongdelay

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

"""`PingPongDelay` - repeats that alternate between the speakers.

The player's text is the class docstring, and every sentence in it that
makes a claim is tied to a test by the `CLAIMS` table in the class's test
file.
"""

VENDOR = "PyDevices"

from . import _component
from .chorus import nominal_damping_hz

# DigitalDelay's arithmetic, reused rather than copied: the same node rounds
# the same way in both classes; the same for SlapbackDelay's `tone_excess`.
from .digitaldelay import (CUT_LAP_FACTOR, DIVISION_BEATS, laps_to_zero,
                           nominal_cut_hz, whole_frames)
from .slapbackdelay import tone_excess

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


#: The Time span, fixed on every instance (dossier section 6): 20-1000 ms,
#: log.
TIME_MIN_MS = 20.0
TIME_MAX_MS = 1000.0

#: The line's headroom over `max_time_ms`: the node clamps a delay at
#: `line_frames - 2` (`audiodsp_feedback_delay.c:148-150`), so a line of
#: exactly `max_time_ms` could not reach it.
LINE_HEADROOM_MS = 1.0

#: The node's own loop ceiling (`audiodsp_feedback_delay.c:157`).
FEEDBACK_MAX = 0.99

#: The Repeat Tone and Repeat Cut spans' corners, Hz. Tone's top stop and
#: Cut's bottom stop are the filters out of circuit.
TONE_MIN_HZ = 800.0
TONE_MAX_HZ = 16000.0
CUT_MIN_HZ = 20.0
CUT_MAX_HZ = 400.0

#: The fixed Time walk, delay-seconds per second: 3/16, exact in float32
#: (dossier section 8.5, `SlapbackDelay`'s section 8 answer 6).
SLEW = 0.1875

#: How close, as a 0..1 knob position, a Time write must come to the
#: constructor's own seeded position to count as a host echoing it back:
#: 1e-6 is 1/7 874 of one MIDI step.
ECHO_TOLERANCE = 1e-6

(TIME_I, FEEDBACK_I, MIX_I, SPREAD_I, SIDE_I, SYNC_I, DIVISION_I, TONE_I,
 CUT_I) = range(9)

#: The constructor defaults NaN falls back to: Time, Feedback, Mix, Spread,
#: Division.
DEFAULT_TIME_MS = 280.0
DEFAULT_FEEDBACK = 0.45
DEFAULT_MIX = 0.3
DEFAULT_SPREAD = 1.0
DEFAULT_DIVISION = 6.0


def _option(value, default):
    """A constructor option as a float; NaN is the option's default."""
    value = float(value)
    if value != value:
        return default
    return value


def _between(value, low, high):
    if value < low:
        return low
    if value > high:
        return high
    return value


def _side(value):
    """`first_side` -> 0.0 (left) or 1.0 (right)."""
    if isinstance(value, str):
        word = value.lower()
        if word == "left":
            return 0.0
        if word == "right":
            return 1.0
        raise ValueError("first_side must be 'left' or 'right', not %r"
                         % (value,))
    return 1.0 if float(value) >= 0.5 else 0.0


[docs] class PingPongDelay(_component.Component): """Two delay lines crossed into each other: the repeats bounce between the speakers. Your dry signal passes untouched on both sides, and the repeats come back one side and then the other, all the way down. **The controls.** The first repeat comes back Time later on the side First Side names, the next Time after that on the other side, and they keep bouncing, each a Feedback's worth quieter than the last. Time runs from 20 to 1000 ms and Feedback from 0 to 0.99. Mix is the echo level: the dry stays at unity up to Mix 1, Mix 2 is the repeats alone, and at Mix 0 the output is the input. Spread moves between two plain delays with the same repeats on both sides, at 0, and the full bounce, at 1. At Spread 1 each repeat is on one side only, and the other side is exact zero. With Sync on, Time is Division of the host's beat, up to 1000 ms; with no host tempo, Time stays where the knob is. The class reads the host's transport only while Sync is on, and then only when a control moves, a patch loads or the host calls `transport_changed()`, never while it plays. Repeat Tone is a low-pass and Repeat Cut a high-pass inside the loop, so each bounce is a little darker or thinner than the last. Repeat Tone's top stop and Repeat Cut's bottom stop take them out, and a filter taken out is out. At 22.05 kHz the top positions of Repeat Tone sit on one clamp below Nyquist and sound the same. Turning Time walks the repeats to the new Time, bending their pitch, instead of clicking. **Stereo and mono.** At Spread 1 the loop hears the average of the two input channels, so what differs between them never repeats. The dry is always each channel's own signal, never swapped or summed. A one-channel source gets an ordinary feedback delay at the same Time, Feedback and Mix, and Spread and First Side do nothing there. **Where it stops.** At 48 kHz every Time position lands on the nearest whole frame. At 44.1 and 22.05 kHz the node lands some positions a fraction of a frame off, and a sliver of each repeat falls on the frame beside it. The dry sits at unity and the repeats add to it, so a hot input can reach the int16 rail. With Repeat Cut out and Mix below 1, an input that peaks at or below floor(32767 (1 - Mix)) - 1 cannot reach the rail, at any Time, Feedback or Spread. Repeat Cut's high-pass overshoots, so with it in leave more room. Keep the input under -6 dBFS and the defaults and patches stay off the rails. **Limits shared by the family.** Mix walks a jump over 20 ms, but any other control that jumps makes the output step: move it in small steps from the host if you need it smooth. When your source ends, the tail rings out as it would on silence. **Latency, tail, portability.** A click comes out on the frame it went in: there is no latency. `tail_samples` is an upper bound on how many frames the output takes to reach exact zero, counted from when your input stops or from when you read it if that is later, for the settings as they stand when you read it. With Repeat Cut in circuit the bound is twice as many repeats as with it out, a margin measured rather than derived. Pass a lower `max_time_ms` for a shorter line: Time then stops at that ceiling, and `get_macro(0)` shows where it stopped. A constructor value outside a knob's span clamps to the nearer stop, a `tone_hz` or `cut_hz` of 0 or less is that filter out, and NaN takes the option's default. `reset()` empties the line and returns to patch 0. The class needs audiodsp's `audioecho`, and on a board without it construction raises `ImportError`. """ NAME = 'PingPongDelay' DISPLAY_NAME = 'Ping-Pong Delay' CATEGORIES = ('Delay',) VERSION = '0.1.0' TIER = _component.AUDIODSP #: The exact constructor values a rack's reset puts back with the knobs. _KEPT = ('_time_exact',) REQUIRES = ("audioecho",) CAPABILITIES = ("tempo_sync",) _SYNC_MACRO = SYNC_I LATENCY_SAMPLES = 0 TAIL_SAMPLES = None #: The defaults and every patch play the ceiling kit's materials #: clean at this level; at -3 dBFS, patch 3 rails on #: a DC step. INPUT_CEILING_DBFS = -6 MACRO_LABELS = ("Time", "Feedback", "Mix", "Spread", "First Side", "Sync", "Division", "Repeat Tone", "Repeat Cut") MACRO_MODES = { 0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "TOGGLE", 5: "TOGGLE", 6: "UNIPOLAR", 7: "UNIPOLAR", 8: "UNIPOLAR", } _MACRO_RANGES = ( (TIME_MIN_MS, TIME_MAX_MS, "log"), # 0 Time, ms (0.0, FEEDBACK_MAX), # 1 Feedback (0.0, 2.0), # 2 Mix; dry at unity to 1 (0.0, 1.0), # 3 Spread (0.0, 1.0), # 4 First Side: left, right (0.0, 1.0), # 5 Sync (0.0, 15.0), # 6 Division index (TONE_MIN_HZ, TONE_MAX_HZ, "log"), # 7 Repeat Tone, Hz; top = out (CUT_MIN_HZ, CUT_MAX_HZ, "log"), # 8 Repeat Cut, Hz; bottom = out ) _MACRO_UNITS = {0: "ms", 7: "Hz", 8: "Hz"} #: `_component.macro_of` of the dossier's section 6 settings; patch 0 is #: the constructor's defaults on the grid. PATCHES = { 0: ("Wide Bounce", (86, 58, 19, 127, 0, 0, 51, 127, 0)), 1: ("Eighth Note Bounce", (86, 64, 19, 127, 0, 127, 51, 127, 0)), 2: ("Quarter Note Bounce", (86, 51, 19, 127, 0, 127, 76, 127, 0)), 3: ("Narrow Bounce", (86, 58, 19, 64, 0, 0, 51, 127, 0)), 4: ("Two Delays", (86, 58, 19, 0, 0, 0, 51, 127, 0)), 5: ("Dark Bounce", (99, 83, 19, 127, 0, 0, 51, 48, 0)), 6: ("Right First", (86, 58, 19, 127, 127, 0, 51, 127, 0)), } def _build(self, time_ms=DEFAULT_TIME_MS, feedback=DEFAULT_FEEDBACK, mix=DEFAULT_MIX, spread=DEFAULT_SPREAD, first_side="left", sync=False, division=DEFAULT_DIVISION, tone_hz=TONE_MAX_HZ, cut_hz=CUT_MIN_HZ, max_time_ms=TIME_MAX_MS, patch=None): max_time_ms = float(max_time_ms) # `not <=` catches NaN, which would otherwise pass both clamps and # size the line from nothing. if not max_time_ms <= TIME_MAX_MS: max_time_ms = TIME_MAX_MS if max_time_ms < TIME_MIN_MS: max_time_ms = TIME_MIN_MS self._max_time_ms = max_time_ms self._frames = 1 #: The longest delay, in whole frames, the read head may still sit #: at. The walk starts from wherever the head is and the class cannot #: see how far it has got, so after a falling move this keeps the old #: Time until a reset lands the head. self._reach = 1 #: True while the node has been built or cleared and not yet told a #: second Time: it snaps onto the configured delay on its first pull. self._fresh = True #: True while several macros are applied at once (the constructor, #: `program_change`); the node is refreshed once, after the last. self._deferred = False self._feedback = 0.0 self._damping = 0.0 self._cut = 0.0 self._node_ms = 0.0 #: The constructor's Time, exactly, until macro 0 moves. Seeding a #: log knob and reading it back is not exact, and a few ulps under a #: half frame lands one frame short. self._time_exact = None self._time_seed = -1.0 self._seeding = True # A log knob cannot seed 0 or a negative, so those clamp to the # nearer stop here; 0 or less is how the node spells a filter out. time_ms = _between(_option(time_ms, DEFAULT_TIME_MS), TIME_MIN_MS, max_time_ms) tone_hz = _option(tone_hz, TONE_MAX_HZ) if not tone_hz > 0.0: tone_hz = TONE_MAX_HZ tone_hz = _between(tone_hz, TONE_MIN_HZ, TONE_MAX_HZ) cut_hz = _option(cut_hz, CUT_MIN_HZ) if not cut_hz > 0.0: cut_hz = CUT_MIN_HZ cut_hz = _between(cut_hz, CUT_MIN_HZ, CUT_MAX_HZ) values = (time_ms, _between(_option(feedback, DEFAULT_FEEDBACK), 0.0, FEEDBACK_MAX), _between(_option(mix, DEFAULT_MIX), 0.0, 2.0), _between(_option(spread, DEFAULT_SPREAD), 0.0, 1.0), _side(first_side), 1.0 if sync else 0.0, _between(_option(division, DEFAULT_DIVISION), 0.0, 15.0), tone_hz, cut_hz) self._delay = audioecho.FeedbackDelay( sample_rate=self._sample_rate, channel_count=self._channel_count, max_delay_ms=max_time_ms + LINE_HEADROOM_MS, delay_ms=time_ms, feedback=0.0, mix=0.0, damping_hz=0.0, cut_hz=0.0, cross_feed=0.0, input_pan=0.0, delay_slew=0.0) # `clear()` empties both lanes and the loop filters and re-primes the # read head (`audiodsp_feedback_delay.c:295-303`, `:286-288`), so a # reset is silent and snaps onto patch 0's Time. self._own(self._delay, reset=self._clear) self._delay.play(self._source) self._output = self._delay self._time_exact = time_ms self._deferred = True try: self._init_macros(values) finally: self._deferred = False self._seeding = False self._time_seed = self._macros[TIME_I] self._refresh() if patch is not None: self.program_change(patch) self._fresh = False def _clear(self): self._delay.clear() self._fresh = True # -- the maps ------------------------------------------------------ def _value(self, index): return _component.macro_value(self._MACRO_RANGES[index], self._macros[index]) def _clamp_ms(self, time_ms): time_ms = float(time_ms) if time_ms > self._max_time_ms: return self._max_time_ms if time_ms < TIME_MIN_MS: return TIME_MIN_MS return time_ms def _node_time_ms(self, frames): """What the node is handed for a whole-frame Time.""" return frames * 1000.0 / self._sample_rate def _tone_damping(self, position): """Macro 7's position -> the node's `damping_hz`: the corner the loop low-pass achieves, clamped below Nyquist and pre-warped. The top stop is exactly 0 (out of circuit) and is never pre-warped.""" if position >= 1.0: return 0.0 corner = _component.macro_value(self._MACRO_RANGES[TONE_I], position) return nominal_damping_hz(self._hz(corner), self._sample_rate) def _cut_hz(self, position): """Macro 8's position -> the node's `cut_hz`: the corner the loop high-pass achieves, clamped and pre-warped. The bottom stop is exactly 0 (out of circuit).""" if position <= 0.0: return 0.0 corner = _component.macro_value(self._MACRO_RANGES[CUT_I], position) return nominal_cut_hz(self._hz(corner), self._sample_rate) def _cross_and_pan(self): """(cross_feed, input_pan) for Spread and First Side. A one-channel node has no second lane: anything but (0, 0) there silences its loop (dossier section 7.1), so Spread and First Side are inert.""" if self._channel_count == 1: return 0.0, 0.0 spread = _between(self._value(SPREAD_I), 0.0, 1.0) if self._macros[SIDE_I] >= 0.5: return spread, spread return spread, -spread def _synced_ms(self): """Division x the host's beat, or `None` with no host transport (the static one), where Time stays where the knob is.""" transport = self._transport if transport is _component.static_transport: return None state = transport() if callable(transport) else transport # A host whose tempo is not a finite positive number (0, None, a # negative, NaN or infinity) leaves Time on the knob, as the static # transport does. `not bpm > 0` catches NaN, and `bpm * 0` is NaN # for infinity. bpm = float(state[2] or 0.0) if not bpm > 0.0 or bpm * 0.0 != 0.0: return None index = int(round(self._value(DIVISION_I))) index = min(len(DIVISION_BEATS) - 1, max(0, index)) return DIVISION_BEATS[index] * 60000.0 / bpm # -- applying ------------------------------------------------------ def _apply_macro(self, index, position): if index == TIME_I and not self._seeding and not ( self._time_exact is not None and abs(position - self._time_seed) <= ECHO_TOLERANCE): # A host that reads Time back and writes the same position # (`set_macro(0, get_macro(0))`) keeps the constructor's exact # Time; any other position drops it. self._time_exact = None if not self._deferred: self._refresh() def _apply_positions(self, positions, patch_index): """Apply a patch (or a rack's restore) whole, then refresh the node once. A refresh per macro would read Time against the outgoing patch's Sync.""" self._deferred = True try: _component.Component._apply_positions(self, positions, patch_index) finally: self._deferred = False self._refresh()
[docs] def reset(self): _component.Component.reset(self) self._fresh = False
def _time_ms(self): """The Time the audio path plays, before it is landed: Division x the beat with Sync on and a host tempo, else the constructor's exact Time until macro 0 moves, else the knob. Clamped at `max_time_ms`, and the knob moved to show the clamp.""" span = self._MACRO_RANGES[TIME_I] synced = None if self._macros[SYNC_I] >= 0.5: synced = self._synced_ms() if synced is not None: self._time_exact = None time_ms = self._clamp_ms(synced) self._macros[TIME_I] = _component.macro_position(span, time_ms) return time_ms if self._time_exact is not None: return self._time_exact time_ms = _component.macro_value(span, self._macros[TIME_I]) clamped = self._clamp_ms(time_ms) if clamped != time_ms: self._macros[TIME_I] = _component.macro_position(span, clamped) return clamped def _refresh(self): rate = self._sample_rate self._frames = max(1, whole_frames(self._time_ms(), rate)) self._node_ms = self._node_time_ms(self._frames) if self._fresh or self._frames > self._reach: self._reach = self._frames # Both out stops are exactly 0, and the Feedback is handed as set. # Since audiodsp v0.6.3rc1 the node keeps an out low-pass's state on # the tap and an out high-pass's at zero (#158, #159), and lands a # low-pass that has stopped moving (#157). damping = self._tone_damping(self._macros[TONE_I]) cut = self._cut_hz(self._macros[CUT_I]) feedback = _between(self._value(FEEDBACK_I), 0.0, FEEDBACK_MAX) self._feedback = feedback self._damping = damping self._cut = cut cross, pan = self._cross_and_pan() self._delay.set( delay_slew=SLEW, delay_ms=self._node_ms, feedback=feedback, mix=_between(self._value(MIX_I), 0.0, 2.0), damping_hz=damping, cut_hz=cut, cross_feed=cross, input_pan=pan) @property def tail_samples(self): """Frames until the output is exactly zero once the input stops, as an upper bound. `laps_to_zero(f, excess)` laps, each at most one frame longer than the longest delay the read head may be at (the read interpolates towards the next older frame), plus the Tone low-pass's memory. While a walk falls, that is the Time it is walking from, until a reset lands the head. The cross-feed hands each lane a convex mix of the two lanes' loop values (`audiodsp_feedback_delay.c:581-589`), so the per-lap argument holds at every Spread. With Repeat Cut in, the laps are counted `CUT_LAP_FACTOR` times, as `DigitalDelay` counts them: the high-pass can lift a lap's peak above the last one's, and that margin is measured, not derived.""" self._check_live() return self._tail_bound() def _tail_bound(self): """`tail_samples` without the liveness check: a plain method, so a subclass can reach it on MicroPython, whose `property` has no `fget`.""" memory, excess = tone_excess(self._damping, self._sample_rate) laps = laps_to_zero(self._feedback, excess) if self._cut > 0.0: laps *= CUT_LAP_FACTOR return int(laps * (self._reach + 1 + memory))