The Adafruit MacroPad runs a Raspberry Pi RP2040 microcontroller and has a built in speaker that makes it simple to play tones and audio clips. The Adafruit CircuitPython MacroPad library includes play_file() which supports MP3 playback, making it super simple to play MP3s on your MacroPad. This page explores using your MacroPad to play MP3 files with the Adafruit CircuitPython MacroPad library.

To get your MacroPad setup with the latest CircuitPython, check out the CircuitPython page in the MacroPad guide. You can find details on using the MacroPad library the MacroPad CircuitPython Library page in the MacroPad guide.

To install the Adafruit CircuitPython MacroPad library and its dependencies, follow the instructions below to download the Project Bundle. If you choose to install the library and its dependencies manually, please check out this guide.

Playing an MP3 File

Update your to the following.

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 folder that matches your CircuitPython version, and copy the entire lib folder and the file to your CIRCUITPY drive.

# SPDX-FileCopyrightText: Copyright (c) 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: Unlicense
MacroPad MP3 playback demo. Plays one of four different MP3 files when one of the first four keys
is pressed. All keys light up a color of the rainbow when pressed, but no audio is played for the
rest of the keys.
from rainbowio import colorwheel
from adafruit_macropad import MacroPad

macropad = MacroPad()

# To include more MP3 files, add the names to this list in the same manner as the others.
# Then, press the key associated with the file's position in the list to play the file!
audio_files = ["slow.mp3", "happy.mp3", "beats.mp3", "upbeats.mp3"]

while True:
    key_event =

    if key_event:
        if key_event.pressed:
            macropad.pixels[key_event.key_number] = colorwheel(
                int(255 / 12) * key_event.key_number
            if key_event.key_number < len(audio_files):

            macropad.pixels.fill((0, 0, 0))

Your CIRCUITPY drive should resemble the following image.


Now, press any one of the first four keys to hear some beats! Once the associated file is finish playing, you can press another of the first four keys to listen to a different one. You can press any of the rest of the keys to see them light up, but no audio will be played.

The video above plays only the slow.mp3 file as a demonstration of what MP3 playback sounds like on the MacroPad.

First, you import rainbowio and adafruit_macropad, and instantiate the MacroPad library.

Next, you create a list called audio_files, and include the names of the MP3 files you wish to play with the full name including .mp3 in quotes.

Inside the loop, the first thing you do is setup to look for the key press by creating the key_event variable and assigning it to Then, you check to see if there is a key_event (i.e. a key being pressed). If it is a key being pressed (key_event.pressed), you light up the key using the key_number to generate a colorwheel() value.

Then, if the key_number is less than the length of the list, you play the file in the list associated with the key number. This works because Python begins counting at 0. Therefore, the first key is number 0 and the fourth key is number 3. The length of the list is 4 (there are four items), so the key numbers associated with the files in the list will always be one less than the length of the list!

Finally, you turn off the NeoPixels when the keys are no longer being pressed and the files are no longer playing.

That's all there is to playing MP3s using the Adafruit CircuitPython MacroPad library and the Adafruit MacroPad!

Adding Your Own MP3 Files

Including additional or different MP3 files is simple. To include additional files, add them to the following line:

audio_files = ["slow.mp3", "happy.mp3", "beats.mp3", "upbeats.mp3"]

To include files other than the default ones, simply change the name of one of the current files to match the name of the file you wish to include. If you wanted the first key to instead play bleeps.mp3, you would update audio_files = to the following:

audio_files = ["bleeps.mp3", "happy.mp3", "beats.mp3", "upbeats.mp3"]

If you wanted to include an additional MP3 file called bloops.mp3, you would update audio_files = to the following:

audio_files = ["slow.mp3", "happy.mp3", "beats.mp3", "upbeats.mp3", "bloops.mp3"]

You can add up to twelve files, one for each key!

This guide was first published on Aug 31, 2021. It was last updated on Jun 18, 2024.

This page (MacroPad MP3) was last updated on Jun 17, 2024.

Text editor powered by tinymce.