Introduction

CircuitPython library with tools for making synths with synthio

This library is a collection of tools derived from my many years of playing with CircuitPython, synthio, and building synthesizers in general. Concepts pulled from these projects and others:

Dependencies

This driver depends on:

Adafruit CircuitPython

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle or individual libraries can be installed using circup.

Installing to a Connected CircuitPython Device with Circup

Make sure that you have circup installed in your Python environment. Install it with the following command if necessary:

pip3 install circup

With circup installed and your CircuitPython device connected use the following command to install:

circup install synthtools

Or the following command to update an existing version:

circup update

Usage Example

import time
from synth_setup import synth as engine
from synthtools import Patch, SubtractiveSynth

patch1 = Patch(name="fat bass", wave="ASAW", detune=1.004,
               filt_type="LPF", filt_f=800, filt_q=1.4,
               amp_env=[0.01, 0.1, 0.8, 0.4],
               vib_rate=5.5, vib_depth=0.0,
               # AHR filter envelope: cutoff swings 800 -> 3800 Hz and back
               fenv_amount=3000, fenv_attack=0.02, fenv_release=0.30,
               # a slow cyclic wobble on top of it (0 = off)
               filt_lfo_rate=0.4, filt_lfo_amount=0.3)
synth = SubtractiveSynth(engine, patch1)
arp = (36, 39, 43, 48)
i = 0
sweep = 0
while True:
    synth.note_on(arp[i % len(arp)], velocity=110)
    time.sleep(0.11)
    synth.note_off(arp[i % len(arp)])
    time.sleep(0.02)
    i += 1
    if i % 32 == 0:  # flip waveforms now and then
        synth.wave = "ASQU" if synth.wave == "ASAW" else "ASAW"

What’s Included

Patch – inert, JSON-able patch data; save/load with save_patches() / load_patches()
Synth – synth engine base: shared voice, patch, and modulation handling, complex filter & pitch envelopes, and a mono mode for a single-voice synth with glide_time portamento
SubtractiveSynth – subtractive two-oscillator synth w/ detune
WavetableSynth – wavetable-playback with adjustable LFO for wave_pos
FMSynth – two-operator phase-modulation voice: a carrier waveform pre-rendered from sin(theta + fm_index*sin(fm_ratio*theta)). fm_ratio must be an integer; fm_index is PM depth in radians, 0 = plain single-oscillator. (Not a full FM synth, see module for details)
BasslineSynth – TB-303-style acid bassline: monophonic, one oscillator, a decay-only filter sweep, per-step slide and accent. Can own its own filter/distortion/echo effects chain via fx_* patch fields
EffectsChain – a generic post-synth effects chain: add, insert, or remove any audiofilters/audiodelays effect and it stays wired. tracking_filter() builds extra filter stages that follow the synth’s own cutoff and resonance for a steeper slope (needs audiofilters in the build)
Waves – waveform factory (saw, square, sine, triangle, noise, and “analog” variants)
Wavetable – loads a wavetable WAV file and lerps between frames
AHREnvelope – shared-block attack/release envelope, used for both the filter and pitch envelopes
Arpeggiator / StepSequencer / TrigSequencer – poll-based sequencers with on/off callbacks
Glider – a standalone pitch-slide block for hand-built synthio.Note graphs (the engines above have their own portamento, via mono + glide_time)
Scale / chord – scales and diatonic/chromatic chords for mapping pads and MIDI onto pitch
Param / ParamSet – (UI) knob-pickup and scaling for UIs with fewer knobs than parameters
ParamScaler – (UI) proportional (“scale”) knob takeover for a single control, when you are not using ParamSet
GaugeCluster – (UI) a bar-graph display of a parameter page
RollingAverage – moving-average smoothing for noisy knob reads

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Table of Contents

Examples

API Reference