circuitpython-synthtools 0.5__py3-none-any.whl

synthtools/paramset.py

@@ -0,0 +1,201 @@
+# pylint: disable=too-many-arguments, too-many-positional-arguments
+# SPDX-FileCopyrightText: Copyright (c) 2023 Tod Kurt
+# SPDX-License-Identifier: MIT
+"""
+``param_set.py``
+================================================================================
+
+``ParamSet`` is a collection of ``Param`` objects that track normalized
+    knob positions, especially for the case when there are fewer knobs
+    than params.
+
+Each ``Param`` is a UI- and implementation-independent way of describing
+    a named numerical parameter with a min/max, a display format, and
+    (optionally) an object attribute that they represent.
+
+20 May 2025 - @todbot / Tod Kurt
+
+"""
+
+import json
+
+
+class Param:
+    """Params are a UI- and implementation-independent way of describing
+    a named numerical parameter with a min/max, a display format, and
+    (optionally) an object attribute that they represent.
+    """
+
+    def __init__(self, name, val, vmin, vmax, fmt, objattr=None):
+        self.name = name
+        self.val = val
+        self.vmin = vmin
+        self.vmax = vmax
+        self.fmt = fmt
+        self.objattr = objattr
+
+    def __str__(self):
+        # fmt: off
+        obstr = 'None' if self.objattr is None else "'%s'" % self.objattr
+        return("Param('" + self.name + "'," + str(self.val) + "," +
+               str(self.vmin) + "," + str(self.vmax) + ",'" + str(self.fmt) +
+               "'," + obstr + ")")
+        # fmt: on
+
+    def __repr__(self):
+        return self.__str__()
+
+    @property
+    def span(self):
+        return self.vmax - self.vmin
+
+    def knob_to_val(self, knobval):
+        """Knobval ranges 0.0-1.0"""
+        return self.vmin + (self.vmax - self.vmin) * knobval
+
+    def update(self, new_knob_val):
+        """Set a param val with a knob, bounded by the param's min/max attributes"""
+        self.val = self.knob_to_val(new_knob_val)
+        return self.val
+
+    def apply_to_obj(self, o):
+        """Apply a parameter to the given object"""
+        if self.objattr:
+            setattr(o, self.objattr, self.val)
+
+
+class ParamSet:
+    """ParamSet is a collection of Params that track normalized knob positions,
+    especially for the case when there are fewer knobs than Params.
+    """
+
+    KNOB_PICKUP = 0
+    KNOB_SCALE = 1
+    KNOB_RELATIVE = 2
+
+    def __init__(
+        self,
+        params,
+        num_knobs,
+        min_knob_change=0.05,
+        knob_smooth=0.5,
+        knob_mode=KNOB_PICKUP,
+    ):
+        self.params = params
+        self.knob_mode = knob_mode
+        self.nparams = len(params)
+        self.nknobs = num_knobs
+        self.min_change = min_knob_change
+        self.smoothing = knob_smooth
+        self.nknobsets = self.nparams // self.nknobs
+        self._idx = 0  # which knobset we're modifying
+        self.is_tracking = [False] * self.nknobs
+
+    def next_knobset(self):
+        self.idx = (self._idx + 1) % self.nknobsets  # calls def idx()
+        return self._idx
+
+    @property
+    def idx(self):
+        """Which knobset is currently being edited"""
+        return self._idx
+
+    @idx.setter
+    def idx(self, i):
+        """Set which knobset to edit, resets knob tracking"""
+        if i != self._idx:
+            self.is_tracking = [False] * self.nknobs  # reset tracking
+        self._idx = i
+
+    def update_knobs(self, new_knob_vals):
+        if self.knob_mode == ParamSet.KNOB_PICKUP:
+            self.update_knobs_pickup(new_knob_vals)
+        elif self.knob_mode == ParamSet.KNOB_SCALE:
+            self.update_knobs_scale(new_knob_vals)
+
+    def update_knobs_pickup(self, new_knob_vals):
+        """new_knob_vals is list of new knob vals, each 0.0-1.0"""
+        for i in range(self.nknobs):
+            param = self.params[(self._idx * self.nknobs) + i]
+            new_val = param.knob_to_val(new_knob_vals[i])
+            if self.is_tracking[i]:
+                # only change param val if difference is big enough FIXME
+                if abs(new_val - param.val) >= 0.1 * self.min_change * param.span:
+                    param.val = new_val
+            else:
+                delta = param.val - new_val
+                if abs(delta) < self.min_change * param.span:
+                    self.is_tracking[i] = True
+
+    def update_knobs_scale(self, new_knob_vals):
+        """new_knob_val is list of new knob vals, each normalized 0.0-1.0"""
+        # note this sucks currently
+        for i in range(self.nknobs):
+            param = self.params[(self._idx * self.nknobs) + i]
+            new_val = param.knob_to_val(new_knob_vals[i])
+            delta_val = new_val - param.val
+
+            val_min, val_max = param.vmin, param.vmax
+            # knob_min, knob_max = 0.0, 1.0
+
+            val_max_pos_delta = val_max - param.val
+            val_min_pos_delta = param.val - val_min
+            knob_max_pos_delta = val_max - new_val
+            knob_min_pos_delta = new_val - val_min
+
+            if delta_val > 0 and knob_max_pos_delta != 0:
+                val_percent_change = delta_val * val_max_pos_delta / knob_max_pos_delta
+            elif delta_val < 0 and knob_min_pos_delta != 0:
+                val_percent_change = delta_val * val_min_pos_delta / knob_min_pos_delta
+            else:
+                val_percent_change = 0
+
+            param.val = min(max(param.val + val_percent_change, val_min), val_max)
+
+    def apply_params(self, obj):
+        """Apply all params to given object"""
+        for i in range(self.nparams):
+            self.params[i].apply_to_obj(obj)
+
+    def apply_knobset(self, obj):
+        """Apply all vals in a knobset to given object"""
+        for i in range(self.nknobs):
+            self.params[(self._idx * self.nknobs) + i].apply_to_obj(obj)
+
+    def param_for_name(self, name):
+        for p in filter(lambda p: p.name == name, self.params):
+            return p
+        return None
+
+    # fmt: off
+    def __str__(self):
+        return("ParamSet(nknobs="+str(self.nknobs) + ", " +
+               "nknobsets="+str(self.nknobsets) +
+               ", params="+str(self.params)+")")
+    # fmt: on
+
+    @staticmethod
+    def load(dumpstr):
+        dumpobj = json.loads(dumpstr)
+        newparams = [Param(**d) for d in dumpobj["params"]]
+        return newparams
+
+    @staticmethod
+    def dump(paramset):
+        dumpobj = {"params": [p.__dict__ for p in paramset.params]}
+        return json.dumps(dumpobj)
+
+
+# simple test
+
+if __name__ == "__main__":
+    myparams = [
+        Param("cutoff", 8000, 0, 9000, "%4d", "filt_frequency"),
+        Param("envmod", 0.5, 0.0, 1.0, "%.2f", "filt_env_depth"),
+        Param("resq", 8000, 0, 9000, "%4d", "resonance"),
+        Param("decay", 0.5, 0.0, 1.0, "%.2f", "decay"),
+    ]
+
+    param_set = ParamSet(myparams, num_knobs=2)
+
+    print("param_set:", param_set)

