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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.5
+Version: 0.5.1
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -44,6 +44,15 @@ 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>`_
+- `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
 =============
@@ -120,10 +129,14 @@ What's Included
 * ``SubtractiveSynth`` -- subtractive two-oscillator synth w/ detune
 * ``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

{circuitpython_synthtools-0.5.dist-info → circuitpython_synthtools-0.5.1.dist-info}/RECORD

@@ -1,9 +1,9 @@
-circuitpython_synthtools-0.5.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
-synthtools/__init__.py,sha256=KIHidF7kUN9xokoowebfF_6bNHwsgjeyrF14_1n00h4,1276
+circuitpython_synthtools-0.5.1.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
+synthtools/__init__.py,sha256=Hb5mohpSOi6Aba8IM48r8xxmJWd3NL7HqQVJ3F0xRHw,1318
 synthtools/ahr_envelope.py,sha256=t5JCgO5iGLVKr4MyKnu0PNV1NOk8YfALUo5q69TrYa0,9968
 synthtools/arpeggiator.py,sha256=n2sPnpZcu9soXsFJCh6OP65_0DuPnvQGUP0ao7V8SXM,3901
-synthtools/audio_fx.py,sha256=xR_1PnPlySlMmQ46DcpBoRfplBmVeYeEKFu22Z55vm0,6929
-synthtools/bassline_synth.py,sha256=pz5KNyR7iyiaLndL7UpSNMxTuMPuz7GNOKd72z6Y4h8,16680
+synthtools/audio_fx.py,sha256=YjnwniyqOu7UjCBnS0smY1Xsanbgoz_Aop-6bqJhGes,7085
+synthtools/bassline_synth.py,sha256=pnnGeYWFTtfEXmhTPOpoxFzh6WQIrAMqWWfWWn-rOvY,29287
 synthtools/blocks.py,sha256=NXRkNgKoTtPMh5eDJ2eC7aXmtuZVrr17ZDhFLhJ5tqY,1998
 synthtools/paramset.py,sha256=agk7IOr-OI_3g9LoV4-hZaZX7cI93GZe1vDeWiiwnqE,6732
 synthtools/patch.py,sha256=_ueCz9XJDZRRt6j6FboLIbQiikH04GRbsKtnVQr4gHE,5250
@@ -19,7 +19,7 @@ synthtools/wavetable_synth.py,sha256=lvxpvITDgkOK6AJVIBbLOUa01wjPSvGxHpbTdS2fY2g
 synthtools/ui/gauge_cluster.py,sha256=QnMBLMFgQhNTw7KQHp51ILzWeCrNLV8TwzDoHl_egG4,2900
 synthtools/ui/param.py,sha256=wJwIiaGlDnGPGCAdeA4veJv5BxbeHE8K4HaddeI6qQs,3629
 synthtools/ui/param_scaler.py,sha256=1Ow9lp7WgFauBV5dVFbynXxYd7OqAJhSKphSZNA_GO8,2958
-circuitpython_synthtools-0.5.dist-info/METADATA,sha256=EsgUQzn0mxBjnCEDQC-trA-ulQh9f9icpQDz0Gc4sfw,5698
-circuitpython_synthtools-0.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-circuitpython_synthtools-0.5.dist-info/top_level.txt,sha256=1xt53cH064i7vvFVDFyuJugc1NogReXvzsXbYGlgnKE,11
-circuitpython_synthtools-0.5.dist-info/RECORD,,
+circuitpython_synthtools-0.5.1.dist-info/METADATA,sha256=pX5x30A4Uz-N2k0S-KBUdKbD8wH3twsdGWtc0pZ7NbI,6454
+circuitpython_synthtools-0.5.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+circuitpython_synthtools-0.5.1.dist-info/top_level.txt,sha256=1xt53cH064i7vvFVDFyuJugc1NogReXvzsXbYGlgnKE,11
+circuitpython_synthtools-0.5.1.dist-info/RECORD,,

synthtools/__init__.py

@@ -25,7 +25,7 @@ Implementation Notes
 
 # imports
 
