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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.6.0
+Version: 0.7.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -162,6 +162,8 @@ What's Included
   ``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.6.0 → circuitpython_synthtools-0.7.0}/README.rst

@@ -142,6 +142,8 @@ What's Included
   ``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.6.0 → circuitpython_synthtools-0.7.0/circuitpython_synthtools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circuitpython-synthtools
-Version: 0.6.0
+Version: 0.7.0
 Summary: CircuitPython helper library to do help doing synthio
 Author-email: Tod Kurt <tod@todbot.com>
 License: MIT
@@ -162,6 +162,8 @@ What's Included
   ``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.6.0 → circuitpython_synthtools-0.7.0}/circuitpython_synthtools.egg-info/SOURCES.txt

@@ -49,6 +49,7 @@ 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
@@ -75,6 +76,7 @@ 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
@@ -95,6 +97,7 @@ 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

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

@@ -82,6 +82,12 @@ Waves
 .. automodule:: synthtools.waves
     :members:
 
+Harmony
+=======
+
+.. automodule:: synthtools.harmony
+    :members:
+
 Arpeggiator
 ===========
 

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

@@ -53,6 +53,16 @@ A bright DX-style FM bell using FMSynth, with a live fm_ratio / fm_index sweep
     :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.7.0/examples/synthtools_harmony_demo.py

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# Play scales and diatonic chords with synthtools.harmony.
+#
+# A Scale is a root note plus a set of semitone offsets; index it by
+# degree and it wraps with octave shifts, so `scale.degree(i)` maps a row
+# of 8 pads straight onto any scale. `scale.chord(degree, shape)` stacks
+# the chord in-key, so the quality follows the mode for free: the triad
+# on degree 0 of a major scale is major, on degree 1 it is minor.
+#
+# It prints every note and chord it plays, so it also reads as a plain
+# console demo with the mixer down.
+
+import time
+
+from synth_setup import synth as engine
+
+from synthtools import Patch, SubtractiveSynth
+from synthtools.harmony import DIATONIC_SHAPE_NAMES, Scale, note_name
+
+# fmt: off
+patch = Patch(name="harmony demo", wave="TRI",
+              amp_env=[0.01, 0.15, 0.5, 0.25],
+              filt_type="LPF", filt_f=2600, filt_q=0.7)
+# fmt: on
+synth = SubtractiveSynth(engine, patch)
+
+# (key note, scale name) -- MIDI 48 is C3
+PROGRESSION = (
+    (48, "major"),
+    (45, "minor"),
+    (50, "dorian"),
+    (43, "mixolydian"),
+    (48, "major_pentatonic"),
+)
+CHORD_SHAPES = ("triad", "7th", "9th", "spread")
+# roman numeral for the degree the chord is built on
+DEGREES = ((0, "I"), (3, "IV"), (4, "V"), (5, "vi"))
+
+
+def play(notes, secs):
+    for n in notes:
+        synth.note_on(n, velocity=100)
+    time.sleep(secs)
+    for n in notes:
+        synth.note_off(n)
+    time.sleep(0.06)
+
+
+while True:
+    for root, scale_name in PROGRESSION:
+        scale = Scale(root=root, name=scale_name)
+        print("\n--- %s %s ---" % (note_name(root, with_octave=False), scale.name))
+
+        # walk the scale, one note per pad
+        line = " ".join(note_name(scale.degree(i)) for i in range(scale.size + 1))
+        print("scale:", line)
+        for i in range(scale.size + 1):
+            play([scale.degree(i)], 0.16)
+        time.sleep(0.3)
+
+        # diatonic chords on a few degrees, through a few voicings
+        for degree, roman in DEGREES:
+            for shape in CHORD_SHAPES:
+                notes = scale.chord(degree, shape)
+                print("  %-3s %-6s %s" % (roman, shape, [note_name(n) for n in notes]))
+                play(notes, 0.4)
+            time.sleep(0.15)
+
+    print("\n(all %d DIATONIC_SHAPES: %s)" % (len(DIATONIC_SHAPE_NAMES), DIATONIC_SHAPE_NAMES))

{circuitpython_synthtools-0.6.0 → circuitpython_synthtools-0.7.0}/pyproject.toml

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

{circuitpython_synthtools-0.6.0 → circuitpython_synthtools-0.7.0}/synthtools/__init__.py

