circuitpython-synthtools 0.5__py3-none-any.whl → 0.6.0__py3-none-any.whl

{circuitpython_synthtools-0.5.dist-info → circuitpython_synthtools-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.5
+Version: 0.6.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -44,6 +44,16 @@ Introduction
 
 CircuitPython library with tools for making synths with synthio
 
+This library is a collection of tools derived from my many years of playing
+with CircuitPython, ``synthio``, and building synthesizers in general.
+Concepts pulled from these projects and others:
+
+- `CircuitPython Synthio Tutorial <https://todbot.github.io/CircuitPython_Synthio_Tutorial/>`_
+- `circuitpython synthio tricks <https://github.com/todbot/circuitpython-synthio-tricks>`_
+- `synthiota <https://github.com/todbot/synthiota>`_
+- `pico_test_synth <https://github.com/todbot/pico_test_synth>`_
+- `picotouch_synth <https://github.com/todbot/picotouch_synth>`_
+- `picostepseq <https://github.com/todbot/picostepseq>`_
 
 Dependencies
 =============
@@ -118,12 +128,22 @@ What's Included
 * ``Synth`` -- synth engine base: shared voice, patch, and modulation handling,
   with ``mono`` mode for a single-voice synth with ``glide_time``  portamento
 * ``SubtractiveSynth`` -- subtractive two-oscillator synth w/ detune
+* ``FMSynth`` -- two-operator phase-modulation voice: a carrier waveform
+  pre-rendered from ``sin(theta + fm_index*sin(fm_ratio*theta))``.
+  ``fm_ratio`` must be an integer; ``fm_index`` is PM depth in radians,
+  0 = plain single-oscillator. (Not a live audio-rate bend modulator --
+  synthio's Math/LFO blocks only update every 256 samples, too slow for
+  that; see the module docstring for why.)
 * ``WavetableSynth`` -- wavetable-playback with adjustable wave_pos
 * ``BasslineSynth`` -- TB-303-style acid bassline: monophonic, one
-  oscillator, a decay-only filter sweep, per-step slide and accent
-* ``EffectsChain`` -- post-synth audio effects: extra filter stages that
-  track the synth's cutoff for a steeper slope, plus optional distortion
-  and tempo-synced echo (needs ``audiofilters`` in the build)
+  oscillator, a decay-only filter sweep, per-step slide and accent. Can
+  own its own filter/distortion/echo effects chain via ``fx_*`` patch
+  fields
+* ``EffectsChain`` -- a generic post-synth effects chain: add, insert, or
+  remove any ``audiofilters``/``audiodelays`` effect and it stays wired.
+  ``tracking_filter()`` builds extra filter stages that follow the synth's
+  own cutoff and resonance for a steeper slope (needs ``audiofilters`` in
+  the build)
 * ``Patch`` -- inert, JSON-able patch data; save/load with
   ``save_patches()`` / ``load_patches()``
 * ``Wavetable`` -- loads a wavetable WAV file and lerps between frames
@@ -135,6 +155,9 @@ What's Included
   sequencers with on/off callbacks
 * ``Param`` / ``ParamSet`` -- knob-pickup and scaling for UIs with fewer
   knobs than parameters
+* ``ParamScaler`` -- proportional ("scale") knob takeover for a single
+  control, when you are not using ``ParamSet``
+* ``GaugeCluster`` -- a bar-graph display of a parameter page
 * ``Glider`` -- a standalone pitch-slide block for hand-built
   ``synthio.Note`` graphs (the engines above have their own portamento,
   via ``mono`` + ``glide_time``)

circuitpython_synthtools-0.6.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+circuitpython_synthtools-0.6.0.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
+synthtools/__init__.py,sha256=WXLJ-chYBMFnvVbSnwyxy2Txv9ixApOKi8vyrKypQlA,2592
+synthtools/ahr_envelope.py,sha256=fWhjp7LahNGjL8qtTgyiAnX5hnviAULuyc9dEJ6t74I,9233
+synthtools/arpeggiator.py,sha256=n2sPnpZcu9soXsFJCh6OP65_0DuPnvQGUP0ao7V8SXM,3901
+synthtools/audio_fx.py,sha256=VzdWT_pCwfQU5GTb8hVGGMwoFV4lxPwWE1Nm7A1a_Fc,6675
+synthtools/bassline_synth.py,sha256=Gkz7MKKUITgND4Se5nAJly9sZLQjHhFdd-aFrOAjeVM,28112
+synthtools/blocks.py,sha256=EsGcDEzIJX_dvBN8CVlDrewtl16x5leU03tum9jrhr0,1995
+synthtools/fm_synth.py,sha256=-r4NcsESjEechkbmV0tZx4pXayHIz4qUfIznKtQoKgQ,6073
+synthtools/gauge_cluster.py,sha256=lcMkRK-db6KV6pu0PUJRWAOJT8IdjgpE_4bAi0lQwxc,2910
+synthtools/param_scaler.py,sha256=dmaFkzRhrfZn54DAgPwZs7P4B4BFd90ZUvMHpWIf2i4,6202
+synthtools/paramset.py,sha256=--V89zHR4pUhkSey1CX7iMLNsF5l1hKmKWrAr3j_cRA,9938
+synthtools/patch.py,sha256=vMr-kdVD66uxY8BrrnB0J6uDLREjuu16I8HzfhAkqHs,6033
+synthtools/pitch_glider.py,sha256=R5h0Lbyq_slo7SKORRM7a0oumVugE15L8hOZJCov0AY,1927
+synthtools/step_sequencer.py,sha256=SkQuDsRtpAdKOXU3OsFmngeDPVQ0OXt3Gj5wqFCkEPM,4202
+synthtools/subtractive_synth.py,sha256=WIpmhbiiLtyQRFV9mHWWM-duST5RfY9HUN4SRf5wTOw,3382
+synthtools/swarm_synth.py,sha256=kCYsdVuaafTKkD06_m22iFaPUMCzeBKX67mkrsEq3pk,10945
+synthtools/synth.py,sha256=ZdmAKWBVzJqPyzU5W1hxnJ6j09D4rnCWm77s5jRW_Ww,36528
+synthtools/trig_sequencer.py,sha256=PaWgsTqOvuRjFUJ6VjxMLBuRkyeYCML9WQXBzx02Onk,2921
+synthtools/utils.py,sha256=deKQbkGXIBdGUOXBOpRCc-UHdPiL8YmybIJ3BBo9aA4,648
+synthtools/waves.py,sha256=lwDka71TsoHGJcyVfmG4t-TEf6TjBwftJEXSS4Qxyx0,22407
+synthtools/wavetable.py,sha256=K1rghAptDYIOwy0PcL9xCllnJH6X3h875MpeuXCm6lQ,2492
+synthtools/wavetable_synth.py,sha256=WUs4FfrKd1hosPiPYnf05I4S8t98ngEMi8qhShkbCps,12896
+circuitpython_synthtools-0.6.0.dist-info/METADATA,sha256=C4HgNUbEFEH2PUe0Pv8sQ9-u7t3P4rSOMQF6upscetw,7086
+circuitpython_synthtools-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+circuitpython_synthtools-0.6.0.dist-info/top_level.txt,sha256=1xt53cH064i7vvFVDFyuJugc1NogReXvzsXbYGlgnKE,11
+circuitpython_synthtools-0.6.0.dist-info/RECORD,,

synthtools/__init__.py

@@ -21,25 +21,64 @@ Implementation Notes
 
 * synthio : https://docs.circuitpython.org/en/latest/shared-bindings/synthio/
 
+Importing
+---------
+
+Names are resolved LAZILY: ``from synthtools import Patch`` imports
+``synthtools.patch`` and nothing else. Adding a tool to this library costs
+nothing to anyone who does not use it.
+
+Anything not listed below is still importable by its module path::
+
+    from synthtools.waves import get_wave
+    from synthtools.step_sequencer import StepSequencer
 """
 
-# imports
-
-from .audio_fx import EffectsChain
-from .bassline_synth import BasslineSynth
-from .patch import Patch, load_patches, save_patches
-from .subtractive_synth import SubtractiveSynth
-from .synth import Synth
-
-# wavetable_synth needs the adafruit_wave library; don't break the whole
-# package if it isn't installed. Import it directly if you want it:
-#     from synthtools.wavetable import Wavetable
-#     from synthtools.wavetable_synth import WavetableSynth
-try:
-    from .wavetable import Wavetable
-    from .wavetable_synth import WavetableSynth
-except ImportError:
-    pass
-
-__version__ = "0.5"
+import sys
+
+__version__ = "0.6.0"
 __repo__ = "https://github.com/todbot/CircuitPython_SynthTools.git"
+
+#: Public name -> the submodule that defines it. Every entry is loaded on
+#: first use and cached by the import system, never at package import.
+_LAZY = {
+    "EffectsChain": "audio_fx",
+    "set_drive": "audio_fx",
+    "sync_delay": "audio_fx",
+    "tracking_filter": "audio_fx",
+    "BasslineSynth": "bassline_synth",
+    "FMSynth": "fm_synth",
+    "GaugeCluster": "gauge_cluster",
+    "ParamScaler": "param_scaler",
+    "Patch": "patch",
+    "load_patches": "patch",
+    "save_patches": "patch",
+    "SubtractiveSynth": "subtractive_synth",
+    "SwarmSynth": "swarm_synth",
+    "Synth": "synth",
+    # These two additionally need adafruit_wave. Asking for one without it
+    # raises ImportError naming adafruit_wave, rather than the name simply
+    # not existing.
+    "Wavetable": "wavetable",
+    "WavetableSynth": "wavetable_synth",
+}
+
+__all__ = tuple(sorted(_LAZY))
+
+
+def __getattr__(name):
+    """Import the submodule that defines ``name`` on first access (PEP 562).
+
+    Verified on CircuitPython 10.3.0-alpha.3 as well as CPython and
+    MicroPython. Note the import must be spelled as an absolute
+    ``__import__`` of the dotted path: ``from . import <mod>`` re-enters
+    this function on MicroPython (a package-attribute lookup) and
+    recurses into AttributeError.
+    """
+    modname = _LAZY.get(name)
+    if modname is None:
+        raise AttributeError(name)
+    full = __name__ + "." + modname
+    if full not in sys.modules:
+        __import__(full)
+    return getattr(sys.modules[full], name)

synthtools/ahr_envelope.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
 # SPDX-License-Identifier: MIT
 #
-# ahr_envelope.py - Attack-Release envelope for synthio, as a modulation
+# ahr_envelope.py -- Attack-Release envelope for synthio, as a modulation
 # SOURCE: it produces 0 -> amount and knows nothing about where that goes.
 #
 # Per voice, three objects:
@@ -12,44 +12,32 @@
 #
 # The LFO is only a *position*: it runs 0 -> 1 through a shared, shaped
 # buffer, and CONSTRAINED_LERP decides what that position maps onto. So
-# release is a matter of moving the endpoints -- NOT of swapping the
-# waveform. That matters: synthio.LFO.waveform is read-only,
-# so an implementation that# reassigns it raises
-#   AttributeError: can't set attribute 'waveform'
-# at every note-off. Mutating the buffer's contents in place is fine, and
-# is documented synthio behaviour.
+# release moves the ENDPOINTS rather than swapping the waveform. That
+# matters, because synthio.LFO.waveform is read-only and reassigning it
+# raises `AttributeError: can't set attribute 'waveform'` at every
+# note-off. Mutating the buffer's contents in place is documented and fine.
 #
 # One consequence is easy to get wrong. Release replays the SAME rising
-# buffer forward, so its output is `V * (1 - s(t))` -- it INVERTS whatever
+# buffer forward, so its output is `V * (1 - s(t))`, INVERTING whatever
 # curvature s has. A buffer holding the obvious t^curve therefore makes the
-# release hang near the top and then fall off a cliff (75% of its height
-# still left at the halfway point, for curve=2): a mirrored attack, not a
+# release hang near the top and then fall off a cliff (at curve=2, 75% of
+# its height is still left at the halfway point): a mirrored attack, not a
 # decay. The buffer holds 1-(1-t)^curve instead, which comes back out of
 # that inversion as V*(1-t)^curve. Attack and release curvature are linked
-# as a result -- one buffer, one exponent. See fill_env_rise() in waves.py.
+# as a result: one buffer, one exponent. See fill_env_rise() in waves.py.
 #
-# --- why this is bigger than the tutorial's version -------------------
-#
-# todsynth/ahr_envelope.py in the synthio tutorial is the same
-# CONSTRAINED_LERP idea, and it is the right size for a monosynth: one
-# object per voice, writing plain floats into env.a / env.b at press. The
-# cost of that is that every global parameter is O(polyphony) -- moving the
-# envelope depth means looping over live voices and writing each one.
-#
-# This is the polyphonic version. ONE instance is a factory for many
-# voices, and the things a knob touches are shared objects nested inside
-# each voice's graph:
+# ONE instance is a factory for many voices. Everything a knob touches is a
+# shared object nested inside each voice's graph:
 #
 #   _amt      the depth, nested in every voice's `depth`
 #   _rate_a   the attack rate, every voice's LFO rate
 #   _rate_r   the release rate
 #   _wave     the shape, rewritten in place under sounding voices
 #
-# so amount, attack, release and curve each reach every sounding voice --
-# including ones already in release -- with a SINGLE write. That is the
-# only reason for the extra indirection. The shared buffer also buys
-# arbitrary integer curve exponents for free, where the tutorial's
-# PRODUCT(lerp, lerp, 1) costs one Math per voice and only gives one curve.
+# so amount, attack, release and curve each reach every sounding voice,
+# release included, with a SINGLE write. That is the whole reason for the
+# extra indirection over a per-voice envelope, which would be O(polyphony)
+# on every global parameter.
 
 import synthio
 
@@ -69,13 +57,13 @@ class AHREnvelope:
         falling=True    amount -> 0, release on to release_amount
 
     The filter envelope is the rising case added to a cutoff bus; a pitch
-    envelope is the falling one added to a bend graph -- it starts off-pitch
+    envelope is the falling one added to a bend graph; it starts off-pitch
     and settles, then on note-off drifts on to release_amount. Nothing here
     knows which.
 
-    The two differ ONLY in make()'s endpoints. Everything else -- the shared
+    The two differ ONLY in make()'s endpoints. Everything else (the shared
     amount block, the shared rates, the in-place shape buffer, the
-    re-aim-the-endpoints release -- is identical, which is why this is one
+    re-aim-the-endpoints release) is identical, which is why this is one
     class with a flag rather than two classes."""
 
     def __init__(
@@ -85,9 +73,9 @@ class AHREnvelope:
         self._release = release
         self._curve = curve
         self._falling = falling
-        # Created ONCE and never replaced. Sounding voices hold references
-        # to all of these, so identity has to survive patch reloads --
-        # assigning a new object here would orphan the live ones.
+        # Created ONCE and never replaced. Sounding voices hold references to
+        # all of these, so identity has to survive patch reloads; assigning a
+        # new object here would orphan the live ones.
         self._wave = env_buffer()
         self._rate_a = scalar_block(1.0)
         self._rate_r = scalar_block(1.0)
@@ -107,8 +95,7 @@ class AHREnvelope:
         fill_env_rise(self._wave, self._curve)
 
     def _refresh_rates(self):
-        # the rise fills the whole buffer, so a rate is just 1/seconds --
-        # no fraction to correct for
+        # the rise fills the whole buffer, so a rate is just 1/seconds
         self._rate_a.a = 1.0 / max(self._attack, 0.001)
         self._rate_r.a = 1.0 / max(self._release, 0.001)
 
@@ -160,8 +147,8 @@ class AHREnvelope:
 
     @amount.setter
     def amount(self, v):
-        # one write into the shared block, reaching every voice including
-        # ones already in release (it stays live inside each voice's depth)
+        # one write into the shared block, reaching every voice, release
+        # included, since it stays live inside each voice's depth
         self._amt.a = v
 
     @property
@@ -183,7 +170,7 @@ class AHREnvelope:
         Returns the CONSTRAINED_LERP block to add to a destination. It
         carries everything start_release() needs: the position LFO in ``c``.
 
-        ``gain`` is a per-voice depth scale -- a plain number, or a block
+        ``gain`` is a per-voice depth scale: a plain number, or a block
         (e.g. a velocity LERP) so whatever drives it stays live.
 
         Returning None is what makes the envelope cost literally nothing
@@ -196,12 +183,12 @@ class AHREnvelope:
         """
         if not self._amt.a and not self._rel_amt.a:
             return None
-        # A plain 1.0 means "nothing is scaling this", and the voice can use
-        # the shared block directly -- one Math lighter in the common case.
-        # A BLOCK is always wrapped, even if it happens to evaluate to 1.0
-        # right now, because it can change while the voice sounds. Hence the
-        # isinstance rather than a bare `gain == 1.0`: what a synthio block
-        # does under `==` is not ours to assume.
+        # A plain 1.0 means nothing is scaling this, so the voice can use the
+        # shared block directly, one Math lighter. A BLOCK is always wrapped
+        # even if it evaluates to 1.0 right now, because it can change while
+        # the voice sounds. Hence isinstance rather than a bare
+        # `gain == 1.0`: what a synthio block does under `==` is not ours to
+        # assume.
         if isinstance(gain, (int, float)) and gain == 1.0:
             depth = self._amt
         else:
@@ -222,7 +209,7 @@ class AHREnvelope:
         structural: there is no gain to recompute.
 
         The target is the shared release-amount BLOCK, not a number, which
-        is what lets it stay live for a voice that is already falling -- and
+        is what lets it stay live for a voice that is already falling, and
         it means the rising and falling cases need no branch here at all,
         since a filter envelope simply has a block that holds 0.0.
         """

synthtools/audio_fx.py

@@ -1,180 +1,155 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
 # SPDX-License-Identifier: MIT
 #
-# audio_fx.py - post-synth effects: extra filter stages that track the
-# synth's cutoff, plus optional distortion and echo.
+# audio_fx.py -- a generic post-synth effects chain, plus a factory for the
+# one effect that needs synth-specific knowledge: extra filter stages that
+# track the synth's own cutoff and resonance.
 #
-# A synthio.Note takes ONE Biquad, so 12 dB/octave is all a voice can do.
-# Steeper means cascading more biquads downstream, and those need
-# somewhere stable to point their `frequency`: Synth rebuilds the voice's
-# cutoff node at every note-on, and it freezes once the Note is freed.
-# BasslineSynth is mono, so it keeps ONE Biquad over one stable cutoff
-# node -- copy `synth.filter`'s frequency and you track it for good.
+# EffectsChain itself never imports audiofilters/audiodelays: it only calls
+# `.play(source)` on whatever effect objects it is handed, so it loads fine
+# where those modules don't exist. Only tracking_filter(), and whatever
+# Distortion/Echo a caller constructs, needs them.
 #
-# Slope: every Biquad is 12 dB/oct including the synth's own, so `stages`
-# gives 12*(stages+1). Default 1 = 24 dB/oct. (A 303 is usually called
-# ~18 dB/oct, which cascaded 2-pole sections cannot make at all.)
+# A synthio.Note takes ONE Biquad, so 12 dB/octave is all a voice can do.
+# Steeper means cascading more biquads downstream, and those need somewhere
+# stable to point their `frequency`: Synth rebuilds the voice's cutoff node
+# at every note-on, and it freezes once the Note is freed. BasslineSynth is
+# mono, so it keeps ONE Biquad over one stable cutoff node; copy
+# `synth.filter`'s frequency and you track it for good. Slope is
+# 12*(stages+1). (A 303 is usually called ~18 dB/oct, which cascaded 2-pole
+# sections cannot make at all.)
 #
-# Q tracks too, on every stage, matching the synth this was ported from
-# (its `resonance` setter pushes the same Q into the voice filter and both
-# extra ones by hand). Here it is automatic: `src.Q` is the synth's live
-# `filt_q` block, the same object the voice's own Biquad reads, so wiring
-# an extra stage's Q to it needs no propagation code at all -- one knob
-# turn reaches every stage the instant it reaches the voice.
+# Q tracks on every stage, and automatically: `src.Q` is the synth's live
+# `filt_q` block, the same object the voice's own Biquad reads, so wiring an
+# extra stage's Q to it needs no propagation code.
 #
-# Identical resonant sections stacked like this do pile up gain at the
-# cutoff faster than one section alone -- each stage adds its own peak on
-# top of the last. At a squelchy filt_q that is real headroom to watch for;
-# it is also most of why a cascaded resonant filter reads as more
-# aggressive than a single one, which is the point here.
+# Identical resonant sections stacked this way do pile up gain at the cutoff,
+# each stage adding its own peak on top of the last. At a squelchy filt_q
+# that is real headroom to watch, and also most of why a cascaded resonant
+# filter reads as more aggressive than a single one.
 
 import synthio
 
 try:
-    import audiodelays
     import audiofilters
 except ImportError:  # not in every CircuitPython build
-    audiodelays = None
     audiofilters = None
 
 
 class EffectsChain:
-    """Post-synth effects: filter stages tracking the synth's cutoff, plus
-    optional distortion and echo. Hand ``output`` to a mixer voice::
-
-        fx = EffectsChain(BasslineSynth(engine, patch), stages=1)
+    """A synth's output, plus an ordered chain of playback effects it runs
+    through. Add, insert, or remove any ``audiofilters``/``audiodelays``
+    effect object; the chain keeps every effect's ``.play(source)`` pointed
+    at whatever now precedes it::
+
+        fx = EffectsChain(synth)
+        fx.add(tracking_filter(synth, stages=1))
+        fx.add(audiofilters.Distortion(mix=0.0, drive=0.5, ...))
         mixer.voice[0].play(fx.output)
 
-    ``stages`` extra 12 dB/octave sections give 12*(stages+1) overall,
-    counting the synth's own, so the default is 24 dB/octave. They track
-    the synth's cutoff AND resonance -- see the module comment.
-
-    ``distortion`` and ``echo`` are opt-in; each costs a buffer and real
-    CPU, and distortion is reportedly too slow to use on an rp2040.
-
-    Needs a CircuitPython build with ``audiofilters`` (and ``audiodelays``
-    for echo). Raises ImportError when constructed rather than when
-    imported, so the rest of the package still loads without them.
+    ``output`` is always the tail: the synth itself when the chain is
+    empty. Building an ``EffectsChain`` touches no effects module at all,
+    so it loads fine even where ``audiofilters`` doesn't exist; only the
+    effects you add to it need it.
+
+    A mixer voice holds whatever object ``output`` *was* at the time you
+    called ``play()``: it has no way to notice ``output`` changing
+    identity later. Any ``add``/``insert``/``remove`` that changes the
+    tail (an ``add``, an ``insert`` at the end, or removing the current
+    tail) needs ``mixer.voice[0].play(fx.output)`` called again to reach
+    the speaker; an insert/remove in the *middle* rewires in place and
+    needs nothing further, since the tail object itself doesn't change.
     """
 
-    def __init__(
-        self,
-        synth,
-        stages=1,
-        distortion=False,
-        echo=False,
-        buffer_size=1024,
-        delay_ms=500,
-        max_delay_ms=500,
-        decay=0.1,
-    ):
-        if audiofilters is None:
-            raise ImportError(
-                "audiofilters is not in this CircuitPython build; "
-                "EffectsChain needs it (audiodelays too, for echo)"
-            )
+    def __init__(self, synth):
         self.synth = synth
-        synthesizer = synth.synthio
-        cfg = {
-            "sample_rate": synthesizer.sample_rate,
-            "channel_count": synthesizer.channel_count,
-            "buffer_size": buffer_size,
-        }
-
-        stages = max(0, int(stages))
-        self.filter = None
-        if stages:
-            src = synth.filter  # the synth's own Biquad, built once
-            if src is None:
-                raise ValueError("synth has no filter (filt_type is None) to track")
-            # Copies sharing src's frequency AND Q blocks -- both live, so
-            # both track the synth (sweep, accent, and a filt_q knob turn)
-            # with nothing to keep in sync by hand. One Filter holding a
-            # tuple, not a Filter each: `filter` runs the sample through
-            # them in order, saving a buffer and a pass per stage.
-            biquads = tuple(
-                synthio.Biquad(src.mode, frequency=src.frequency, Q=src.Q) for _ in range(stages)
-            )
-            self.filter = audiofilters.Filter(filter=biquads, mix=1.0, **cfg)
-
-        self.distortion = None
-        if distortion:
-            # fmt: off
-            self.distortion = audiofilters.Distortion(
-                mode=audiofilters.DistortionMode.LOFI, mix=0.0, drive=0.5,
-                soft_clip=True, pre_gain=0, post_gain=0, **cfg)
-            # fmt: on
-
-        self.echo = None
-        if echo:
-            if audiodelays is None:
-                raise ImportError("audiodelays is not in this CircuitPython build")
-            # fmt: off
-            self.echo = audiodelays.Echo(
-                mix=0.0, max_delay_ms=max_delay_ms, delay_ms=delay_ms,
-                decay=decay, freq_shift=False, **cfg)
-            # fmt: on
-
-        # wire whatever exists, in order, and remember the tail
-        self.output = synthesizer
-        for fx in (self.filter, self.distortion, self.echo):
-            if fx is not None:
-                fx.play(self.output)
-                self.output = fx
-
-    # --- knobs, all no-ops when the effect was not built ----------------
-
-    @property
-    def filter_mix(self):
-        """Dry/wet for the extra filter stages. 1.0 = fully filtered."""
-        return self.filter.mix if self.filter is not None else 0.0
-
-    @filter_mix.setter
-    def filter_mix(self, v):
-        if self.filter is not None:
-            self.filter.mix = v
+        self._effects = []
 
     @property
-    def drive(self):
-        """Distortion amount, 0..1. Driven through pre_gain, not the
-        `drive` parameter, which does not do what its name suggests in LOFI
-        mode; post_gain pulls back the level pre_gain adds."""
-        return self.distortion.pre_gain / 50.0 if self.distortion is not None else 0.0
-
-    @drive.setter
-    def drive(self, v):
-        if self.distortion is not None:
-            self.distortion.pre_gain = v * 50.0
-            self.distortion.post_gain = v * -25.0
+    def effects(self):
+        """The chain in order, outermost effect last. Read-only: go
+        through :meth:`add`/:meth:`insert`/:meth:`remove` so an effect's
+        ``.play()`` source can never drift out of sync with this list."""
+        return tuple(self._effects)
 
     @property
-    def drive_mix(self):
-        return self.distortion.mix if self.distortion is not None else 0.0
-
-    @drive_mix.setter
-    def drive_mix(self, v):
-        if self.distortion is not None:
-            self.distortion.mix = v
-
-    @property
-    def delay_mix(self):
-        return self.echo.mix if self.echo is not None else 0.0
-
-    @delay_mix.setter
-    def delay_mix(self, v):
-        if self.echo is not None:
-            self.echo.mix = v
-
-    @property
-    def delay_ms(self):
-        return self.echo.delay_ms if self.echo is not None else 0.0
-
-    @delay_ms.setter
-    def delay_ms(self, v):
-        if self.echo is not None:
-            self.echo.delay_ms = v
-
-    def delay_sync(self, bpm, steps=4, steps_per_beat=4):
-        """Set the echo time to ``steps`` sequencer steps at ``bpm``. A
-        tempo-synced delay is most of what makes an acid line sit right."""
-        self.delay_ms = (60_000.0 / bpm / steps_per_beat) * steps
+    def output(self):
+        """The tail of the chain: what a mixer voice should play."""
+        return self._effects[-1] if self._effects else self.synth.synthio
+
+    def add(self, effect):
+        """Append ``effect`` to the end of the chain and return it."""
+        effect.play(self.output)
+        self._effects.append(effect)
+        return effect
+
+    def insert(self, index, effect):
+        """Insert ``effect`` at ``index`` (Python list semantics, negative
+        included), rewiring everything from there on."""
+        self._effects.insert(index, effect)
+        self._rewire(self._effects.index(effect))
+        return effect
+
+    def remove(self, effect):
+        """Take ``effect`` out of the chain and rewire around the gap."""
+        index = self._effects.index(effect)
+        del self._effects[index]
+        self._rewire(index)
+
+    def _rewire(self, from_index):
+        src = self._effects[from_index - 1] if from_index > 0 else self.synth.synthio
+        for stage in self._effects[from_index:]:
+            stage.play(src)
+            src = stage
+
+
+def tracking_filter(synth, stages=1, buffer_size=1024, mix=1.0):
+    """Build one ``audiofilters.Filter`` holding ``stages`` extra Biquads
+    that track ``synth.filter``'s cutoff AND resonance; see the module
+    comment for why that's automatic once they share the live blocks.
+    ``stages`` extra 12 dB/octave sections plus the synth's own give
+    ``12*(stages+1)`` overall.
+
+    Raises ``ImportError`` if this build has no ``audiofilters``,
+    ``ValueError`` if ``stages < 1`` or ``synth`` has no filter to track
+    (either a poly synth, which has no ``.filter`` at all, or a mono one
+    built with ``filt_type=None``).
+    """
+    if audiofilters is None:
+        raise ImportError("audiofilters is not in this CircuitPython build")
+    if stages < 1:
+        raise ValueError("stages must be >= 1")
+    src = getattr(synth, "filter", None)
+    if src is None:
+        raise ValueError("synth has no filter to track (mono-only, and filt_type must be set)")
+    synthesizer = synth.synthio
+    # Copies sharing src's frequency AND Q blocks, both live, so both track
+    # the synth (sweep, accent, a filt_q turn) with nothing to keep in sync
+    # by hand. One Filter holding a tuple, not a Filter each: `filter` runs
+    # the sample through them in order, saving a buffer and a pass per stage.
+    biquads = tuple(
+        synthio.Biquad(src.mode, frequency=src.frequency, Q=src.Q) for _ in range(stages)
+    )
+    return audiofilters.Filter(
+        filter=biquads,
+        mix=mix,
+        sample_rate=synthesizer.sample_rate,
+        channel_count=synthesizer.channel_count,
+        buffer_size=buffer_size,
+    )
+
+
+def set_drive(distortion, amount):
+    """Set a ``Distortion`` effect's drive, 0..1, through ``pre_gain`` and
+    ``post_gain`` (LOFI mode's own ``drive`` parameter does not do what
+    its name suggests); ``post_gain`` pulls back the level ``pre_gain``
+    adds."""
+    distortion.pre_gain = amount * 50.0
+    distortion.post_gain = amount * -25.0
+
+
+def sync_delay(echo, bpm, steps=4, steps_per_beat=4):
+    """Set an ``Echo`` effect's ``delay_ms`` to ``steps`` sequencer steps
+    at ``bpm``: a tempo-synced delay is most of what makes a repeating
+    line sit right."""
+    echo.delay_ms = (60_000.0 / bpm / steps_per_beat) * steps