synthtools/patch.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# patch.py - pure-data patch objects, trivially JSON serializable.
+# Rule: only JSON-native types live here (str, int, float, bool, list).
+# Never a synthio object, never a ulab array.
+
+import json
+
+
+class Patch:
+    """A synth patch. Unknown kwargs land in __dict__ and round-trip
+    through JSON untouched, so synth-type-specific fields (wave_file,
+    wave_pos, ...) need no subclassing."""
+
+    def __init__(self, **kw):
+        self.name = "init"
+        self.synth_type = "subtractive"  # dispatch hint for patch banks
+        self.wave = "SAW"  # waveform name, see waves.py
+        self.detune = 1.001  # osc2 freq ratio, 1.0 = single osc
+        self.filt_type = "LPF"  # "LPF" | "HPF" | "BPF" | "NOTCH" | None
+        self.filt_f = 2500  # filter cutoff in Hz
+        self.filt_q = 1.1  # filter resonance
+        # list, not tuple: JSON round-trips it as a list anyway, and a list
+        # lets you set one stage in place (amp_env[0] = x) without rebuilding.
+        self.amp_env = [0.01, 0.10, 0.8, 0.35]  # attack, decay, sustain, release
+        self.vib_rate = 5.0  # Hz
+        self.vib_depth = 0.0  # in bend units: 1.0 = one octave, 0.006 ~ 10 cents
+        self.vib_delay = 0.0  # seconds for vibrato to fade in (0 = immediate)
+        # Portamento. Only applies while the synth's `mono` is set; a
+        # polyphonic synth ignores it. 0 = jump straight to pitch.
+        self.glide_time = 0.0  # seconds to slide from the previous note
+        # Pitch envelope, in the same bend units. Bends INTO the note from
+        # penv_amount to true pitch, then on note-off drifts OUT to
+        # penv_out_amount. Both amounts default to 0 = off, and a voice with
+        # both off costs nothing.
+        self.penv_amount = 0.0  # bend at note-on; + starts sharp, - flat
+        self.penv_time = 0.10  # seconds to settle to true pitch
+        self.penv_out_amount = 0.0  # bend drifted to after note-off
+        self.penv_out_time = 0.20  # seconds for that drift
+        # --- the four filter-cutoff modulations -----------------------
+        # cutoff = filt_f + filt_lfo + fenv + velocity, summed in one
+        # synthio block graph. See synth.py.
+        # 1. filt_f above is the base.
+        # 2. cyclic LFO, additive: filt_f is the floor, the LFO opens upward
+        self.filt_lfo_rate = 0.5  # Hz
+        self.filt_lfo_amount = 0  # Hz added above filt_f, 0..amount; 0 = off
+        # 3. AHR envelope, added to the cutoff in Hz. amount 0 = off (and
+        #    costs nothing: no per-voice blocks are created).
+        self.fenv_amount = 0  # Hz of cutoff swing; negative sweeps down
+        self.fenv_attack = 0.05  # seconds to reach full depth
+        self.fenv_release = 0.40  # seconds to fall back to zero
+        # Integer exponent on the envelope shape: 1 = linear, 2+ increasingly
+        # curved. The attack rises fast and eases into the peak; the release
+        # drops fast and tails off -- the conventional analog feel. Both come
+        # from one shared buffer holding 1-(1-t)^curve, so they are linked:
+        # see fill_env_rise() in waves.py for why the release decides.
+        self.fenv_curve = 1
+        # 4. Velocity. The units differ on purpose: filt_vel adds to a
+        #    cutoff so it is in Hz, fenv_vel scales a depth so it is a
+        #    0-1 fraction. Both default to "velocity changes nothing".
+        self.filt_vel = 0  # Hz of cutoff at full velocity; negative
+        #                       means hard playing CLOSES the filter
+        self.fenv_vel = 0.0  # 0 = uniform depth, 1.0 = depth tracks velocity
+        # setattr loop, not self.__dict__.update(kw): CircuitPython's
+        # instance __dict__ is a read-only mapping and update() raises
+        # TypeError. Reading it (dict(self.__dict__)) is fine.
+        for k, v in kw.items():
+            setattr(self, k, v)
+
+    # --- dict / JSON round-trip -------------------------------------
+
+    def to_dict(self):
+        return dict(self.__dict__)
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(**d)
+
+    def to_json(self):
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, s):
+        return cls(**json.loads(s))
+
+    # --- filesystem helpers -----------------------------------------
+    # note: writing to CIRCUITPY from code requires storage.remount()
+
+    def save(self, filepath):
+        with open(filepath, "w") as f:
+            f.write(self.to_json())
+
+    @classmethod
+    def load(cls, filepath):
+        with open(filepath) as f:
+            return cls.from_json(f.read())
+
+    def __repr__(self):
+        return "Patch(%s)" % ", ".join("%s=%r" % (k, v) for k, v in sorted(self.__dict__.items()))
+
+
+# --- simple patch banks: a JSON list of patch dicts -----------------
+
+
+def save_patches(patches, filepath):
+    """Write a list of Patch objects to filepath as one JSON array."""
+    with open(filepath, "w") as f:
+        json.dump([p.to_dict() for p in patches], f)
+
+
+def load_patches(filepath):
+    """Read a list of Patch objects back from a file written by
+    save_patches()."""
+    with open(filepath) as f:
+        return [Patch.from_dict(d) for d in json.load(f)]

