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

{circuitpython_synthtools-0.5.1/circuitpython_synthtools.egg-info → circuitpython_synthtools-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.5.1
+Version: 0.7.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -50,6 +50,7 @@ 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>`_
@@ -127,6 +128,12 @@ 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. Can
@@ -148,10 +155,15 @@ 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``)
 * ``RollingAverage`` -- moving-average smoothing for noisy knob reads
+* ``Scale`` / ``chord`` -- scales and diatonic/chromatic chords for
+  mapping pads and MIDI onto pitch
 
 Documentation
 =============

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/README.rst

@@ -30,6 +30,7 @@ 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>`_
@@ -107,6 +108,12 @@ 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. Can
@@ -128,10 +135,15 @@ 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``)
 * ``RollingAverage`` -- moving-average smoothing for noisy knob reads
+* ``Scale`` / ``chord`` -- scales and diatonic/chromatic chords for
+  mapping pads and MIDI onto pitch
 
 Documentation
 =============

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0/circuitpython_synthtools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.5.1
+Version: 0.7.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -50,6 +50,7 @@ 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>`_
@@ -127,6 +128,12 @@ 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. Can
@@ -148,10 +155,15 @@ 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``)
 * ``RollingAverage`` -- moving-average smoothing for noisy knob reads
+* ``Scale`` / ``chord`` -- scales and diatonic/chromatic chords for
+  mapping pads and MIDI onto pitch
 
 Documentation
 =============

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/circuitpython_synthtools.egg-info/SOURCES.txt

@@ -48,9 +48,15 @@ examples/synthinst_pitch_demo.py
 examples/synthinst_wave_demo.py
 examples/synthtools_ahr_envelope_bend.py
 examples/synthtools_bassline_demo.py
+examples/synthtools_fm_demo.py
+examples/synthtools_harmony_demo.py
+examples/synthtools_midi_demo.py
 examples/synthtools_simpletest.py
+examples/synthtools_swarm_demo.py
 examples/synthtools_wavetable_simple.py
 examples/trig_sequencer_demo.py
+examples/ui/synthtools_gaugecluster_test.py
+examples/ui/synthtools_paramscaler_demo.py
 examples/wavetables/BRAIDS02.WAV
 examples/wavetables/PLAITS02.WAV
 examples/wavs/kit0_909/00_909kick4.wav
@@ -68,32 +74,40 @@ synthtools/arpeggiator.py
 synthtools/audio_fx.py
 synthtools/bassline_synth.py
 synthtools/blocks.py
+synthtools/fm_synth.py
+synthtools/gauge_cluster.py
+synthtools/harmony.py
+synthtools/param_scaler.py
 synthtools/paramset.py
 synthtools/patch.py
 synthtools/pitch_glider.py
 synthtools/step_sequencer.py
 synthtools/subtractive_synth.py
+synthtools/swarm_synth.py
 synthtools/synth.py
 synthtools/trig_sequencer.py
 synthtools/utils.py
 synthtools/waves.py
 synthtools/wavetable.py
 synthtools/wavetable_synth.py
-synthtools/ui/gauge_cluster.py
-synthtools/ui/param.py
-synthtools/ui/param_scaler.py
 tests/README.md
 tests/plot_env.py
 tests/run_tests.sh
 tests/test_arpeggiator.py
 tests/test_audio_fx.py
 tests/test_env_shapes.py
+tests/test_fm_synth.py
+tests/test_harmony.py
 tests/test_mono.py
+tests/test_param_scaler.py
+tests/test_paramset.py
 tests/test_patch.py
 tests/test_pytest_smoke.py
+tests/test_swarm_synth.py
 tests/test_wiring.py
 tests/hw/run_on_device.py
 tests/hw/test_device.py
+tests/hw/test_display_cost.py
 tests/stubs/synthio.py
 tests/stubs/ulab/__init__.py
 tests/stubs/ulab/numpy.py

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/conftest.py

@@ -1,18 +1,17 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
 # SPDX-License-Identifier: MIT
 #
-# This project has no pytest suite -- see tests/README.md. The real tests
+# This project has no pytest suite; see tests/README.md. The real tests
 # are plain scripts run via `sh tests/run_tests.sh`, deliberately runnable
 # under a bare MicroPython too, which is incompatible with how pytest
 # collects and executes test modules.
 #
 # The shared Adafruit CI build action runs bare `python -m pytest`
 # whenever a tests/ directory exists at all, with no way to opt out or
-# scope it -- so without this file, pytest recursively discovers and
+# scope it, so without this file, pytest recursively discovers and
 # tries to *import* every test_*.py / *_test.py file in the whole repo:
 #   - examples/*_test.py expect to be copied flat onto a CIRCUITPY drive
-#     alongside their sibling modules (see CLAUDE.md's examples note),
-#     not run from this tree.
-#   - tests/hw/test_device.py needs a real synthio -- it only runs on
+#     alongside their sibling modules, not run from this tree.
+#   - tests/hw/test_device.py needs a real synthio: it only runs on
 #     actual hardware (see tests/README.md).
 collect_ignore_glob = ["examples/*", "tests/hw/*"]

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/docs/api.rst

@@ -28,6 +28,18 @@ Subtractive Synth
 .. automodule:: synthtools.subtractive_synth
     :members:
 
+FM Synth
+========
+
+.. automodule:: synthtools.fm_synth
+    :members:
+
+Swarm Synth
+===========
+
+.. automodule:: synthtools.swarm_synth
+    :members:
+
 Bassline Synth
 ==============
 
@@ -70,6 +82,12 @@ Waves
 .. automodule:: synthtools.waves
     :members:
 
+Harmony
+=======
+
+.. automodule:: synthtools.harmony
+    :members:
+
 Arpeggiator
 ===========
 
@@ -105,3 +123,15 @@ Utils
 
 .. automodule:: synthtools.utils
     :members:
+
+Param Scaler
+============
+
+.. automodule:: synthtools.param_scaler
+    :members:
+
+Gauge Cluster
+=============
+
+.. automodule:: synthtools.gauge_cluster
+    :members:

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/docs/conf.py

@@ -22,12 +22,21 @@ extensions = [
 ]
 
 # synthtools/__init__.py now imports the engine (synth.py etc.), which pulls
-# in synthio and ulab at import time -- neither exists off-device, so autodoc
+# in synthio and ulab at import time: neither exists off-device, so autodoc
 # needs mocks or it fails to import the package at all. adafruit_wave is
 # optional at runtime (synthtools/__init__.py already guards it with
 # try/except ImportError) but still needs mocking here since the docs build
 # has no real one installed either.
-autodoc_mock_imports = ["synthio", "ulab", "adafruit_wave"]
+# displayio/vectorio come with synthtools.gauge_cluster; micropython (for
+# const) with synthtools.param_scaler. None ships on desktop CPython.
+autodoc_mock_imports = [
+    "synthio",
+    "ulab",
+    "adafruit_wave",
+    "displayio",
+    "vectorio",
+    "micropython",
+]
 
 autodoc_preserve_defaults = True
 

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/docs/examples.rst

@@ -44,6 +44,25 @@ Show how to use Synth's pitch modulation features
     :caption: examples/synthtools_pitch_demo.py
     :linenos:
 
+FM synth demo
+-------------
+
+A bright DX-style FM bell using FMSynth, with a live fm_ratio / fm_index sweep
+
+.. literalinclude:: ../examples/synthtools_fm_demo.py
+    :caption: examples/synthtools_fm_demo.py
+    :linenos:
+
+Harmony demo
+------------
+
+Walk scales and play diatonic chords with harmony.Scale, cycling through a
+short chord progression
+
+.. literalinclude:: ../examples/synthtools_harmony_demo.py
+    :caption: examples/synthtools_harmony_demo.py
+    :linenos:
+
 
 
  

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/examples/synth_setup.py

@@ -12,7 +12,7 @@ import board
 import keypad
 import synthio
 
-SAMPLE_RATE = 44100
+SAMPLE_RATE = 22050
 CHANNEL_COUNT = 2
 BUFFER_SIZE = 2048
 

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/examples/synthinst_code1.py

@@ -45,7 +45,7 @@ while True:
     i += 1
 
     # live filter sweep: one write into a shared block, O(1) in polyphony.
-    # deadband it -- a jittery pot otherwise writes on every single frame.
+    # deadband it: a jittery pot otherwise writes on every single frame.
     sweep = (sweep + 7) % 100
     new_f = 400 + 30 * sweep
     if abs(new_f - synth.filt_f) > 5:
@@ -62,7 +62,7 @@ while True:
     #   synth.filt_vel = -1500         # hard playing CLOSES the filter
     #   synth.pitch_bend(0.05)
 
-    # NOTE none of the above touched `patch` -- knob turns are live state
+    # NOTE none of the above touched `patch`; knob turns are live state
     # only. To keep them, snapshot first:
     #   synth.save_patch().save("/my_patch.json")
     # and reloading the old patch is therefore a revert:

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/examples/synthinst_fenv_demo.py

@@ -20,16 +20,16 @@ patch = Patch(
     detune=1.004,
     # A filter has to exist before an envelope can sweep it. filt_f is the
     # resting cutoff, i.e. the FLOOR the envelope rises from and falls back
-    # to -- keep it low and let the envelope supply the brightness.
+    # to: keep it low and let the envelope supply the brightness.
     filt_type="LPF",
     filt_f=350,
     filt_q=1.6,
     # The envelope itself. fenv_amount is Hz ABOVE filt_f, and it defaults
-    # to 0, which switches the envelope off entirely -- it is the one field
+    # to 0, which switches the envelope off entirely: it is the one field
     # you cannot leave out.
     fenv_amount=4000,
     # 0.05s, not 0.02s. synthio updates blocks every 256 samples (~5.8ms at
-    # 44.1kHz), so a 0.02s attack is barely THREE steps -- you hear a click,
+    # 44.1kHz), so a 0.02s attack is barely THREE steps: you hear a click,
     # not a sweep. Anything you want to hear as movement needs to span a few
     # dozen updates.
     fenv_attack=0.05,
@@ -40,11 +40,11 @@ patch = Patch(
     filt_lfo_rate=0.4,
     filt_lfo_amount=0,
     # Velocity: both default to 0, meaning "velocity changes nothing".
-    # filt_vel is signed -- negative means hard playing closes the filter.
+    # filt_vel is signed: negative means hard playing closes the filter.
     filt_vel=0,
     fenv_vel=0.0,
     # The amp release must OUTLAST fenv_release, because the filter envelope
-    # only runs while the note is alive -- a short amp release silently cuts
+    # only runs while the note is alive: a short amp release silently cuts
     # the sweep short. But not by much: a long amp tail piles voices on top
     # of each other, and four overlapping sweeps at different points average
     # out into a constant brightness. 0.22 against fenv_release 0.22 keeps
@@ -60,7 +60,7 @@ riff = (36, 36, 48, 36, 43, 36, 46, 36)
 # any of this is audible:
 #   1. AHR holds at PEAK for as long as the key is down, so the only movement
 #      during the loud part of a note is the attack. The note has to be long
-#      enough to contain it -- a 0.10s note cannot show off a 0.25s attack, it
+#      enough to contain it: a 0.10s note cannot show off a 0.25s attack, it
 #      just sounds duller because the sweep never finishes.
 #   2. note lifetime / BEAT = how many voices overlap. At BEAT 0.16 with a 0.5s
 #      amp release that was 3.7 voices, each at a different point in its sweep,
@@ -85,40 +85,40 @@ def play(bars, label, velocity=110):
 while True:
     # 1. the envelope switched off: flat, dull, no movement at all
     synth.fenv_amount = 0
-    play(1, "fenv_amount=0     -- envelope off, static filter")
+    play(1, "fenv_amount=0    ; envelope off, static filter")
 
     # 2. switched on: the classic filter pluck
     synth.fenv_amount = 4000
-    play(1, "fenv_amount=4000  -- sweeps 350 -> 4350 Hz and back")
+    play(1, "fenv_amount=4000 ; sweeps 350 -> 4350 Hz and back")
 
     # 3. slower attack: the sweep becomes a swell rather than a pluck. This
-    #    only reads because the key is held 0.28s -- longer than the attack.
+    #    only reads because the key is held 0.28s: longer than the attack.
     #    Ask for a 0.25s swell on a 0.10s note and you just get a duller note.
     synth.fenv_attack = 0.25
-    play(1, "fenv_attack=0.25  -- slow rise, a swell not a pluck")
+    play(1, "fenv_attack=0.25 : slow rise, a swell not a pluck")
     synth.fenv_attack = 0.05
 
     # 4. longer release: the tail rings on after the key is up. The amp
-    #    release has to be raised WITH it -- the filter envelope stops dead
+    #    release has to be raised WITH it: the filter envelope stops dead
     #    when the voice is freed, so a 0.45s sweep under a 0.22s amp release
     #    is silently truncated to 0.22s and sounds like nothing changed.
     synth.release_time = 0.5
     synth.fenv_release = 0.45
-    play(1, "fenv_release=0.45 -- long tail (amp release raised to match)")
+    play(1, "fenv_release=0.45: long tail (amp release raised to match)")
     synth.fenv_release = 0.22
     synth.release_time = 0.22
 
-    # 5. curve: 1 is a straight line up and down. 2 is the analog feel --
+    # 5. curve: 1 is a straight line up and down. 2 is the analog feel:
     #    the rise snaps up and eases into the peak, and the release drops
     #    fast then tails off (15% of its height by halfway, vs 50% linear).
     synth.fenv_curve = 2
-    play(1, "fenv_curve=2      -- snappy rise, decaying tail on release")
+    play(1, "fenv_curve=2      (snappy rise, decaying tail on release")
     synth.fenv_curve = 3
-    play(1, "fenv_curve=3      -- more so: nearly a pluck")
+    play(1, "fenv_curve=3     ) more so: nearly a pluck")
     synth.fenv_curve = 1
 
     # 6. the cyclic LFO: the fourth modulation on the same cutoff. It SUMS
-    #    with the envelope, which is exactly why it needs its own moment --
+    #    with the envelope, which is exactly why it needs its own moment:
     #    with fenv_amount at 4000 the cutoff sits at 4-5kHz, and a 900Hz
     #    wobble up there is 0.39 of an octave on a 65Hz saw that has almost
     #    no energy left above 4kHz. Inaudible, despite being a big number.
@@ -126,26 +126,26 @@ while True:
     #    harmonics to remove.
     #
     #    So: envelope off, and put the LFO somewhere it can be heard. The
-    #    LFO is ADDITIVE -- filt_f is the floor and it opens 0..amount
+    #    LFO is ADDITIVE: filt_f is the floor and it opens 0..amount
     #    upward, it does not swing either side of filt_f. So to get a wide
     #    sweep, put the floor LOW and let the amount do the work.
     #    Note the rate too: 0.4Hz is a 2.5s cycle, slower than one note, so
     #    it drifts across the phrase instead of wobbling within a note.
     synth.fenv_amount = 0
     synth.filt_f = 120
-    synth.filt_lfo_amount = 1800  # 120..1920 Hz -- 4 octaves
+    synth.filt_lfo_amount = 1800  # 120..1920 Hz (4 octaves
     synth.filt_lfo_rate = 3.0  # ~1.5 cycles per note
-    play(1, "filt_lfo 1800 @ 3Hz -- envelope off, LFO alone: 120..1920 Hz")
+    play(1, "filt_lfo 1800 @ 3Hz) envelope off, LFO alone: 120..1920 Hz")
 
     #    ...and now both at once, with the envelope kept small enough that
     #    the LFO still reads on top of it. It reads less at the envelope's
-    #    peak than between notes -- that is the additive Hz bus being
+    #    peak than between notes: that is the additive Hz bus being
     #    honest, not a bug: the same Hz depth is fewer octaves higher up.
     synth.filt_f = 250
     synth.fenv_amount = 200
     synth.filt_lfo_amount = 1800
     synth.filt_lfo_rate = 5.0
-    play(1, "filt_lfo + fenv     -- the two summing on one cutoff")
+    play(1, "filt_lfo + fenv    : the two summing on one cutoff")
     synth.filt_lfo_amount = 0
     synth.filt_lfo_rate = 0.4
     synth.filt_f = 350
@@ -155,14 +155,14 @@ while True:
     #    NEW notes (at 0 no per-voice node is built at all), but once a voice
     #    has one, the knob keeps reaching it.
     synth.filt_vel = 2500
-    play(1, "filt_vel=2500     -- soft notes darker (every 4th is soft)")
+    play(1, "filt_vel=2500     (soft notes darker (every 4th is soft)")
     synth.filt_vel = -2500
-    play(1, "filt_vel=-2500    -- inverted: hard notes darker")
+    play(1, "filt_vel=-2500   ) inverted: hard notes darker")
     synth.filt_vel = 0
 
     # 8. velocity scales how far the envelope sweeps
     synth.fenv_vel = 1.0
-    play(1, "fenv_vel=1.0      -- soft notes sweep less far")
+    play(1, "fenv_vel=1.0     : soft notes sweep less far")
     synth.fenv_vel = 0.0
 
     # Nothing above was written to `patch`. To keep the current sound:

{circuitpython_synthtools-0.5.1 → circuitpython_synthtools-0.7.0}/examples/synthinst_pad_demo.py

@@ -10,7 +10,7 @@
 #
 # The third of the three: synthinst_fenv_demo.py is the filter as a plucky
 # attack gesture, synthinst_pitch_demo.py is everything reaching note.bend,
-# and this one is the filter moving SLOWLY under held chords -- where the
+# and this one is the filter moving SLOWLY under held chords; where the
 # envelope's shape and the filter LFO actually become audible as motion
 # rather than as a transient.
 #
@@ -18,13 +18,13 @@
 # synth.max_polyphony is 24 on rp2040 (measured; the synthio stub docstring
 # still claims 12 and is out of date). SubtractiveSynth spends TWO Notes
 # per key whenever detune != 1.0, and releasing notes hold their slots
-# until the amp envelope finishes -- and with a 2.6s release, chords here
+# until the amp envelope finishes, and with a 2.6s release, chords here
 # DO overlap. So:
 #
 #     4-note chord, detune on  ->  8 Notes, 16 while two chords overlap
 #     5-note chord, detune on  -> 10 Notes, 20 while two chords overlap
 #
-# Both fit. Detune stays on, which matters on a pad -- two slightly
+# Both fit. Detune stays on, which matters on a pad: two slightly
 # mistuned saws per key is most of what makes it sound wide. Go past
 # 5-note chords and the arithmetic is worth redoing.
 #
@@ -45,10 +45,10 @@ from synthtools import Patch, SubtractiveSynth
 patch = Patch(
     name="slowpad",
     wave="SAW",
-    detune=1.004,  # two Notes per key -- see the polyphony note above
+    detune=1.004,  # two Notes per key: see the polyphony note above
     filt_type="LPF",
     # A low floor and real resonance. Resonance is what makes a slow sweep
-    # audible as MOVEMENT -- at filt_q 0.7 a slow sweep just sounds like a
+    # audible as MOVEMENT: at filt_q 0.7 a slow sweep just sounds like a
     # tone control being turned, with no character to track.
     filt_f=180,
     filt_q=1.9,
@@ -59,7 +59,7 @@ patch = Patch(
     filt_lfo_rate=0.5,
     filt_lfo_amount=0,
     # Pad amp envelope. The release (2.6) must OUTLAST fenv_release, or the
-    # voice is freed part-way down and the filter sweep is cut short --
+    # voice is freed part-way down and the filter sweep is cut short:
     # it sounds like a broken envelope but is just the note ending.
     amp_env=[0.35, 0.3, 0.85, 2.6],
 )
@@ -104,31 +104,31 @@ while True:
 
     # 1. reference: filter parked, nothing moves
     synth.fenv_amount = 0
-    chord("fenv_amount=0      -- static filter, dull and unmoving", secs=2)
+    chord("fenv_amount=0     ; static filter, dull and unmoving", secs=2)
 
     # 2. the classic slow swell. Held 6s against a 2.5s attack, so you hear
     #    the sweep finish and then sit at the top for a while.
     synth.fenv_amount = 5000
     synth.fenv_attack = 2.5
-    chord("fenv_attack=2.5    -- slow swell up to 5180 Hz, then holds")
+    chord("fenv_attack=2.5   : slow swell up to 5180 Hz, then holds")
 
     # 3. slower still, and held longer to contain it
     synth.fenv_attack = 5.0
-    chord("fenv_attack=5.0    -- a very slow open, held 7s", secs=6.0)
+    chord("fenv_attack=5.0   : a very slow open, held 7s", secs=6.0)
     synth.fenv_attack = 2.5
 
     # 4. the release half. fenv_release 2.5 under an amp release of 2.6:
     #    the filter closes as the chord fades, which is most of what makes
     #    a pad sound like it is being played rather than switched off.
     synth.fenv_release = 2.5
-    chord("fenv_release=2.5   -- listen past the key release, it closes down",
+    chord("fenv_release=2.5  : listen past the key release, it closes down",
           secs=4.0, tail=3.5)
 
     # 5. curve. On a plucky note this is nearly inaudible; over 2.5s it is
     #    obvious. 1 is a straight line; 3 snaps open early then eases into
     #    the top, and drops away fast on release with a long tail.
     synth.fenv_curve = 3
-    chord("fenv_curve=3       -- same times, front-loaded: opens early",
+    chord("fenv_curve=3      : same times, front-loaded: opens early",
           secs=6.0, tail=3.5)
     synth.fenv_curve = 1
 
@@ -143,15 +143,15 @@ while True:
     synth.fenv_amount = 0
     synth.filt_lfo_rate = 0.1
     synth.filt_lfo_amount = 2000
-    chord("filt_lfo 2000 @ 0.1Hz -- one slow sweep up & back, no envelope", secs=12.0)
+    chord("filt_lfo 2000 @ 0.1Hz: one slow sweep up & back, no envelope", secs=12.0)
 
     # 7. both at once. The envelope opens it on the attack, the LFO keeps
-    #    it moving afterwards -- they SUM on one cutoff, so the envelope's
+    #    it moving afterwards: they SUM on one cutoff, so the envelope's
     #    5000 raises the floor the LFO wobbles around.
     synth.fenv_amount = 3000
     synth.filt_lfo_amount = 2500
     synth.filt_lfo_rate = 0.12
-    chord("fenv + slow LFO    -- envelope opens it, LFO keeps it breathing",
+    chord("fenv + slow LFO   : envelope opens it, LFO keeps it breathing",
           secs=12.0)
     synth.filt_lfo_amount = 0
     synth.fenv_amount = 5000
@@ -164,14 +164,14 @@ while True:
     #    different brightness and they pull apart as the chord opens.
     #    A single global envelope could not do this.
     synth.fenv_vel = 1.0
-    chord("fenv_vel=1.0       -- one chord, four velocities, four sweeps",
+    chord("fenv_vel=1.0      : one chord, four velocities, four sweeps",
           vels=(40, 70, 100, 127), secs=8.0)
     synth.fenv_vel = 0.0
 
     # 9. The same point in time rather than in depth: notes entering 0.9s
     #    apart each start their OWN envelope from zero, so the chord opens
     #    as a staircase instead of all at once.
-    stagger("staggered entry   -- each voice sweeps on its own clock")
+    stagger("staggered entry  : each voice sweeps on its own clock")
 
     print()
     print("=== a whole progression, everything on ===")