Source code for audioeffects.tapedelay

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

"""`TapeDelay` - a tape echo with two transports: the Roland RE-201's motor
and the Maestro EP-3's sliding head.

Your dry signal passes untouched, and the repeats follow it off a loop of
tape, each one a little darker than the last.

**Controls.** Time is the delay, from 20 to 1200 ms, and Feedback is how
much of each repeat goes round again, up to 0.99. Mix is the echo return:
the dry stays at unity up to Mix 1, Mix 2 is the repeats alone, and at Mix 0
the output is the input. Spacing is how far the worn head sits off the tape:
more spacing, darker repeats. Wow and Flutter are the transport's slow and
fast wobble. Record Level drives the tape harder, a soft squash on every
pass. Spread feeds each channel's repeats into the other, and does nothing
on a mono source. With Sync on, Time is Division of the host's beat; with no
host tempo, Time stays where the knob is.

**Two characters.** `character="varispeed"`, the default, is the RE-201:
Time moves the motor, so a Time move bends the pitch of everything on the
tape instead of clicking, then settles. Glide does nothing on this
character. `character="sliding-head"` is the EP-3: Time slides a head, so the pitch
bends only while the head moves, at the rate Glide sets, and the tape runs
at one speed, so the darkening does not follow Time. Glide 0 is an instant
slide, and its price is a click.

**Where the pitch bend stops.** A Time move made while the last one is still
bending takes its rate from the last Time you set, not from where the tape
has got to, so it does not telescope as a real motor would. A long rising
move, or a rising slide at the fastest Glides, can read more than 10 cents
off the ideal bend, because the node walks its read head in single
precision.

**The tape.** The wobble is periodic, not random. A Wow or Flutter move
glides in, whether it changes how deep the wobble is or the balance between
them: a new balance takes the wobble out and brings it back in the new
shape. The darkening follows
the tape's loss law only up to a band top that rises with the tape's speed.
Record Level has no memory: tape hysteresis is not modelled. The RE-201's
Bass and Treble are not here. Keep the input under -6 dBFS and the defaults
and patches stay off the rails.

**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. When your source
ends, the tail rings out as it would on silence.

**Latency, tail, portability.** Latency is zero samples: nothing looks ahead.
`tail_samples` is an upper bound on how long the output takes to reach exact
zero once your input stops, at every Feedback and Spread, stereo and mono.
Pass a lower `max_time_ms` for a shorter line: Time then stops at that
ceiling, and `get_macro(0)` shows where it stopped. The class needs
audiodsp's `audioecho`, and on a board without it construction raises
`ImportError`. `character` must be `"varispeed"` or `"sliding-head"`.

**Cost.** Measured at v0.6.2 at the default and every patch, the full class
costs 0.551-0.608 ms a block on the P4 and 1.056-1.093 ms on the S3, over the
budgets of 0.480 ms and 0.800 ms. Measured at v0.6.2, patch 8 on a class
built with `max_time_ms=800` costs 0.445-0.455 ms on the P4 and 0.781-0.797
ms on the S3, inside both budgets.
`reset()` returns to patch 0, so a host that wants the lean patch sets it
again after a reset.
"""

VENDOR = "PyDevices"

from array import array
import math

from . import _component
from .chorus import nominal_damping_hz

# DigitalDelay's tail and transport arithmetic, reused rather than copied:
# the same node rounds the same way in both classes.
from .digitaldelay import DIVISION_BEATS, laps_to_zero, whole_frames

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


CHARACTERS = ("varispeed", "sliding-head")
VARISPEED, SLIDING_HEAD = CHARACTERS

#: The Time map, fixed on every instance (dossier section 6): 20-1 200 ms.
TIME_MIN_MS = 20.0
TIME_MAX_MS = 1200.0

#: Glide is the time a full-range Time move takes on sliding-head; the
#: node's `delay_slew` is FULL_RANGE_MS / glide_ms (dossier section 6).
FULL_RANGE_MS = TIME_MAX_MS - TIME_MIN_MS

#: The Glide knob's span, log, with grid 0 the jump.
GLIDE_MIN_MS = 1200.0
GLIDE_MAX_MS = 12000.0

#: At slew 1 a rising Time stands the read head still. A constructor Glide
#: under 1 191.9 ms is pinned here; no grid position gets there (grid 1 is
#: 1 222.0 ms, slew 0.966).
SLEW_PIN = 0.99