synthtools/pitch_glider.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 Tod Kurt
+# SPDX-License-Identifier: MIT
+"""
+``pitch_glider``
+================================================================================
+
+``Glider`` is a portamento feature for synthio.Notes. Attach to note.bend.
+
+10 Feb 2025 - @todbot / Tod Kurt
+
+"""
+# pitch_glider.py --
+# part of todbot circuitpython synthio tutorial
+# 10 Feb 2025 - @todbot / Tod Kurt
+
+import synthio
+import ulab.numpy as np
+
+
+class Glider:
+    """Attach a Glider to note.bend to implement portamento"""
+
+    def __init__(self, glide_time, midi_note):
+        glide_time = glide_time or 0.001
+        self.pos = synthio.LFO(
+            once=True,
+            rate=1 / glide_time,
+            waveform=np.array((0, 32767), dtype=np.int16),
+        )
+        self.lerp = synthio.Math(synthio.MathOperation.CONSTRAINED_LERP, 0, 0, self.pos)
+        self.midi_note = midi_note
+
+    def update(self, new_midi_note):
+        """Update the glide destination based on new midi note"""
+        self.lerp.a = self.bend_amount(new_midi_note, self.midi_note)
+        self.lerp.b = 0  # end on the new note
+        self.pos.retrigger()  # restart the lerp
+        # print("bend_amount:", self.bend_amount(self.midi_note, new_midi_note),
+        #      "old", self.midi_note, "new:", new_midi_note, self.lerp.a, self.lerp.b)
+        self.midi_note = new_midi_note
+
+    def bend_amount(self, old_midi_note, new_midi_note):
+        """Calculate how much note.bend has to happen between two notes"""
+        return (new_midi_note - old_midi_note) * (1 / 12)
+
+    @property
+    def glide_time(self):
+        """Return glide time in seconds"""
+        return 1 / self.pos.rate
+
+    @glide_time.setter
+    def glide_time(self, glide_time):
+        """Set glide time in seconds, sets the rate of underlying LFO"""
+        glide_time = glide_time or 0.001  # ensure non-zero for division
+        self.pos.rate = 1 / glide_time

