CircuitPython Audio Out

Though the following example uses the Circuit Playground Express to demonstrate, the code works exactly the same way with the Circuit Playground Bluefruit. Simply copy the code and follow along with your Circuit Playground Bluefruit!

The Circuit Playground Express has some nice built in audio output capabilities.

There are two ways to get audio output, one is via the small built in speaker. The other is by using alligator clips to connect a headphone or powered speaker to the A0/AUDIO pin.

The speaker is over here, its small but can make some loud sounds! You can ENABLE or disable the speaker. If you disable the speaker, audio will only come out the A0/AUDIO pin. If you enable the speaker, audio will come out from both!

If you want to connect a speaker or headphones, use two alligator clips and connect GND to the sleeve of the headphone, and A0/AUDIO to the tip.

The A0/AUDIO pin cannot drive a speaker directly, please only connect headphones, or powered speakers!

Basic Tones

We can start by making simple tones. We will play sine waves. We first generate a single period of a sine wave in python, with the math.sin function, and stick it into sine_wave.

Then we enable the speaker by setting the SPEAKER_ENABLE pin to be an output and True.

We can create the audio object with this line that sets the output pin and the sine wave sample object and give it the sample array

audio = AudioOut(board.SPEAKER)
sine_wave_sample = RawSample(sine_wave)

Finally you can run - if you only want to play the sample once, call as is. If you want it to loop the sample, which we definitely do so its one long tone, pass in loop=True

You can then do whatever you like, the tone will play in the background until you call audio.stop()

import time
import array
import math
import board
import digitalio

    from audiocore import RawSample
except ImportError:
    from audioio import RawSample

    from audioio import AudioOut
except ImportError:
        from audiopwmio import PWMAudioOut as AudioOut
    except ImportError:
        pass  # not always supported by every board!

FREQUENCY = 440  # 440 Hz middle 'A'
SAMPLERATE = 8000  # 8000 samples/second, recommended!

# Generate one period of sine wav.
sine_wave = array.array("H", [0] * length)
for i in range(length):
    sine_wave[i] = int(math.sin(math.pi * 2 * i / 18) * (2 ** 15) + 2 ** 15)

# Enable the speaker
speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE)
speaker_enable.direction = digitalio.Direction.OUTPUT
speaker_enable.value = True

audio = AudioOut(board.SPEAKER)
sine_wave_sample = RawSample(sine_wave), loop=True)  # Keep playing the sample over and over
time.sleep(1)  # until...
audio.stop()  # We tell the board to stop

Playing Audio Files

Tones are lovely but lets play some music! You can drag-and-drop audio files onto the CIRCUITPY drive and then play them with a Python command

Here's the two files we're going to play:

Click the green buttons to download the wave files, and save them onto your CIRCUITPY drive, alongside your and lib files

This is the example code we'll be using

import board
import digitalio

    from audiocore import WaveFile
except ImportError:
    from audioio import WaveFile

    from audioio import AudioOut
except ImportError:
        from audiopwmio import PWMAudioOut as AudioOut
    except ImportError:
        pass  # not always supported by every board!

# Enable the speaker
spkrenable = digitalio.DigitalInOut(board.SPEAKER_ENABLE)
spkrenable.direction = digitalio.Direction.OUTPUT
spkrenable.value = True

# Make the 2 input buttons
buttonA = digitalio.DigitalInOut(board.BUTTON_A)
buttonA.direction = digitalio.Direction.INPUT
buttonA.pull = digitalio.Pull.DOWN

buttonB = digitalio.DigitalInOut(board.BUTTON_B)
buttonB.direction = digitalio.Direction.INPUT
buttonB.pull = digitalio.Pull.DOWN

# The two files assigned to buttons A & B
audiofiles = ["rimshot.wav", "laugh.wav"]

def play_file(filename):
    print("Playing file: " + filename)
    wave_file = open(filename, "rb")
    with WaveFile(wave_file) as wave:
        with AudioOut(board.SPEAKER) as audio:
            while audio.playing:

while True:
    if buttonA.value:
    if buttonB.value:

This example creates two input buttons using the onboard buttons, then has a helper function that will:

  1. open a file on the disk drive with wave_file = open(filename, "rb")
  2. create the wave file object with with WaveFile(wave_file) as wave:
  3. create the audio playback object with with AudioOut(board.SPEAKER) as audio:
  4. and finally play it until its done:
    while audio.playing:

 Upload the code then try pressing the two buttons one at a time to create your own laugh track!

If you want to use your own sound files, you can! Record, sample, remix, or simply download files from a sound file sight, such as Then, to make sure you have the files converted to the proper specifications, check out this guide here that'll show you how! Spoiler alert: you'll need to make a small, 22Khz (or lower), 16 bit PCM, mono  .wav file!

This guide was first published on Oct 12, 2017. It was last updated on Oct 12, 2017. This page (CircuitPython Audio Out) was last updated on Dec 05, 2019.