#: The Glide knob's position for a constructor Glide faster than grid 1:
#: grid 1 itself, never grid 0, the jump (DigitalDelay's `GLIDE_FLOOR`).
GLIDE_FLOOR = 1.0 / 127.0

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

#: The line's headroom over `max_time_ms`: one frame for the node's
#: `line_frames - 2` clamp (`audiodsp_feedback_delay.c:148-150`) plus the
#: wow table's largest excursion, 3.096 ms at the Wow and Flutter stops,
#: rounded up (dossier Tier 3).
LINE_HEADROOM_MS = 5.0

#: S3 eq. (13)'s play gap and tape thickness, metres (dossier section 6).
GAP_M = 5e-6
THICK_M = 35e-6

#: The Spacing knob, micrometres, log.
SPACING_MIN_UM = 2.0
SPACING_MAX_UM = 20.0

#: The speed law (dossier section 6). Varispeed: 40 cm/s at Time 180 ms and
#: below, 12 cm/s at 600 ms and above, 40 x 180 / T between (fixed heads:
#: T is inversely v). Sliding-head: the Echoplex's roughly 8 ips.
V_FAST = 0.40
V_SLOW = 0.12
T_FAST_MS = 180.0
T_SLOW_MS = 600.0
V_SLIDING = 0.2032

#: The wow table: one period of TABLE_POINTS Q15 points at WOW_HZ, holding
#: the wow line at harmonic WOW_HARMONIC, the flutter line at
#: FLUTTER_HARMONIC and the drift at harmonics 1-9, amplitude 1/k, at
#: DRIFT_PHASES (dossier section 6).
#: TABLE_POINTS is not a cost lever. The node reads any length the same way,
#: and a shorter table silently kills the flutter: at 1 024 points harmonic
#: 512 sits on the table's Nyquist, at 256 it folds onto DC, and the Flutter
#: knob then writes the same table as Flutter 0 while T4 still reads two
#: lines, an interpolation image of the wow line (the 2026-09-28 cost study).
WOW_HZ = 0.01
TABLE_POINTS = 4096
WOW_HARMONIC = 72
FLUTTER_HARMONIC = 512
WOW_LINE_HZ = 0.72
FLUTTER_LINE_HZ = 5.12
DRIFT_PHASES = (0.37, 2.91, 5.02, 1.18, 4.40, 3.33, 0.84, 5.71, 2.26)
#: The drift's peak excursion, ms per cent of Wow.
DRIFT_PER_WOW_CENT_MS = 0.25
WOW_MAX_CENTS = 8.0
FLUTTER_MAX_CENTS = 4.0

(TIME_I, FEEDBACK_I, MIX_I, GLIDE_I, WOW_I, FLUTTER_I, RECORD_I, SPACING_I,
 SPREAD_I, SYNC_I, DIVISION_I) = range(11)

#: 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.
ECHO_TOLERANCE = 1e-6

#: The constructor defaults, which NaN falls back to.
DEFAULTS = (350.0, 0.45, 0.35, 6000.0, 2.0, 1.0, 0.2, 5.0, 0.0, 0.0, 6.0)


# -- the loss law -------------------------------------------------------------

