# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`MultiTapDelay` - one recording read by several heads on a fixed grid.
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. How it works, and why, is in the docstrings of `_route`, `_wire` and
`_resync` below.
"""
VENDOR = "PyDevices"
from array import array
import math
import struct
from . import _component
from .chorus import nominal_damping_hz
# DigitalDelay's tail arithmetic, reused rather than copied: the lap node
# is the same node and rounds the same way.
from .digitaldelay import laps_to_zero, whole_frames
import audiocore
try:
import audiodelays
import audiomixer
except ImportError: # pragma: no cover - a bare build
audiodelays = None
audiomixer = None
try:
import audioecho
import audioroute
except ImportError: # pragma: no cover - a stock board
audioecho = None
audioroute = None
#: Section 6's spans, fixed on every instance.
TIME_MIN_MS = 20.0
TIME_MAX_MS = 400.0
HEADS_MIN = 3
HEADS_MAX = 8
FEEDBACK_MAX = 0.95
TONE_MIN_HZ = 800.0
TONE_MAX_HZ = 16000.0
#: Tilt's span in dB from head 1 to head K at |Tilt| = 1 (ours).
TILT_DB = 12.0
#: `max_lap_ms`: 400 ms x four heads by default, and never under 540 ms,
#: where every Heads keeps Time alive and its span at 3.33 : 1 or more.
MAX_LAP_MS = 1600.0
MIN_LAP_MS = 540.0
#: The block every node renders, in frames.
BLOCK = 256
#: How far the tap node's own timeline runs behind the dry, in frames, and
#: so how much shorter than k n1 each head's offset is handed (`_route`).
#: Every offset k n1 - LAG must be at least one frame: an offset of 0 reads
#: the line a whole lap back, and a negative one is a position the node
#: refuses. The shortest head is Time's 20 ms, and the lap clamp never
#: lands n1 below it, so that holds exactly where 20 ms lands on more than
#: LAG frames: at MIN_SAMPLE_RATE and above (257 frames at 12 825 Hz, 441
#: at 22.05 kHz). The class refuses a lower rate at construction.
LAG = BLOCK
#: The lowest sample rate the class accepts: the least whole rate at which
#: Time's 20 ms lands on more than LAG frames, floor(20 fs / 1000 + 0.5).
MIN_SAMPLE_RATE = 12825
#: S1's `Head Combinations for Each Mode`, modes 1-11. Mode 12 is every
#: head on the plain grid (section 8.3), so it is not in the table.
HEAD_SETS = ((1,), (2,), (3,), (1, 2), (2, 3), (1, 3), (1, 2, 3), (1, 4),
(3, 4), (1, 3, 4), (1, 2, 4))
#: Division's sixteen note values, in quarter-note beats, rising: 1/32,
#: 1/16T, 1/32., 1/16, 1/8T, 1/16., 1/8, 1/4T, 1/8., 1/4, 1/2T, 1/4., 1/2,
#: 1/1T, 1/2., 1/1 (`DigitalDelay`'s).
DIVISION_BEATS = (0.125, 1.0 / 6.0, 0.1875, 0.25, 1.0 / 3.0, 0.375, 0.5,
2.0 / 3.0, 0.75, 1.0, 4.0 / 3.0, 1.5, 2.0, 8.0 / 3.0, 3.0,
4.0)
#: The tap node truncates every sample it sends round toward zero; the
#: tail bound reckons with a decay this much larger, relatively, so a
#: board's single-precision arithmetic can only lengthen it.
DECAY_MARGIN = 2.0 ** -16
(TIME_I, PATTERN_I, HEADS_I, FEEDBACK_I, MIX_I, TILT_I, TONE_I, SYNC_I,
DIVISION_I) = range(9)
[docs]
def f32(value):
"""`value` rounded to single precision: exact emulation on a desktop,
the identity on a board, whose float already is one."""
return struct.unpack("<f", struct.pack("<f", value))[0]
def _f32_step(value, up):
"""The next single-precision value above (or below) a positive one."""
bits = struct.unpack("<I", struct.pack("<f", value))[0]
bits += 1 if up else -1
return struct.unpack("<f", struct.pack("<I", bits))[0]
[docs]
def lap_node_frames(value_ms, sample_rate):
"""The lap node's own arithmetic for a `delay_ms` it is handed,
`value * rate / 1000.0f` in single precision
(`audiodsp_feedback_delay.c:148` at v0.6.3rc1)."""
return f32(f32(f32(value_ms) * f32(sample_rate)) / f32(1000.0))
[docs]
def lap_node_ms(lap, sample_rate):
"""The `delay_ms` the lap node is handed for a lap of `lap` frames: the
least single-precision value whose frames, the node's way, are at or
over `lap`. From float32(lap 1000 / fs), step up one float32 unit while
the frames are under; if the start is already over, step down while
the next value down is still at or over."""
value = f32(lap * 1000.0 / sample_rate)
frames = lap_node_frames(value, sample_rate)
while frames < lap:
value = _f32_step(value, True)
frames = lap_node_frames(value, sample_rate)
while frames > lap:
lower = _f32_step(value, False)
if lap_node_frames(lower, sample_rate) < lap:
break
value = lower
frames = lap_node_frames(value, sample_rate)
return value
[docs]
def head_set(mode, heads, table=HEAD_SETS):
"""Pattern mode 1-12 on a grid of `heads` heads -> the heads that
sound, rising. Mode 12 is every head 1 ... K."""
if mode >= 12:
return tuple(range(1, heads + 1))
return tuple(k for k in table[mode - 1] if k <= heads)
[docs]
def head_levels(selected, heads, tilt):
"""Tilt's law: a straight line in dB across the grid, `TILT_DB` x Tilt
from head 1 to head K, far heads louder for Tilt > 0, with the loudest
sounding head at exactly 1.0."""
db = [TILT_DB * tilt * (k - 1) / (heads - 1) for k in selected]
top = max(db)
return tuple(1.0 if value == top else 10.0 ** ((value - top) / 20.0)
for value in db)
[docs]
def landed(time_ms, heads, sample_rate, max_lap_ms):
"""(n1, P) in frames: the base on the nearest whole frame, clamped so
the lap P = K n1 fits `max_lap_ms`."""
n1 = max(1, whole_frames(time_ms, sample_rate))
cap = int(math.floor(max_lap_ms * sample_rate / 1000.0)) // heads
if n1 > cap:
n1 = cap
return n1, heads * n1
[docs]
def trunc_laps(decay):
"""Laps of the tap node's own loop to exact zero from full scale. Once
the input stops it writes `(int32_t)(delayed * decay)`
(`audiodsp_multitap.c:32` at v0.6.3rc1), which truncates toward zero, so a peak x
goes to floor(x d) < x and the count is finite at every decay."""
decay = min(max(float(decay), 0.0), 1.0) * (1.0 + DECAY_MARGIN)
laps = 0
peak = 32768
while peak > 0:
laps += 1
image = int(math.floor(decay * peak))
if image >= peak:
image = peak - 1
peak = image
return laps
[docs]
def tone_excess(damping_hz, sample_rate):
"""`DigitalDelay._tone_excess` for a pre-warped `damping_hz`: (memory
frames, relative excess) of the lap node's loop low-pass, (0, 0.0)
with it out."""
if damping_hz <= 0.0:
return 0, 0.0
per_frame = 2.0 * math.pi * damping_hz / sample_rate
coefficient = 1.0 - math.exp(-per_frame)
frames = int(math.ceil(32.0 * math.log(2.0) / per_frame))
return frames, 2.0 ** -17 + 2.0 ** -24 / coefficient
def _number(value, default):
"""`value` as a float, or `default` for NaN or something that is not a
number."""
try:
value = float(value)
except (TypeError, ValueError):
return float(default)
if value != value:
return float(default)
return value
[docs]
class MultiTapDelay(_component.Component):
"""A multi-head echo: one recording read by several heads on a grid.
The heads of a multi-head tape echo, after the Roland Space Echo's
multi-head modes: your dry signal passes untouched, and a pattern of
echoes follows it.
**The controls.**
Time is the gap to head 1, landed on a whole frame, and head k sounds at
exactly k times that gap.
Heads is how many heads the grid has, and the pattern repeats once per
trip past the farthest of them.
Pattern picks which heads sound, from the twelve positions of the Roland
RE-202's mode selector.
Its last position sounds every head on the grid, not the RE-202's
unpublished positions.
The lap is the farthest head on the grid, sounded or not, so heads past
the ones a position sounds lengthen the lap without sounding.
Feedback sends the pattern round again, each lap quieter.
Repeat Tone darkens each lap a little more than the one before, once per
lap, never once per head.
Tilt leans the pattern's levels towards the near heads or the far ones.
Up to Mix 1 the dry passes at unity, and at Mix 2 the echoes play alone.
At unity the dry is exact to the sample, mono and stereo, right up to
the rails, on every interpreter.
Keep the input under -6 dBFS and the defaults and patches stay off the
rails.
Mix 0 is a wire.
Sync locks Time to Division of the host's beat, clamped to Time's span.
With no host tempo, Time stays on the knob.
Time runs from 20 to 400 ms, Heads from 3 to 8, Feedback from 0 to 0.95
and Mix from 0 to 2.
`max_lap_ms` (1600 by default, 540 at least) caps the lap: where a grid
would pass it, Time comes down to fit.
A click comes out on the frame it went in: there is no latency.
A one-channel source gets the same effect on its one channel.
The sample rate must be at least 12 825 Hz: below it the constructor
raises `ValueError`.
**Reset, Mix at zero and the tail.**
The lines are not fed while Mix is 0, so a return from Mix 0 starts both
lines empty.
`reset()` empties both lines and returns to patch 0.
Neither a reset nor a trip to Mix 0 drops a frame of your source or
plays one twice, whatever size of buffer it hands out.
`tail_samples` is an upper bound on how long the echoes take to reach
exact zero once your input stops.
The tail rings on while your source hands back nothing.
**On a board.**
Measured at v0.6.3, patch 4 costs 5.567 ms a block on the ESP32-S3,
where a block lasts 5.333 ms, so it needs a P4-class board: the ESP32-P4
runs it in 3.865 ms.
Patch 3 costs 4.163 ms on the ESP32-S3, inside the 4.267 ms budget, and
may need a P4-class board too, especially when the board is running
anything else.
**Limits shared by the family.**
A control that jumps makes the output step: move it in small steps from
the host if you need it smooth.
"""
NAME = 'MultiTapDelay'
DISPLAY_NAME = 'Multi-Tap Delay'
CATEGORIES = ('Delay',)
VERSION = '0.1.0'
TIER = _component.AUDIODSP
REQUIRES = ("audioecho", "audioroute")
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, the defaults rail on
#: a 100 Hz square.
INPUT_CEILING_DBFS = -6
MACRO_LABELS = ("Time", "Pattern", "Heads", "Feedback", "Mix", "Tilt",
"Repeat Tone", "Sync", "Division")
MACRO_MODES = {
0: "UNIPOLAR",
1: "UNIPOLAR",
2: "UNIPOLAR",
3: "UNIPOLAR",
4: "UNIPOLAR",
5: "BIPOLAR",
6: "UNIPOLAR",
7: "TOGGLE",
8: "UNIPOLAR",
}
_MACRO_RANGES = (
(TIME_MIN_MS, TIME_MAX_MS, "log"), # 0 Time, the base head t1, ms
(0.0, 11.0), # 1 Pattern index -> mode 1-12
(float(HEADS_MIN), float(HEADS_MAX)), # 2 Heads K
(0.0, FEEDBACK_MAX), # 3 Feedback, the lap level
(0.0, 2.0), # 4 Mix; dry at unity to 1
(-1.0, 1.0), # 5 Tilt
(TONE_MIN_HZ, TONE_MAX_HZ, "log"), # 6 Repeat Tone, Hz; top = out
(0.0, 1.0), # 7 Sync
(0.0, 15.0), # 8 Division index
)
_MACRO_UNITS = {0: "ms", 6: "Hz"}
#: `_component.macro_of` of the dossier's section 6 settings; patch 0
#: is the constructor's defaults on the grid.
PATCHES = {
0: ("Three Heads, Even", (85, 69, 0, 60, 22, 64, 68, 0, 25)),
1: ("Three Heads, Even - lean", (85, 69, 0, 60, 22, 64, 127, 0, 25)),
2: ("Two Heads, Near Loudest", (93, 35, 25, 67, 22, 32, 68, 0, 25)),
3: ("Four Heads, Far Loudest", (55, 127, 25, 67, 22, 96, 78, 0, 25)),
4: ("Eight Heads, Dense", (29, 127, 127, 74, 19, 64, 56, 0, 25)),
5: ("One Head, Long Repeats", (76, 23, 0, 94, 22, 64, 48, 0, 25)),
6: ("Triplet Grid, Synced", (85, 69, 0, 60, 22, 64, 68, 127, 34)),
}
#: The head-set table a Pattern position reads (S1's, modes 1-11).
_SETS = HEAD_SETS
def _build(self, time_ms=150.0, pattern=7, heads=3, feedback=0.45,
mix=0.35, tilt=0.0, tone_hz=4000.0, sync=False, division=3,
max_lap_ms=MAX_LAP_MS, patch=None):
rate = self._sample_rate
channels = self._channel_count
self._check_rate(rate)
max_lap_ms = _number(max_lap_ms, MAX_LAP_MS)
if max_lap_ms > MAX_LAP_MS:
max_lap_ms = MAX_LAP_MS
if max_lap_ms < MIN_LAP_MS:
max_lap_ms = MIN_LAP_MS
self._max_lap_ms = max_lap_ms
# Constructor values in the macros' own units. A value outside a
# span clamps to the nearer stop (`macro_position` does that), NaN
# takes the default, and a Time of 0 or less is the bottom of its
# span, which a log knob cannot seed. Repeat Tone at 0 or less is
# its out stop, as it is on the node.
time_ms = _number(time_ms, 150.0)
if not time_ms > 0.0:
time_ms = TIME_MIN_MS
tone_hz = _number(tone_hz, 4000.0)
if not tone_hz > 0.0:
tone_hz = TONE_MAX_HZ
pattern = int(math.floor(_number(pattern, 7) + 0.5))
pattern = min(12, max(1, pattern))
heads = int(math.floor(_number(heads, HEADS_MIN) + 0.5))
heads = min(HEADS_MAX, max(HEADS_MIN, heads))
#: What the nodes were last handed, so a move writes only what it
#: changes (a `delay_ms` write re-bases the tap node's line).
self._tap_ms = None
self._taps = None
self._n1 = 1
self._lap = HEADS_MIN
self._heads = heads
self._selected = ()
self._levels = ()
self._lap_ms = 0.0
self._feedback = 0.0
self._lap_mix = 0.0
self._decay = 0.0
self._damping = 0.0
self._lean = False
#: Which node the tap node is playing: None until the graph is
#: wired, then True (the Splitter's tap, the lean graph) or False
#: (the lap node).
self._plugged = None
#: True once the Mixer's voices and the tap node have been played,
#: which happens the first time Mix is above 0.
self._wired = False
#: True while Mix 0 has the output port on the borrowed source.
self._at_source = False
self._deferred = False
#: True inside `reset()`, where a `play()` must not reach the
#: borrowed source (`_route`).
self._resetting = False
# The input adapter re-blocks whatever the app hands the class into
# the palette's own blocks, which `audioroute.Splitter` needs: a
# bare `audiocore.RawSample` hands back its whole array at once. It
# is also what Mix 0 hands out (`_route`), so the source is read
# through it, and only through it, at every Mix: whatever part of a
# source buffer it holds plays next, whichever way the output goes.
adapter = audioroute.MidSide(width=1.0, sample_rate=rate,
channel_count=channels)
adapter.play(self._source)
# A MidSide with no source hands out one block of zeros per pull and
# never finishes: what the tap node primes from, and what the
# Splitter reads while the graph is wired and while `_resync` swaps
# tap 1's pending block for zeros (`_route`).
self._hush = audioroute.MidSide(width=1.0, sample_rate=rate,
channel_count=channels)
# The Splitter reads the adapter through a port, so `_wire` and
# `_resync` can point it at `_hush` without touching the adapter:
# a MidSide's `play()` drops the frames it holds, and the unread
# rest of a long source buffer has to stay where it is.
self._in = audioroute.Port(adapter)
split = audioroute.Splitter(self._in, taps=2)
dry = split.tap(0)
tap1 = split.tap(1)
self._silence = audiocore.RawSample(
array("h", bytes(2 * 2 * channels)),
sample_rate=rate, channel_count=channels)
# The tap node always plays this port; the graph's two shapes are
# the port pointed at the lap node or at the Splitter's tap, and a
# re-point is one store that pulls nothing.
self._feed = audioroute.Port(self._hush)
# The laps: the lap node recirculates at P with the darkening in
# its loop. Its `mix` is the Feedback, so its output is the dry plus
# Feedback x the loop: lap 1 at unity, lap n at Feedback^(n - 1).
self._fd = audioecho.FeedbackDelay(
sample_rate=rate, channel_count=channels,
max_delay_ms=max_lap_ms + 1.0,
delay_ms=max_lap_ms * 0.5, feedback=0.0, mix=0.0,
damping_hz=0.0, cut_hz=0.0, delay_slew=0.0)
# The heads: wet only (`mix` 1.0 in its 0..1 convention, doubled to
# 2 in the node), 256 frames a pull.
self._tapnode = audiodelays.MultiTapDelay(
max_delay_ms=int(math.ceil(max_lap_ms)) + 1,
delay_ms=max_lap_ms * 0.5, decay=0.0, mix=1.0,
taps=((1.0, 1.0),), buffer_size=BLOCK * channels * 2,
sample_rate=rate, bits_per_sample=16, samples_signed=True,
channel_count=channels)
self._mixer = audiomixer.Mixer(
voice_count=2, buffer_size=BLOCK * channels * 4,
channel_count=channels, bits_per_sample=16, samples_signed=True,
sample_rate=rate)
# The tail: a MidSide at width 1 is the identity, byte for byte, and
# its reset forwards nothing upstream. A host that resets the
# output (a mixer voice's `play()` does) would otherwise reach the
# Mixer, whose voices re-prime from the Splitter's taps and throw
# away the source's block they already hold (`_route`).
self._tail = audioroute.MidSide(width=1.0, sample_rate=rate,
channel_count=channels)
self._tail.play(self._mixer)
# What Mix 0 hands out (`_bypass`): the input adapter behind one
# more width-1 MidSide, byte for byte, whose reset forwards nothing,
# so a host resetting the output at Mix 0 leaves the adapter's
# unread frames where they are, as the tail does above Mix 0. The
# adapter hands it whole 256-frame blocks, so it never holds any.
self._through = audioroute.MidSide(width=1.0, sample_rate=rate,
channel_count=channels)
self._through.play(adapter)
self._adapter = adapter
self._split = split
self._dry = dry
self._tap1 = tap1
# The Mixer and the Splitter's side are not reset: a Mixer voice
# resets its source recursively, which would reach the borrowed
# source. The tap node's reset empties its line through
# `audiocore.reset_buffer`; the lap node's `clear` empties its line
# and loop filters. The feed port is not reset either: it would
# forward the reset to whatever it points at. Nor is the input
# adapter: what it holds is the source's own audio, not yet heard,
# and a reset that dropped it would put every later frame early (a
# source in 512-frame buffers, 256 frames) or play a bare
# `RawSample` again from its first frame (`DeEsser` owns its
# adapter the same way).
self._own(self._through)
self._own(self._tail)
self._own(self._mixer, reset=False)
self._own(self._tapnode)
self._own(self._feed, reset=False)
self._own(self._fd, reset=self._fd.clear)
self._own(dry, reset=False)
self._own(tap1, reset=False)
self._own(split, reset=False)
self._own(self._in, reset=False)
self._own(adapter, reset=False)
self._own(self._hush, reset=False)
self._own(self._silence, reset=False)
self._output = self._tail
self._ready = False
self._init_macros((time_ms, float(pattern - 1), float(heads),
feedback, mix, tilt, tone_hz,
1.0 if sync else 0.0, _number(division, 3)),
patch)
self._ready = True
self._route()
def _check_rate(self, rate):
"""Refuse, before anything is built, a rate at which the shortest
head would be handed an offset of 0 or less (`LAG`)."""
if whole_frames(TIME_MIN_MS, rate) <= LAG:
raise ValueError(
"MultiTapDelay needs a sample rate of at least %d Hz (got "
"%d): below it the 20 ms head is %d frames or fewer, which "
"the tap node's one-block lag cannot place"
% (MIN_SAMPLE_RATE, rate, LAG))
# -- the maps ------------------------------------------------------
def _value(self, index):
return _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
def _pattern_mode(self):
"""Pattern's position -> mode 1-12: index floor(11 p + 0.5)."""
index = int(math.floor(11.0 * self._macros[PATTERN_I] + 0.5))
return min(12, max(1, index + 1))
def _heads_count(self):
"""Heads' position -> K = floor(3 + 5 p + 0.5), 3-8."""
count = int(math.floor(HEADS_MIN + (HEADS_MAX - HEADS_MIN)
* self._macros[HEADS_I] + 0.5))
return min(HEADS_MAX, max(HEADS_MIN, count))
def _head_set(self, mode, heads=None):
return head_set(mode, self._heads_count() if heads is None
else heads, type(self)._SETS)
def _tone_damping(self):
"""Repeat Tone -> the lap node's `damping_hz`, pre-warped so one
pass is -3 dB at the knob's corner after the Nyquist clamp. The
top stop is exactly 0: out of circuit, the lean graph."""
if self._macros[TONE_I] >= 1.0:
return 0.0
return nominal_damping_hz(self._hz(self._value(TONE_I)),
self._sample_rate)
def _synced_ms(self):
"""Division x the host's beat, or `None` with no host transport
(the static one) or a tempo that is not a finite positive number,
where Time stays on the knob."""
transport = self._transport
if transport is _component.static_transport:
return None
state = transport() if callable(transport) else transport
try:
bpm = float(state[2] or 0.0)
except (TypeError, ValueError, IndexError):
return None
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
def _tap_node_ms(self, lap):
"""The tap node's `delay_ms` for a lap of `lap` frames: half a
frame over, so its truncation lands on `lap` in either float
width."""
return (lap + 0.5) * 1000.0 / self._sample_rate
def _tap_positions(self, selected, n1, lap):
"""Head k at (k n1 - LAG + 0.5) / P, so the node's truncation of
the offset lands on k n1 - LAG: the tap node reads its input one
block after the dry has played it (`_route`), so each head sounds
at exactly k n1 against the dry."""
return tuple((k * n1 - LAG + 0.5) / lap for k in selected)
def _lap_node_ms(self, lap):
return lap_node_ms(lap, self._sample_rate)
# -- applying ------------------------------------------------------
def _apply_macro(self, index, position):
del index, position
if not self._deferred:
self._refresh()
def _apply_positions(self, positions, patch_index):
"""Apply a patch (or a rack's restore) whole, then refresh once, so Time is never
read against the outgoing patch's Sync and the graph re-plugs at
most once."""
self._deferred = True
try:
_component.Component._apply_positions(self, positions,
patch_index)
finally:
self._deferred = False
self._refresh()
def _refresh(self):
rate = self._sample_rate
if self._macros[SYNC_I] >= 0.5:
synced = self._synced_ms()
if synced is not None:
synced = min(TIME_MAX_MS, max(TIME_MIN_MS, synced))
self._macros[TIME_I] = _component.macro_position(
self._MACRO_RANGES[TIME_I], synced)
heads = self._heads_count()
n1, lap = landed(self._value(TIME_I), heads, rate, self._max_lap_ms)
selected = self._head_set(self._pattern_mode(), heads)
levels = head_levels(selected, heads, self._value(TILT_I))
taps = tuple(zip(self._tap_positions(selected, n1, lap), levels))
feedback = self._value(FEEDBACK_I)
feedback = min(FEEDBACK_MAX, max(0.0, feedback))
lean = self._macros[TONE_I] >= 1.0
damping = self._tone_damping()
# The Feedback is handed as set. Up to audiodsp v0.6.2 the lap
# node's loop low-pass could hold a small value for ever a hair
# either side of 1 - 0.5 / k, and this class stepped the Feedback
# clear of those windows; since v0.6.3rc1 the node lands a damping
# state that has stopped moving (audiodsp#157), and `laps_to_zero`
# counts that landing's one extra lap.
loop = feedback
decay = feedback if lean else 0.0
tap_ms = self._tap_node_ms(lap)
lap_ms = self._lap_node_ms(lap)
if tap_ms != self._tap_ms:
self._tapnode.delay_ms = tap_ms
self._tap_ms = tap_ms
if taps != self._taps:
self._tapnode.taps = taps
self._taps = taps
self._tapnode.decay = decay
self._fd.set(delay_ms=lap_ms, feedback=loop, mix=loop,
damping_hz=damping, cut_hz=0.0, delay_slew=0.0)
#: The lap node's `mix`, which is its Feedback (dossier section 4).
self._lap_mix = loop
mix = self._value(MIX_I)
self._mixer.voice[0].level = self._dry_level(mix)
self._mixer.voice[1].level = min(1.0, mix)
self._n1 = n1
self._lap = lap
self._heads = heads
self._selected = selected
self._levels = levels
self._lap_ms = lap_ms
self._feedback = loop
self._decay = decay
self._damping = damping
self._lean = lean
self._route()
def _dry_level(self, mix):
"""The dry voice's level, min(1, 2 - Mix). A Mixer voice scales by
(sample x Q15 level) >> 15 and a level of 1.0 is Q15 32768, so unity
passes every sample through exactly, mono and stereo, on every
interpreter at AUDIODSP_PIN."""
return min(1.0, 2.0 - mix)
def _route(self):
"""Where the output port points, and what the tap node reads.
Mix 0 hands the input adapter out through the port (`_bypass`, by
way of `_through`), a width-1 MidSide that passes the source byte
for byte, so it is a wire on every interpreter without a Mixer
voice in the way. The source is read through the adapter at every
Mix, so whatever part of a buffer it holds plays next either way.
Nothing is pulled through the graph while the port is on the
adapter, so nothing here may prime from it then: a `play()` would
take a block away from the port. `_route_around` marks the graph
stranded, and the return clears it through `_rejoin` (the base's
stale-block helper) before `_resync`; the adapter is not reset by
either, since it is registered without one.
**The tap node runs one block behind the dry.** A Mixer voice's
`play()` primes one block from its source, and the voices hand
that block out on the first pull, so whatever the tap node renders
at wiring is rendered with the settings of that moment. If that
were the source's first block, a Time or Heads move before the
first pull would re-base the tap node's planar line under it, and
in stereo the right lane would lose its first block's heads. So
the tap node primes a block of zeros instead (it plays `_feed`,
pointed at `_hush`), renders those zeros for the wet voice's
prime, and only then is the port pointed at the lap node or the
Splitter's tap, which pulls nothing. The source's first block
reaches the tap node's line on the second pull, with whatever the
settings are by then; every head is handed LAG frames short
(`_tap_positions`), so it still sounds at exactly k n1 against the
dry, and the Splitter's tap 1 always holds the one block the tap
node has not reached yet.
Crossing Repeat Tone's out stop re-points the port (and empties
the lap node going in), which pulls nothing, so any number of
crossings between two pulls leaves the wet where it was against the
dry. Coming back from Mix 0, and in `reset()`, `_resync` empties
both lines and swaps that one pending block on tap 1 for a block of
zeros (the Splitter reads `_hush` for one pull of each tap), so no
audio from before either reaches the lines, nothing is taken from
the source, and a second or third `_resync` before the next pull
leaves exactly what the first did.
**Every wiring is quiet** (`_wire`): the Splitter reads `_hush`
while the voices prime, and one pull of the Mixer hands the primed
zeros out, so the graph is left as it is between two pulls
mid-stream and nothing is taken from the source. Up to re-audit fix
round 1 a wiring outside `reset()` primed the dry voice with the
source's first block, and a `_resync` before the first pull then
dropped that block's heads (tap 1 held it, not yet heard) and, in
mono on a native build, refilled the tap's own buffer the voice was
pointing into, so the dry's first 256 samples played as zeros.
Where `audiocore.get_buffer` is left out (CircuitPython's default
board builds), every pull here goes through `_pull_node`: a scratch
mixer voice primes one block through a width-1 MidSide standing on
the node, which moves the node exactly as `get_buffer` would. So
the wiring is quiet and `_resync` swaps tap 1's block on every
build, and a board renders what a desktop does, byte for byte.
"""
if not self._ready:
return
if self._macros[MIX_I] <= 0.0:
self._route_around(self._bypass())
self._at_source = True
return
if not self._wired:
self._wire(self._quiet_wiring())
self._wired = True
elif self._at_source or self._resetting:
# The base's stale-block helper clears what `_route_around`
# left (both lines and the tail); `_resync` clears the lines
# again, which changes nothing, and swaps tap 1's block.
self._rejoin()
self._resync()
elif self._lean != self._plugged:
self._plug(self._lean)
self._at_source = False
self._output = self._tail
[docs]
def reset(self):
"""Empty both lines and restore patch 0, without pulling the
borrowed source (`_route`)."""
self._check_live()
self._resetting = True
try:
_component.Component.reset(self)
finally:
self._resetting = False
def _target(self, lean):
"""What the feed port points at: the Splitter's tap (the lean
graph, the tap node's own `decay` making the laps) or the lap
node."""
return self._tap1 if lean else self._fd
def _bypass(self):
"""What Mix 0 hands out: the input adapter, a width-1 MidSide that
passes the source byte for byte in the palette's blocks, behind
`_through`, which keeps a host's reset off it. Pointing the output
at the source itself would skip whatever part of a source buffer
the adapter holds (a source in 512-frame buffers jumps 256 frames
ahead) and hand a bare `RawSample` out again from its first
frame."""
return self._through
def _quiet_wiring(self):
"""Whether `_wire` primes the voices from `_hush`: always, since
`_pull_node` hands the primed zeros out on every build."""
return True
def _wire(self, quiet=False):
"""Play every node once, the first time Mix is above 0 (`_route`).
`quiet`: the Splitter reads `_hush` while the voices prime, so the
dry voice primes zeros and tap 1's pending block is zeros, and one
pull of the Mixer hands those zeros out. Nothing is taken from the
source, and the graph is left as it is between two pulls
mid-stream: no voice holds a block, the dry tap is caught up, and
tap 1 is one block behind it. A voice that still held its primed
block would point into a mono `SplitterTap`'s own buffer, which
`_resync` refills, and tap 1 would hold audio whose dry had not
played yet, which `_resync` drops."""
self._fd.play(self._tap1)
self._feed.play(self._hush)
self._tapnode.play(self._feed, loop=False)
if quiet:
self._in.play(self._hush)
_component.open_level_gates(self._mixer, self._mixer.voice,
self._silence)
self._mixer.voice[0].play(self._dry, loop=False)
self._mixer.voice[1].play(self._tapnode, loop=False)
self._feed.play(self._target(self._lean))
self._plugged = self._lean
if quiet:
self._in.play(self._adapter)
self._pull_node(self._mixer)
def _resync(self):
"""Empty both lines and swap the block tap 1 holds for the tap node
for a block of zeros, the same however many times it runs between
two pulls (`_route`).
With the Splitter reading `_hush`, one pull of tap 1 then one of the
dry tap always leaves tap 0 caught up and tap 1 one block of zeros
behind it. From the usual state (tap 1 holding the source's last
block, tap 0 caught up) the first pull drops that block and the
second writes the zeros. From the state this leaves, a second call
reads those zeros back and writes them again, so nothing of the
source is taken and the tap node stays one block behind the dry.
A quiet wiring (`_wire`) leaves tap 1 holding zeros and no voice
holding a block, so right after construction this is that state
too: the dry tap's pull refills no buffer a voice still points
into, and what tap 1 drops was never audio."""
self._fd.clear()
audiocore.reset_buffer(self._tapnode)
self._in.play(self._hush)
try:
self._pull_node(self._tap1)
self._pull_node(self._dry)
finally:
self._in.play(self._adapter)
self._feed.play(self._target(self._lean))
self._plugged = self._lean
def _plug(self, lean):
"""Point the feed port at the Splitter's tap or at the lap node,
emptying the lap node going in. A store: nothing is pulled, so the
dry is never disturbed and the wet does not move against it."""
if not lean:
self._fd.clear()
self._feed.play(self._target(lean))
self._plugged = lean
# -- the contract's reads ------------------------------------------
@property
def tail_samples(self):
"""Frames until the output is exactly zero once the input stops,
as an upper bound.
Repeat Tone in: `laps_to_zero(f', excess) x (P + 1 + memory) + P`,
`DigitalDelay`'s bound for the lap node at the Feedback it is
handed, plus one lap for the tap node's line to be read out.
Repeat Tone out: `(trunc_laps(f) + 1) x P`, the tap node's own
truncating loop. Finite at every setting.
"""
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`."""
lap = self._lap
if self._macros[MIX_I] <= 0.0:
return 0
if self._lean:
return int((trunc_laps(self._decay) + 1) * lap)
memory, excess = tone_excess(self._damping, self._sample_rate)
laps = laps_to_zero(self._feedback, excess)
return int(laps * (lap + 1 + memory) + lap)