ESP32 MicroPython Mini Mp3 Player Module
The ESP32 is a versatile 3.3V microcontroller with WiFi, Bluetooth, and multiple hardware UART ports. Combined with the DIYables Mini Mp3 Player module and MicroPython, you can build anything from a simple sound effect board to a WiFi-controlled jukebox.
This tutorial walks you through:
- Connecting the Mini Mp3 Player to an ESP32 — directly, without a resistor.
- Loading mp3 files onto the SD card correctly.
- Playing, pausing, resuming, stopping, and skipping tracks.
- Adjusting volume with physical buttons.
- Repeating tracks, shuffling, and organizing audio into folders.
- Monitoring playback status from your code.
Components Needed
Or you can buy the following kits:
| 1 | × | DIYables ESP32 Starter Kit (ESP32 included) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables .
Additionally, some of these links are for products from our own brand, DIYables .
No resistor required. The ESP32 operates at 3.3V — the same voltage the Mini Mp3 Player's UART expects.
The Mini Mp3 Player Module
The DIYables Mini Mp3 Player is a compact audio decoder board based on the YX5200-24SS chip. It reads mp3 files from a micro SD card and outputs audio through a built-in 3W amplifier or via DAC pins for an external amplifier.
The ESP32 communicates with this module over UART at 9600 baud — a perfect match because the ESP32 has three hardware UART ports. You can dedicate UART2 to the mp3 module while keeping UART0 free for MicroPython's REPL console.
The module supports a rich set of serial commands:
- Transport: play, pause, resume, stop, next, previous
- Volume: 31 levels (0–30), adjustable on the fly
- Equalizer: 6 presets — Normal, Pop, Rock, Jazz, Classic, Bass
- Repeat modes: loop a single track, loop a folder, loop everything, or shuffle
- Folder playback: organize audio into numbered directories
- Advertisements: interrupt the current track with an announcement, then auto-resume
- Status queries: read track number, volume level, play state, and file counts
Pin Description
| Pin | Purpose | ESP32 Connection |
|---|---|---|
| VCC | 3.2V to 5.0V power input | Connect to ESP32 3.3V or 5V (VIN) |
| GND | Ground | Connect to ESP32 GND |
| RX | Serial data input | Connect to ESP32 GPIO17 (TX2) |
| TX | Serial data output | Connect to ESP32 GPIO16 (RX2) |
| SPK_1 | Speaker + (built-in amp, 3W max) | Connect to speaker |
| SPK_2 | Speaker − | Connect to speaker |
| DAC_R | Right channel line output | Optional — for external amp |
| DAC_L | Left channel line output | Optional — for external amp |
| BUSY | LOW = playing, HIGH = stopped | Optional — read with GPIO |
| IO_1 | Short press → prev; long press → vol down | Not used (controlled via UART) |
| IO_2 | Short press → next; long press → vol up | Not used (controlled via UART) |
Wiring
The ESP32 uses 3.3V logic natively, so you wire the serial lines directly — no level shifting or resistors needed.
We recommend using UART2 (available by default on most ESP32 DevKit boards):
| Mini Mp3 Player | ESP32 | Notes |
|---|---|---|
| VCC | 3.3V | Or 5V from VIN if available |
| GND | GND | |
| RX | GPIO 17 (TX2) | Direct connection |
| TX | GPIO 16 (RX2) | Direct connection |
| SPK_1 | Speaker + | |
| SPK_2 | Speaker − |
This image is created using Fritzing. Click to enlarge image
Tip: If your ESP32 variant does not expose GPIO 16/17 (some DevKit-C V4 boards use them for PSRAM), you can reassign UART pins in code:
uart = UART(2, baudrate=9600, tx=4, rx=5)
Getting the SD Card Ready
Before uploading any MicroPython code to the ESP32, prepare the micro SD card:
- Format the card as FAT16 or FAT32 (use your computer's disk utility).
- Copy mp3 files to the root directory with zero-padded names:
/001.mp3
/002.mp3
/003.mp3
- Optionally, organize tracks into numbered folders for multi-category playback:
/01/001.mp3 ← folder 1, track 1
/01/002.mp3 ← folder 1, track 2
/02/001.mp3 ← folder 2, track 1
Key rules for the ESP32 + Mini Mp3 Player setup:
- Track numbers start at 1, not 0.
- The module determines track order by the sequence files were copied to the card — not by filename. Format the card first, then copy files one at a time in order.
- Folder names must be 2-digit zero-padded (01–99). File names inside folders must be 3-digit zero-padded (001–255).
- Insert the SD card into the Mini Mp3 Player module before powering the ESP32.
Detailed Instructions
Here's instructions on how to set up and run your MicroPython code on the ESP32 using Thonny IDE:
- Make sure Thonny IDE is installed on your computer.
- Confirm that MicroPython firmware is loaded on your ESP32 board.
- If this is your first time using an ESP32 with MicroPython, check out the ESP32 MicroPython Getting Started guide for step-by-step instructions.
- Connect the ESP32 board to the Mini Mp3 Player module according to the provided diagram.
- Connect the ESP32 board to your computer with a USB cable.
- Open Thonny IDE on your computer.
- In Thonny IDE, go to Tools Options.
- Under the Interpreter tab, choose MicroPython (ESP32) from the dropdown menu.
- Make sure the correct port is selected. Thonny IDE usually detects it automatically, but you might need to select it manually (like COM12 on Windows or /dev/ttyACM0 on Linux).
- Navigate to the Tools Manage packages on the Thonny IDE.
- Search "DIYables-MicroPython-MiniMp3", then find the Mini Mp3 Player library created by DIYables.
- Click on DIYables-MicroPython-MiniMp3, then click Install button to install the Mini Mp3 Player library.
- Copy the provided MicroPython code and paste it into Thonny's editor.
- Save the code to your ESP32 by:
- Clicking the Save button or pressing Ctrl+S.
- In the save dialog, choose MicroPython device.
- Name the file main.py.
- Click the green Run button (or press F5) to execute the script.
- Insert the SD card with mp3 files into the Mini Mp3 Player module.
- Listen for audio playback through the connected speaker.
Starter Code Template
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
uart = UART(2, baudrate=9600, tx=17, rx=16)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
mp3.set_volume(25) # 0 = silence, 30 = maximum
ESP32 MicroPython Code — Play a Track
"""
* DIYables MicroPython Mini Mp3 Player - Play One Track
*
* This example plays one track once then stops.
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* SD Card: Put mp3 files in root, named 001.mp3, 002.mp3, etc.
"""
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
mp3.set_volume(25) # Set volume (0 to 30)
print("Playing track 1...")
mp3.play(1) # Play track 001.mp3
Try It
- Load the SD card, wire the module, connect the ESP32 via USB.
- Upload the code using Thonny IDE or your preferred MicroPython tool.
Playback Control
All playback commands are non-blocking — the ESP32 sends the command via UART2 and returns immediately, so your MicroPython code keeps running.
| Method | What Happens | Code Example |
|---|---|---|
| play(n) | Plays track number n from root | mp3.play(1) |
| play_next() | Jumps to the next track | mp3.play_next() |
| play_previous() | Goes back one track | mp3.play_previous() |
| pause() | Freezes playback at current position | mp3.pause() |
| resume() | Continues from the paused position | mp3.resume() |
| stop() | Stops playback entirely | mp3.stop() |
ESP32 MicroPython Code — Multiple Tracks
"""
* DIYables MicroPython Mini Mp3 Player - Play Multiple Tracks
*
* This example plays tracks one after another with a delay between them.
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* SD Card: Put mp3 files in root, named 001.mp3, 002.mp3, 003.mp3
"""
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
current_track = 1
total_tracks = 3 # Change this to match your SD card
track_duration = 5000 # Wait 5 seconds between tracks (adjust as needed)
mp3.set_volume(20)
print("Playing track 1...")
mp3.play(current_track)
last_track_time = time.ticks_ms()
while True:
if time.ticks_diff(time.ticks_ms(), last_track_time) >= track_duration:
current_track += 1
if current_track > total_tracks:
current_track = 1 # Loop back to first track
print("Playing track", current_track)
mp3.play(current_track)
last_track_time = time.ticks_ms()
ESP32 MicroPython Code — Next/Previous
"""
* DIYables MicroPython Mini Mp3 Player - Next/Previous with Buttons
*
* This example uses two buttons to play next/previous tracks.
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button NEXT -> GPIO1 (other leg to GND)
* Button PREV -> GPIO3 (other leg to GND)
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button NEXT -> GPIO2 (other leg to GND)
* Button PREV -> GPIO3 (other leg to GND)
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button NEXT -> D2 (GPIO5, other leg to GND)
* Button PREV -> D3 (GPIO6, other leg to GND)
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button NEXT -> D2 (other leg to GND)
* Button PREV -> D3 (other leg to GND)
*
* SD Card: Put mp3 files in root, named 001.mp3, 002.mp3, etc.
"""
from machine import UART, Pin
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
button_next = Pin(1, Pin.IN, Pin.PULL_UP)
button_prev = Pin(3, Pin.IN, Pin.PULL_UP)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# button_next = Pin(2, Pin.IN, Pin.PULL_UP)
# button_prev = Pin(3, Pin.IN, Pin.PULL_UP)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# button_next = Pin(5, Pin.IN, Pin.PULL_UP)
# button_prev = Pin(6, Pin.IN, Pin.PULL_UP)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
# button_next = Pin(2, Pin.IN, Pin.PULL_UP)
# button_prev = Pin(3, Pin.IN, Pin.PULL_UP)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
mp3.set_volume(20)
mp3.play(1) # Start with track 1
print("Press NEXT or PREV button to change track")
while True:
if button_next.value() == 0:
print("Next track")
mp3.play_next()
time.sleep_ms(300) # Simple debounce
if button_prev.value() == 0:
print("Previous track")
mp3.play_previous()
time.sleep_ms(300) # Simple debounce
ESP32 MicroPython Code — Pause/Resume
"""
* DIYables MicroPython Mini Mp3 Player - Pause and Resume
*
* This example demonstrates pausing and resuming playback using a button.
* Press the button to toggle between pause and resume.
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button -> GPIO1 (other leg to GND)
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button -> GPIO2 (other leg to GND)
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button -> D2 (GPIO5, other leg to GND)
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
* Button -> D2 (other leg to GND)
*
* SD Card: Put mp3 files in root, named 001.mp3, 002.mp3, etc.
"""
from machine import UART, Pin
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
button = Pin(1, Pin.IN, Pin.PULL_UP)
paused = False
mp3.set_volume(20)
mp3.play(1)
print("Playing. Press button to pause/resume.")
while True:
if button.value() == 0: # Button pressed (active LOW)
if paused:
mp3.resume()
print("Resumed")
else:
mp3.pause()
print("Paused")
paused = not paused
time.sleep_ms(300) # Simple debounce
ESP32 MicroPython Code — Loop a Track
"""
* DIYables MicroPython Mini Mp3 Player - Loop Track
*
* This example loops (repeats) a track continuously with EQ setting.
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* SD Card file structure:
* /001.mp3
* /002.mp3
* ...
"""
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
import DIYables_MicroPython_MiniMp3.DIYables_MicroPython_MiniMp3 as mp3_const
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
mp3.set_volume(25) # Volume: 0 to 30
mp3.set_eq(mp3_const.EQ_NORMAL)
print("Playing track 1 on loop...")
mp3.loop_track(1)
Repeat & Shuffle
These repeat modes run entirely on the mp3 module — the ESP32 just sends the command once and the module handles continuous playback on its own.
| Method | Behavior | Example |
|---|---|---|
| loop_track(n) | Repeat one track endlessly | mp3.loop_track(1) |
| loop_folder(f) | Cycle through all tracks in a folder | mp3.loop_folder(1) |
| loop_all() | Play every track on the SD card, then restart | mp3.loop_all() |
| stop_loop() | Stop repeating after the current track ends | mp3.stop_loop() |
| shuffle() | Play all tracks in random order | mp3.shuffle() |
ESP32 MicroPython Code — Folder Playback
"""
* DIYables MicroPython Mini Mp3 Player - Play from Folder
*
* This example plays tracks from specific folders on the SD card.
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* SD Card file structure:
* /01/001.mp3 <- play_folder(1, 1)
* /01/002.mp3 <- play_folder(1, 2)
* /02/001.mp3 <- play_folder(2, 1)
* /02/002.mp3 <- play_folder(2, 2)
"""
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
mp3.set_volume(20)
# Play track 1 from folder 01
print("Playing folder 01, track 001...")
mp3.play_folder(1, 1)
time.sleep(5)
# Play track 2 from folder 01
print("Playing folder 01, track 002...")
mp3.play_folder(1, 2)
time.sleep(5)
# Play track 1 from folder 02
print("Playing folder 02, track 001...")
mp3.play_folder(2, 1)
Folder API
Folder-based playback is great for ESP32 projects that need categorized audio — for example, different languages, sound categories, or playlists.
| Method | Description | Example |
|---|---|---|
| play_folder(f, t) | Play track t from folder f (up to 99 folders, 255 tracks each) | mp3.play_folder(1, 1) |
| play_large_folder(f, t) | Large folder mode (up to 15 folders, 3000 tracks each) | mp3.play_large_folder(1, 2000) |
| play_from_mp3_folder(t) | Play from the special /mp3 folder (up to 9999 tracks) | mp3.play_from_mp3_folder(1) |
ESP32 MicroPython Code — Serial Console Control
"""
* DIYables MicroPython Mini Mp3 Player - Serial Command Control
*
* Control the Mp3 player by typing commands in the serial console.
* Great for testing all functions without extra hardware.
*
* Commands (type in serial console, then press Enter):
* 1-9 Play track 1 to 9
* + Volume up
* - Volume down
* p Pause
* r Resume
* s Stop
* n Next track
* b Previous track (back)
* ? Show current status
*
* Product: DIYables Mini Mp3 Player Module
* https://diyables.io/products/mini-mp3-player-module
*
* Wiring (ESP32):
* Mini Mp3 RX -> ESP32 TX (GPIO17)
* Mini Mp3 TX -> ESP32 RX (GPIO16)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Raspberry Pi Pico):
* Mini Mp3 RX -> Pico TX (GPIO4)
* Mini Mp3 TX -> Pico RX (GPIO5)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Nano ESP32):
* Mini Mp3 RX -> D1 (GPIO43, TX)
* Mini Mp3 TX -> D0 (GPIO44, RX)
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* Wiring (Arduino Giga R1 WiFi):
* Mini Mp3 RX -> TX1
* Mini Mp3 TX -> RX1
* Mini Mp3 VCC -> 3.3V
* Mini Mp3 GND -> GND
* Speaker connected to SPK_1 and SPK_2 pins
*
* SD Card: Put mp3 files in root, named 001.mp3, 002.mp3, etc.
"""
import sys
import select
from machine import UART
import time
from DIYables_MicroPython_MiniMp3 import MiniMp3Player
# --- For ESP32 ---
uart = UART(2, baudrate=9600, tx=17, rx=16)
# --- For Raspberry Pi Pico (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=4, rx=5)
# --- For Arduino Nano ESP32 (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600, tx=43, rx=44)
# --- For Arduino Giga R1 WiFi (uncomment below, comment above) ---
# uart = UART(1, baudrate=9600)
mp3 = MiniMp3Player(uart)
time.sleep(1) # Wait for the module to initialize
mp3.set_volume(20)
print("=== DIYables Mini Mp3 Player ===")
print("Commands:")
print(" 1-9 Play track number")
print(" + Volume up")
print(" - Volume down")
print(" p Pause")
print(" r Resume")
print(" s Stop")
print(" n Next track")
print(" b Previous track")
print(" ? Show status")
print("================================")
poll = select.poll()
poll.register(sys.stdin, select.POLLIN)
while True:
events = poll.poll(100) # 100ms timeout
if events:
cmd = sys.stdin.read(1)
if cmd in '123456789':
track = int(cmd)
print("Playing track", track)
mp3.play(track)
elif cmd == '+':
print("Volume up")
mp3.volume_up()
elif cmd == '-':
print("Volume down")
mp3.volume_down()
elif cmd == 'p':
print("Paused")
mp3.pause()
elif cmd == 'r':
print("Resumed")
mp3.resume()
elif cmd == 's':
print("Stopped")
mp3.stop()
elif cmd == 'n':
print("Next track")
mp3.play_next()
elif cmd == 'b':
print("Previous track")
mp3.play_previous()
elif cmd == '?':
print("--- Status ---")
vol = mp3.get_volume()
print("Volume:", vol)
track = mp3.get_current_track()
print("Current track:", track)
playing = mp3.is_playing()
print("Playing:", "Yes" if playing else "No")
total = mp3.get_track_count()
print("Total tracks:", total)
print("--------------")
| Command | Effect |
|---|---|
| 1–9 | Play track |
| + / − | Volume |
| p / r / s | Pause / Resume / Stop |
| n / b | Next / Previous |
| ? | Status |
Equalizer Options
The module has a built-in DSP with six EQ presets. On the ESP32, you can switch EQ modes in real time — even while a track is playing. This is useful for IoT projects where users select audio profiles via a web interface or Bluetooth.
| Constant | ID | Sound Profile |
|---|---|---|
| EQ_NORMAL | 0 | Flat / neutral response |
| EQ_POP | 1 | Bright vocals and highs |
| EQ_ROCK | 2 | Punchy mids and lows |
| EQ_JAZZ | 3 | Warm, smooth tone |
| EQ_CLASSIC | 4 | Balanced across all frequencies |
| EQ_BASS | 5 | Heavy low-end boost |
import DIYables_MicroPython_MiniMp3.DIYables_MicroPython_MiniMp3 as mp3_const
mp3.set_eq(mp3_const.EQ_BASS) # Great for small speakers
Checking Module Status
Status queries send a request over UART2 and wait for the module's reply. They block for up to 100 ms (configurable with set_timeout()). If no response arrives, they return −1.
On the ESP32, you might use these in a web server handler or a periodic check loop — just keep in mind the brief blocking time.
| Function | Return | Description |
|---|---|---|
| is_playing() | bool | True if a track is currently playing |
| get_volume() | int | Current volume level (0–30) |
| get_eq() | int | Active equalizer preset (0–5) |
| get_track_count() | int | Number of tracks on the SD card |
| get_current_track() | int | Track number currently playing |
| get_folder_count() | int | Number of folders on the SD card |
| get_track_count_in_folder(f) | int | Number of tracks in folder f |