-from .audio_fx import EffectsChain
+from .audio_fx import EffectsChain, set_drive, sync_delay, tracking_filter
 from .bassline_synth import BasslineSynth
 from .patch import Patch, load_patches, save_patches
 from .subtractive_synth import SubtractiveSynth
@@ -41,5 +41,5 @@ try:
 except ImportError:
     pass
 
-__version__ = "0.5"
+__version__ = "0.5.1"
 __repo__ = "https://github.com/todbot/CircuitPython_SynthTools.git"

synthtools/audio_fx.py

@@ -1,8 +1,14 @@
 # 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.
+#
+# EffectsChain itself never imports audiofilters/audiodelays -- it just
+# calls `.play(source)` on whatever effect objects it's handed, so it loads
+# fine even where those modules don't exist. Only tracking_filter() (and
+# whatever Distortion/Echo objects a caller constructs) needs them.
 #
 # 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
@@ -11,9 +17,9 @@
 # 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: 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.)
+# Slope: every Biquad is 12 dB/oct, so `stages` extra ones plus the
+# synth's own give 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
@@ -31,150 +37,126 @@
 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, 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)
+    )
+    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

synthtools/bassline_synth.py

@@ -57,10 +57,18 @@
 
 import synthio
 
+from .audio_fx import EffectsChain, set_drive, tracking_filter
 from .blocks import clamp, product, sum3
-from .synth import Synth
+from .synth import FILTER_MODES, Synth
 from .waves import get_wave
 
+try:
+    import audiodelays
+    import audiofilters
+except ImportError:  # not in every CircuitPython build
+    audiodelays = None
+    audiofilters = None
+
 
 class BasslineSynth(Synth):
     """Monophonic acid bassline synth after the Roland TB-303: one
@@ -98,7 +106,16 @@ class BasslineSynth(Synth):
     # fmt: off
     _PARAMS = Synth._PARAMS + ("wave", "envmod", "decay", "amp_level",
                                "accent", "accent_cutoff", "accent_q",
-                               "slide_time", "transpose")
+                               "slide_time", "transpose",
+                               # the three STRUCTURAL fx_* fields
+                               # (fx_filter_stages, fx_distortion_on,
+                               # fx_echo_on) are deliberately absent: a
+                               # set_param() from a MIDI CC would silently
+                               # mute the fx chain, since nothing here can
+                               # reach into the mixer and re-play() the
+                               # new tail. See the "effects chain" section.
+                               "fx_filter_mix", "fx_drive", "fx_drive_mix",
+                               "fx_delay_ms", "fx_delay_mix", "fx_delay_decay")
     # fmt: on
 
     #: Inherently monophonic -- accent and glide are both shared state
@@ -125,6 +142,23 @@ class BasslineSynth(Synth):
     _filter = None  # the shared Biquad; see _build_filter()
     _cutoff = None  # its stable frequency node
 
+    # --- the owned effects chain: class attrs; see _build_fx() ----------
+    FX_BUFFER_SIZE = 1024
+    FX_MAX_DELAY_MS = 1000.0  # buffer sizing only, not a knob -- see fx_delay_ms
+    _fx_filter_stages = 0
+    _fx_filter_mix = 1.0
+    _fx_distortion_on = False
+    _fx_drive = 0.0
+    _fx_drive_mix = 0.0
+    _fx_echo_on = False
+    _fx_delay_ms = 300.0
+    _fx_delay_mix = 0.0
+    _fx_delay_decay = 0.3
+    _fx = None  # the owned EffectsChain, lazily built by _build_fx()
+    _fx_stage = None  # tracking_filter()'s Filter, if fx_filter_stages > 0
+    _fx_dist = None  # audiofilters.Distortion, if fx_distortion_on
+    _fx_delay = None  # audiodelays.Echo, if fx_echo_on
+
     def __init__(self, synthesizer, patch=None):
         super().__init__(synthesizer, patch)
         # _env_accent has no other home: Synth.__init__ calls _make_env()
@@ -150,6 +184,34 @@ class BasslineSynth(Synth):
         self._refresh_accent()  # also derives fenv_amount from envmod
         self._rebuild_env()
 
+        # --- the owned effects chain -------------------------------------
+        # Compare the three STRUCTURAL fields against what's already live
+        # BEFORE overwriting them: only a real shape change should drop
+        # self._fx. A patch load that leaves the fx shape alone must reach
+        # the live effects the same as every other param here, not freeze
+        # them -- see the "effects chain" section for why a naive
+        # unconditional invalidate is a silent wrong-sound bug.
+        new_stages = getattr(p, "fx_filter_stages", 0)
+        new_distortion_on = getattr(p, "fx_distortion_on", False)
+        new_echo_on = getattr(p, "fx_echo_on", False)
+        structural_changed = (
+            new_stages != self._fx_filter_stages
+            or new_distortion_on != self._fx_distortion_on
+            or new_echo_on != self._fx_echo_on
+        )
+        self._fx_filter_stages = new_stages
+        self._fx_distortion_on = new_distortion_on
+        self._fx_echo_on = new_echo_on
+        self._fx_filter_mix = getattr(p, "fx_filter_mix", 1.0)
+        self._fx_drive = getattr(p, "fx_drive", 0.0)
+        self._fx_drive_mix = getattr(p, "fx_drive_mix", 0.0)
+        self._fx_delay_ms = getattr(p, "fx_delay_ms", 300.0)
+        self._fx_delay_mix = getattr(p, "fx_delay_mix", 0.0)
+        self._fx_delay_decay = getattr(p, "fx_delay_decay", 0.3)
+        if structural_changed:
+            self._fx = None  # rebuilt lazily, next .fx/.output access
+        self._push_fx_live()
+
     def _decompile(self):
         super()._decompile()
         p = self.patch
@@ -165,6 +227,15 @@ class BasslineSynth(Synth):
         # which on an accented step is the boosted depth. envmod is the
         # real knob, so re-derive the clean value rather than store that.
         p.fenv_amount = -self._envmod * self._filt_f_blk.a
+        p.fx_filter_stages = self._fx_filter_stages
+        p.fx_filter_mix = self._fx_filter_mix
+        p.fx_distortion_on = self._fx_distortion_on
+        p.fx_drive = self._fx_drive
+        p.fx_drive_mix = self._fx_drive_mix
+        p.fx_echo_on = self._fx_echo_on
+        p.fx_delay_ms = self._fx_delay_ms
+        p.fx_delay_mix = self._fx_delay_mix
+        p.fx_delay_decay = self._fx_delay_decay
 
     # --- the shared filter ------------------------------------------------
     # Mono, so ONE Biquad and one cutoff node serve every note: built once
@@ -218,6 +289,108 @@ class BasslineSynth(Synth):
     def _make_filter(self):
         return self.filter
 
+    # --- the owned effects chain (optional) -------------------------------
+    # A specialized EffectsChain, not the general-purpose one: fixed order
+    # (filter -> distortion -> echo, the acid-bass signal flow), built
+    # from the SAME tracking_filter()/set_drive() free functions the demo
+    # used to call by hand. The three fx_*_on/fx_filter_stages fields are
+    # STRUCTURAL -- they decide what exists -- everything else is a LIVE
+    # write into whatever's already built. See fx_drive and friends below.
+
+    def _fx_cfg(self):
+        s = self.synthio
+        return {
+            "sample_rate": s.sample_rate,
+            "channel_count": s.channel_count,
+            "buffer_size": self.FX_BUFFER_SIZE,
+        }
+
+    def _build_fx(self):
+        """Build the owned chain from the current fx_* fields, once.
+
+        Atomic: everything lands in locals and self._fx/_fx_stage/_fx_dist/
+        _fx_delay are only assigned once every requested piece succeeds.
+        Assigning self._fx as each piece is built and then raising partway
+        (audiofilters present but audiodelays isn't, say) would leave
+        self._fx non-None with an fx_echo_on that never got its Echo --
+        later code would treat the chain as already built and never retry.
+        """
+        if self._fx is not None:
+            return
+        chain = EffectsChain(self)
+        stage = dist = delay = None
+        # No filter to track with filt_type=None -- an ordinary, silent
+        # no-op, the same as _voice_cutoff() returning None. tracking_filter
+        # itself raises ValueError for external callers who don't already
+        # know why; internally we do, so we just skip the stage instead of
+        # letting that surface from an `output` property read.
+        if self._fx_filter_stages > 0 and self._filt_mode is not None:
+            stage = chain.add(
+                tracking_filter(self, stages=self._fx_filter_stages, mix=self._fx_filter_mix)
+            )
+        if self._fx_distortion_on:
+            if audiofilters is None:
+                raise ImportError("audiofilters is not in this CircuitPython build")
+            # fmt: off
+            dist = chain.add(audiofilters.Distortion(
+                mode=audiofilters.DistortionMode.LOFI, mix=self._fx_drive_mix,
+                soft_clip=True, pre_gain=0, post_gain=0, **self._fx_cfg()))
+            # fmt: on
+            set_drive(dist, self._fx_drive)
+        if self._fx_echo_on:
+            if audiodelays is None:
+                raise ImportError("audiodelays is not in this CircuitPython build")
+            # fmt: off
+            delay = chain.add(audiodelays.Echo(
+                mix=self._fx_delay_mix, delay_ms=self._fx_delay_ms,
+                max_delay_ms=self.FX_MAX_DELAY_MS, decay=self._fx_delay_decay,
+                freq_shift=False, **self._fx_cfg()))
+            # fmt: on
+        self._fx, self._fx_stage, self._fx_dist, self._fx_delay = chain, stage, dist, delay
+
+    def _push_fx_live(self):
+        """Push the current fx_* values into whatever's already built.
+
+        A no-op for anything not built yet -- called by every live fx_*
+        setter AND by _recompile(), so a patch load reaches a chain that's
+        already sounding exactly like every other param in this class,
+        even mid-transition after a structural change has invalidated
+        self._fx but left the still-playing objects in place.
+        """
+        if self._fx_stage is not None:
+            self._fx_stage.mix = self._fx_filter_mix
+        if self._fx_dist is not None:
+            set_drive(self._fx_dist, self._fx_drive)
+            self._fx_dist.mix = self._fx_drive_mix
+        if self._fx_delay is not None:
+            self._fx_delay.delay_ms = self._fx_delay_ms
+            self._fx_delay.mix = self._fx_delay_mix
+            self._fx_delay.decay = self._fx_delay_decay
+
+    @property
+    def fx(self):
+        """The owned effects chain, built the first time anything needs
+        it. Add/insert/remove more effects on it if you want to extend
+        past filter+distortion+echo -- it's an ordinary ``EffectsChain``.
+        """
+        self._build_fx()
+        return self._fx
+
+    @property
+    def output(self):
+        """What a mixer voice should play: the synth itself, or the tail
+        of ``fx`` if any ``fx_*`` field asked for an effect.
+
+        A mixer voice's ``play()`` captures this object's identity at
+        call time. Changing any STRUCTURAL field (``fx_filter_stages``,
+        ``fx_distortion_on``, ``fx_echo_on`` -- directly, via
+        ``set_param()``, or via ``load_patch()``) invalidates the owned
+        chain, so re-fetch ``output`` and hand it to the mixer voice
+        again afterward. The LIVE fx knobs (mix, drive, delay time) need
+        no such thing -- they reach whatever's already playing.
+        """
+        return self.fx.output
+
     # --- accent ----------------------------------------------------------
 
     def _refresh_accent(self):
@@ -307,6 +480,25 @@ class BasslineSynth(Synth):
         self._filt_f_blk.a = v
         self._refresh_accent()
 
+    @property
+    def filt_type(self):
+        return self._filt_type
+
+    @filt_type.setter
+    def filt_type(self, v):
+        # Overridden to also invalidate the owned fx chain on a real mode
+        # change. _build_filter() already re-swaps the VOICE Biquad live
+        # (its frequency/Q are shared blocks, but `mode` isn't), and
+        # tracking_filter() copies that same mode as a plain value into
+        # each owned stage -- so left alone, a filt_type change would
+        # leave the voice on the new mode and the owned stages stuck on
+        # the old one: wrong sound, no exception.
+        old_mode = self._filt_mode
+        self._filt_type = v
+        self._filt_mode = FILTER_MODES.get(v)
+        if self._filt_mode != old_mode:
+            self._fx = None
+
     @property
     def envmod(self):
         """Filter sweep depth, 0..1, as a fraction of ``filt_f``.
@@ -408,3 +600,112 @@ class BasslineSynth(Synth):
     def wave(self, v):
         self._wave_name = v
         get_wave(v)  # O(1); warms the cache for the next note-on
+
+    # --- owned effects chain: the three STRUCTURAL switches --------------
+    # Changing any of these invalidates self._fx (rebuilt lazily, next
+    # .fx/.output access) but leaves whatever is currently built alone --
+    # it's still what the mixer is playing. See "the owned effects chain"
+    # above for why, and output's docstring for the resulting contract.
+
+    @property
+    def fx_filter_stages(self):
+        """Extra 12 dB/octave Biquad stages cascaded after the voice's own
+        filter, via ``tracking_filter()``. 0 = none (the default -- costs
+        nothing and never touches ``audiofilters``). Has no effect while
+        ``filt_type`` is ``None``: there is no cutoff to track."""
+        return self._fx_filter_stages
+
+    @fx_filter_stages.setter
+    def fx_filter_stages(self, v):
+        self._fx_filter_stages = v
+        self._fx = None
+
+    @property
+    def fx_distortion_on(self):
+        """Whether a distortion stage exists at all. Separate from
+        ``fx_drive_mix`` on purpose: even at mix 0 a ``Distortion`` effect
+        costs a buffer and real CPU every block, so whether one *exists*
+        has to be deliberate."""
+        return self._fx_distortion_on
+
+    @fx_distortion_on.setter
+    def fx_distortion_on(self, v):
+        self._fx_distortion_on = v
+        self._fx = None
+
+    @property
+    def fx_echo_on(self):
+        """Whether an echo stage exists at all -- see ``fx_distortion_on``,
+        same reasoning."""
+        return self._fx_echo_on
+
+    @fx_echo_on.setter
+    def fx_echo_on(self, v):
+        self._fx_echo_on = v
+        self._fx = None
+
+    # --- owned effects chain: the six LIVE knobs --------------------------
+    # Each reaches whatever's already built via _push_fx_live(); a no-op
+    # until the matching structural switch above turns the effect on.
+
+    @property
+    def fx_filter_mix(self):
+        """Dry/wet for the extra filter stages, 1.0 = fully filtered."""
+        return self._fx_filter_mix
+
+    @fx_filter_mix.setter
+    def fx_filter_mix(self, v):
+        self._fx_filter_mix = v
+        self._push_fx_live()
+
+    @property
+    def fx_drive(self):
+        """Distortion amount, 0..1, via ``set_drive()`` (LOFI mode's own
+        ``drive`` parameter does not behave as its name suggests)."""
+        return self._fx_drive
+
+    @fx_drive.setter
+    def fx_drive(self, v):
+        self._fx_drive = v
+        self._push_fx_live()
+
+    @property
+    def fx_drive_mix(self):
+        """Dry/wet for the distortion stage."""
+        return self._fx_drive_mix
+
+    @fx_drive_mix.setter
+    def fx_drive_mix(self, v):
+        self._fx_drive_mix = v
+        self._push_fx_live()
+
+    @property
+    def fx_delay_ms(self):
+        """Echo delay time in milliseconds."""
+        return self._fx_delay_ms
+
+    @fx_delay_ms.setter
+    def fx_delay_ms(self, v):
+        self._fx_delay_ms = v
+        self._push_fx_live()
+
+    @property
+    def fx_delay_mix(self):
+        """Dry/wet for the echo stage."""
+        return self._fx_delay_mix
+
+    @fx_delay_mix.setter
+    def fx_delay_mix(self, v):
+        self._fx_delay_mix = v
+        self._push_fx_live()
+
+    @property
+    def fx_delay_decay(self):
+        """Echo feedback, 0..1 -- how much each repeat carries into the
+        next. Unrelated to ``decay``, the filter-envelope fall time."""
+        return self._fx_delay_decay
+
+    @fx_delay_decay.setter
+    def fx_delay_decay(self, v):
+        self._fx_delay_decay = v
+        self._push_fx_live()