ESP32 S3 UNO - Mini Mp3 Player Module

Hardware Preparation

Or you can buy the following kits:

Overview of Mini Mp3 Player Module

It helps to know what the module can do before you write any code. Once you see its features, each example sketch below will feel easy.

The DIYables Mini Mp3 Player is a small mp3 decoder board with a YX5200-24SS chip on it. It reads mp3 files straight from a micro SD card. A built-in amplifier can drive a speaker of up to 3W. If you want a bigger sound, you can take a line-level signal from the DAC pins and feed it to an external amplifier.

The ESP32 S3 Uno talks to the module over UART at 9600 baud. You send a short command, and the module does the rest. You do not need to decode any audio on the board.

What it can do

You can play, pause, resume and stop tracks. The volume goes from 0 to 30, and there are six equalizer presets: Normal, Pop, Rock, Jazz, Classic and Bass.

Playback modes

The module can repeat one track, repeat a folder, or shuffle every track on the card. It also supports numbered folders, and it can interrupt the current song to play an advertisement track.

Status queries

You can ask the module for the current track, volume, play state and more. This is useful when you want to show the status on the Serial Monitor or a display.

Module Pinout

Most projects only use six pins: power, ground, the two UART pins and the two speaker pins. The other pins are there for extra options.

ESP32 S3 Uno Pinout

The image below shows the pinout of the ESP32 S3 Uno form board. Use it to find the Uno header pins (D2, D10, D11…) and their GPIO numbers while you wire the circuit.

Wiring Diagram

Power the module from the 5V pin and connect its UART pins to D10 and D11. The speaker goes straight to SPK_1 and SPK_2.

This image is created using Fritzing. Click to enlarge image

The ESP32 S3 Uno uses 3.3V logic, and its pins are NOT 5V tolerant. The YX5200 chip also works at 3.3V logic, even when VCC is 5V, so the signal on its TX pin is safe for D10 (GPIO10). Keep the 1K resistor on the RX line. It limits current and cuts the hiss and noise that this module often makes without it.

The button examples later in this tutorial add push buttons on D2 (GPIO18) and D3 (GPIO17). The other leg of each button goes to GND.

Preparing the SD Card

The module is picky about file names and file order. A few minutes spent here will save you a lot of confusion later.

1. Format the micro SD card as FAT16 or FAT32.
2. Copy your mp3 files to the root folder, with zero-padded names:

1. To play by folder, make numbered folders and put numbered files inside them:

Rules to remember

Track numbers start at 1, not 0. Folder names use 2 digits (01 to 99), and file names inside folders use 3 digits (001 to 255).

The module sets the track order by the order in which you copied the files, not by their names. So format the card first, and then copy the files one by one in the order you want.

Installing the Library

The DIYables_MiniMp3 library builds every command packet for you, so your sketch stays short. You install it once from the Library Manager.

1. Connect the board to your computer with a USB Type-C cable.
2. Open Arduino IDE, choose the ESP32S3 Dev Module board and the correct COM port.
3. Open the Library Manager by clicking the Libraries icon on the left side.
4. Search for "DIYables_MiniMp3" and find the library by DIYables.
5. Click Install to get the latest version.

• Search for DIYables_MiniMp3 created by DIYables and click the Install button.

The library has no other dependencies, so nothing else needs to be installed.

ESP32 S3 Uno Code - Play a Single Track

This is the simplest test, and a good first step to check your wiring. The sketch sets the volume to 25 and plays track 001.mp3 once.

Serial1 is started on GPIO10 (RX) and GPIO11 (TX) at 9600 baud, and the library uses it to talk to the module. The one-second delay gives the module time to read the SD card before the first command.

How To Run

