MP3 playback is supported on most/many RP2040, SAMD51 and nRF boards. It is not supported on any SAMD21 (too slow) or ESP32 (different core chipset) boards. Check whether your board is supported by going to its download page on and looking for "audiomp3" in the list of "built in modules available".

Compressed audio can be a nice alternative to uncompressed WAV files - especially when you have a small filesystem like that on many CircuitPython boards: those WAV files get pretty big fast! Thanks to the expiration of the MP3 patent pool, we can now include MP3 decoding as a core CircuitPython capability and you can even play multiple MP3s at a time!

CircuitPython supports any MP3 file you like. We've found that mono and stereo files from 32kbit/s to 128kbit/s work, with sample rates from 16kHz to 44.1kHz. The DAC output on the SAMD51 M4 is just 12-bit so there's not much point in using higher bitrates.

We're going to play one short mp3 file, wait for a button to be pressed, and then play a second short mp3 file. Use the same wiring as the other audio examples.

Because creating an MP3Decoder object takes a lot of memory, it's best to do this just once when your program starts, and then update the .file property of the MP3Decoder when you want to play a different file.  Otherwise, you may encounter the dreaded MemoryError.

Installing Project Code

In the example below, click the Download Project Bundle button below to download the necessary libraries and the file in a zip file. Extract the contents of the zip file, open the directory CircuitPython_Essentials/CircuitPython_Audio_Out_MP3/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

# SPDX-FileCopyrightText: 2020 Jeff Epler for Adafruit Industries
# SPDX-License-Identifier: MIT

"""CircuitPython Essentials Audio Out MP3 Example"""
import board
import digitalio

from audiomp3 import MP3Decoder

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

button = digitalio.DigitalInOut(board.A1)

# The listed mp3files will be played in order
mp3files = ["slow.mp3", "happy.mp3"]

# You have to specify some mp3 file when creating the decoder
mp3 = open(mp3files[0], "rb")
decoder = MP3Decoder(mp3)
audio = AudioOut(board.A0)

while True:
    for filename in mp3files:
        # Updating the .file property of the existing decoder
        # helps avoid running out of memory (MemoryError exception)
        decoder.file = open(filename, "rb")
        print("playing", filename)

        # This allows you to do other things while the audio plays!
        while audio.playing:

        print("Waiting for button press to continue!")
        while button.value:

This guide was first published on Apr 02, 2018. It was last updated on Jul 17, 2024.

This page (CircuitPython MP3 Audio) was last updated on Jul 17, 2024.

Text editor powered by tinymce.