synthtools/step_sequencer.py

@@ -0,0 +1,113 @@
+## pylint: disable=invalid-name, too-many-arguments, too-many-instance-attributes
+# SPDX-FileCopyrightText: Copyright (c) 2023 Tod Kurt
+# SPDX-License-Identifier: MIT
+"""
+``step_sequencer``
+================================================================================
+
+``StepSequencer`` is a note-based 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
+
+
+class StepSequencer:
+    """
+    StepSequencer contains a list of meloci events in list of steps.
+
+    :param int step_count: how many for all the triggers
+    :param int steps_per_beat: number of steps in a beat (1=quarter note, 2=8th note, 4=16th note)
+    :param function on_func: function to call on note-on
+    :param function off_func: function to call on note-off
+    """
+
+    def __init__(self, step_count, steps_per_beat, on_func=None, off_func=None):
+        self.steps_per_beat = steps_per_beat  # 1 = 1/4 note, 2 = 8th note, 4 = 16th note
+        self.step_count = step_count  # how big the sequence is
+        self.i = 0  # where in the step sequence we currently are
+
+        # our sequence, list of step "objects": ie. list (notenum, vel, gate, on)
+        self.steps = [[0, 127, 0.5, True] for i in range(step_count)]
+
+        self.on_func = on_func  # callback to invoke when 'note on' should be sent
+        self.off_func = off_func  # callback to invoke when 'note off' should be sent
+        self.gate_off_millis = 0  # when in the future our note off should occur
+        self.held_note = None  # the current note playing
+        self.transpose = 0
+        self.playing = False  # is sequence running or not (but use .start()/.stop())
+        self.next_millis = 0
+        self.error_millis = 0
+
+    @property
+    def bpm(self):
+        """Returns bpm, computed"""
+        return 60_000 / self.step_millis / self.steps_per_beat
+
+    @bpm.setter
+    def bpm(self, bpm):
+        """Sets the internal tempo. step_millis is time between steps"""
+        self.step_millis = 60_000 / self.steps_per_beat / bpm
+        # print("stepseq.set_bpm: %6.2f %d" % (self.step_millis, bpm) )
+
+    def set_gates(self, gate):
+        """Set all gates to a specified percentage 0-1"""
+        for i in range(self.step_count):
+            self.steps[i][2] = gate
+
+    def start(self):
+        """Start sequencer going"""
+        self.next_millis = ticks_ms()
+        self.playing = True
+        self.error_millis = 0
+
+    def stop(self):
+        """Stop sequencer, turning off any currently-sounding note"""
+        if self.held_note:
+            self.off_func(*self.held_note)
+        self.playing = False
+        self.i = 0
+
+    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:
+            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]

synthtools/subtractive_synth.py

@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# subtractive.py - classic two-oscillator subtractive synth.
+#
+# Osc2 is a detuned copy of osc1; detune=1.0 collapses to a single osc.
+
+import synthio
+
+from .synth import Synth
+from .waves import get_wave_2x, random_phase_wave
+
+
+class SubtractiveSynth(Synth):
+    """Classic two-oscillator subtractive synth: one waveform, an optional
+    detuned second oscillator, through the shared Synth filter/envelope
+    graph.
+
+    ``detune=1.0`` (the default) collapses to a single oscillator, so an
+    ordinary patch costs one Note per key; any other detune spends TWO
+    Notes per key (see the polyphony-budget note in the project docs).
+    Each oscillator gets its own random phase per note-on, and osc2 is
+    scaled down (60% of osc1) so a detuned voice's peak amplitude does not
+    exceed a single-oscillator one.
+    """
+
+    _PARAMS = Synth._PARAMS + ("wave", "detune")
+
+    # class attrs: the base __init__ builds its graph before this subclass
+    # has run any setup of its own
+    _wave_name = "SAW"
+    _detune = 1.0
+
+    def _recompile(self):
+        super()._recompile()
+        self._wave_name = self.patch.wave
+        self._detune = self.patch.detune
+        get_wave_2x(self._wave_name)  # warm the cache; note-on only slices
+
+    def _decompile(self):
+        super()._decompile()
+        self.patch.wave = self._wave_name
+        self.patch.detune = self._detune
+
+    def _make_notes(self, midi_note, velocity):
+        f = synthio.midi_to_hz(midi_note)
+        amp = velocity / 127
+        detuned = self._detune and self._detune != 1.0
+        # Each oscillator gets its OWN random start point in the wave's
+        # cycle, rerolled every note-on -- see waves.random_phase_wave().
+        # Rebalanced only when osc2 exists: undetuned (single-osc) patches
+        # stay at full amp, unchanged. When osc2 is present, split so the
+        # two sum to amp * 1.0 instead of amp * 1.6 -- the old worst case
+        # (both oscillators in phase, still possible now that phase is
+        # random) could exceed int16 range on its own, before the filter
+        # even sees it. 0.625/0.375 keeps osc2 at 60% of osc1's level, same
+        # blend as before, just scaled so the ceiling is 1.0 instead of 1.6.
+        # fmt: off
+        n1 = synthio.Note(f, waveform=random_phase_wave(self._wave_name),
+                          envelope=self._env,
+                          amplitude=amp * 0.625 if detuned else amp,
+                          filter=self._make_filter(), bend=self._bend_cur)
+        if detuned:
+            n2 = synthio.Note(f * self._detune,
+                              waveform=random_phase_wave(self._wave_name),
+                              envelope=self._env, amplitude=amp * 0.375,
+                              filter=self._make_filter(), bend=self._bend_cur)
+            return (n1, n2)
+        return (n1,)
+        # fmt: on
+
+    @property
+    def wave(self):
+        return self._wave_name
+
+    @wave.setter
+    def wave(self, v):
+        self._wave_name = v
+        get_wave_2x(v)  # O(1); warms the cache for the next note-on
+
+    @property
+    def detune(self):
+        return self._detune
+
+    @detune.setter
+    def detune(self, v):
+        # genuinely per-note (each osc2 has its own frequency), so this one
+        # cannot be a shared block: O(polyphony).
+        self._detune = v
+        for notes in self.voices.values():
+            if len(notes) > 1:
+                notes[1].frequency = notes[0].frequency * v