circuitpython-synthtools 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

{circuitpython_synthtools-0.6.0.dist-info → circuitpython_synthtools-0.7.0.dist-info}/METADATA

@@ -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.dist-info → circuitpython_synthtools-0.7.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-circuitpython_synthtools-0.6.0.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
-synthtools/__init__.py,sha256=WXLJ-chYBMFnvVbSnwyxy2Txv9ixApOKi8vyrKypQlA,2592
+circuitpython_synthtools-0.7.0.dist-info/licenses/LICENSE,sha256=jhhRyxpqyQxyF_D6SzY2-jCA5v8Z8JXfezCtxBS85CM,1075
+synthtools/__init__.py,sha256=n0ZXMz7Uu0pPEqalR51IxkClI9DTwuUbpu5yPj_whn8,2752
 synthtools/ahr_envelope.py,sha256=fWhjp7LahNGjL8qtTgyiAnX5hnviAULuyc9dEJ6t74I,9233
 synthtools/arpeggiator.py,sha256=n2sPnpZcu9soXsFJCh6OP65_0DuPnvQGUP0ao7V8SXM,3901
 synthtools/audio_fx.py,sha256=VzdWT_pCwfQU5GTb8hVGGMwoFV4lxPwWE1Nm7A1a_Fc,6675
@@ -7,6 +7,7 @@ synthtools/bassline_synth.py,sha256=Gkz7MKKUITgND4Se5nAJly9sZLQjHhFdd-aFrOAjeVM,
 synthtools/blocks.py,sha256=EsGcDEzIJX_dvBN8CVlDrewtl16x5leU03tum9jrhr0,1995
 synthtools/fm_synth.py,sha256=-r4NcsESjEechkbmV0tZx4pXayHIz4qUfIznKtQoKgQ,6073
 synthtools/gauge_cluster.py,sha256=lcMkRK-db6KV6pu0PUJRWAOJT8IdjgpE_4bAi0lQwxc,2910
+synthtools/harmony.py,sha256=V_btMIqO-Ep2x64XwM1A1agSeQqwPcbLqpvGjxlnpUE,6206
 synthtools/param_scaler.py,sha256=dmaFkzRhrfZn54DAgPwZs7P4B4BFd90ZUvMHpWIf2i4,6202
 synthtools/paramset.py,sha256=--V89zHR4pUhkSey1CX7iMLNsF5l1hKmKWrAr3j_cRA,9938
 synthtools/patch.py,sha256=vMr-kdVD66uxY8BrrnB0J6uDLREjuu16I8HzfhAkqHs,6033
@@ -20,7 +21,7 @@ synthtools/utils.py,sha256=deKQbkGXIBdGUOXBOpRCc-UHdPiL8YmybIJ3BBo9aA4,648
 synthtools/waves.py,sha256=lwDka71TsoHGJcyVfmG4t-TEf6TjBwftJEXSS4Qxyx0,22407
 synthtools/wavetable.py,sha256=K1rghAptDYIOwy0PcL9xCllnJH6X3h875MpeuXCm6lQ,2492
 synthtools/wavetable_synth.py,sha256=WUs4FfrKd1hosPiPYnf05I4S8t98ngEMi8qhShkbCps,12896
-circuitpython_synthtools-0.6.0.dist-info/METADATA,sha256=C4HgNUbEFEH2PUe0Pv8sQ9-u7t3P4rSOMQF6upscetw,7086
-circuitpython_synthtools-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-circuitpython_synthtools-0.6.0.dist-info/top_level.txt,sha256=1xt53cH064i7vvFVDFyuJugc1NogReXvzsXbYGlgnKE,11
-circuitpython_synthtools-0.6.0.dist-info/RECORD,,
+circuitpython_synthtools-0.7.0.dist-info/METADATA,sha256=WY049mABTbxBi_qkmr_a_Dh3AZ9ImrnVP0w81veUu0M,7189
+circuitpython_synthtools-0.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+circuitpython_synthtools-0.7.0.dist-info/top_level.txt,sha256=1xt53cH064i7vvFVDFyuJugc1NogReXvzsXbYGlgnKE,11
+circuitpython_synthtools-0.7.0.dist-info/RECORD,,

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",

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)