Skip to main content

Introduction

Documentation Status Discord Build Status Code Style: Ruff

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:

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.

Metadata

Release files for circuitpython-synthtools 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for circuitpython-synthtools 0.8.1
File Size Uploaded Provenance Actions
circuitpython_synthtools-0.8.1.tar.gz 412.0 kB Without provenance Details for circuitpython_synthtools-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for circuitpython-synthtools 0.8.1
File Interpreter ABI Platform Actions
circuitpython_synthtools-0.8.1-py3-none-any.whl Python 3 none any Details for circuitpython_synthtools-0.8.1-py3-none-any.whl

Total release size: 494.2 kB

Release files / circuitpython_synthtools-0.8.1.tar.gz

Download URL circuitpython_synthtools-0.8.1.tar.gz
Size 412.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ab04439e29f7ebcf9114a959a13f2cb7f5b8b88c3fe0912eafd108d8a6d4bbb9
BLAKE2b-256 checksum
How to use checksums
6624f1ff54977258f5ccb3538ea2ab2fa0e056fd9a18c61f9e7e720813f1f4bb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / circuitpython_synthtools-0.8.1-py3-none-any.whl

Download URL circuitpython_synthtools-0.8.1-py3-none-any.whl
Size 82.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
070b297374645989578a82ff77c6affcfbc320f057bee42d21edee88ca32fc36
BLAKE2b-256 checksum
How to use checksums
d578402c533164c77652fbec1907e2cc2c1cadd328fb09d4509241c5120cb2fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for circuitpython-synthtools 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page