CircuitPython Synthio Tutorial

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.

What this guide is

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.

Who this guide is for

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.

How this guide is structured

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.

Sections

1. Getting Started

– Going from a fresh Pico to making boops and responding to inputs

2. Modulation

– Making those boops sound more alive with LFOs and Envelopes

3. Filters

– How to use synthio’s filters and modulate them

4. Oscillators and Wavetables

– Change a note’s waveform, at any time, even use WAVs

5. MIDI

– How to respond to MIDI messages (velocity, pitchbend, CCs) in synthio

6. Audio Effects

– Using the audiofilters and audiodelays modules to add effects

7. Synth Voice

– Buildling a full synth voice in synthio

Examples

Here’s some simple examples using synthio showing what’s possible

Projects using synthio

I and others have created several projects and libraries that use synthio. Some are listed here:

Changelog