circuitpython-synthtools 0.5__tar.gz → 0.5.1__tar.gz

{circuitpython_synthtools-0.5 → circuitpython_synthtools-0.5.1}/PKG-INFO

@@ -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 → circuitpython_synthtools-0.5.1}/README.rst

@@ -24,6 +24,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
 =============
@@ -100,10 +109,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 → circuitpython_synthtools-0.5.1}/circuitpython_synthtools.egg-info/PKG-INFO

@@ -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 → circuitpython_synthtools-0.5.1}/examples/synthtools_bassline_demo.py

@@ -62,27 +62,26 @@ patch = Patch(
     amp_level=0.75,  # un-accented level, so accents have room to be louder
     slide_time=0.09,
     transpose=0,
+    # --- BasslineSynth's own effects chain, if this build has
+    # audiofilters. A synthio.Note holds ONE Biquad, so the voice alone
+    # is 12 dB/octave; one extra stage makes 24, where the squelch really
+    # lives. The stage tracks synth.filter's cutoff AND resonance on its
+    # own, so it follows the sweep and the accent with nothing to keep in
+    # sync by hand -- see fx_filter_stages in bassline_synth.py.
+    fx_filter_stages=1,
 )
 
 synth = BasslineSynth(engine, patch)
 
-# --- extra filter slope, if this build has audiofilters -----------------
-# A synthio.Note holds ONE Biquad, so the voice alone is 12 dB/octave.
-# One extra stage makes 24, which is where the squelch really lives. The
-# stage tracks synth.cutoff_block, so it follows the sweep and the accent
-# with nothing to keep in sync by hand.
 try:
-    from synthtools.audio_fx import EffectsChain
-
-    fx = EffectsChain(synth, stages=1)
-    mixer.voice[0].play(fx.output)  # replaces synth_setup's direct hookup
+    mixer.voice[0].play(synth.output)  # replaces synth_setup's direct hookup
     print("filter: 24 dB/octave (1 extra stage)")
 except ImportError:
     print("no audiofilters in this build -- 12 dB/octave, voice filter only")
+    mixer.voice[0].play(synth.synthio)
 
 # --- the pattern --------------------------------------------------------
-# (midi_note, slide, accent), or None for a rest. Slides and accents are
-# what turn a scale into a bassline, so this leans on both.
+# (midi_note, slide, accent), or None for a rest.
 PATTERN = (
     (36, False, True),
     (36, False, False),

{circuitpython_synthtools-0.5 → circuitpython_synthtools-0.5.1}/pyproject.toml

@@ -13,7 +13,7 @@ requires = [
 [project]
 name = "circuitpython-synthtools"
 description = "CircuitPython helper library to do help doing synthio"
-version = "0.5"
+version = "0.5.1"
 readme = "README.rst"
 authors = [
     {name = "Tod Kurt", email = "tod@todbot.com"}

{circuitpython_synthtools-0.5 → circuitpython_synthtools-0.5.1}/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"

circuitpython_synthtools-0.5.1/synthtools/audio_fx.py

@@ -0,0 +1,162 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# 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
+# 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: 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
+# 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.
+#
+# 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.
+
+import synthio
+
+try:
+    import audiofilters
+except ImportError:  # not in every CircuitPython build
+    audiofilters = None
+
+
+class EffectsChain:
+    """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)
+
+    ``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):
+        self.synth = synth
+        self._effects = []
+
+    @property
+    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 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