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:

Then, you can modify the code to add a potentiometer or rotary encoder to control the volume.

ESP32 MicroPython mp3 player

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×Breadboard
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.

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.
    Serial MP3 Player Module Pinout
    image source: diyables.io

    Speaker Pinout

    A speaker usually has two connection points:

    • 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.

How It Works

Here's what you need to do:

  1. Load a list of songs or recordings onto a Micro SD card.
  2. Insert the Micro SD card into the MP3 player module.
  3. Connect the MP3 player module to the ESP32.
  4. Hook up the MP3 player module to a speaker.
  5. 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
The wiring diagram between ESP32 MicroPython MP3 player module

This image is created using Fritzing. Click to enlarge image

How to connect ESP32 and mp3 player

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

The wiring diagram between ESP32 MicroPython MP3 player speaker

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.
ESP32 MicroPython 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

Video Tutorial

Learn More

※ OUR MESSAGES

  • As freelancers, We are AVAILABLE for HIRE. See how to outsource your project to us
  • Please feel free to share the link of this tutorial. However, Please do not use our content on any other websites. We invested a lot of effort and time to create the content, please respect our work!