1. New to the ESP32 S3 Uno? Follow ESP32 S3 Uno - Getting Started first.
2. Prepare the SD card with mp3 files (001.mp3, 002.mp3…) and put it in the module.
3. Wire it up as shown in the diagram.
4. Connect the board to your computer with a USB Type-C cable.
5. Open Arduino IDE, choose the ESP32S3 Dev Module board and the correct COM port.
6. Copy the code above and paste it into the Arduino IDE.
7. Click Upload to send the code to the ESP32 S3 Uno.
8. Listen: track 001.mp3 plays through the speaker.
9. Tip: If you hear nothing, open the Serial Monitor at 9600 baud and check that "Playing track 1..." appears. If it does, check the speaker wires and the SD card files.

Playback Functions at a Glance

These are the basic commands you will use most often.

ESP32 S3 Uno Code - Play Multiple Tracks in Sequence

Now you can build a small playlist. This sketch plays tracks 1 to 3 in a loop, with a fixed wait between them.

The sketch uses millis() instead of delay(), so loop() keeps running while it waits. Change totalTracks to match your card, and trackDuration to set the gap in milliseconds.

How To Run

1. Check the SD card: it needs at least 3 tracks (001.mp3, 002.mp3, 003.mp3).
2. Upload the code to the ESP32 S3 Uno.
3. Listen: tracks 1, 2 and 3 play in a loop, with 5 seconds between each start.
4. Tip: If your songs are longer than 5 seconds, raise trackDuration, or the next track will cut the current one short.

ESP32 S3 Uno Code - Volume Control with Buttons

Two push buttons let you turn the volume up and down while the music plays. Wire the UP button to D2 (GPIO18) and the DOWN button to D3 (GPIO17), with the other leg of each button to GND.

The buttons use INPUT_PULLUP, so they read LOW when pressed and need no external resistor. Each press changes the volume by one step, between 0 and 30, and a 200 ms delay acts as a simple debounce.

How To Run

1. Add the two buttons on D2 (GPIO18) and D3 (GPIO17), then upload the code.
2. Open the Serial Monitor at 9600 baud.
3. Press the buttons while track 1 repeats, and listen to the volume change.
4. Tip: Hold a button down to change the volume quickly, about 5 steps per second.

Volume Functions

You can set the level directly or step it up and down.

ESP32 S3 Uno Code - Next and Previous Track Buttons

With two buttons you can move through your playlist like on a real mp3 player. The NEXT button is on D2 (GPIO18), and the PREV button is on D3 (GPIO17).

The sketch starts with track 1. Each press calls playNext() or playPrevious() and prints the action to the Serial Monitor.

How To Run

1. Wire the NEXT and PREV buttons to D2 (GPIO18) and D3 (GPIO17).
2. Upload the sketch to the ESP32 S3 Uno.
3. Press the buttons to jump between tracks.
4. Tip: After the last track, playNext() goes back to the first track on the card.

ESP32 S3 Uno Code - Pause and Resume Toggle

One button is enough to pause and resume. Wire it to D2 (GPIO18).

A bool variable named paused remembers the current state. Each press calls pause() or resume() and then flips the variable.

How To Run

1. Wire a button to D2 (GPIO18), then upload the code.
2. Press the button once to pause the music.
3. Press it again to continue from the same spot.
4. Tip: If one press toggles twice, raise the 300 ms debounce delay a little.

ESP32 S3 Uno Code - Loop a Track

Sometimes you want one sound to repeat forever, like background music or an alarm. This sketch loops track 001.mp3 with the Normal equalizer.

The module handles the repeat by itself. After loopTrack(1), the ESP32 S3 Uno is free, so you can put your own code in loop().

How To Run

1. Upload the code to the ESP32 S3 Uno.
2. Listen: track 001.mp3 plays again and again.
3. Tip: Change EQ_NORMAL to EQ_ROCK or EQ_BASS to hear a different sound profile.

Repeat and Shuffle Functions

These functions control how the module repeats or mixes your tracks.

ESP32 S3 Uno Code - Play from a Folder

Folders help you sort sounds into groups, such as one folder for music and one for voice messages. This sketch plays tracks from folder 01 and then folder 02.

