circuitpython-synthtools 0.8.1__tar.gz → 0.9.0__tar.gz

{circuitpython_synthtools-0.8.1/circuitpython_synthtools.egg-info → circuitpython_synthtools-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.8.1
+Version: 0.9.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: Adafruit-Blinka
+Requires-Dist: adafruit-circuitpython-ticks
 Provides-Extra: optional
 Dynamic: license-file
 
@@ -60,6 +61,8 @@ Dependencies
 This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Adafruit CircuitPython Ticks <https://github.com/adafruit/Adafruit_CircuitPython_Ticks>`_
+  (``StepSequencer``)
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/README.rst

@@ -40,6 +40,8 @@ Dependencies
 This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Adafruit CircuitPython Ticks <https://github.com/adafruit/Adafruit_CircuitPython_Ticks>`_
+  (``StepSequencer``)
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0/circuitpython_synthtools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.8.1
+Version: 0.9.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: Adafruit-Blinka
+Requires-Dist: adafruit-circuitpython-ticks
 Provides-Extra: optional
 Dynamic: license-file
 
@@ -60,6 +61,8 @@ Dependencies
 This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Adafruit CircuitPython Ticks <https://github.com/adafruit/Adafruit_CircuitPython_Ticks>`_
+  (``StepSequencer``)
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/circuitpython_synthtools.egg-info/SOURCES.txt

@@ -105,6 +105,7 @@ tests/test_param_scaler.py
 tests/test_paramset.py
 tests/test_patch.py
 tests/test_pytest_smoke.py
+tests/test_step_sequencer.py
 tests/test_swarm_synth.py
 tests/test_trig_sequencer.py
 tests/test_wiring.py
@@ -113,6 +114,7 @@ tests/hw/test_device.py
 tests/hw/test_display_cost.py
 tests/hw/test_trig_sequencer_timing.py
 tests/hw/test_wavetable_cost.py
+tests/lib/adafruit_ticks.py
 tests/render/FINDINGS.md
 tests/render/README.md
 tests/render/analyze_renders.py

circuitpython_synthtools-0.9.0/circuitpython_synthtools.egg-info/requires.txt

@@ -0,0 +1,4 @@
+Adafruit-Blinka
+adafruit-circuitpython-ticks
+
+[optional]

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/docs/conf.py

@@ -33,6 +33,7 @@ autodoc_mock_imports = [
     "synthio",
     "ulab",
     "adafruit_wave",
+    "adafruit_ticks",
     "displayio",
     "vectorio",
     "micropython",

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/pyproject.toml

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

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/requirements.txt

@@ -4,3 +4,4 @@
 # SPDX-License-Identifier: MIT
 
 Adafruit-Blinka
+adafruit-circuitpython-ticks

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/synthtools/__init__.py

@@ -36,7 +36,7 @@ Anything not listed below is still importable by its module path::
 
 import sys
 
-__version__ = "0.8.1"
+__version__ = "0.9.0"
 __repo__ = "https://github.com/todbot/CircuitPython_SynthTools.git"
 
 #: Public name -> the submodule that defines it. Every entry is loaded on

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/synthtools/arpeggiator.py

@@ -11,16 +11,7 @@ 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
-
+from adafruit_ticks import ticks_add, ticks_diff, ticks_ms
 
 patterns = (
     (0, 4, 7, 12),
@@ -68,6 +59,7 @@ class Arpeggiator:
         self.held_note = None
         self.next_millis = 0
         self.held_millis = 0
+        self._frac_millis = 0.0  # step_millis's fraction, carried between steps
 
     def set_bpm(self, bpm, rate=None):
         """Set BPM and optionally rate"""
@@ -90,6 +82,7 @@ class Arpeggiator:
     def start(self):
         """Start the arpeggiator running"""
         self.next_millis = ticks_ms()
+        self._frac_millis = 0.0
         self.on = True
 
     def stop(self):
@@ -105,12 +98,12 @@ class Arpeggiator:
         now = ticks_ms()
 
         # trigger note-off after gate time
-        if self.held_note and now - self.held_millis > 0:
+        if self.held_note and ticks_diff(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
+        delta_millis = ticks_diff(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)
@@ -120,8 +113,13 @@ class Arpeggiator:
             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
+            # int ticks: they wrap at 2**29, first ~65 s after power-on, and a
+            # 30-bit float can't hold one that big to the ms
+            self._frac_millis += self.step_millis
+            step = int(self._frac_millis)
+            self._frac_millis -= step
+            self.held_millis = ticks_add(now, int(self.step_millis * self.gate))
+            self.next_millis = ticks_add(now, step - delta_millis // 2)
 
             # go to next note
             self.i = (self.i + 1) % len(self.notes)

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/synthtools/step_sequencer.py

@@ -11,15 +11,7 @@ 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
+from adafruit_ticks import ticks_add, ticks_diff, ticks_ms
 
 
 class StepSequencer:
@@ -46,8 +38,10 @@ class StepSequencer:
         self.held_note = None  # the current note playing
         self.transpose = 0
         self.playing = False  # is sequence running or not (but use .start()/.stop())
+        self.external_clock = False  # owner calls trigger(), update() only releases gates
+        self.catch_up_steps = 0  # how far behind to still play every step, late, not resync
         self.next_millis = 0
-        self.error_millis = 0
+        self._frac_millis = 0.0  # step_millis's fraction, carried between steps
 
     @property
     def bpm(self):
@@ -68,46 +62,61 @@ class StepSequencer:
     def start(self):
         """Start sequencer going"""
         self.next_millis = ticks_ms()
+        self._frac_millis = 0.0
         self.playing = True
-        self.error_millis = 0
 
-    def stop(self):
-        """Stop sequencer, turning off any currently-sounding note"""
+    def pause(self):
+        """Pause sequencer where it is, turning off any currently-sounding note"""
         if self.held_note:
             self.off_func(*self.held_note)
+            self.held_note = None
         self.playing = False
+
+    def stop(self):
+        """Stop sequencer and rewind, turning off any currently-sounding note"""
+        self.pause()
         self.i = 0
 
+    def trigger(self, now=None):
+        """Play the current step and advance, for an owner keeping its own clock"""
+        if now is None:
+            now = ticks_ms()
+        if self.i >= self.step_count:  # step_count shrank under us
+            self.i = 0
+        (note, vel, gate, on) = self.steps[self.i]  # get new note to play
+        note += self.transpose  # adjust for transpose
+        self.held_note = (note, vel, gate, on)  # save it for when we note_off it
+
+        # trigger new note
+        self.on_func(*self.held_note)  # held_note = (note,vel,gate,on)
+
+        # prep for next step in sequence
+        self.i = (self.i + 1) % self.step_count
+
+        # int ticks: they wrap at 2**29, first ~65 s after power-on, and a
+        # 30-bit float can't hold one that big to the ms
+        self._frac_millis += self.step_millis
+        step = int(self._frac_millis)
+        self._frac_millis -= step
+        self.next_millis = ticks_add(self.next_millis, step)
+        # a stall put us too far behind
+        if ticks_diff(self.next_millis, now) < -self.catch_up_steps * step:
+            self.next_millis = ticks_add(now, step)
+        # next note off is some percentage smaller
+        gate = int(self.step_millis * self.held_note[2])
+        self.gate_off_millis = ticks_add(now, gate)
+
     def update(self):
         """Update the sequencer. Call as frequently as possible"""
         if not self.playing:
             return
 
         now = ticks_ms()
-        delta_millis = now - self.next_millis
 
         # trigger note-off after gate time
-        if now - self.gate_off_millis >= 0 and self.held_note:
+        if self.held_note and ticks_diff(now, self.gate_off_millis) >= 0:
             self.off_func(*self.held_note)
             self.held_note = None
 
-        if delta_millis >= 0:  # if zero or great, time for next step
-            # print("                      delta_millis:", delta_millis, self.error_millis)
-            self.error_millis += delta_millis
-            (note, vel, gate, on) = self.steps[self.i]  # get new note to play
-            note += self.transpose  # adjust for transpose
-            self.held_note = (note, vel, gate, on)  # save it for when we note_off it
-
-            # trigger new note
-            self.on_func(*self.held_note)  # held_note = (note,vel,gate,on)
-
-            # prep for next step in sequence
-            self.i = (self.i + 1) % self.step_count
-
-            # set up when next note on is, with some error correction
-            self.next_millis = now + self.step_millis
-            if self.error_millis > 1:
-                self.next_millis -= self.error_millis
-                self.error_millis = 0
-            # next note off is some percentage smaller
-            self.gate_off_millis = now + self.step_millis * self.held_note[2]
+        if not self.external_clock and ticks_diff(now, self.next_millis) >= 0:
+            self.trigger(now)

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/synthtools/trig_sequencer.py

@@ -11,15 +11,7 @@ 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
+from adafruit_ticks import ticks_add, ticks_diff, ticks_ms
 
 
 class TrigSequencer:
@@ -45,6 +37,7 @@ class TrigSequencer:
         self.drum_map = [0] * trig_count
         self.step_millis = 0  # real value once bpm is set; update()/start() need it to exist
         self.next_millis = 0
+        self._frac_millis = 0.0  # step_millis's fraction, carried between steps
 
     @property
     def bpm(self):
@@ -58,6 +51,7 @@ class TrigSequencer:
     def start(self):
         """Start sequencer going"""
         self.next_millis = ticks_ms()
+        self._frac_millis = 0.0
         self.playing = True
 
     def stop(self):
@@ -78,15 +72,19 @@ class TrigSequencer:
             return
 
         now = ticks_ms()
-        delta_millis = now - self.next_millis
 
-        if delta_millis >= 0:  # time to play
+        if ticks_diff(now, self.next_millis) >= 0:  # time to play
             for t in range(self.trig_count):
                 if self.trigs[t][self.i] == 1:
                     self.on_func(t, self.drum_map[t])
 
             # prep for next step in sequence
             self.i = (self.i + 1) % self.step_count
-            self.next_millis += self.step_millis
-            if self.next_millis < now:  # a stall put us a whole step behind: resync
-                self.next_millis = now + self.step_millis
+            # int ticks: they wrap at 2**29, first ~65 s after power-on, and a
+            # 30-bit float can't hold one that big to the ms
+            self._frac_millis += self.step_millis
+            step = int(self._frac_millis)
+            self._frac_millis -= step
+            self.next_millis = ticks_add(self.next_millis, step)
+            if ticks_diff(self.next_millis, now) < 0:  # a stall put us a whole step behind
+                self.next_millis = ticks_add(now, step)

circuitpython_synthtools-0.9.0/tests/lib/adafruit_ticks.py

@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+# SPDX-FileCopyrightText: Copyright (c) 2021 Jeff Epler for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_ticks`
+================================================================================
+
+Work with intervals and deadlines in milliseconds
+
+
+* Author(s): Jeff Epler
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+
+"""
+
+# imports
+from micropython import const
+
+__version__ = "1.1.7"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_ticks.git"
+
+_TICKS_PERIOD = const(1 << 29)
+_TICKS_MAX = const(_TICKS_PERIOD - 1)
+_TICKS_HALFPERIOD = const(_TICKS_PERIOD // 2)
+
+# Get the correct implementation of ticks_ms.  There are three possibilities:
+#
+#  - supervisor.ticks_ms is present.  This will be the case starting in CP7.0
+#
+#  - time.ticks_ms is present. This is the case for MicroPython & for the "unix
+#    port" of CircuitPython, used for some automated testing.
+#
+#  - time.monotonic_ns is present, and works.  This is the case on most
+#    Express boards in CP6.x, and most host computer versions of Python.
+#
+#  - Otherwise, time.monotonic is assumed to be present.  This is the case
+#    on most non-express boards in CP6.x, and some old host computer versions
+#    of Python.
+#
+#    Note that on microcontrollers, this time source becomes increasingly
+#    inaccurate when the board has not been reset in a long time, losing the
+#    ability to measure 1ms intervals after about 1 hour, and losing the
+#    ability to meausre 128ms intervals after 6 days.  The only solution is to
+#    either upgrade to a version with supervisor.ticks_ms, or to switch to a
+#    board with time.monotonic_ns.
+
+try:
+    from supervisor import ticks_ms
+except (ImportError, NameError):
+    import time
+
+    if _ticks_ms := getattr(time, "ticks_ms", None):
+
+        def ticks_ms() -> int:
+            """Return the time in milliseconds since an unspecified moment,
+            wrapping after 2**29ms.
+
+            The wrap value was chosen so that it is always possible to add or
+            subtract two `ticks_ms` values without overflow on a board without
+            long ints (or without allocating any long integer objects, on
+            boards with long ints).
+
+            This ticks value comes from a low-accuracy clock internal to the
+            microcontroller, just like `time.monotonic`.  Due to its low
+            accuracy and the fact that it "wraps around" every few days, it is
+            intended for working with short term events like advancing an LED
+            animation, not for long term events like counting down the time
+            until a holiday."""
+            return _ticks_ms() & _TICKS_MAX
+
+    else:
+        try:
+            from time import monotonic_ns as _monotonic_ns
+
+            _monotonic_ns()  # Check that monotonic_ns is usable
+
+            def ticks_ms() -> int:
+                """Return the time in milliseconds since an unspecified moment,
+                wrapping after 2**29ms.
+
+                The wrap value was chosen so that it is always possible to add or
+                subtract two `ticks_ms` values without overflow on a board without
+                long ints (or without allocating any long integer objects, on
+                boards with long ints).
+
+                This ticks value comes from a low-accuracy clock internal to the
+                microcontroller, just like `time.monotonic`.  Due to its low
+                accuracy and the fact that it "wraps around" every few days, it is
+                intended for working with short term events like advancing an LED
+                animation, not for long term events like counting down the time
+                until a holiday."""
+                return (_monotonic_ns() // 1_000_000) & _TICKS_MAX
+
+        except (ImportError, NameError, NotImplementedError):
+            from time import monotonic as _monotonic
+
+            def ticks_ms() -> int:
+                """Return the time in milliseconds since an unspecified moment,
+                wrapping after 2**29ms.
+
+                The wrap value was chosen so that it is always possible to add or
+                subtract two `ticks_ms` values without overflow on a board without
+                long ints (or without allocating any long integer objects, on
+                boards with long ints).
+
+                This ticks value comes from a low-accuracy clock internal to the
+                microcontroller, just like `time.monotonic`.  Due to its low
+                accuracy and the fact that it "wraps around" every few days, it is
+                intended for working with short term events like advancing an LED
+                animation, not for long term events like counting down the time
+                until a holiday."""
+                return int(_monotonic() * 1000) & _TICKS_MAX
+
+
+def ticks_add(ticks: int, delta: int) -> int:
+    "Add a delta to a base number of ticks, performing wraparound at 2**29ms."
+    if -_TICKS_HALFPERIOD < delta < _TICKS_HALFPERIOD:
+        return (ticks + delta) % _TICKS_PERIOD
+    raise OverflowError("ticks interval overflow")
+
+
+def ticks_diff(ticks1: int, ticks2: int) -> int:
+    """Compute the signed difference between two ticks values,
+    assuming that they are within 2**28 ticks"""
+    diff = (ticks1 - ticks2) & _TICKS_MAX
+    diff = ((diff + _TICKS_HALFPERIOD) & _TICKS_MAX) - _TICKS_HALFPERIOD
+    return diff
+
+
+def ticks_less(ticks1: int, ticks2: int) -> bool:
+    """Return true if ticks1 is before ticks2 and false otherwise,
+    assuming that they are within 2**28 ticks"""
+    return ticks_diff(ticks1, ticks2) < 0

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/tests/run_tests.sh

@@ -40,6 +40,7 @@ if command -v python3 >/dev/null 2>&1; then
     run python3 tests/test_audio_fx.py
     run python3 tests/test_arpeggiator.py
     run python3 tests/test_trig_sequencer.py
+    run python3 tests/test_step_sequencer.py
     run python3 tests/test_paramset.py
     run python3 tests/test_param_scaler.py
     run python3 tests/test_harmony.py
@@ -58,6 +59,7 @@ if command -v micropython >/dev/null 2>&1; then
     run micropython tests/test_audio_fx.py
     run micropython tests/test_arpeggiator.py
     run micropython tests/test_trig_sequencer.py
+    run micropython tests/test_step_sequencer.py
     run micropython tests/test_paramset.py
     run micropython tests/test_param_scaler.py
     run micropython tests/test_harmony.py

{circuitpython_synthtools-0.8.1 → circuitpython_synthtools-0.9.0}/tests/test_arpeggiator.py

@@ -5,8 +5,8 @@ for the constructor bug fixed alongside this file: Arpeggiator.__init__
 called `self.set_bpm(120)` with no rate, which overwrote self.rate with
 set_bpm's own default (None) and raised TypeError on every construction.
 
-arpeggiator.py imports only `time` (with a `supervisor.ticks_ms` shim), so
-like test_patch.py this runs on a bare interpreter: no stubs needed.
+arpeggiator.py needs only adafruit_ticks, vendored unchanged in tests/lib/,
+so like test_patch.py this runs on a bare interpreter: no stubs needed.
 ticks_ms is monkeypatched to a fake, settable clock so the timing tests are
 exact and instant instead of racing real wall-clock sleeps.
 
@@ -18,6 +18,7 @@ import sys
 
 _D = __file__.rsplit("/", 1)[0] if "/" in __file__ else "."
 sys.path.insert(0, _D + "/../synthtools")  # direct: skips synthtools/__init__
+sys.path.insert(0, _D + "/lib")  # the real adafruit_ticks, vendored
 
 import arpeggiator  # noqa: E402
 from arpeggiator import Arpeggiator  # noqa: E402
@@ -33,8 +34,11 @@ def ck(cond, msg):
 _now = [0]
 
 
+WRAP = 1 << 29
+
+
 def fake_ticks_ms():
-    return _now[0]
+    return _now[0] % WRAP  # wraps like supervisor.ticks_ms()
 
 
 def set_time(ms):
@@ -162,6 +166,24 @@ ck(advance(375) == [("on", 60 + 12)],
    "next pass must transpose by oct_distance * octave")
 ck(arp4.i == 1, "i must advance normally within the transposed pass")
 
+# --- across the ticks_ms() wrap: no stop, no hiccup -----------------------
+# supervisor.ticks_ms() first wraps ~65 s after power-on
+ons, offs = [], []
+arp5 = Arpeggiator(4, lambda n: ons.append(_now[0]), lambda n: offs.append(_now[0]))
+arp5.set_bpm(120, 4)
+arp5.notes = [60]
+set_time(WRAP - 600)
+arp5.start()
+while _now[0] < WRAP + 1000:
+    arp5.update()
+    _now[0] += 1
+gaps = [b - a for a, b in zip(ons, ons[1:])]
+ck(len(ons) == 13 and min(gaps) == max(gaps) == 125,
+   "notes must keep coming every 125 ms across the wrap, got gaps %r" % gaps)
+ck(len(offs) == len(ons), "gates must keep releasing across the wrap, got %d" % len(offs))
+ck(isinstance(arp5.next_millis, int) and isinstance(arp5.held_millis, int),
+   "tick math must stay int; a 30-bit float can't hold a tick near 2**29")
+
 if fails:
     print("FAILURES (%d):" % len(fails))
     for f in fails: