Compressed audio can be a nice alternative to uncompressed WAV files, especially when you have a small filesystem like that on many CircuitPython boards, as WAV files get sizeable quite quickly. You can listen to a much longer playlist with CircuitPython, using the built in MP3 playback capability!
Necessary Hardware
You'll need the following additional hardware to complete the examples on this page.
To connect a speaker up to the Raspberry Pi Pico, you'll use a PAM8302 amplifier. Wire it up as shown below.
- PAM8302 A+ to Pico GP0
- PAM8302 A- to Pico GND
- PAM8302 VIN to Pico 3.3v
- PAM8302 GND to Pico GND
- PAM8302 screw terminal + to speaker +
- PAM8302 screw terminal - to speaker -
CircuitPython-Compatible MP3 Files
CircuitPython supports any MP3 file, as long as it is the right bit rate and sample rate for your board.
Mono and stereo files less than 64kbit/s work, with sample rates from 8kHz to 24kHz. The RP2040 has a PWM output with 10 bits, so there's not much point in using high bit rates.
On faster microcontrollers with more RAM, such as the RP2350, higher bit rates have been shown to work. You may wish to experiment with your audio and the microcontroller, noting that CD quality audio will generally not be playable but certainly files will with suitable downsampling.
Be aware, doing things like updating a display, or having intense flash activity like reading and writing files can result in distorted sounds or noise during playback.
You can find an example of converting an MP3 file using Audacity in this guide. The parameters suggested above may not be exactly what's in the guide, but the concept will be the same.
Playing an MP3 File
Update your code.py to the following.
Click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, open the folder that matches your CircuitPython version, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.
Your CIRCUITPY drive should now look something like this:
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
CircuitPython single MP3 playback example for Raspberry Pi Pico.
Plays a single MP3 once.
"""
import board
import audiomp3
import audiopwmio
audio = audiopwmio.PWMAudioOut(board.GP0)
decoder = audiomp3.MP3Decoder(open("slow.mp3", "rb"))
audio.play(decoder)
while audio.playing:
pass
print("Done playing!")
As soon as you save, the MP3 will begin playing! It plays only once. Connect to the serial console, and reload to play it again.
First, you import the necessary modules. All of these modules are built into CircuitPython, so this example does not require you to copy any external libraries to your board. Then, you setup the audio object and provide it the speaker pin.
Next, you create the decoder object and tell it the name of the MP3 file you'd like to play, in this case, "slow.mp3".
Then, you use the audio object to play the decoded MP3 file. while the audio is playing, pass, or do nothing. (You can add other code here such as blinking an LED or whatever you like.)
Finally, you print Done playing! to the serial console to let you know the MP3 playback has concluded.
That's all there is to playing a single MP3 file using CircuitPython!
Playing Multiple MP3 Files
The previous example plays a single MP3 file. But what if you want to include a playlist? This example has you covered.
Update your code.py to the following.
Click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, open the folder that matches your CircuitPython version, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
CircuitPython multiple MP3 playback example for Raspberry Pi Pico.
Plays two MP3 files consecutively, once time each.
"""
import board
import audiomp3
import audiopwmio
audio = audiopwmio.PWMAudioOut(board.GP0)
mp3files = ["slow.mp3", "happy.mp3"]
mp3 = open(mp3files[0], "rb")
decoder = audiomp3.MP3Decoder(mp3)
for filename in mp3files:
decoder.file = open(filename, "rb")
audio.play(decoder)
print("Playing:", filename)
while audio.playing:
pass
print("Done playing!")
As soon as you save, the MP3s will begin playing! They play only once. Connect to the serial console, and reload to play them again.
The code starts out the same, with the same imports and audio setup.
This time, however, you create a list of mp3files, with each file name as a string, including the .mp3. There are only two in this list, but you could add as many as you like to the list, copy the associated files to your CIRCUITPY drive, and the code will play them each consecutively.
Then, you open the first MP3 file in the list, and use it to construct the decoder object. This is necessary to be able to reuse the decoder object multiple times later.
Then, for each file in the mp3files list, you open the file in the decoder, use the audio object to play the decoded MP3 file. You print to the serial console Playing: and the name of the file currently playing. Then, while the audio is playing, pass, or do nothing.
Finally, you print Done playing! to the serial console to let you know the MP3 playback has concluded.
That's all there is to playing multiple MP3 files using CircuitPython!
CircuitPython MP3 Capable Pins
MP3 playback is supported on specific pins. The good news is, there's a simple way to find out which pins support audio playback.
Save the following file as code.py on your CIRCUITPY drive. Then, connect to the serial console to see a list of pins printed out. This file runs only once, so if you do not see anything in the output, press CTRL+D to reload and run the code again.
This microcontroller also support I2S, which allows use of a higher quality external DAC. The sample rates and bit rates are still limited to those shown above, but the audio quality can be substantially better. This script does not provide I2S-capable pins.
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
CircuitPython Audio-capable pin identifying script
"""
import board
from microcontroller import Pin
try:
from audioio import AudioOut
except ImportError:
from audiopwmio import PWMAudioOut as AudioOut
def is_audio(audio_pin_name):
try:
p = AudioOut(audio_pin_name)
p.deinit()
return True
except ValueError:
return False
except RuntimeError:
return False
def get_unique_pins():
exclude = [
getattr(board, p)
for p in [
# This is not an exhaustive list of unexposed pins. Your results
# may include other pins that you cannot easily connect to.
"NEOPIXEL",
"DOTSTAR_CLOCK",
"DOTSTAR_DATA",
"APA102_SCK",
"APA102_MOSI",
"LED",
"SWITCH",
"BUTTON",
]
if p in dir(board)
]
pins = [
pin
for pin in [getattr(board, p) for p in dir(board)]
if isinstance(pin, Pin) and pin not in exclude
]
unique = []
for p in pins:
if p not in unique:
unique.append(p)
return unique
for audio_pin in get_unique_pins():
if is_audio(audio_pin):
print("Audio pin:", audio_pin)
Page last edited August 13, 2025
Text editor powered by tinymce.
