Source code for audioeffects.rack

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

"""`Rack` - a serial chain of effects, as a single effect.

The player's text is the class docstring, and the sentences in it that make
a claim are tied to tests by the `CLAIMS` table in the class's test file.
"""

VENDOR = "PyDevices"

from . import _component


[docs] class Rack(_component.Component): """A pedalboard cable run: name the effects in order and get a single effect back. For example: rack = Rack.create(source, 48000, chain=( ("Fuzz", {}), ("DigitalDelay", {"mix": 0.3, "feedback": 0.4}), ("ConvolutionReverb", {}), )) audio_out.play(rack.output) `chain` is a tuple of entries, each an effect name, a `(name, options)` pair whose options are that effect's constructor keywords, or an effect class in place of a name. `("Rack", {"chain": ...})` nests a rack. A rack adds no sound of its own: it sounds exactly like the same pedals patched by hand, one into the next. Empty, it is a patch cable, and its output is your source. A mono source gives a mono rack. Order matters as soon as one pedal isn't a plain filter: drive into a reverb isn't a reverb into drive. `latency_samples` and `tail_samples` are the sums of the pedals' own, read live, so they follow a pedal's knobs; the tail is `None` as soon as one pedal's is. There is no rack Mix, Bypass or Output knob, and patch 0 is its only patch. Turn a pedal's own Mix down; `ShimmerHall` and `AirSpace` are racks with knobs. The chain is set when the rack is built: to change pedals, build a new rack. To turn a pedal's knob, reach it through `rack.effects`, a tuple of the pedals in chain order. `reset()` clears every pedal and puts each back to the settings the rack built it with, undoing knob moves made since. `program_change(0)` does the putting back alone, without clearing anything. A host's `audiocore.reset_buffer(rack.output)` clears the last pedal only, and on an empty rack it rewinds your own source, because the output is your source. Call `rack.reset()` instead. A tempo-synced pedal follows the song's tempo wherever it sits, nested racks included: each pedal gets the rack's transport unless its entry names its own, and `transport_changed()` reaches every pedal. `capabilities` is the union of the pedals' own, set when the rack is built. A rack builds nothing of its own, so it costs what its pedals cost. Heavy pedals add up quickly on a small board: if the sound breaks up, trim the chain. The class itself runs on a stock board; a built rack needs whatever modules its pedals need. `deinit()` releases every pedal, nested racks included, and never your source. If an entry fails to build, or `patch` is refused, the pedals already built are released before the error reaches you. """ NAME = 'Rack' DISPLAY_NAME = 'Effect Rack' CATEGORIES = ('Effect Rack',) VERSION = '0.1.0' TIER = _component.STOCK MACRO_LABELS = () MACRO_MODES = {} _MACRO_RANGES = () PATCHES = {0: ("Default", ())} def _build(self, chain=(), patch=None): built = [] tail = self._source try: for entry in chain: name, options = _entry(entry) child = self._child(name, tail, options) built.append(child) tail = child.output self._effects = tuple(built) # What patch 0 and reset() restore: each child's settings as the # rack built it (`_record`). self._built = tuple(_record(child) for child in built) capabilities = [] for child in built: for capability in child.capabilities: if capability not in capabilities: capabilities.append(capability) self._capabilities = tuple(capabilities) # No port of its own: the rack's output IS the last child's # output (its port), and an empty rack's IS the source. Set # directly, around the `_output` property, which would wrap it # in a new port. self._port = tail # Last, and inside the release: a `patch` the rack refuses # raises here, with every child built. self._init_macros((), patch) except BaseException: # The constructor never returns, so nobody else can release # what was built: do it here, tail first, and re-raise. for child in reversed(built): child.deinit() raise def _child(self, name, source, options): """One chain entry built around `source`, with the rack's transport unless the entry names its own.""" transport = options.pop("transport", self._transport) if isinstance(name, str): if name == Rack.NAME: name = Rack else: import audioeffects return audioeffects.create(name, source, self._sample_rate, transport=transport, **options) return name.create(source, self._sample_rate, transport=transport, **options) # -- the reads ------------------------------------------------------ @property def effects(self): """The children, in chain order.""" self._check_live() return self._effects @property def latency_samples(self): self._check_live() total = 0 for child in self._effects: total += child.latency_samples return total @property def tail_samples(self): self._check_live() total = 0 for child in self._effects: tail = child.tail_samples if tail is None: return None total += tail return total @property def capabilities(self): self._check_live() return self._capabilities # -- the surface ---------------------------------------------------- def _apply_positions(self, positions, patch_index): """Patch 0: every child back to the settings the rack built it with. A nested rack restores inside itself.""" _component.Component._apply_positions(self, positions, patch_index) for child, record in zip(self._effects, self._built): _restore(child, record)
[docs] def transport_changed(self): self._check_live() for child in self._effects: child.transport_changed()
[docs] def reset(self): """Each child's own reset, tail first, reloading the settings the rack built it with in place of its patch 0, so no child passes through a patch the rack never gave it: one built at Mix 0 would re-arm there and pull a block of the source. A nested rack's reset does the same inside itself. The borrowed source is never named.""" self._check_live() for position in range(len(self._effects) - 1, -1, -1): child = self._effects[position] record = self._built[position] if isinstance(child, _component.Component): child._reset_to = record try: child.reset() finally: child._reset_to = None else: child.reset() _restore(child, record) self._stranded = False self._patch_index = 0
[docs] def deinit(self): """Every child's own deinit, tail first. The port is never released here: it is the last child's, or, for an empty rack, the source.""" if self._deinited: return for child in reversed(self._effects): child.deinit() self._port = None self._deinited = True
def _record(child): """What puts `child` back as it stands: its `_record()`, or, for a child on another base, its positions and patch index.""" if isinstance(child, _component.Component): return child._record() return (list(child._macros), child._patch_index) def _restore(child, record): """Put `child` back to `record`, without clearing anything.""" if isinstance(child, _component.Component): child._restore(record) else: child._apply_positions(list(record[0]), record[1]) def _entry(entry): """(name or class, options dict) for one chain entry.""" if isinstance(entry, (str, type)): return entry, {} try: name, options = entry except (TypeError, ValueError): raise ValueError("a chain entry is a NAME, an effect class or a " "(NAME, options) pair, not %r" % (entry,)) return name, dict(options)