Published December 13, 2022 © CC BY-NC-SA

X'mas Music Box - Super Simple CircuitPython MP3 Player

Let's build a Christmas decoration that plays music from a SD card with some lights!

BeginnerFull instructions provided559

X'mas Music Box - Super Simple CircuitPython MP3 Player

Things used in this project

Hardware components

Adafruit ItsyBitsy M4 Express

Development Board, Class D Audio Amplifier Module

Speaker (8 ohms 0.5 watt)

SD Card Module

SparkFun Pushbutton switch 12mm

Adafruit NeoPixel Ring: WS2812 5050 RGB LED

Software apps and online services

CircuitPython

Story

Some Background

This is a pretty simple project, also the little wood house might look familiar, because it's the same house I've used for the IoTThe Thesmart house project (an off-the-shelf product I've bought online - it's not even laser-cut. I had this idea of making it into a Christmas decoration with some DIY materials bought from a local dollar shop (including the mini wooden fences), and to put a functional music playing device inside the small cabin without many exposed electronic parts.

I've used a dedicate MP3 player module in my lightsaber fixing project. It is convenient, but the module generates white noises whenever powering up. So I decided to try an alternative of using CircuitPython, for some boards can play WAV or MP3 files directly from its simulated-USB storage (for which you can directly drag and drop files).

On the other hand, most CircuitPython-supported boards do not have a lot of internal storage space; most Adafruit Express boards has additional 2MB flash, some may have 4MB or 8MB. So I add a SPI SD card module, and this also allows me to add or delete music without having to reprogramm the board. The content of the memory card will be mounted can accessed directly.

The Project

I've tried to write the code as generic as I can: in theory this works on any Adafruit M4/SAMD51, RP2040 and ESP32-S2 boards (M0/SAMD21 firmwares do not support MP3) with minimal changes. The whole thing uses one single button switch, one SD card module, amplifier/speaker and optional NeoPixel LEDs.

(See the video I've posted on Twitter.)

The on-board LED serves as the cabin interior light

In my own example I used a LM386 amplifier with a 8 ohms/0.5 watts speaker, which is way enough to play classic Christmas songs. You can use other combinations or attach a 3.5mm jack, etc. (If you are using a stereo amplifier, use only right or left side channel. It does not matter for CircuitPython.)

How to Use

Since the code sorts all .mp3 files by name, you should name the files as 01.xxx, 02.xxx... at root. If the device is powered on without a SD card, or the card has no MP3 files, or your firmware lacks some required Python module, the on-board LED (either NeoPixel or Dotstar, if there is one) will flashed red.

All internal/external LEDs, if there is any, will cycle through the same rainbow color. You can decorate them wherever you like. Be noted that you should consider the power consumption issue if you have lots of LEDs.

The single button serves three functions: a short press (less than 0.4 secs) pause/resume the music. Medium press (0.4~1.2 secs) will skip to next track. Long press (longer than 1.2 secs) will jump back to the first track.

Since this is meant to be a decoration (which plays background Christmas music on its own) than a actual music player, I don't need external displays or more controls. But it won't be too difficult if you want to expand this into a full-feature MP3 player.

* * *

NOTE - the audio amplifier wiring below is missing a connection between input "g" and GND of the board.

Code

Xmas Music Box

# ----------------------------------------

import board, busio

# button
BTN_PIN = board.D4
QUICK_PRESS_THRESHOLD = 0.4  # second; pause/resume
MID_PRESS_THRESHOLD = 1.2  # second; play next track
# long press = back to start

# audio out (DAC or PWM)
AUDIO_PIN = board.A0

# SPI SD card module
SDCARD_MOUNT = 'SD'
SDCARD_CS_PIN = board.D2
try:
    SPI = board.SPI()
except:
    # for RP2040s
    SPI = busio.SPI(clock=board.GP18, MOSI=board.GP19, MISO=board.GP16)

# on board RGB LED (neopixel or dotstar)
BOARD_HAS_LED = hasattr(board, 'DOTSTAR_CLOCK') or hasattr(board, 'APA102_MOSI') or hasattr(board, 'NEOPIXEL')
BOARD_LEDS_NUM = 1
BOARD_LED_BRIGHTNESS = 1.0

# external RGB LEDs (neopixel)
EXT_LEDS_NUM = 13  # set to 0 if you have none
EXT_LEDS_PIN = board.D5
EXT_LEDS_BRIGHTNESS = 0.2

# ----------------------------------------

import time, gc

gc.enable()

def openMp3(filename):
    return open(f'/{SDCARD_MOUNT}/{filename}', 'rb')

try:
    from rainbowio import colorwheel
    
    # https://github.com/adafruit/Adafruit_CircuitPython_NeoPixel/releases
    from neopixel import NeoPixel
    
    if BOARD_HAS_LED:
        if hasattr(board, 'DOTSTAR_CLOCK') or hasattr(board, 'APA102_MOSI'):
            # https://github.com/adafruit/Adafruit_CircuitPython_DotStar/releases
            from adafruit_dotstar import DotStar
            try:
                board_led = DotStar(board.DOTSTAR_CLOCK, board.DOTSTAR_DATA, BOARD_LEDS_NUM)
            except:
                board_led = DotStar(board.APA102_SCK, board.APA102_MOSI, BOARD_LEDS_NUM)
        else:
            board_led = NeoPixel(board.NEOPIXEL, BOARD_LEDS_NUM)
        board_led.brightness = BOARD_LED_BRIGHTNESS
        board_led.fill((255, 255, 255))
        board_led.show()
    
    if EXT_LEDS_NUM > 0:
        ext_leds = NeoPixel(EXT_LEDS_PIN, EXT_LEDS_NUM)
        ext_leds.brightness = EXT_LEDS_BRIGHTNESS
        ext_leds.fill((0, 0, 0))
        ext_leds.show()

    from digitalio import DigitalInOut, Pull
    button = DigitalInOut(BTN_PIN)
    button.switch_to_input(pull=Pull.UP)
    
    import storage
    from sdcardio import SDCard
    sdcard = SDCard(SPI, SDCARD_CS_PIN)
    vfs = storage.VfsFat(sdcard)
    storage.mount(vfs, f'/{SDCARD_MOUNT}')

    mp3files = [name for name, _, _, _ in vfs.ilistdir('/')
                if name.endswith('.mp3') and not name.startswith('.')]
    
    if not mp3files:  # empty list
        raise Exception('No mp3 files found on sd card')
    
    mp3files.sort()
    
    print('List of found mp3 files:')
    for filename in mp3files:
        print(f'* {filename}')
    print(f'Total: {len(mp3files)} tracks')
    
    try:
        from audioio import AudioOut
    except ImportError:
        from audiopwmio import PWMAudioOut as AudioOut
    from audiomp3 import MP3Decoder

    audio = AudioOut(AUDIO_PIN)
    mp3 = openMp3(mp3files[0])
    decoder = MP3Decoder(mp3)

except Exception as e:
    print('Error occurred:', e)
    try:
        if BOARD_HAS_LED:
            board_led.fill((255, 0, 0))
            board_led.show()
    finally:
        while True:
            pass

startPress = 0
pressDuration = 0
isPressing = False
mp3Index = 0
ledIndex = 0

def playMp3():
    print(f'Playing track: {mp3files[mp3Index]}')
    time.sleep(0.5)
    decoder.file = openMp3(mp3files[mp3Index])
    audio.play(decoder)

def forwardMp3():
    global mp3Index
    mp3Index = (mp3Index + 1) % len(mp3files)

time.sleep(1)
playMp3()

while True:
    if not audio.playing:
        forwardMp3()
        playMp3()
        
    if not button.value and not isPressing:
        isPressing = True
        startPress = time.monotonic_ns()
    
    if button.value and isPressing:
        isPressing = False
        pressDuration = (time.monotonic_ns() - startPress) / 1000000000
        if pressDuration <= QUICK_PRESS_THRESHOLD:
            if audio.paused and audio.playing:
                audio.resume()
                print('Audio resumed')
            elif not audio.paused and audio.playing:
                audio.pause()
                print('Audio paused')
        elif pressDuration <= MID_PRESS_THRESHOLD:
            audio.stop()
            print('Skip to next track...')
            forwardMp3()
            playMp3()
        else:  # long press
            audio.stop()
            print('Back to first track...')
            mp3Index = 0
            playMp3()
    
    ledIndex = (ledIndex + 1) % 255
    color = colorwheel(ledIndex)
    if BOARD_HAS_LED:
        board_led.fill(color)
        board_led.show()
    if EXT_LEDS_NUM > 0:
        ext_leds.fill(color)
        ext_leds.show()
    
    time.sleep(0.1)