@@ -36,7 +36,7 @@ Anything not listed below is still importable by its module path::
 
 import sys
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 __repo__ = "https://github.com/todbot/CircuitPython_SynthTools.git"
 
 #: Public name -> the submodule that defines it. Every entry is loaded on
@@ -49,6 +49,12 @@ _LAZY = {
     "BasslineSynth": "bassline_synth",
     "FMSynth": "fm_synth",
     "GaugeCluster": "gauge_cluster",
+    "Scale": "harmony",
+    "chord": "harmony",
+    "note_name": "harmony",
+    "SCALES": "harmony",
+    "CHORDS": "harmony",
+    "DIATONIC_SHAPES": "harmony",
     "ParamScaler": "param_scaler",
     "Patch": "patch",
     "load_patches": "patch",

circuitpython_synthtools-0.7.0/synthtools/harmony.py

@@ -0,0 +1,198 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+"""
+``harmony``
+================================================================================
+
+Scales and chords for mapping controllers onto musical pitch.
+
+A ``Scale`` is a root MIDI note plus a set of semitone offsets. Index it
+by scale degree to get MIDI notes; degrees past the end (or negative)
+wrap with octave shifts, so a row of pads maps straight onto the scale
+without bounds checks. ``Scale.chord()`` stacks in-key chords by degree;
+the module-level ``chord()`` builds chromatic chords from an interval
+table.
+
+Pure Python, no dependencies. Part of synthtools.
+
+"""
+
+# The *_NAMES tuples are written out rather than `tuple(SCALES)` because
+# MicroPython does not guarantee dict iteration order (CPython 3.7+ does),
+# and a UI that builds a selector from the order and stores an index needs
+# it stable across interpreters. Keep each tuple in step with its dict.
+
+#: name -> ascending semitone offsets from the root, one octave. The root
+#: (0) is always the first entry; the octave (12) is implied, not listed.
+SCALES = {
+    "major": (0, 2, 4, 5, 7, 9, 11),
+    "minor": (0, 2, 3, 5, 7, 8, 10),  # natural minor / aeolian
+    "dorian": (0, 2, 3, 5, 7, 9, 10),
+    "phrygian": (0, 1, 3, 5, 7, 8, 10),
+    "lydian": (0, 2, 4, 6, 7, 9, 11),
+    "mixolydian": (0, 2, 4, 5, 7, 9, 10),
+    "locrian": (0, 1, 3, 5, 6, 8, 10),
+    "harmonic_minor": (0, 2, 3, 5, 7, 8, 11),
+    "melodic_minor": (0, 2, 3, 5, 7, 9, 11),
+    "major_pentatonic": (0, 2, 4, 7, 9),
+    "minor_pentatonic": (0, 3, 5, 7, 10),
+    "blues": (0, 3, 5, 6, 7, 10),
+    "whole_tone": (0, 2, 4, 6, 8, 10),
+    "chromatic": (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11),
+}
+
+SCALE_NAMES = (
+    "major",
+    "minor",
+    "dorian",
+    "phrygian",
+    "lydian",
+    "mixolydian",
+    "locrian",
+    "harmonic_minor",
+    "melodic_minor",
+    "major_pentatonic",
+    "minor_pentatonic",
+    "blues",
+    "whole_tone",
+    "chromatic",
+)
+
+#: name -> semitone offsets from a root note. Chromatic, key-independent.
+CHORDS = {
+    "1": (0,),
+    "5": (0, 7),
+    "oct": (0, 12),
+    "maj": (0, 4, 7),
+    "min": (0, 3, 7),
+    "dim": (0, 3, 6),
+    "aug": (0, 4, 8),
+    "sus2": (0, 2, 7),
+    "sus4": (0, 5, 7),
+    "6": (0, 4, 7, 9),
+    "min6": (0, 3, 7, 9),
+    "maj7": (0, 4, 7, 11),
+    "min7": (0, 3, 7, 10),
+    "dom7": (0, 4, 7, 10),
+    "dim7": (0, 3, 6, 9),
+    "add9": (0, 4, 7, 14),
+    "maj9": (0, 4, 7, 11, 14),
+    "min9": (0, 3, 7, 10, 14),
+}
+
+CHORD_NAMES = (
+    "1",
+    "5",
+    "oct",
+    "maj",
+    "min",
+    "dim",
+    "aug",
+    "sus2",
+    "sus4",
+    "6",
+    "min6",
+    "maj7",
+    "min7",
+    "dom7",
+    "dim7",
+    "add9",
+    "maj9",
+    "min9",
+)
+
+#: name -> scale-degree offsets (not semitones). Stacked in the current
+#: scale, so quality follows the key: "triad" on degree 0 of a major
+#: scale is major, on degree 1 it is minor, and so on.
+DIATONIC_SHAPES = {
+    "root": (0,),
+    "oct": (0, 7),
+    "5th": (0, 4),
+    "triad": (0, 2, 4),
+    "7th": (0, 2, 4, 6),
+    "9th": (0, 2, 4, 6, 8),
+    "sus": (0, 3, 4),
+    "spread": (0, 4, 9),
+}
+
+DIATONIC_SHAPE_NAMES = ("root", "oct", "5th", "triad", "7th", "9th", "sus", "spread")
+
+NOTE_NAMES = ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B")
+
+
+def note_name(midi, with_octave=True):
+    """``"C4"``, ``"F#3"`` ... MIDI 60 is C4 here. Software that calls
+    middle C "C3" should subtract 1 from the octave."""
+    n = NOTE_NAMES[int(midi) % 12]
+    return "%s%d" % (n, int(midi) // 12 - 1) if with_octave else n
+
+
+def chord(root, name):
+    """MIDI notes of chromatic chord ``name`` (see ``CHORDS``) on ``root``."""
+    return [root + i for i in CHORDS[name]]
+
+
+class Scale:
+    """A scale: a root MIDI note and a set of semitone offsets.
+
+    :param root: MIDI note of scale degree 0
+    :param name: a key of ``SCALES``, or an explicit sequence of ascending
+        semitone offsets starting at 0
+    """
+
+    def __init__(self, root=60, name="major"):
+        self.root = root
+        self.set_scale(name)
+
+    def set_scale(self, name):
+        """Switch scale in place, keeping the root. ``name`` is a ``SCALES``
+        key or an explicit offset sequence; an unknown name falls back to
+        major rather than raising, so a knob mapped past the list is safe."""
+        if isinstance(name, str):
+            self.name = name if name in SCALES else "major"
+            self.steps = SCALES[self.name]
+        else:
+            self.name = "custom"
+            self.steps = tuple(name)
+
+    @property
+    def size(self):
+        """Notes per octave in this scale."""
+        return len(self.steps)
+
+    def degree(self, n):
+        """MIDI note for 0-based scale degree ``n``. ``n`` may be any
+        integer: it wraps with octave shifts, so ``degree(size)`` is the
+        octave above the root and ``degree(-1)`` the step below it."""
+        octaves, i = divmod(int(n), len(self.steps))
+        return self.root + 12 * octaves + self.steps[i]
+
+    def __getitem__(self, n):
+        return self.degree(n)
+
+    def chord(self, degree, shape="triad"):
+        """Diatonic chord as a list of MIDI notes: the degree offsets of
+        ``shape`` (a ``DIATONIC_SHAPES`` key or an explicit offset
+        sequence) added to ``degree``, each taken through the scale so the
+        chord stays in key."""
+        offsets = DIATONIC_SHAPES[shape] if isinstance(shape, str) else shape
+        return [self.degree(degree + o) for o in offsets]
+
+    def contains(self, midi):
+        """Whether ``midi`` is a note of this scale, in any octave."""
+        return (int(midi) - self.root) % 12 in self.steps
+
+    def snap(self, midi):
+        """The scale note nearest ``midi`` (ties round down). Useful for
+        quantizing a chromatic source -- MIDI input, an LFO -- onto the
+        scale."""
+        rel = int(round(midi)) - self.root
+        octaves, semis = divmod(rel, 12)
+        best = self.steps[0]
+        for step in self.steps:
+            if abs(step - semis) < abs(best - semis):
+                best = step
+        return self.root + 12 * octaves + best
+
+    def __repr__(self):
+        return "Scale(root=%d, name=%r)" % (self.root, self.name)

{circuitpython_synthtools-0.6.0 → circuitpython_synthtools-0.7.0}/tests/run_tests.sh

@@ -41,6 +41,7 @@ if command -v python3 >/dev/null 2>&1; then
     run python3 tests/test_arpeggiator.py
     run python3 tests/test_paramset.py
     run python3 tests/test_param_scaler.py
+    run python3 tests/test_harmony.py
 else
     echo "python3 not found, skipping the CPython tier"
     status=1
@@ -57,6 +58,7 @@ if command -v micropython >/dev/null 2>&1; then
     run micropython tests/test_arpeggiator.py
     run micropython tests/test_paramset.py
     run micropython tests/test_param_scaler.py
+    run micropython tests/test_harmony.py
 else
     printf '\nmicropython not found, skipping the portability tier.\n'
     printf 'Install it to catch the MicroPython-only bugs: brew install micropython\n'

circuitpython_synthtools-0.7.0/tests/test_harmony.py

@@ -0,0 +1,139 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+"""harmony: scales, chords, and the degree-wrap arithmetic.
+
+harmony.py imports nothing, so this runs on a bare interpreter and is a
+portability canary alongside test_patch.py / test_paramset.py: the whole
+reason Scale.degree() uses divmod is that a pad row indexes past the end
+of the scale, and negative divmod has to wrap the same way on MicroPython.
+
+    python3 tests/test_harmony.py
+    micropython tests/test_harmony.py
+"""
+
+import sys
+
+_D = __file__.rsplit("/", 1)[0] if "/" in __file__ else "."
+sys.path.insert(0, _D + "/../synthtools")  # direct: skips synthtools/__init__
+
+from harmony import (  # noqa: E402
+    CHORD_NAMES,
+    CHORDS,
+    DIATONIC_SHAPE_NAMES,
+    DIATONIC_SHAPES,
+    SCALE_NAMES,
+    SCALES,
+    Scale,
+    chord,
+    note_name,
+)
+
+fails = []
+
+
+def ck(cond, msg):
+    if not cond:
+        fails.append(msg)
+
+
+# --- the portability canary -------------------------------------------
+# Python floors towards negative infinity, so divmod(-1, 7) == (-1, 6):
+# degree(-1) is the top note of the octave below. MicroPython must agree.
+ck(divmod(-1, 7) == (-1, 6), "negative divmod does not wrap: %r" % (divmod(-1, 7),))
+ck(divmod(-8, 7) == (-2, 6), "negative divmod does not wrap over an octave")
+
+
+# --- Scale.degree ----------------------------------------------------
+s = Scale(60, "major")
+ck(
+    [s.degree(n) for n in range(8)] == [60, 62, 64, 65, 67, 69, 71, 72],
+    "C major degrees 0..7 wrong: %r" % [s.degree(n) for n in range(8)],
+)
+ck(s.degree(7) == s.root + 12, "degree(size) is not the octave: %d" % s.degree(7))
+ck(s.degree(-1) == 59, "degree(-1) is not the leading tone below: %d" % s.degree(-1))
+ck(s.degree(14) == 84, "two octaves up wrong: %d" % s.degree(14))
+ck(s[3] == s.degree(3), "__getitem__ disagrees with degree()")
+ck(s.size == 7, "major scale size should be 7, got %d" % s.size)
+
+# a pentatonic keeps climbing past its 5 notes
+p = Scale(57, "minor_pentatonic")
+ck(
+    [p.degree(n) for n in range(6)] == [57, 60, 62, 64, 67, 69],
+    "A minor pentatonic wrong: %r" % [p.degree(n) for n in range(6)],
+)
+
+
+# --- chromatic chord() --------------------------------------------------
+ck(chord(60, "maj") == [60, 64, 67], "C maj wrong: %r" % chord(60, "maj"))
+ck(chord(60, "min") == [60, 63, 67], "C min wrong: %r" % chord(60, "min"))
+ck(chord(60, "dom7") == [60, 64, 67, 70], "C7 wrong: %r" % chord(60, "dom7"))
+ck(chord(48, "maj9") == [48, 52, 55, 59, 62], "Cmaj9 wrong: %r" % chord(48, "maj9"))
+
+
+# --- Scale.chord: diatonic quality falls out of the key --------------
+c = Scale(60, "major")
+ck(c.chord(0, "triad") == [60, 64, 67], "I is not major: %r" % c.chord(0, "triad"))
+ck(c.chord(1, "triad") == [62, 65, 69], "ii is not minor: %r" % c.chord(1, "triad"))
+ck(c.chord(6, "triad") == [71, 74, 77], "vii is not diminished-shaped")
+ck(c.chord(4, "7th") == [67, 71, 74, 77], "V7 is not dominant-shaped: %r" % c.chord(4, "7th"))
+ck(len(c.chord(0, "9th")) == 5, "9th is not 5 notes")
+ck(c.chord(0, (0, 4)) == [60, 67], "explicit degree-offset shape ignored")
+ck(c.chord(0, "spread")[-1] > c.chord(0, "spread")[0] + 12, "spread does not open past an octave")
+
+
+# --- set_scale ------------------------------------------------------
+q = Scale(60, "major")
+q.set_scale("bogus_scale")
+ck(q.name == "major" and q.steps == SCALES["major"], "unknown scale did not fall back to major")
+q.set_scale((0, 3, 7))
+ck(q.name == "custom" and q.steps == (0, 3, 7), "explicit offsets not accepted")
+ck(q.degree(0) == 60 and q.degree(1) == 63 and q.degree(3) == 72, "custom scale degrees wrong")
+
+
+# --- contains / snap --------------------------------------------------
+cm = Scale(60, "major")
+ck(cm.contains(64) and cm.contains(64 + 12) and cm.contains(64 - 24), "E should be in C major")
+ck(not cm.contains(61) and not cm.contains(61 + 12), "C# should not be in C major")
+ck(cm.snap(61) == 60, "snap C#4 -> C4 expected, got %d" % cm.snap(61))
+ck(cm.snap(66) == 65, "snap F#4 -> F4 expected, got %d" % cm.snap(66))
+ck(cm.snap(67) == 67, "snap of an in-scale note must be a no-op, got %d" % cm.snap(67))
+ck(cm.snap(72) == 72, "snap of the octave must be a no-op, got %d" % cm.snap(72))
+
+
+# --- note_name -----------------------------------------------------
+ck(note_name(60) == "C4", "MIDI 60 is C4 here, got %s" % note_name(60))
+ck(note_name(69) == "A4", "MIDI 69 is A4, got %s" % note_name(69))
+ck(note_name(61, False) == "C#", "note_name without octave wrong: %s" % note_name(61, False))
+ck(note_name(48) == "C3" and note_name(72) == "C5", "octave numbering off")
+
+
+# --- table invariants -----------------------------------------------
+for name, steps in SCALES.items():
+    ck(isinstance(steps, tuple) and steps[0] == 0, "scale %s must be a tuple starting at 0" % name)
+    ck(list(steps) == sorted(steps), "scale %s not ascending" % name)
+    ck(all(0 <= x <= 11 for x in steps), "scale %s has an out-of-octave step" % name)
+for name, ivals in CHORDS.items():
+    ck(isinstance(ivals, tuple) and ivals[0] == 0, "chord %s must be a tuple starting at 0" % name)
+for name, offs in DIATONIC_SHAPES.items():
+    ck(isinstance(offs, tuple) and offs[0] == 0, "shape %s must be a tuple starting at 0" % name)
+
+# The *_NAMES tuples are hand-written (MicroPython dict order is not
+# stable) so a UI selector index means the same thing everywhere: check
+# they cover their dicts exactly, and that the fixed order holds.
+for names, table, what in (
+    (SCALE_NAMES, SCALES, "SCALE_NAMES"),
+    (CHORD_NAMES, CHORDS, "CHORD_NAMES"),
+    (DIATONIC_SHAPE_NAMES, DIATONIC_SHAPES, "DIATONIC_SHAPE_NAMES"),
+):
+    ck(set(names) == set(table), "%s does not cover its dict exactly" % what)
+    ck(len(names) == len(table), "%s has a duplicate or a gap" % what)
+ck(SCALE_NAMES[0] == "major", "major must stay first in SCALE_NAMES (the default)")
+ck(DIATONIC_SHAPE_NAMES[3] == "triad", "DIATONIC_SHAPE_NAMES order shifted")
+
+
+if fails:
+    print("FAIL (%d)" % len(fails))
+    for f in fails:
+        print("  -", f)
+    sys.exit(1)
+print("test_harmony: ok")