[docs] def eq13_gain(k, spacing_m): """S3 eq. (13), one pass, as a linear gain at wavenumber `k` (rad/m): spacing e^(-k d), thickness (1 - e^(-k delta)) / (k delta) and gap |sinc(k g / 2)|, at `GAP_M` and `THICK_M`.""" spacing = math.exp(-k * spacing_m) kd = k * THICK_M thickness = (1.0 - math.exp(-kd)) / kd half = k * GAP_M / 2.0 gap = abs(math.sin(half) / half) return spacing * thickness * gap
[docs] def k3_of(spacing_m): """The wavenumber at which eq. (13) is at half power (-3.01 dB), by bisection in log k: 15 967 rad/m (393.5 um) at 5 um.""" lo, hi = 1.0, 1e7 for _ in range(200): mid = math.sqrt(lo * hi) gain = eq13_gain(mid, spacing_m) if gain * gain > 0.5: lo = mid else: hi = mid return math.sqrt(lo * hi)
[docs] def speed(character, time_ms): """Tape speed, m/s, for a character at a Time (dossier section 6).""" if character == SLIDING_HEAD: return V_SLIDING t = float(time_ms) if t < T_FAST_MS: t = T_FAST_MS if t > T_SLOW_MS: t = T_SLOW_MS return V_FAST * T_FAST_MS / t
[docs] def tone_excess(damping_hz, sample_rate): """(frames, relative excess) for the loop low-pass at `damping_hz` (already pre-warped): after `frames` frames whatever its state held weighs under 2^-17 of it, and its single-precision state can rest up to 2^-24 / a above the line's peak, a being the coefficient. `DigitalDelay`'s `_tone_excess`, as a function of the handed value.""" 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
# -- the glide laws -----------------------------------------------------------
[docs] def slew_of(glide_ms): """Sliding-head's `delay_slew` for a Glide: 0 (the jump) at Glide 0, otherwise 1 180 ms over `glide_ms`, pinned at 0.99.""" glide_ms = float(glide_ms) if not glide_ms > 0.0: return 0.0 slew = FULL_RANGE_MS / glide_ms if slew > SLEW_PIN: slew = SLEW_PIN return slew
[docs] def varispeed_slew(from_ms, to_ms): """The tape equation for a speed step from a settled transport: dT/dt = 1 - T_old / T_new, so the walk runs |dT| / T_new delay-seconds per second and lasts exactly T_new (S4 eq. 3).""" return abs(float(to_ms) - float(from_ms)) / float(to_ms)
# -- the wow table ------------------------------------------------------------ _SINE = None _DRIFT = None def _shapes(): """(one period of sine, the unit drift) at `TABLE_POINTS`, float32, computed once and shared by every instance. The drift is harmonics 1-9 at amplitude 1/k and `DRIFT_PHASES`, scaled to a peak of 1.""" global _SINE, _DRIFT if _SINE is None: points = TABLE_POINTS mask = points - 1 quarter = points // 4 sine = array("f", [0.0] * points) for n in range(points): sine[n] = math.sin(2.0 * math.pi * n / points) weights = [(k, math.cos(p) / k, math.sin(p) / k) for k, p in zip(range(1, 10), DRIFT_PHASES)] drift = array("f", [0.0] * points) peak = 0.0 for n in range(points): total = 0.0 for k, c, s in weights: i = k * n total += (sine[i & mask] * c + sine[(i + quarter) & mask] * s) drift[n] = total if abs(total) > peak: peak = abs(total) for n in range(points): drift[n] = drift[n] / peak _DRIFT = drift _SINE = sine return _SINE, _DRIFT
[docs] def cents_to_depth_ms(cents, line_hz): """A delay D sin(2 pi f t) ms moves pitch by a peak ratio of 1 + 2 pi f D / 1000, so `cents` peak is D = (2^(cents/1200) - 1) / (2 pi f) x 1000: 8 cents of the 0.72 Hz line is 1.024 ms, 4 cents of the 5.12 Hz line 0.072 ms.""" cents = float(cents) if not cents > 0.0: return 0.0 return ((2.0 ** (cents / 1200.0) - 1.0) / (2.0 * math.pi * line_hz) * 1000.0)
[docs] def wow_table(wow_cents, flutter_cents, out, flutter_harmonic=FLUTTER_HARMONIC, drift=True): """Write the wow table for (Wow, Flutter) into `out`, an int16 array of `TABLE_POINTS`, and return its peak excursion in ms, which is the node's `wow_depth_ms`; 0.0 (and `out` untouched) with nothing to write. The wow line's peak is `cents_to_depth_ms(wow, 0.72 Hz)`, the flutter line's `cents_to_depth_ms(flutter, 5.12 Hz)` and the drift's 0.25 ms per cent of Wow; the table is their sum normalised to its own peak.""" w = cents_to_depth_ms(wow_cents, WOW_LINE_HZ) f = cents_to_depth_ms(flutter_cents, FLUTTER_LINE_HZ) d = DRIFT_PER_WOW_CENT_MS * float(wow_cents) if drift else 0.0 if not d > 0.0: d = 0.0 if w <= 0.0 and f <= 0.0 and d <= 0.0: return 0.0 sine, walk = _shapes() mask = TABLE_POINTS - 1 peak = 0.0 for n in range(TABLE_POINTS): x = (w * sine[(WOW_HARMONIC * n) & mask] + f * sine[(flutter_harmonic * n) & mask] + d * walk[n]) if abs(x) > peak: peak = abs(x) scale = 32767.0 / peak for n in range(TABLE_POINTS): x = (w * sine[(WOW_HARMONIC * n) & mask] + f * sine[(flutter_harmonic * n) & mask] + d * walk[n]) out[n] = int(math.floor(x * scale + 0.5)) return peak
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
[docs] class TapeDelay(_component.Component): """A tape echo with the RE-201's motor or the EP-3's sliding head. The module docstring is the player's manual.""" NAME = 'TapeDelay' #: NaN is this option's own stop, not the default (documented above). _NAN_OWN = ('glide_ms',) DISPLAY_NAME = 'Tape Delay' CATEGORIES = ('Delay',) VERSION = '0.1.0' TIER = _component.AUDIODSP #: The exact constructor values a rack's reset puts back with the knobs. _KEPT = ('_glide_exact', '_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, the defaults rail on #: a 100 Hz square. INPUT_CEILING_DBFS = -6 MACRO_LABELS = ("Time", "Feedback", "Mix", "Glide", "Wow", "Flutter", "Record Level", "Spacing", "Spread", "Sync", "Division") MACRO_MODES = { 0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR", 6: "UNIPOLAR", 7: "UNIPOLAR", 8: "UNIPOLAR", 9: "TOGGLE", 10: "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 (GLIDE_MIN_MS, GLIDE_MAX_MS, "log"), # 3 Glide, ms; grid 0 = jump (0.0, WOW_MAX_CENTS), # 4 Wow, cents at 0.72 Hz (0.0, FLUTTER_MAX_CENTS), # 5 Flutter, cents at 5.12 Hz (0.0, 1.0), # 6 Record Level, loop_drive (SPACING_MIN_UM, SPACING_MAX_UM, "log"), # 7 Spacing, um (0.0, 1.0), # 8 Spread, cross_feed (0.0, 1.0), # 9 Sync (0.0, 15.0), # 10 Division index ) _MACRO_UNITS = {0: "ms", 3: "ms", 4: "cents", 5: "cents", 7: "um"} #: `_component.macro_of` of the dossier's section 6 settings; patch 0 is #: the constructor's defaults on the grid. Patch 8 is patch 0 with Record #: Level at 0, the board's lean patch (with `max_time_ms=800`; the module #: docstring's Cost). PATCHES = { 0: ("Warm Repeats", (89, 58, 22, 89, 32, 32, 25, 51, 0, 0, 51)), 1: ("Long Repeats, Slow Glide", (114, 71, 22, 127, 32, 32, 25, 51, 0, 0, 51)), 2: ("Short Slap", (47, 19, 32, 89, 16, 16, 25, 51, 0, 0, 51)), 3: ("Dark Repeats, Heavy Wow", (97, 71, 22, 89, 95, 64, 25, 111, 0, 0, 51)), 4: ("High Intensity", (93, 115, 25, 89, 32, 32, 76, 51, 0, 0, 51)), 5: ("Worn Heads", (89, 58, 22, 89, 64, 95, 64, 127, 0, 0, 51)), 6: ("Clean Transport", (89, 58, 22, 89, 0, 0, 0, 0, 0, 0, 51)), 7: ("Dotted Eighth, Synced", (89, 58, 22, 89, 32, 32, 25, 51, 0, 127, 68)), 8: ("Tape Delay - lean", (89, 58, 22, 89, 32, 32, 0, 51, 0, 0, 51)), } def _build(self, time_ms=350.0, feedback=0.45, mix=0.35, glide_ms=6000.0, wow_cents=2.0, flutter_cents=1.0, record_level=0.2, spacing_um=5.0, spread=0.0, sync=False, division=6, character=VARISPEED, max_time_ms=TIME_MAX_MS, patch=None): if character not in CHARACTERS: raise ValueError( "character must be 'varispeed' or 'sliding-head'") self._character = character 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 #: The whole-frame Time last handed to the node, and in ms. self._frames = 0 self._node_ms = 0.0 #: The Time the loss corner is read at: the clamped Time before it #: is landed on a frame. self._time_played = 0.0 #: The longest delay, in whole frames, the read head may still sit #: at. A 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 jump or 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._slew = 0.0 self._feedback = 0.0 self._damping = 0.0 self._corner = 0.0 self._spread = 0.0 self._wow_ms = 0.0 #: (Wow, Flutter) the current table was written for. self._wow_key = None #: Two tables: the node borrows one while a move writes the other. self._tables = (array("h", [0] * TABLE_POINTS), array("h", [0] * TABLE_POINTS)) self._table_index = 1 self._table = None #: k3 for the Spacing last asked, keyed by the Spacing in metres. self._k3_key = None self._k3 = 0.0 # A log knob cannot seed 0 or a negative; those clamp to the bottom. time_ms = _option(time_ms, DEFAULTS[TIME_I]) if not time_ms > 0.0: time_ms = TIME_MIN_MS time_ms = _between(time_ms, TIME_MIN_MS, TIME_MAX_MS) spacing_um = _option(spacing_um, DEFAULTS[SPACING_I]) if not spacing_um > 0.0: spacing_um = SPACING_MIN_UM #: A constructor Glide stays on the audio path until macro 3 moves: #: the span starts at 1 200 ms, so a faster Glide (down to the 0.99 #: pin) or an exact 0 has no knob position. A slower one is clamped #: to the span's top, 12 s. 0, a negative and NaN are the jump. glide_ms = float(glide_ms) if glide_ms > GLIDE_MAX_MS: glide_ms = GLIDE_MAX_MS if not glide_ms > 0.0: glide_ms = 0.0 self._glide_exact = glide_ms #: The constructor's Time, exactly, until macro 0 moves. Seeding a #: log knob and reading it back is not exact: 350.0 ms comes back a #: few ulps under, which at 22.05 kHz (7 717.5 frames) would land on #: 7 717 instead of the 7 718 the whole-frame law gives 350.0. self._time_exact = time_ms self._time_seed = -1.0 self._seeding = True values = (time_ms, _option(feedback, DEFAULTS[FEEDBACK_I]), _option(mix, DEFAULTS[MIX_I]), max(GLIDE_MIN_MS, glide_ms), _option(wow_cents, DEFAULTS[WOW_I]), _option(flutter_cents, DEFAULTS[FLUTTER_I]), _option(record_level, DEFAULTS[RECORD_I]), spacing_um, _option(spread, DEFAULTS[SPREAD_I]), 1.0 if sync else 0.0, _option(division, DEFAULTS[DIVISION_I])) 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=self._clamp_ms(time_ms), feedback=0.0, mix=0.0, damping_hz=0.0, cut_hz=0.0, delay_slew=0.0) # `clear()` empties the line and the loop filters and re-primes the # read head, so a reset is silent and snaps onto the current Time. self._own(self._delay, reset=self._clear) self._delay.play(self._source) self._output = self._delay self._deferred = True try: self._init_macros(values) finally: self._deferred = False self._seeding = False # The knob is seeded where the constructor's Glide is, or at grid 1 # for a faster one; `_glide_exact` carries the real value, so a # get_macro / set_macro round trip keeps it gliding. if self._glide_exact > 0.0 and self._macros[GLIDE_I] < GLIDE_FLOOR: self._macros[GLIDE_I] = GLIDE_FLOOR self._refresh() # Read after the refresh, which re-seats a Time above `max_time_ms`. self._time_seed = self._macros[TIME_I] 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 _time_ms(self): """The Time the audio path plays, before it is clamped and landed.""" if self._time_exact is not None: return self._time_exact return self._value(TIME_I) def _glide_ms(self): if self._glide_exact is not None: return self._glide_exact if self._macros[GLIDE_I] <= 0.0: return 0.0 return self._value(GLIDE_I) def _walk_rate(self, from_ms, to_ms): """The node's `delay_slew` for a Time move: the tape equation on varispeed, the Glide law on sliding-head.""" if self._character == VARISPEED: return varispeed_slew(from_ms, to_ms) return slew_of(self._glide_ms()) def _corner_hz(self, time_ms, spacing_um): """The loop low-pass's -3 dB corner, before the clamp and the pre-warp: eq. (13)'s half-power point, v k3(d) / 2 pi.""" spacing_m = spacing_um * 1e-6 if spacing_m != self._k3_key: self._k3 = k3_of(spacing_m) self._k3_key = spacing_m return speed(self._character, time_ms) * self._k3 / (2.0 * math.pi) def _write_table(self, wow_cents, flutter_cents, out): """Hook for the table law; returns the depth in ms.""" return wow_table(wow_cents, flutter_cents, out) def _transport_state(self): transport = self._transport state = transport() if callable(transport) else transport return transport, state 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, state = self._transport_state() if transport is _component.static_transport: return None # A host whose tempo is not a finite positive number (0, None, a # negative, NaN or infinity) leaves Time on the knob. `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 not self._seeding: if index == GLIDE_I: self._glide_exact = None elif index == TIME_I 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 # keeps the constructor's exact Time; any other 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, so Time is read against the new patch's Sync and moves once.""" 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) # The cleared node snaps onto the current Time on its next pull. self._reach = max(1, self._frames) self._fresh = False
def _refresh(self): fs = self._sample_rate span = self._MACRO_RANGES[TIME_I] if self._macros[SYNC_I] >= 0.5: synced = self._synced_ms() if synced is not None: # Division quantises Time into the same map, and the clamp # shows through get_macro(0) the same way. self._time_exact = None self._macros[TIME_I] = _component.macro_position( span, self._clamp_ms(synced)) time_ms = self._time_ms() clamped = self._clamp_ms(time_ms) if clamped != time_ms: if self._time_exact is not None: self._time_exact = clamped self._macros[TIME_I] = _component.macro_position(span, clamped) frames = max(1, whole_frames(clamped, fs)) node_ms = frames * 1000.0 / fs if self._character == VARISPEED: # The motor's law sets each move's rate from the Time it leaves; # with no move the walk in progress keeps its rate. if frames != self._frames and not self._fresh: self._slew = self._walk_rate(self._node_ms, node_ms) else: self._slew = self._walk_rate(self._node_ms, node_ms) if self._fresh or self._slew <= 0.0: # A fresh node snaps onto the target, and with the slew off the # read head jumps there on the next frame. self._reach = frames elif frames > self._reach: self._reach = frames self._frames = frames self._node_ms = node_ms self._time_played = clamped spacing = _between(self._value(SPACING_I), SPACING_MIN_UM, SPACING_MAX_UM) self._corner = self._corner_hz(clamped, spacing) self._damping = nominal_damping_hz(self._hz(self._corner), fs) # Handed as set: since audiodsp v0.6.3rc1 the node lands a loop # low-pass that has stopped moving (#157), so no Feedback holds a # small value for ever and nothing is stepped clear here. self._feedback = _between(self._value(FEEDBACK_I), 0.0, FEEDBACK_MAX) wow = _between(self._value(WOW_I), 0.0, WOW_MAX_CENTS) flutter = _between(self._value(FLUTTER_I), 0.0, FLUTTER_MAX_CENTS) key = (wow, flutter) if key != self._wow_key: # Write the table the node is not reading, then hand it over. spare = 1 - self._table_index depth = self._write_table(wow, flutter, self._tables[spare]) if depth > 0.0: self._table_index = spare self._table = self._tables[spare] elif self._fresh: self._table = None # Otherwise a playing node keeps the table it has: the node ramps # the old depth out over 20 ms (audiodsp#160), and without a # table it would ramp it out on its own sine instead, a jump in # the read offset. At depth 0 the table moves nothing. self._wow_ms = depth self._wow_key = key # At one channel the node's cross-feed sends the repeat nowhere. # At two, Spread is handed as set: since audiodsp v0.6.3rc3 a # cross-fed tail reaches exact zero however the node rounds the # cross-feed sum (audiodsp#173), so the 1/4096 grid is gone. if self._channel_count == 1: self._spread = 0.0 else: self._spread = _between(self._value(SPREAD_I), 0.0, 1.0) self._delay.set( delay_slew=self._slew, delay_ms=node_ms, feedback=self._feedback, mix=_between(self._value(MIX_I), 0.0, 2.0), loop_drive=_between(self._value(RECORD_I), 0.0, 1.0), damping_hz=self._damping, cut_hz=0.0, cross_feed=self._spread, wow_hz=WOW_HZ, wow_depth_ms=self._wow_ms, wow_shape=self._table) @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 of the longest delay the read head may be at, plus the wow table's peak excursion in frames rounded up, plus one frame for the interpolated read, plus the loop low-pass's memory. Finite at every setting the class reaches, stereo and mono, at every Spread.""" 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) wow = int(math.ceil(self._wow_ms * self._sample_rate / 1000.0)) return int(laps * (self._reach + wow + 1 + memory))