playFolder(folder, track) takes two numbers: the folder and the file inside it. The sketch waits 5 seconds between each track, and then stops.

How To Run

1. Set up the SD card with folders 01 and 02, each holding numbered files (001.mp3, 002.mp3).
2. Upload the sketch to the ESP32 S3 Uno.
3. Listen: folder 01 track 001, then folder 01 track 002, then folder 02 track 001.
4. Tip: If the wrong file plays, format the card and copy the files again in the right order.

Folder Playback Functions

Pick the function that fits the size of your sound library.

ESP32 S3 Uno Code - Serial Monitor Control

This is the best sketch for testing. You type one-letter commands in the Serial Monitor and control every feature without any buttons.

The sketch reads one character at a time and runs the matching command in a switch block. The "?" command asks the module for its volume, current track, play state and track count.

How To Run

1. Upload the code, then open the Serial Monitor at 9600 baud.
2. Type a command from the table below and press Enter.

1. Tip: Set the Serial Monitor line ending to "No line ending" so that only your command is sent.

Equalizer Modes

The equalizer changes the tone of the sound. The module has six presets, and you can switch between them with one line of code.

Querying Playback Status

Your ESP32 S3 Uno code can also ask the module what it is doing. This lets you react to the player, for example to start the next song only when the current one ends.

Each call waits up to 100 ms for the reply from the module. A return value of −1 means an error or a timeout.

FAQ

Why does the ESP32 S3 Uno code use Serial1 instead of SoftwareSerial?

The SoftwareSerial library does not exist for the ESP32 S3 Uno. The board has free hardware UART ports, so the code uses Serial1 and maps it to D10 (GPIO10) for RX and D11 (GPIO11) for TX. A hardware port is also more reliable than a software one.

Can I connect the mini mp3 player to D0 and D1 on the ESP32 S3 Uno?

It is better not to. D0 (GPIO44) and D1 (GPIO43) are used by the USB-serial port for uploads and the Serial Monitor. If the module is on these pins, uploads can fail and the Serial Monitor can show garbage. Keep the module on D10 and D11.

Is the mini mp3 player safe with the 3.3V pins of the ESP32 S3 Uno?

Yes. The YX5200 chip uses 3.3V logic, so its TX signal is safe for the ESP32 S3 Uno, even when the module is powered from 5V. Keep the 1K resistor on the module RX line to reduce noise.

Should I power the module from 3.3V or 5V?

The module works from 3.2V to 5V. Use 5V for a louder speaker and more stable sound. The 3.3V pin can work for quiet sound, but a speaker at high volume can pull too much current and cause resets or crackling.

Why does the wrong track play?

The module numbers tracks by the order in which they were copied to the card, not by their file names. Format the card and copy the files one by one in the order you want.

What if my project needs more buttons than the Uno headers give?

The ESP32 S3 Uno has two extra rows of holes with more GPIOs: GPIO15 and GPIO16 (I/O, PWM, analog), GPIO45 and GPIO35 to GPIO42 (I/O, PWM), and GPIO47/GPIO48 (output only, PWM). Solder pin headers to use them and write the GPIO number in your code. For extra buttons in this project, GPIO35 to GPIO42 or GPIO15/GPIO16 are good choices. Do not use GPIO47/GPIO48 for buttons, because they are output only. Also keep two warnings in mind. First, GPIO47 and GPIO48 may run at 1.8V instead of 3.3V on some modules (especially ones with "V" in the name, like R8V or R16V), so 3.3V devices can be damaged or act strangely. Second, GPIO0, GPIO3 (D6), GPIO45 and GPIO46 (D9) are boot strapping pins, and a wrong connection can stop the board from booting or uploading code. Use the other extra pins first.

Troubleshooting

Learn More

• ESP32 S3 UNO - MP3 Player
• ESP32 S3 UNO - Piezo Buzzer
• ESP32 S3 UNO - Buzzer