This is a guide on how to interface the YX5300 / YX6300 Serial MP3 Music Player Module with the ESP32 programmed with Arduino IDE. You’ll learn how to wire the MP3 player to the ESP32 and play sounds and music tracks from.mp3/.wav files that are stored in a MicroSD card. As a project example, we’ll also show you how to build an MP3 audio player with button controls and a volume knob.
Table of Contents
In this tutorial, we’ll cover the following topics:
- Introducing the YX5300 / YX6300 Serial MP3 Music Player Module
- Wiring the YX5300 / YX6300 Serial MP3 Music Player to the ESP32
- Preparing the MicroSD Card
- Connecting Headphones or Speakers to the YX5300 Module
- Installing the YX5300 for ESP32 Library (YX6300 compatible)
- Testing the YX5300 / YX6300 MP3 Player (Play Sound)
- Troubleshooting the YX5300 / YX6300 MP3 Player Module
- PROJECT: YX5300 / YX6300 MP3 Player with Button Controls and Volume Knob
Introducing the YX5300 / YX6300 Serial MP3 Music Player Module
The YX5300 / YX6300 is a low-cost Serial (UART) MP3 music player module that can be interfaced with microcontrollers (such as the ESP32, ESP8266, or Arduino) to play .mp3 or .wav files stored on a MicroSD card by sending serial commands.
Where to Buy?
You can check our Maker Advisor Tools page to compare the YX5300 / YX6300 module price in different stores:
Wiring the YX5300 / YX6300 Serial MP3 Music Player to the ESP32
Wiring the MP3 player to the ESP32 is quite simple, as it only requires two serial pins: RX and TX.
| YX5300 / YX6300 | ESP32 |
| TX | GPIO 16 (UART 2 RX) |
| RX | GPIO 17 (UART 2 TX) |
| VCC | VIN (5V) |
| GND | GND |
According to the product specifications in the manual, the VCC works with voltages between 3.2V-5.2V. According to our testing, it works most reliably when connected to 5V (VIN).
* you can use any other RX/TX GPIOs. Check the ESP32 Pinout Guide:
- ESP32 Pinout Reference: Which GPIO pins should you use?
- ESP32-S3 DevKitC Pinout Reference Guide: GPIOs Explained
You may also like: ESP32 UART Communication (Serial): Set Pins, Interfaces, Send and Receive Data (Arduino IDE).
We’ll connect the RX pin to GPIO 17, and the TX pin to GPIO 16.
Important: in all projects that use serial commands, you need to connect the pins TX-RX and the RX-TX. However, if the code is not running properly (not sending/receiving serial commands), you might need to swap the wiring and connect RX-RX and TX-TX. One of our Serial MP3 players came with the wrong labels on the module, and the only way it worked was connected with TX-TX and RX-RX.
Preparing the MicroSD Card
The YX5300 MP3 player has a microSD card slot where you can insert a microSD card to store your .mp3 or .wav files. Here are the main specifications that the module supports.
| YX5300 | Value |
| Supported MicroSD Cards | MicroSD <= 32GB |
| Card Format | FAT16 / FAT32 |
| Track Formats | .mp3 / .wav |
| Frequencies | 8-48 kHz |
Before proceeding with the tutorial, make sure you format your microSD card as FAT32. Follow the next instructions to format your microSD card or use a software tool like SD Card Formater (compatible with Windows and Mac OS).
1. Insert the microSD card into your computer. Go to My Computer and right-click on the SD card. Select Format as shown in the figure below.
2. A new window pops up. Select FAT32, press Start to initialize the formatting process and follow the onscreen instructions.
3. In order to play music tracks, you must have folders and your files named correctly, so the MP3 module can access them. Here’s an example of the folder and filename structure:
01/
001xxx.mp3
002xxx.mp3
003xxx.mp3
02/
004xxx.mp3
005xxx.mp3
03/
006xxx.mp3
007xxx.mp3
008xxx.mp3Your folders must have 2-digits and each tracks needs to start with 3-digit. Each track name must be unique. Note: there is a maximum of 99 folders with 255 songs in each folder.
Example, start by creating 2 folders in your microSD card (name your folders: 01 and 02):
4. Copy .mp3 or .wav files, starting with 001, 002, and 003. The file names must be sequencial and start with 3-digits.
5. Finally, remove the microSD card from you computer and attach it to the YX5300 module.
You can click here to download a .zip folder with the royalty free music files used for this project.
Connecting Headphones or Speakers to the YX5300 Module
The YX5300 doesn’t come with any headphones or speakers, but you can use some heaphones similar to the ones illustrated in the image below and plug them into the module headphone jack.
Installing the YX5300 for ESP32 Library (YX6300 compatible)
There are several libraries to interface the YX5300 serial module with the ESP32. We’ll use the YX5300_ESP32 library by bluejunimo (even though the library is called YX5300 for ESP32, it’s also fully compatible with the YX6300 MP3 module without any additional changes).
You can install the library via the Arduino IDE library Manager. Search for YX5300 for ESP32 and install the library by bluejunimo.
Preparing Arduino IDE
We’ll program the ESP32 board using Arduino IDE. So, make sure you have the ESP32 add-on installed. Follow the next tutorial:
If you prefer using VSCode + PlatformIO, follow the next tutorial instead:
Testing the YX5300 / YX6300 MP3 Player (Play Sound)
The following code is the one provided by the library to test the MP3 player module. You’ll test if the module is working if you can hear the audio files being played in the headphone or speaker.
/*********
Rui Santos & Sara Santos - Random Nerd Tutorials
Complete project details at https://RandomNerdTutorials.com/esp32-yx5300-yx6300-mp3-player-arduino/
Example based on the library example by bluejunimo https://github.com/bluejunimo/YX5300_ESP32/
*********/
#include <YX5300_ESP32.h>
// Connect to YX5300 Serial pins (RX and TX)
#define RX 16
#define TX 17
// mp3 object
YX5300_ESP32 mp3;
void setup() {
// Initialize connection with the YX5300/YX6300 module
mp3 = YX5300_ESP32(Serial2, RX, TX);
// Shows the hex commands being sent to the mp3 device (includes helpful errors)
Serial.begin(115200);
mp3.enableDebugging();
// Plays the first track stored on the microSD Card (Track Formats .mp3/.wav | Frequencies 8-48 kHz)
// MicroSD Card folder and file structure, example folder name 01 and file name 001xxx.mp3:
// 01/001xxx.mp3 01/002xxx.mp3 01/003xxx.mp3 02/004xxx.mp3
mp3.playTrack(1);
}
void loop() {
// put your main code here, to run repeatedly:
}
How the Code Works
Let’s break down how the code works.
Include YX5300_ESP32 library
First, you need to include the YX5300_ESP32.h library created by bluejunimo that will make it very easy to interface with the MP3 player module
#include <YX5300_ESP32.h>Initialize the YX5300
Set the YX5300 RX and TX pins and create an object for the module called mp3.
#define RX 16
#define TX 17
YX5300_ESP32 mp3;setup()
In the setup(), start by initializing the module with the a specific Serial channel.
mp3 = YX5300_ESP32(Serial2, RX, TX);Recommended reading: ESP32 UART Communication (Serial): Set Pins, Interfaces, Send and Receive Data (Arduino IDE).
Enable the Serial communication and MP3 debugging, so you can see the hex serial commands being sent to the device. With debugging enabled, you will also see helpful errors.
Serial.begin(115200);
mp3.enableDebugging();You can quickly play the first track stored on the microSD Card using the following command:
mp3.playTrack(1);Demonstration
Upload the previous code to your ESP32 board. It will play the first track stored in the microSD card. Your serial monitor should be printing a similar message:
If you have the headphones or speaker plugged into the headphone jack, you should be hearing the first track stored in your microSD card. If you are experiencing any issues, follow the next troubleshooting section.
Troubleshooting the YX5300/YX6300 MP3 Player Module
If you uploaded the previous code, but you can’t hear any sound with the YX5300/YX6300 MP3 Player Module it can be one of these following issues.
- Wiring error: in all projects that use serial commands, you need to connect the pins TX-RX and the RX-TX. However, if the code is not running properly (not sending/receiving serial commands), you might need to swap the wiring and connect RX-RX and TX-TX. One of our Serial MP3 players came with the wrong labels on the module, and the only way it worked was connected with TX-TX and RX-RX;
- Not enough power: according to the product specifications in the manual, the VCC is works with voltages between 3.2V-5.2V. According to our testing, it works most reliably when connected to 5V (VIN);
- MicroSD card issue: your microSD must be equal or less than 32GB and formated with FAT16 / FAT32. The track formats must be in an .mp3 / .wav files with 8-48 kHz frequencies;
- Wrong folder structure / filenames: your microSD card folder and file structure is incorrect, example folder and filenames: 01/001xxx.mp3 01/002xxx.mp3 01/003xxx.mp3 02/004xxx.mp3;
- Issue headphones/speaker: we recommend testing your headphones/speakers in another device to make sure they are working.
YX5300 / YX6300 MP3 Player with Button Controls and Volume Knob
As a project example, we’ll show you how to build an MP3 player with button controls and a volume knob. Having the Arduino IDE prepared with the library installed and the microSD card inserted in the YX5300 module with the correct folders and files described earlier, you can continue following this guide.
Parts Required
- ESP32 Board (model of your choice)
- YX5300 / YX6300 Serial MP3 Music Player
- MicroSD Card
- Headphones / Speaker with plug
- 3x Pushbuttons
- 1x Potentiometer
- Jumper Wires
- Breadboard
You can use the preceding links or go directly to MakerAdvisor.com/tools to find all the parts for your projects at the best price!
Schematic Diagram
Wiring the MP3 player to the ESP32 is quite simple, as it only requires two serial pins: RX and TX.
| YX5300 / YX6300 | ESP32 |
| TX | GPIO 16 (UART 2 RX) |
| RX | GPIO 17 (UART 2 TX) |
| VCC | VIN (5V) |
| GND | GND |
According to the product specifications in the manual, the VCC is works with voltages between 3.2V-5.2V. According to our testing, it works most reliably when connected to 5V (VIN).
| Potentiometer/Pushbuttons | ESP32 |
| Potentiometer | GPIO 4 |
| Play/Pause Pushutton | GPIO 5 |
| Previous Track Pushbutton | GPIO 18 |
| Next Track Pushbutton | GPIO 19 |
Wire all the components to your ESP32 using the previous tables or by following the schematic diagram below.
MP3 Player Code
Upload the following code to turn your ESP32 into an MP3 audio player device.
/*********
Rui Santos & Sara Santos - Random Nerd Tutorials
Complete project details at https://RandomNerdTutorials.com/esp32-yx5300-yx6300-mp3-player-arduino/
*********/
#include <YX5300_ESP32.h>
// Connect to YX5300 Serial pins (RX and TX)
#define RX 16
#define TX 17
// Global variables for the pushbuttons
const uint8_t pinBtnPlay = 5;
const uint8_t pinBtnPrev = 18;
const uint8_t pinBtnNext = 19;
// Bool variable to track if the audio is playing or paused
volatile bool isPlaying = true;
// Variables for debouncing the pushbuttons
const unsigned long DEBOUNCE_DELAY = 500; // in milliseconds
volatile unsigned long lastPressTime = 0;
// Analog input pin the potentiometer is attached to
const uint8_t potVolume = 4;
// Auxiliary volume variables
#define MIN_VOLUME 0
#define MAX_VOLUME 30
int current_volume = 0;
// mp3 object
YX5300_ESP32 mp3;
// Play/Pause Button Interrupt Service Routine (ISR)
void ARDUINO_ISR_ATTR buttonPlay() {
unsigned long now = millis();
if (now - lastPressTime > DEBOUNCE_DELAY) {
if(isPlaying) {
mp3.pause();
isPlaying = false;
}
else {
mp3.resume();
isPlaying = true;
}
}
lastPressTime = now;
}
// Previous Track Button Interrupt Service Routine (ISR)
void ARDUINO_ISR_ATTR buttonPrev() {
unsigned long now = millis();
if (now - lastPressTime > DEBOUNCE_DELAY) {
mp3.prev();
isPlaying = true;
}
lastPressTime = now;
}
// Next Track Button Interrupt Service Routine (ISR)
void ARDUINO_ISR_ATTR buttonNext() {
unsigned long now = millis();
if (now - lastPressTime > DEBOUNCE_DELAY) {
mp3.next();
isPlaying = true;
}
lastPressTime = now;
}
void setup() {
// Init pushbuttons with internal pullup resistor
pinMode(pinBtnPlay, INPUT_PULLUP);
pinMode(pinBtnPrev, INPUT_PULLUP);
pinMode(pinBtnNext, INPUT_PULLUP);
// Set interrupts ISR functions
attachInterrupt(pinBtnPlay, buttonPlay, HIGH);
attachInterrupt(pinBtnPrev, buttonPrev, HIGH);
attachInterrupt(pinBtnNext, buttonNext, HIGH);
// Initialize connection with the YX5300/YX6300 module
mp3 = YX5300_ESP32(Serial2, RX, TX);
// Shows the hex commands being sent to the mp3 device (includes helpful errors)
Serial.begin(115200);
mp3.enableDebugging();
// Plays the first track stored on the SD Card (Track Formats .mp3/.wav | Frequencies 8-48 kHz)
// SD Card folder and file structure, example folder name 01 and file name 001xxx.mp3:
// 01/001xxx.mp3 01/002xxx.mp3 01/003xxx.mp3 02/004xxx.mp3
mp3.playTrack(1);
}
void loop() {
// Read the potentiometer's value
int raw_value = analogRead(potVolume);
// Map the value to the min/max of the mp3 device's volume values
int new_volume = map(raw_value, 0, 4095, MIN_VOLUME, MAX_VOLUME);
// Change the volume if the pot position has changed
if(new_volume != current_volume) {
// Update the mp3 device's volume
mp3.setVolume(new_volume);
// Update the current volume with the new volume
current_volume = new_volume;
}
}
How the Code Works
Let’s take a look at how the code works so that you can understand how to use the YX5300 serial commands, interrupts to trigger the button commands and potentiometer to adjust the volume.
Include YX5300_ESP32 library
First, you need to include the YX5300_ESP32.h library created by bluejunimo that will make it very easy to interface with the MP3 player module
#include <YX5300_ESP32.h>Initialize the YX5300
Set the YX5300 RX and TX pins and create an object for the module called mp3.
#define RX 16
#define TX 17
YX5300_ESP32 mp3;Variables
Create some global variables for the pushbuttons GPIOs and potentiometer.
const uint8_t pinBtnPlay = 5;
const uint8_t pinBtnPrev = 18;
const uint8_t pinBtnNext = 19;
const uint8_t potVolume = 4; Define a bool variable to track if the audio is playing or paused.
volatile bool isPlaying = true;These next two variables are used for debouncing the pushbuttons.
const unsigned long DEBOUNCE_DELAY = 500; // in milliseconds
volatile unsigned long lastPressTime = 0;Finally, you need these variables to check the min/max volume and store the courrent volume according potentiometer position.
#define MIN_VOLUME 0
#define MAX_VOLUME 30
int current_volume = 0;setup()
In the setup(), initialize the pushbuttons as inputs and set them as interrupts to detect changes on their states.
pinMode(pinBtnPlay, INPUT_PULLUP);
pinMode(pinBtnPrev, INPUT_PULLUP);
pinMode(pinBtnNext, INPUT_PULLUP);
attachInterrupt(pinBtnPlay, buttonPlay, HIGH);
attachInterrupt(pinBtnPrev, buttonPrev, HIGH);
attachInterrupt(pinBtnNext, buttonNext, HIGH);Learn more about ESP32 interrupts: ESP32 GPIO Interrupts with Arduino IDE.
Then, initialize the module with a specific Serial channel.
mp3 = YX5300_ESP32(Serial2, RX, TX);Enable the Serial communication and MP3 debugging, so you can see the hex serial commands being sent to the device. With debugging enabled, you will also see helpful errors.
Serial.begin(115200);
mp3.enableDebugging();You can quickly play the first track stored on the microSD Card using the following command:
mp3.playTrack(1);Button Interrupts
Create 3 interrupt functions that are instantly called when the play/pause, previous track, and next track pushbuttons are pressed.
void ARDUINO_ISR_ATTR buttonPlay() {
unsigned long now = millis();
if (now - lastPressTime > DEBOUNCE_DELAY) {
if(isPlaying) {
mp3.pause();
isPlaying = false;
}
else {
mp3.resume();
isPlaying = true;
}
}
lastPressTime = now;
}Depending on the pushbutton that was pressed, a specific function will run. These are the 4 main methods that control the MP3 player, and their names are pretty self-explanatory:
mp3.resume();
mp3.pause();
mp3.prev();
mp3.next();loop()
In the loop(), you constantly read the current potentiometer volume.
int raw_value = analogRead(potVolume);Then, if the volume has changed (increased or decreased), you adjust the volume.
int new_volume = map(raw_value, 0, 4095, MIN_VOLUME, MAX_VOLUME);
if(new_volume != current_volume) {
mp3.setVolume(new_volume);
current_volume = new_volume;
}MP3 Player Demonstration
Upload the previous code to your ESP32 board with all the components wired. It will play the first track stored in the microSD card (you can click here to download a .zip folder with the royalty free music files used for this project).
In your Arduino IDE serial monitor, you should see similar messages when you press the pushbuttons.
Check if everything is working:
- First pushbutton plays the track or pauses the track;
- The second pushbutton returns to the previous track;
- The third pushubtton skpis to the next track;
- Finally, you can move the potentiometer knob to adjust the volume.
Watch the next video for a project live demonstration.
Wrapping Up
This was a comprehensive guide on how to interface the YX5300/YX6300 MP3 Player with the ESP32. It can be quite useful to play sounds or music with your ESP32 board. Additionally, you can add any sensor to your project so that the ESP32 starts playing audio when a certain condition is met.
We hope you’ve found this guide useful. We have other guides that might be helpful:
- ESP32 with NEO-M8N GPS Module: GPS Logger and Display on Google Earth
- ESP32 with APDS9960 Proximity, Light, RGB, and Gesture Sensor
- Getting Started with ESP32 Cheap Yellow Display Board
- ESP32: Free Guides for Sensors and Modules
To learn more about the ESP32, make sure to check out our resources:
