Version: 0.4 - 23 Apr 2025
Welcome to a CircuitPython Synthio Tutorial.
In CircuitPython, synthio
is a built-in module for doing sound synthesis
on microcontrollers.
This guide focuses on using synthio with the Raspberry Pico RP2040 and Pico 2 RP2350
with an PCM5102a I2S DAC
for audio output, but applies to other microcontrollers that support synthio
(like ESP32) and other audio output techniques (like PWMOut and
analog AudioOut).
The main URL for this tutorial is: https://todbot.github.io/CircuitPython_Synthio_Tutorial/ Its repo is https://github.com/todbot/CircuitPython_Synthio_Tutorial where you can download all the code as a zip file.
This guide hopes to show how synthio
"thinks" about sound synthesis,
showing techniques for implementing common synthesis concepts with synthio.
This guide provides over 50 complete CircuitPython example programs (with a video for each one)
that show different aspects of synthio, acting as a starting point for your own explorations
and combinining them into new synth devices.
This guide will focus on a Pico RP2040 and PCM5102a I2S DAC,
but it applies to any board that supports synthio.
All code will work unchanged on a Pico 2 (RP2350) and soem code will only work on
the RP2350.
This tutorial assumes you know some Python and CircuitPython already.
It doesn't try to assume you know much about synthesizers or music theory,
Of course, knowing the basics of "subtractive synthesis" will help understand
more what synthio is doing and how it differs from that standard.
This guide is broken up into multiple sections. Each section focuses on a topic, and will use techniques and terms discussed in previous sections.
Every example code block is a fully working program, no code snippets here, with
download links to ready-to-run code. After each code block, is a demo video
showing the code in action.
Some functionality will be provided by external libraries or included scripts
(most notably synth_setup.py).
Each example code block in the guide also exists as a code_[name].py file
that can be copied to your device's CIRCUITPY drive as code.py to run.
The file will sometimes contain extra explanatory comments or print statements.
Almost every example also has an accompanying video to let you hear and see
what it's doing.
Every example (hopefully) does something sonically interesting just sitting there, and most will also have a bit of interactivity with the knobs and button. So even if you don't have the knobs & button wired up, you should still get a sense of what the example is about.
-- Going from a fresh Pico to making boops and responding to inputs
-- Making those boops sound more alive with LFOs and Envelopes
-- How to use synthio's filters and modulate them
-- Change a note's waveform, at any time, even use WAVs
-- How to respond to MIDI messages (velocity, pitchbend, CCs) in synthio
-- Using the audiofilters and audiodelays modules to add effects
-- Buildling a full synth voice in synthio
Here's some simple examples using synthio showing what's possible
- tiny_lfo_song -- song with just LFOs
- eighties_dystopia -- 80s-style miasma
- quicky_theremin -- simple theremin using
touchio - wavetable_midisynth -- Play wavetables with MIDI
- monosynth1 -- MIDI-controlled thick monosynth
- two_pot_drone_synth -- 3-voice two-knob drone synth
I and others have created several projects and libraries that use synthio.
Some are listed here:
- todbot: circuitpython-syntho-tricks
- todbot: pico_test_synth
- todbot: qtpy_synth
- todbot: Workshop Computer
- gamblor: synth drum sounds
- cedargrove CircuitPython_WaveBuilder
- cedargrove: CircuitPython_Chime
- relic-se: PicoSynth_Sandbox
- relic-se: CircuitPython_SynthVoice, CircuitPython_Waveform, CircuitPython_KeyManager
- 0.4 - 23 Apr 2025 - added video examples for Section 4, changed to embeds
- 0.3 - 21 Apr 2025 - added video examples for Section 3
- 0.2 - 14 Apr 2025 - added video examples for Section 1 & 2
- 0.1 - 4 Apr 2025 - initial release for review