circuitpython-synthtools 0.5__py3-none-any.whl

synthtools/waves.py

@@ -0,0 +1,499 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# waves.py - waveform name -> ulab int16 array, built once, cached forever.
+#
+# All notes share these arrays by reference: zero per-note allocation.
+#
+# Also holds `Waves`, a string-keyed factory with a few extra conveniences
+# (WAV loading, LFO shape helpers) for building instruments interactively.
+# `Waves.make_waveform()` delegates to `get_wave()` for the waveform types
+# they share, rather than generating them a second way.
+#
+# adafruit_wave is imported lazily, inside Waves.wav()/wav_info() only: it
+# isn't available under plain CPython (no pip package here), and everything
+# else in this module -- including the CPython test tier -- must not require
+# it just to build a waveform buffer.
+
+import random
+
+import ulab.numpy as np
+
+_cache = {}  # (name, size) -> np.array
+
+
+def _saw(size, vol):
+    return np.linspace(vol, -vol, num=size, dtype=np.int16)
+
+
+def _squ(size, vol):
+    h = size // 2
+    return np.concatenate(
+        (np.ones(h, dtype=np.int16) * vol, np.ones(size - h, dtype=np.int16) * -vol)
+    )
+
+
+def _sin(size, vol):
+    return np.array(
+        np.sin(np.linspace(0, 2 * np.pi, num=size, endpoint=False)) * vol, dtype=np.int16
+    )
+
+
+def _tri(size, vol):
+    h = size // 2
+    return np.concatenate(
+        (
+            np.linspace(-vol, vol, num=h, dtype=np.int16),
+            np.linspace(vol, -vol, num=size - h, dtype=np.int16),
+        )
+    )
+
+
+def _nze(size, vol):
+    return np.array([random.randint(-vol, vol) for _ in range(size)], dtype=np.int16)
+
+
+# --- hand-drawn "analog" waveforms, ported from the Mozzi Arduino synth
+# library's tables/ (saw_analogue512_int8.h, triangle_analogue512_int8.h,
+# square_analogue512_int8.h, smoothsquare8192_int8.h). Each is fixed
+# sampled data -- drawn by hand in Audacity, not generated by a formula --
+# so there is no recipe to regenerate them; only the sample data itself
+# can be shrunk. Each native table below was block-averaged offline (real
+# numpy, not on device) from the raw int8 samples, DC-corrected,
+# peak-normalized to +-127, and phase-rotated to start where the other
+# builders in this file start (peak-first for the saws, trough-first for
+# the triangle, plateau-first for the squares), then had its own first
+# sample appended as a cyclic sentinel so _resample_table()'s wraparound
+# from last sample back to first never needs a special case.
+#
+# Stored as a space-separated string, not a Python list/tuple literal:
+# ruff-format lays out a literal collection that doesn't fit on one line
+# one element per line, which turns a 129-number table into 129 source
+# lines. A string is never reflowed that way, so this keeps ~580 numbers
+# total to a few dozen compact lines.
+
+
+def _ints(s):
+    return tuple(int(v) for v in s.split())
+
+
+def _resample_table(table, size, vol, peak=127):
+    """Lerp a small native ``table`` (length N+1, table[-1] == table[0]) up
+    to ``size`` samples, scaled from its own +-127-ish native range to
+    +-vol. Plain Python scalar loop, not vectorized ulab ops: the
+    MicroPython ulab fallback (tests/stubs/ulab/numpy.py) supports only
+    int/slice indexing, so there is no fancy-indexing gather to lean on
+    here -- same shape as _nze() above."""
+    n = len(table) - 1
+    scale = vol / peak
+    out = []
+    for k in range(size):
+        pos = (k / size) * n
+        i = int(pos)
+        frac = pos - i
+        a = table[i]
+        b = table[i + 1]
+        out.append(int(round((a * (1.0 - frac) + b * frac) * scale)))
+    return np.array(out, dtype=np.int16)
+
+
+# saw_analogue512_int8.h: 512 raw int8 samples -> N=128 native, round-trip
+# RMS error 5.1% of peak at size=256.
+_ASAW_TABLE = _ints(
+    "112 103 105 101 100 97 97 94 93 90 89 86 85 82 81 79 78 75 74 71 70 "
+    "68 67 64 63 61 59 57 56 53 52 50 49 46 45 43 42 39 38 35 34 32 31 29 "
+    "28 25 24 22 21 18 17 15 14 12 11 8 7 5 4 2 1 -1 -3 -5 -6 -8 -9 -11 "
+    "-12 -15 -15 -18 -19 -21 -22 -24 -25 -27 -28 -30 -31 -33 -34 -36 -37 "
+    "-39 -40 -42 -43 -45 -46 -48 -49 -51 -52 -54 -54 -57 -57 -60 -60 -62 "
+    "-63 -65 -66 -67 -68 -71 -71 -73 -74 -76 -76 -78 -79 -81 -82 -84 -84 "
+    "-87 -87 -89 -89 -92 -91 -96 -73 81 112"
+)
+
+
+def _asaw(size, vol):
+    return _resample_table(_ASAW_TABLE, size, vol)
+
+
+# triangle_analogue512_int8.h: 512 raw int8 samples -> N=64 native,
+# round-trip RMS error 2.6% of peak at size=256.
+_ATRI_TABLE = _ints(
+    "-106 -101 -95 -89 -84 -78 -71 -65 -58 -52 -45 -38 -31 -24 -17 -10 -2 "
+    "5 13 21 29 37 45 53 62 71 78 87 96 105 114 123 125 116 107 98 89 80 "
+    "73 64 55 47 39 31 23 15 7 0 -8 -15 -23 -30 -37 -43 -50 -57 -63 -70 "
+    "-76 -82 -88 -94 -99 -105 -106"
+)
+
+
+def _atri(size, vol):
+    return _resample_table(_ATRI_TABLE, size, vol)
+
+
+# square_analogue512_int8.h: 512 raw int8 samples -> N=128 native,
+# round-trip RMS error 7.5% of peak at size=256.
+_ASQU_TABLE = _ints(
+    "107 104 110 105 109 106 109 106 109 106 109 106 109 107 108 107 108 "
+    "107 108 107 108 107 108 107 108 107 108 107 108 107 108 107 108 107 "
+    "108 107 108 107 108 107 108 107 108 107 108 107 108 107 108 107 109 "
+    "106 109 106 109 106 109 106 110 104 111 102 119 38 -106 -105 -109 "
+    "-106 -109 -106 -108 -107 -108 -107 -108 -107 -108 -107 -108 -107 "
+    "-108 -107 -108 -107 -108 -107 -108 -107 -108 -107 -108 -107 -108 "
+    "-107 -108 -107 -108 -107 -108 -107 -108 -107 -108 -107 -108 -107 "
+    "-108 -107 -108 -107 -108 -107 -108 -107 -108 -107 -108 -107 -109 "
+    "-107 -109 -106 -109 -106 -110 -103 -114 -51 107"
+)
+
+
+def _asqu(size, vol):
+    return _resample_table(_ASQU_TABLE, size, vol)
+
+
+# smoothsquare8192_int8.h: 8192 raw int8 samples -> N=256 native,
+# round-trip RMS error 2.4% of peak at size=256. DC-centering an
+# asymmetric hand-drawn wave means the two plateaus don't land at equal
+# +-magnitude after normalizing to +-127 (one side is ~117 here) --
+# inaudible, and expected for any non-zero-mean source.
+_SSQU_TABLE = _ints(
+    "-5 -5 -5 -5 -5 -5 -5 -5 -4 -2 1 5 10 17 27 38 52 67 83 100 115 117 "
+    "117 117 117 117 117 117 117 117 117 117 117 117 117 113 104 96 89 85 "
+    "83 83 85 88 93 98 104 110 116 117 117 117 117 117 117 117 117 117 "
+    "117 117 117 117 117 114 113 111 110 110 110 110 111 112 114 115 116 "
+    "117 117 117 117 117 117 117 117 117 117 117 117 117 117 117 117 116 "
+    "116 116 116 116 116 116 117 117 117 117 117 117 117 117 117 117 117 "
+    "117 117 117 117 117 117 117 117 117 117 117 117 117 117 117 117 117 "
+    "117 117 117 117 117 115 113 109 103 93 81 64 44 19 -9 -40 -73 -108 "
+    "-127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 "
+    "-127 -126 -112 -93 -79 -68 -61 -59 -60 -65 -72 -82 -94 -106 -117 "
+    "-126 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 "
+    "-127 -124 -120 -116 -114 -113 -113 -113 -114 -116 -118 -121 -124 "
+    "-126 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 "
+    "-127 -127 -126 -125 -125 -124 -124 -124 -124 -125 -125 -126 -126 "
+    "-127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 "
+    "-127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 -127 "
+    "-127 -127 -127 -127 -127 -127 -5"
+)
+
+
+def _ssqu(size, vol):
+    return _resample_table(_SSQU_TABLE, size, vol)
+
+
+_builders = {
+    "SAW": _saw,  # plain formula sawtooth
+    "SQU": _squ,  # plain formula square
+    "SIN": _sin,  # plain formula sine
+    "TRI": _tri,  # plain formula triangle
+    "NZE": _nze,  # white noise, resampled fresh every call
+    "ASAW": _asaw,  # Mozzi hand-drawn "analog" saw, wobbly decay
+    "ATRI": _atri,  # Mozzi hand-drawn "analog" triangle
+    "ASQU": _asqu,  # Mozzi hand-drawn "analog" square, rippled plateaus
+    "SSQU": _ssqu,  # Mozzi hand-drawn square, soft rounded corners
+}
+
+
+def get_wave(name, size=256, volume=28000):
+    """Return a cached int16 waveform array for ``name``. Builds on first use."""
+    key = (name, size)
+    w = _cache.get(key)
+    if w is None:
+        w = _builders[name](size, volume)
+        _cache[key] = w
+    return w
+
+
+def wave_names():
+    return list(_builders.keys())
+
+
+_2x_cache = {}  # (name, size) -> np.array, two cycles of get_wave() back to back
+
+
+def get_wave_2x(name, size=256, volume=28000):
+    """Two cycles of get_wave(name), concatenated. Built once and cached,
+    like get_wave() itself -- not a per-voice or per-note cost. This is the
+    shared source buffer random_phase_wave() slices from: doubling the
+    length means any offset in [0, size) has a full cycle available without
+    having to wrap around the end."""
+    key = (name, size)
+    w = _2x_cache.get(key)
+    if w is None:
+        base = get_wave(name, size, volume)
+        w = np.concatenate((base, base))
+        _2x_cache[key] = w
+    return w
+
+
+def random_phase_wave(name, size=256, volume=28000):
+    """One cycle of ``name``, starting at a random point in its cycle.
+
+    Unlike get_wave()/get_wave_2x(), this is NOT cached -- every call slices
+    a fresh ``size``-sample window out of the shared 2x buffer at a random
+    offset, so the returned array differs call to call. That makes it a
+    per-note-on cost: one array copy, the same tier as building a fresh
+    synthio.Note or Biquad at press time, not a per-sample one. Call it once
+    per oscillator per note-on, not from a hot path."""
+    wave2x = get_wave_2x(name, size, volume)
+    start = random.randint(0, size - 1)
+    return wave2x[start : start + size]
+
+
+# --- envelope shapes for one-shot LFOs -------------------------------
+# A synthio.LFO with once=True runs its waveform once and then holds the
+# final sample forever. So a buffer holding nothing but a rise 0 -> peak
+# already IS attack-then-hold: there is no need to write a plateau after
+# the rise, because the LFO supplies one for free and for as long as the
+# key is down. Release re-runs the same rise through a CONSTRAINED_LERP
+# with swapped endpoints -- see ahr_envelope.py.
+
+ENV_SIZE = 64
+ENV_PEAK = 32767
+
+
+def env_buffer():
+    """A writable buffer for an AHR envelope shape."""
+    return np.zeros(ENV_SIZE, dtype=np.int16)
+
+
+_ramp = None
+
+
+def ramp_wave():
+    """A cached 0 -> peak ramp, for one-shot LFOs used as a POSITION.
+
+    Two samples is all it takes: synthio interpolates between waveform
+    entries, so (0, ENV_PEAK) with once=True is a clean linear ramp that
+    holds at the top -- the tutorial's idiom for fade-ins and bends.
+
+    Note this is NOT interchangeable with LFO(waveform=None): the default
+    waveform is a zero-centred triangle that would come back down again.
+    A ramp has to be spelled out.
+
+    Read-only and shared by every user, unlike the envelope shape buffers,
+    which are per-instance because they get rewritten in place."""
+    global _ramp
+    if _ramp is None:
+        _ramp = np.array((0, ENV_PEAK), dtype=np.int16)
+    return _ramp
+
+
+def _curve_ramp(start, stop, n, curve):
+    """Normalized ramp start -> stop over n points, raised to the integer
+    power ``curve``. Repeated multiply rather than ``**``: elementwise float
+    multiply is already proven on ulab, ``**`` is not.
+
+    For start/stop in [0,1] the result stays in [0,1], so scaling by
+    ENV_PEAK cannot leave int16 range. Call it descending (1.0 -> 0) to get
+    (1-t)^curve; ulab has no negative strides, so a descending linspace is
+    the way to reverse a ramp, never a [::-1] slice.
+
+    Allocates one array per multiply, so curve > 1 costs curve-1 extra
+    temporaries. Fine for a patch load or a switch, not for a knob path."""
+    t = np.linspace(start, stop, num=n)
+    y = t
+    for _ in range(curve - 1):
+        y = y * t
+    return y
+
+
+def _clamp_curve(curve):
+    curve = int(curve)
+    return 1 if curve < 1 else curve
+
+
+def fill_env_rise(buf, curve=1):
+    """Rise 0 -> ENV_PEAK across the WHOLE buffer, shaped 1 - (1-t)^curve.
+
+    ``curve`` is an integer exponent: 1 = linear, 2+ = increasingly
+    fast-start, easing into the peak. That shape is chosen for what it does
+    at the OTHER end. The release reruns this same buffer through a
+    CONSTRAINED_LERP with swapped endpoints, i.e. ``V * (1 - s(t))``, so
+
+        s(t) = 1 - (1-t)^curve   =>   release = V * (1-t)^curve
+
+    which is the conventional decay: quick initial drop, long tail. The
+    obvious alternative, s(t) = t^curve, makes the release ``V * (1 - t^curve)``
+    -- still at 75% of its value halfway through at curve=2, hanging near the
+    top and then falling off a cliff. A mirrored attack, not a decay.
+
+    NOTE this is a deliberate divergence from the synthio tutorial, whose
+    PRODUCT(lerp, lerp, 1) is t^2, the shape described above. The tutorial
+    keeps attack and release shapes independent, so it can afford t^2 for the
+    rise; sharing one buffer means the release gets the casting vote.
+
+    There is deliberately no hold segment and no second, falling buffer:
+      - the hold is what ``once=True`` already does after the last sample
+        (measured on device: a one-shot LFO reads 0.9999 at both 0.5s and
+        1.5s after a 0.2s rise), so writing a plateau here would only shorten
+        the rise and force the release rate to compensate for it;
+      - a second buffer is unreachable mid-note anyway, because
+        synthio.LFO.waveform is read-only.
+
+    Written IN PLACE, so every voice sharing this array morphs live."""
+    curve = _clamp_curve(curve)
+    n = len(buf)
+    if curve == 1:
+        # 1 - (1-t)^1 is just t, so take the integer linspace directly:
+        # bit-identical to a plain linear ramp and one float array cheaper
+        buf[:] = np.linspace(0, ENV_PEAK, num=n, dtype=np.int16)
+    else:
+        # `* -ENV_PEAK + ENV_PEAK`, NOT `ENV_PEAK - arr`: the pure-Python
+        # ulab fallback implements __sub__ but not __rsub__, so
+        # scalar-minus-array raises TypeError on the MicroPython tier.
+        # Array-times-scalar and array-plus-scalar are both fine.
+        # Endpoints stay exact for any curve because linspace pins its last
+        # element: (1-t) is exactly 1.0 at index 0 and exactly 0.0 at the end.
+        buf[:] = np.array(_curve_ramp(1.0, 0.0, n, curve) * (-ENV_PEAK) + ENV_PEAK, dtype=np.int16)
+
+
+# --- Waves: string-keyed factory + WAV loading, for interactive use ---
+
+_NAME_ALIASES = {
+    "SIN": "SIN",
+    "SINE": "SIN",
+    "SQU": "SQU",
+    "SQUARE": "SQU",
+    "SAW": "SAW",
+    "TRI": "TRI",
+    "TRIANGLE": "TRI",
+    "NZE": "NZE",
+    "NOISE": "NZE",
+    "ASAW": "ASAW",
+    "ANALOG_SAW": "ASAW",
+    "ATRI": "ATRI",
+    "ANALOG_TRI": "ATRI",
+    "ASQU": "ASQU",
+    "ANALOG_SQU": "ASQU",
+    "SSQU": "SSQU",
+    "SMOOTH_SQU": "SSQU",
+}
+
+
+class Waves:
+    """
+    Generate waveforms for either oscillator or LFO use.
+    By default, size is 256, volume is max +-32767
+    """
+
+    waveform_types = ("SIN", "SQU", "SAW", "TRI", "SIL", "NZE", "ASAW", "ATRI", "ASQU", "SSQU")
+
+    @staticmethod
+    def make_waveform(waveid, size=256, volume=32767):
+        """Return a waveform by string name, one of ``waveform_types``.
+
+        Delegates to ``get_wave()`` for the types it also builds, rather than
+        generating them a second way; SIL has no ``get_wave`` equivalent and
+        stays local.
+        """
+        waveid = waveid.upper()
+        if waveid in ("SIL", "SILENCE"):
+            return Waves.silence(size)
+        canonical = _NAME_ALIASES.get(waveid)
+        if canonical is None:
+            print("unknown wave type", waveid)
+            return None
+        return get_wave(canonical, size, volume)
+
+    @staticmethod
+    def sine(size, volume):
+        """Sine waveform"""
+        return get_wave("SIN", size, volume)
+
+    @staticmethod
+    def square(size, volume):
+        """Square waveform"""
+        return get_wave("SQU", size, volume)
+
+    @staticmethod
+    def triangle(size, min_vol, max_vol):
+        """Triangle waveform. ``get_wave``'s TRI is symmetric about 0, so this
+        only delegates when min_vol/max_vol are the usual +-volume pair."""
+        if min_vol == -max_vol:
+            return get_wave("TRI", size, max_vol)
+        return np.concatenate(
+            (
+                np.linspace(min_vol, max_vol, num=size // 2, dtype=np.int16),
+                np.linspace(max_vol, min_vol, num=size // 2, dtype=np.int16),
+            )
+        )
+
+    @staticmethod
+    def saw(size, volume):
+        """Saw (aka Ramp) waveform"""
+        return Waves.saw_down(size, volume)
+
+    @staticmethod
+    def saw_down(size, volume):
+        """Saw waveform from max to min"""
+        return get_wave("SAW", size, volume)
+
+    @staticmethod
+    def saw_up(size, volume):
+        """Saw waveform from min to max"""
+        return np.linspace(-volume, volume, num=size, dtype=np.int16)
+
+    @staticmethod
+    def silence(size):
+        """All zeros waveform"""
+        return np.zeros(size, dtype=np.int16)
+
+    @staticmethod
+    def noise(size, volume):
+        """White noise waveform (from random.randint)"""
+        return get_wave("NZE", size, volume)
+
+    @staticmethod
+    def from_list(vals):
+        """Waveform from a list of values, useful for LFOs"""
+        return np.array([int(v) for v in vals], dtype=np.int16)
+
+    @staticmethod
+    def lfo_ramp_up_pos():
+        """Simple two-element ramp-up waveform for synthio.LFO (which does interpolation)"""
+        return np.array((0, 32767), dtype=np.int16)
+
+    @staticmethod
+    def lfo_ramp_down_pos():
+        """Simple two-element row-downwaveform for synthio.LFO (which does interpolation)"""
+        return np.array((32767, 0), dtype=np.int16)
+
+    @staticmethod
+    def lfo_triangle_pos():
+        """Simple three-element triangle waveform for synthio.LFO (which does interpolation)"""
+        return np.array((0, 32767, 0), dtype=np.int16)
+
+    @staticmethod
+    def lfo_triangle():
+        """Simple four-element triangle waveform for synthio.LFO (which does interpolation)"""
+        return np.array((0, 32767, 0, -32767), dtype=np.int16)
+
+    @staticmethod
+    def from_ar_times(attack_time=1, release_time=1):
+        """
+        Generate a fake Attack/Release 'Envelope' using an LFO waveform.
+        This is a dumb way of doing it, but since we cannot get .value()
+        out of Envelope, we have to fake it with an LFO.
+        """
+        a10 = int(attack_time * 10)
+        r10 = int(release_time * 10)
+        a = [i * 65535 // a10 - 32767 for i in range(a10)]
+        r = [32767 - i * 65535 // r10 for i in range(r10)]
+        return Waves.from_list(a + [32767] + r)
+
+    @staticmethod
+    def wav(filepath, size=256, pos=0):
+        """Create a waveform from a WAV file using adafruit_wave"""
+        import adafruit_wave
+
+        with adafruit_wave.open(filepath) as w:
+            if w.getsampwidth() != 2 or w.getnchannels() != 1:
+                raise ValueError("unsupported format")
+            n = size
+            w.setpos(pos)
+            return np.frombuffer(w.readframes(n), dtype=np.int16)
+
+    @staticmethod
+    def wav_info(filepath):
+        """return (nframes,nchannels,sampwidth) from a WAV filename"""
+        import adafruit_wave
+
+        with adafruit_wave.open(filepath) as w:
+            return (w.getnframes(), w.getnchannels(), w.getsampwidth())

synthtools/wavetable.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# wavetable.py - reads Serum-style single-cycle WAV wavetables (16-bit mono,
+# waves of `size` samples back to back) into a reusable waveform buffer.
+# Requires the adafruit_wave library.
+#
+# This is the tool: a waveform-buffer helper for use as a synthio.Note's
+# `waveform`. For the polyphonic synth instrument built on top of it, see
+# wavetable_synth.py.
+
+import adafruit_wave
+import ulab.numpy as np
+
+
+class Wavetable:
+    """Reads one wave (or a lerp between two adjacent waves) out of a
+    wavetable WAV file into a fixed, reusable buffer."""
+
+    def __init__(self, filepath, size=256):
+        self.w = adafruit_wave.open(filepath)
+        if self.w.getsampwidth() != 2 or self.w.getnchannels() != 1:
+            raise ValueError("16-bit mono WAV required")
+        self.size = size
+        self.num_waves = self.w.getnframes() // size
+        self.waveform = np.zeros(size, dtype=np.int16)  # the shared buffer
+
+    def _read_wave(self, i):
+        self.w.setpos(i * self.size)
+        return np.frombuffer(self.w.readframes(self.size), dtype=np.int16)
+
+    def set_wave_pos(self, pos):
+        """pos is fractional: 3.25 = 25% between wave 3 and wave 4."""
+        n = self.num_waves
+        if n < 2:  # single-wave file: nothing to blend
+            self.waveform[:] = self._read_wave(0)
+            return
+        if pos < 0:
+            pos = 0.0
+        elif pos > n - 1:
+            pos = n - 1.0
+        i = int(pos)
+        if i > n - 2:  # at the very top, blend the last pair
+            i = n - 2
+        frac = pos - i
+
+        wave_a = self._read_wave(i)
+        if frac <= 0.0:  # exact wave: skip the read and the math
+            self.waveform[:] = wave_a
+            return
+        wave_b = self._read_wave(i + 1)
+
+        # Convex combination, evaluated in float. Do NOT write this as the
+        # usual  wave_a + frac * (wave_b - wave_a)  -- that subtraction is
+        # performed in int16 and wraps whenever the two samples straddle
+        # zero at high amplitude (32000 - -32000 = 64000 -> +1536), which
+        # then pushes the result past 32767 and raises
+        #   OverflowError: value must fit in 2 byte(s)
+        # on the store back into the int16 buffer. Multiplying by the float
+        # weights first promotes to float, and since frac is in [0,1] the
+        # result is bounded by the two inputs, so it always fits.
+        self.waveform[:] = np.array(wave_a * (1.0 - frac) + wave_b * frac, dtype=np.int16)

synthtools/wavetable_synth.py

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Tod Kurt
+# SPDX-License-Identifier: MIT
+#
+# wavetable_synth.py - polyphonic wavetable synth instrument, built on the
+# Synth engine (synth.py) and the Wavetable waveform-buffer tool
+# (wavetable.py).
+#
+# All sounding notes share self._wavetable.waveform by reference, so
+# setting wave_pos morphs already-sounding notes live -- the lerp writes
+# into the one buffer synthio is reading from. O(1) in polyphony.
+
+import synthio
+
+from .synth import Synth
+from .wavetable import Wavetable
+
+
+class WavetableSynth(Synth):
+    """Polyphonic wavetable synth: one Note per key, its waveform a
+    position (wave_pos) lerped between two adjacent frames of a loaded
+    wavetable WAV file (wave_file), through the shared Synth
+    filter/envelope graph.
+
+    All sounding notes share the Wavetable's waveform buffer by
+    reference, so moving wave_pos morphs already-sounding notes live --
+    the lerp writes into the one buffer synthio is reading from, O(1) in
+    polyphony regardless of how many notes are held.
+    """
+
+    _PARAMS = Synth._PARAMS + ("wave_pos", "wave_file")
+
+    # class attrs: base __init__ calls _recompile() before subclass setup
+    _wavetable = None
+    _wt_path = None
+    _wave_pos = 0
+
+    def _recompile(self):
+        super()._recompile()
+        p = self.patch
+        if p.wave_file != self._wt_path:  # heavy: only on file change
+            self._wavetable = Wavetable(p.wave_file)
+            self._wt_path = p.wave_file
+        self._wave_pos = getattr(p, "wave_pos", 0)
+        self._wavetable.set_wave_pos(self._wave_pos)
+        self._wave = self._wavetable.waveform
+
+    def _decompile(self):
+        super()._decompile()
+        self.patch.wave_file = self._wt_path
+        self.patch.wave_pos = self._wave_pos
+
+    def _make_notes(self, midi_note, velocity):
+        f = synthio.midi_to_hz(midi_note)
+        # fmt: off
+        return (synthio.Note(f, waveform=self._wave, envelope=self._env,
+                             amplitude=velocity / 127,
+                             filter=self._make_filter(),
+                             bend=self._bend_cur),)
+        # fmt: on
+
+    @property
+    def wave_pos(self):
+        return self._wave_pos
+
+    @wave_pos.setter
+    def wave_pos(self, v):
+        self._wave_pos = v
+        self._wavetable.set_wave_pos(v)  # in-place: morphs sounding notes
+
+    @property
+    def wave_file(self):
+        return self._wt_path
+
+    @wave_file.setter
+    def wave_file(self, v):
+        if v != self._wt_path:  # reopens file; next note-on uses it
+            self._wavetable = Wavetable(v)
+            self._wt_path = v
+            self._wavetable.set_wave_pos(self._wave_pos)
+            self._wave = self._wavetable.waveform