ESP32 MicroPython MP3 Player
This guide teaches you how to build an MP3 player using an ESP32 microcontroller with MicroPython, an MP3 player module, a Micro SD Card, and a speaker. The MP3 player plays songs or audio files stored on the Micro SD Card. The ESP32 controls the MP3 player module to choose and play tracks from the SD card, turn them into sound, and send the audio to the speaker. In detail, we will learn:
- How to connect a MP3 player and speaker to ESP32
- How to write the MicroPython code for ESP32 to play music from a micro SD Card
- How to include buttons for play, pause, next, and previous functions
Then, you can modify the code to add a potentiometer or rotary encoder to control the volume.
Hardware Preparation
| 1 | × | ESP-WROOM-32 Dev Module | |
| 1 | × | USB Cable Type-C | |
| 1 | × | Serial MP3 Player Module | |
| 1 | × | Micro SD Card | |
| 1 | × | 3.5mm Aux Speaker | |
| 1 | × | Jumper Wires | |
| 1 | × | (Recommended) Screw Terminal Expansion Board for ESP32 |
Or you can buy the following sensor kits:
| 1 | × | DIYables Sensor Kit (30 sensors/displays) | |
| 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.
Overview of Serial MP3 Player Module and Speaker
Serial MP3 Player Module Pinout
A serial MP3 player module has three main interfaces:
- ESP32 Interface:
- RX pin: Used to receive data. Connect this to the TX pin on your ESP32 using a Serial connection.
- TX pin: Used to send data. Connect this to the RX pin on your ESP32 using a Serial connection.
- VCC pin: Supplies power. Connect this to the 3.3V pin on your ESP32.
- GND pin: Ground pin. Connect this to a ground (0V) source.
- Speaker Interface:
- Comes with a 3.5mm Aux output female jack.
- Micro SD Card Interface:
- The Micro SD Card slot is located on the back of the MP3 module.
- Audio connection: It has a 3.5mm Aux male connector for connecting to an MP3 player.
- Power connection: It can connect to a USB, a 5V power adapter, or other power sources.
image source: diyables.io
Speaker Pinout
A speaker usually has two connection points:
How It Works
Here's what you need to do:
- Load a list of songs or recordings onto a Micro SD card.
- Insert the Micro SD card into the MP3 player module.
- Connect the MP3 player module to the ESP32.
- Hook up the MP3 player module to a speaker.
- Plug the speaker into a power source. If you uses headphone or earphone, you do not need to do this step.
Each MP3 file on the Micro SD card is numbered, starting from 0, which sets the order of the songs. We will write the MicroPython script for the ESP32 to send different commands to the MP3 player module. It supports commands are:
- Start Playing
- Stop
- Play Next Track
- Play Previous Track
- Adjust Volume
Once receiving the command, The MP3 player module plays the files stored on the Micro SD card, turns them into audio signals, and sends these signals to the speaker through the 3.5mm Aux jack.
Wiring Diagram
- How to connect ESP32 and mp3 player using breadboard
This image is created using Fritzing. Click to enlarge image
- How to connect ESP32 and mp3 player using screw terminal block breakout board
ESP32 MicroPython Code - Play Music
The code below begins to play the first song stored on the Micro SD Card.
"""
This ESP32 MicroPython code was developed by newbiely.com
This ESP32 MicroPython code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-mp3-player
"""
from machine import UART, Pin
import time
# Define constants
CMD_PLAY_NEXT = 0x01
CMD_PLAY_PREV = 0x02
CMD_PLAY_W_INDEX = 0x03
CMD_SET_VOLUME = 0x06
CMD_SEL_DEV = 0x09
CMD_PLAY_W_VOL = 0x22
CMD_PLAY = 0x0D
CMD_PAUSE = 0x0E
CMD_SINGLE_CYCLE = 0x19
DEV_TF = 0x02
SINGLE_CYCLE_ON = 0x00
SINGLE_CYCLE_OFF = 0x01
ESP32_RX = 16 # The ESP32 pin GPIO16 connected to the TX of the Serial MP3 Player module
ESP32_TX = 17 # The ESP32 pin GPIO17 connected to the RX of the Serial MP3 Player module
# Initialize UART with the correct pins and baud rate
mp3 = UART(1, baudrate=9600, tx=Pin(ESP32_TX), rx=Pin(ESP32_RX))
def mp3_command(command, dat):
frame = bytearray(8)
frame[0] = 0x7e # starting byte
frame[1] = 0xff # version
frame[2] = 0x06 # the number of bytes of the command without starting byte and ending byte
frame[3] = command #
frame[4] = 0x00 # 0x00 = no feedback, 0x01 = feedback
frame[5] = (dat >> 8) & 0xFF # data high byte
frame[6] = dat & 0xFF # data low byte
frame[7] = 0xef # ending byte
mp3.write(frame)
# Wait for the chip initialization to complete
time.sleep(0.5)
# Select the TF card
mp3_command(CMD_SEL_DEV, DEV_TF)
time.sleep(0.2) # wait for 200ms
# Play MP3
mp3_command(CMD_PLAY, 0x0000)
# mp3_command(CMD_PAUSE, 0x0000) # Pause mp3
# mp3_command(CMD_PLAY_NEXT, 0x0000) # Play next mp3
# mp3_command(CMD_PLAY_PREV, 0x0000) # Play previous mp3
# mp3_command(CMD_SET_VOLUME, 30) # Change volume to 30
# Main loop to keep the script running
while True:
time.sleep(0.1) # Prevent tight loop
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 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).
- 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.
- Enjoy the music
ESP32 MicroPython Code - Play Music with control buttons
This image is created using Fritzing. Click to enlarge image
The following code is an updated version of the previous one. It features four buttons that help you manage the MP3 player.
"""
This ESP32 MicroPython code was developed by newbiely.com
This ESP32 MicroPython code is made available for public use without any restriction
For comprehensive instructions and wiring diagrams, please visit:
https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-mp3-player
"""
from machine import UART, Pin
import time
from DIYables_MicroPython_Button import Button
# Define constants
CMD_PLAY_NEXT = 0x01
CMD_PLAY_PREV = 0x02
CMD_PLAY_W_INDEX = 0x03
CMD_SET_VOLUME = 0x06
CMD_SEL_DEV = 0x09
CMD_PLAY_W_VOL = 0x22
CMD_PLAY = 0x0D
CMD_PAUSE = 0x0E
CMD_SINGLE_CYCLE = 0x19
DEV_TF = 0x02
SINGLE_CYCLE_ON = 0x00
SINGLE_CYCLE_OFF = 0x01
ESP32_RX = 16 # The ESP32 pin GPIO16 connected to the TX of the Serial MP3 Player module
ESP32_TX = 17 # The ESP32 pin GPIO17 connected to the RX of the Serial MP3 Player module
# Initialize UART with the correct pins and baud rate
mp3 = UART(1, baudrate=9600, tx=Pin(ESP32_TX), rx=Pin(ESP32_RX))
# Initialize buttons using the Button library
button_play = Button(32) # The ESP32 pin GPIO32 for play
button_pause = Button(33) # The ESP32 pin GPIO33 for pause
button_next = Button(25) # The ESP32 pin GPIO25 for next
button_prev = Button(26) # The ESP32 pin GPIO26 for previous
# Set debounce time to 50 milliseconds for each button
button_play.set_debounce_time(50)
button_pause.set_debounce_time(50)
button_next.set_debounce_time(50)
button_prev.set_debounce_time(50)
def mp3_command(command, dat):
frame = bytearray(8)
frame[0] = 0x7e # starting byte
frame[1] = 0xff # version
frame[2] = 0x06 # the number of bytes of the command without starting byte and ending byte
frame[3] = command #
frame[4] = 0x00 # 0x00 = no feedback, 0x01 = feedback
frame[5] = (dat >> 8) & 0xFF # data high byte
frame[6] = dat & 0xFF # data low byte
frame[7] = 0xef # ending byte
mp3.write(frame)
# Wait for the chip initialization to complete
time.sleep(0.5)
# Select the TF card
mp3_command(CMD_SEL_DEV, DEV_TF)
time.sleep(0.2) # wait for 200ms
# Main loop to check buttons and send commands
while True:
# Update the state of each button
button_play.loop()
button_pause.loop()
button_next.loop()
button_prev.loop()
# Handle play button press
if button_play.is_pressed():
print("Play mp3")
mp3_command(CMD_PLAY, 0x0000)
# Handle pause button press
if button_pause.is_pressed():
print("Pause mp3")
mp3_command(CMD_PAUSE, 0x0000)
# Handle next button press
if button_next.is_pressed():
print("Play next mp3")
mp3_command(CMD_PLAY_NEXT, 0x0000)
# Handle previous button press
if button_prev.is_pressed():
print("Play previous mp3")
mp3_command(CMD_PLAY_PREV, 0x0000)
time.sleep(0.01) # Small delay to be gentle on the CPU
Detailed Instructions
- On Thonny IDE, navigate to the Tools Manage packages on the Thonny IDE.
- Search “DIYables-MicroPython-Button”, then find the Button library created by DIYables.
- Click on DIYables-MicroPython-Button, then click Install button to install Button library.
- Copy the above code and paste it to the Thonny IDE's editor.
- Save the script to your ESP32 board.
- Click the green Run button (or press F5) to run the script. The script will execute.
- Press the buttons one by one.
- Enjoy the music