circuitpython-synthtools 0.5__py3-none-any.whl

circuitpython_synthtools-0.5.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: circuitpython-synthtools
+Version: 0.5
+Summary: CircuitPython helper library to do help doing synthio
+Author-email: Tod Kurt <tod@todbot.com>
+License: MIT
+Project-URL: Homepage, https://github.com/todbot/CircuitPython_SynthTools
+Keywords: adafruit,blinka,circuitpython,micropython,synthtools,synth,synthio,synthesizer,waveform,wav,wave,wavetable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: Adafruit-Blinka
+Provides-Extra: optional
+Dynamic: license-file
+
+Introduction
+============
+
+
+.. image:: https://readthedocs.org/projects/circuitpython-synthtools/badge/?version=latest
+    :target: https://circuitpython-synthtools.readthedocs.io/
+    :alt: Documentation Status
+
+
+
+.. image:: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://adafru.it/discord
+    :alt: Discord
+
+
+.. image:: https://github.com/todbot/CircuitPython_SynthTools/workflows/Build%20CI/badge.svg
+    :target: https://github.com/todbot/CircuitPython_SynthTools/actions
+    :alt: Build Status
+
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://github.com/astral-sh/ruff
+    :alt: Code Style: Ruff
+
+CircuitPython library with tools for making synths with synthio
+
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
+or individual libraries can be installed using
+`circup <https://github.com/adafruit/circup>`_.
+
+
+Installing to a Connected CircuitPython Device with Circup
+==========================================================
+
+Make sure that you have ``circup`` installed in your Python environment.
+Install it with the following command if necessary:
+
+.. code-block:: shell
+
+    pip3 install circup
+
+With ``circup`` installed and your CircuitPython device connected use the
+following command to install:
+
+.. code-block:: shell
+
+    circup install synthtools
+
+Or the following command to update an existing version:
+
+.. code-block:: shell
+
+    circup update
+
+Usage Example
+=============
+
+.. code-block:: python
+
+    import time
+    from synth_setup import synth as engine
+    from synthtools import Patch, SubtractiveSynth
+
+    patch1 = Patch(name="fat bass", wave="ASAW", detune=1.004,
+                   filt_type="LPF", filt_f=800, filt_q=1.4,
+                   amp_env=[0.01, 0.1, 0.8, 0.4],
+                   vib_rate=5.5, vib_depth=0.0,
+                   # AHR filter envelope: cutoff swings 800 -> 3800 Hz and back
+                   fenv_amount=3000, fenv_attack=0.02, fenv_release=0.30,
+                   # a slow cyclic wobble on top of it (0 = off)
+                   filt_lfo_rate=0.4, filt_lfo_amount=0.3)
+    synth = SubtractiveSynth(engine, patch1)
+    arp = (36, 39, 43, 48)
+    i = 0
+    sweep = 0
+    while True:
+        synth.note_on(arp[i % len(arp)], velocity=110)
+        time.sleep(0.11)
+        synth.note_off(arp[i % len(arp)])
+        time.sleep(0.02)
+        i += 1
+        if i % 32 == 0:  # flip waveforms now and then
+            synth.wave = "ASQU" if synth.wave == "ASAW" else "ASAW"
+
+
+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
+* ``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)
+* ``Patch`` -- inert, JSON-able patch data; save/load with
+  ``save_patches()`` / ``load_patches()``
+* ``Wavetable`` -- loads a wavetable WAV file and lerps between frames
+* ``AHREnvelope`` -- shared-block attack/release envelope, used for both
+  the filter and pitch envelopes
+* ``Waves`` -- waveform factory (saw, square, sine, triangle, noise, and
+  "analog" variants)
+* ``Arpeggiator`` / ``StepSequencer`` / ``TrigSequencer`` -- poll-based
+  sequencers with on/off callbacks
+* ``Param`` / ``ParamSet`` -- knob-pickup and scaling for UIs with fewer
+  knobs than parameters
+* ``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
+
+Documentation
+=============
+API documentation for this library can be found on `Read the Docs <https://circuitpython-synthtools.readthedocs.io/>`_.
+
+For information on building library documentation, please check out
+`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/todbot/CircuitPython_SynthTools/blob/HEAD/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.

circuitpython_synthtools-0.5.dist-info/RECORD

@@ -0,0 +1,25 @@
+circuitpython_synthtools-0.5.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
+synthtools/__init__.py,sha256=KIHidF7kUN9xokoowebfF_6bNHwsgjeyrF14_1n00h4,1276
+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/blocks.py,sha256=NXRkNgKoTtPMh5eDJ2eC7aXmtuZVrr17ZDhFLhJ5tqY,1998
+synthtools/paramset.py,sha256=agk7IOr-OI_3g9LoV4-hZaZX7cI93GZe1vDeWiiwnqE,6732
+synthtools/patch.py,sha256=_ueCz9XJDZRRt6j6FboLIbQiikH04GRbsKtnVQr4gHE,5250
+synthtools/pitch_glider.py,sha256=R5h0Lbyq_slo7SKORRM7a0oumVugE15L8hOZJCov0AY,1927
+synthtools/step_sequencer.py,sha256=SkQuDsRtpAdKOXU3OsFmngeDPVQ0OXt3Gj5wqFCkEPM,4202
+synthtools/subtractive_synth.py,sha256=_NOS_P6atTSksPVA1iQxBffGrHvaqddrQYj1KWaHOxE,3552
+synthtools/synth.py,sha256=XFghrQy3To2ImRKYUx3LpmlH4aNfFIfRqheM-rGQvnE,31769
+synthtools/trig_sequencer.py,sha256=PaWgsTqOvuRjFUJ6VjxMLBuRkyeYCML9WQXBzx02Onk,2921
+synthtools/utils.py,sha256=z0gCbt238W-F29kYpRDXpvQTPZv30rghtHjiwgOpBnw,650
+synthtools/waves.py,sha256=j0Suuzd6_CpOaqkq5oEBCfN1NTWQQMGz9sc2dO-ehpg,19128
+synthtools/wavetable.py,sha256=yrJf2bxjGoOq4PlE4904xQHwmDBrLhb_RH_2xhnxGNk,2545
+synthtools/wavetable_synth.py,sha256=lvxpvITDgkOK6AJVIBbLOUa01wjPSvGxHpbTdS2fY2g,2744
+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.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

circuitpython_synthtools-0.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Tod Kurt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

circuitpython_synthtools-0.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+synthtools

synthtools/__init__.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+# SPDX-FileCopyrightText: Copyright (c) 2024 Tod Kurt
+#
+# SPDX-License-Identifier: MIT
+"""
+`synthtools`
+================================================================================
+
+CircuitPython helper library to do help doing synthio
+
+
+* Author(s): Tod Kurt
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+
+* synthio : https://docs.circuitpython.org/en/latest/shared-bindings/synthio/
+
+"""
+
+# 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"
+__repo__ = "https://github.com/todbot/CircuitPython_SynthTools.git"

synthtools/ahr_envelope.py

@@ -0,0 +1,232 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# 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:
+#
+#   pos = LFO(waveform = shared shape, rate = shared rate, once = True)
+#   env = Math(CONSTRAINED_LERP, 0.0, depth, pos)      -> the output block
+#         depth = the shared amount block, or PRODUCT(amount, gain)
+#
+# 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.
+#
+# 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
+# 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
+# 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.
+#
+# --- 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:
+#
+#   _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.
+
+import synthio
+
+from .blocks import product, scalar_block
+from .waves import env_buffer, fill_env_rise
+
+
+class AHREnvelope:
+    """Shared-block attack/release envelope. One instance owns the shape
+    buffer, the rate blocks and the depth blocks; make() hands out one small
+    block graph per voice that reads them.
+
+    Both DESTINATION- and DIRECTION-agnostic, so one class covers every
+    one-shot envelope in the library:
+
+        falling=False   0 -> amount, release back to release_amount
+        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
+    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
+    amount block, the shared rates, the in-place shape buffer, the
+    re-aim-the-endpoints release -- is identical, which is why this is one
+    class with a flag rather than two classes."""
+
+    def __init__(
+        self, attack=0.05, release=0.4, amount=0.0, curve=1, falling=False, release_amount=0.0
+    ):
+        self._attack = attack
+        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.
+        self._wave = env_buffer()
+        self._rate_a = scalar_block(1.0)
+        self._rate_r = scalar_block(1.0)
+        self._amt = scalar_block(amount)
+        # Where a release lands. A BLOCK even when it only ever holds 0.0
+        # (the filter case): that removes the special case from
+        # start_release() and keeps the target live for releasing voices.
+        self._rel_amt = scalar_block(release_amount)
+        self._refresh_shape()
+        self._refresh_rates()
+
+    # --- shape ----------------------------------------------------------
+
+    def _refresh_shape(self):
+        """Rewrite the shared shape in place. Voices already sounding pick
+        this up immediately, because they read this very buffer."""
+        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
+        self._rate_a.a = 1.0 / max(self._attack, 0.001)
+        self._rate_r.a = 1.0 / max(self._release, 0.001)
+
+    def configure(self, attack, release, amount, curve, release_amount=0.0):
+        """Set everything at once with a single shape rebuild. For patch
+        loads; the individual properties are the knob path."""
+        self._attack = attack
+        self._release = release
+        self._curve = curve
+        self._amt.a = amount
+        self._rel_amt.a = release_amount
+        self._refresh_shape()
+        self._refresh_rates()
+
+    # --- live parameters, all O(1) --------------------------------------
+
+    @property
+    def attack(self):
+        return self._attack
+
+    @attack.setter
+    def attack(self, v):
+        # only a rate now: no shape rebuild, so this is cheap on a knob
+        self._attack = v
+        self._refresh_rates()
+
+    @property
+    def release(self):
+        return self._release
+
+    @release.setter
+    def release(self, v):
+        self._release = v
+        self._refresh_rates()
+
+    @property
+    def curve(self):
+        return self._curve
+
+    @curve.setter
+    def curve(self, v):
+        # a switch, not a knob: rebuilds the shape, so it allocates
+        self._curve = v
+        self._refresh_shape()
+
+    @property
+    def amount(self):
+        return self._amt.a
+
+    @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)
+        self._amt.a = v
+
+    @property
+    def release_amount(self):
+        return self._rel_amt.a
+
+    @release_amount.setter
+    def release_amount(self, v):
+        # where a release lands. One write, and because start_release()
+        # parks the BLOCK in env.b rather than a number, it reaches voices
+        # that are already falling.
+        self._rel_amt.a = v
+
+    # --- per-voice ------------------------------------------------------
+
+    def make(self, gain=1.0):
+        """One voice's envelope, or None when it would do nothing at all.
+
+        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
+        (e.g. a velocity LERP) so whatever drives it stays live.
+
+        Returning None is what makes the envelope cost literally nothing
+        when switched off. Note the guard tests BOTH amounts: an envelope
+        that does nothing during the note but drifts somewhere on release
+        (amount 0, release_amount set) still needs its node built at press,
+        because note-off has nothing to re-aim otherwise. The flip side:
+        a voice pressed while both were 0 has no envelope at all, so
+        raising either mid-note only affects NEW notes.
+        """
+        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.
+        if isinstance(gain, (int, float)) and gain == 1.0:
+            depth = self._amt
+        else:
+            depth = product(self._amt, gain)
+        pos = synthio.LFO(waveform=self._wave, rate=self._rate_a, once=True)
+        # The ONLY difference between a filter envelope and a pitch envelope:
+        # which end of the lerp the amount sits at.
+        if self._falling:
+            return synthio.Math(synthio.MathOperation.CONSTRAINED_LERP, depth, 0.0, pos)
+        return synthio.Math(synthio.MathOperation.CONSTRAINED_LERP, 0.0, depth, pos)
+
+    def start_release(self, env):
+        """Send a voice's envelope into release. Call at note-off.
+
+        Re-aims the same position LFO instead of swapping its waveform, so
+        the fall starts wherever the envelope actually got to and a key
+        lifted mid-attack does not jump to full depth first. Continuity is
+        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
+        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.
+        """
+        env.a = env.value  # move from here...
+        env.b = self._rel_amt  # ...to wherever the release lands
+        env.c.rate = self._rate_r
+        env.c.retrigger()

synthtools/arpeggiator.py

@@ -0,0 +1,129 @@
+## pylint: disable=invalid-name
+# SPDX-FileCopyrightText: Copyright (c) 2023 Tod Kurt
+# SPDX-License-Identifier: MIT
+"""
+``arpeggiator``
+================================================================================
+
+``Arpeggiator`` is a melodic arpeggiator / sequencer for musical events
+
+Part of synthtools.
+
+"""
+
+import time
+
+try:
+    from supervisor import ticks_ms
+except ImportError:
+
+    def ticks_ms():
+        """stand-in for supervisor.ticks_ms"""
+        return time.monotonic_ns() // 1_000_000
+
+
+patterns = (
+    (0, 4, 7, 12),
+    (0, 3, 7, 10),
+    (0, 3, 6, 3),
+    (0, 5, 7, 12),
+    (0, 12, 0, -12),
+    (0, -12, -12, 0),
+    (0, 0, 0, 0),
+)
+
+pattern_names = (
+    "major",
+    "minor7",
+    "diminished",
+    "suspend4",
+    "octaves",
+    "octaves2",
+    "root",
+)
+
+
+class Arpeggiator:
+    """Poll-based arpeggiator: call update() as often as possible.
+
+    Holds a stack of notes added with add_note()/del_note() and steps
+    through them at ``step_millis`` (derived from ``rate`` and bpm, set via
+    set_bpm()), firing ``on_func``/``off_func`` at each gated step. ``rate`` is
+    in notes-per-beat: 1 = quarter notes, 2 = eighths, 4 = sixteenths.
+    """
+
+    def __init__(self, rate, on_func=None, off_func=None):
+        self.rate = rate  # 1 = 1/4 note, 2 = 1/8th note, 4 = 16th note
+        self.set_bpm(120, rate)
+        self.oct_distance = 12  # distance between repeats  (Ableton nomenclature)
+        self.oct_range = 1  # max number of self.distance to do (Ableton nomenclature)
+        self.octave = 0  # which arp step we're on, this is confusing with above
+        self.on_func = on_func
+        self.off_func = off_func
+        self.notes = []  # the list of notes currently pressed
+        self.transpose = 0
+        self.i = 0  # where in the notes list
+        self.gate = 0.5
+        self.on = False
+        self.held_note = None
+        self.next_millis = 0
+        self.held_millis = 0
+
+    def set_bpm(self, bpm, rate=None):
+        """Set BPM and optionally rate"""
+        self.bpm = bpm
+        self.rate = rate
+        self.step_millis = 60_000 / self.rate / self.bpm
+
+    def add_note(self, note):
+        """Add a note to the arpeggio"""
+        if note not in self.notes:
+            self.notes.append(note)
+
+    def del_note(self, note):
+        """Remove a note from the arpeggio"""
+        if note in self.notes:
+            self.notes.remove(note)
+            if self.i >= len(self.notes):
+                self.i = 0
+
+    def start(self):
+        """Start the arpeggiator running"""
+        self.next_millis = ticks_ms()
+        self.on = True
+
+    def stop(self):
+        """Stop the arpeggiator, note_offs any held notes"""
+        self.on = False
+        self.off_func(self.held_note)  # turn off any held note
+
+    def update(self):
+        """Update the arpeggiator. Call as frequently as possible"""
+
+        if not self.on:
+            return
+        now = ticks_ms()
+
+        # trigger note-off after gate time
+        if self.held_note and now - self.held_millis > 0:
+            self.off_func(self.held_note)
+            self.held_note = None
+
+        # trigger note-on on if time to do so
+        delta_millis = now - self.next_millis
+        if delta_millis >= 0 and len(self.notes) > 0:  # time for new note
+            note = self.notes[self.i] + self.oct_distance * self.octave
+            # print("\t\t\t\t\t", "delta:",delta_millis)
+
+            # trigger new note
+            self.on_func(note)
+            self.held_note = note  # save for note-off
+
+            # set up when note off and next note happens
+            self.held_millis = now + (self.step_millis * self.gate)
+            self.next_millis = now + self.step_millis - delta_millis // 2
+
+            # go to next note
+            self.i = (self.i + 1) % len(self.notes)
+            if self.i == 0:
+                self.octave = (self.octave + 1) % self.oct_range