ESP8266 DfPlayer Audio Player




Introduction: ESP8266 DfPlayer Audio Player

This is an mp3 audio player built from a esp8266 wifi module and a dfPlayer mp3 module. It plays files from a SD card.

I housed it in an old computer speaker and made it battery operated, but it could be built into any speaker enclosure.

Features include

  • 4 local buttons for standalone use (volume, simple selection)
  • Mobile browser interface with play controls and folder navigation
  • Mute control to allow headphone use
  • Easy set up via WifiManager
  • Over the air firmware updates
  • File browser for maintenance
  • dfPlayer up to 2W audio output to speaker (mono). Stereo to headphones

Step 1: Components and Tools Needed

The following parts are needed

  • ESP-12F wifi processing module
  • dfPlayer mp3 module with micro SD card holder
  • 18650 battery and holder
  • LIPO charger module
  • Push button switches x4
  • Power slide switch x 1
  • Voltage regulator using low drop out 3.3V chip (e.g. XC6203)
  • Scrap of circuit board to make regulator
  • 2.2K resistor
  • 10K resistor x 2
  • 47K resistor
  • 220 uF decoupling capacitor
  • Hook up wire
  • Loudspeaker + enclosure (e.g. computer speaker or old radio)
  • Headphone jack. May already be present on existing enclosure.
  • SD card (4GB recommended but almost any size can be used)

These can all be sourced for very modest amounts on sites like eBay

Tools needed

  • Drill and files to make holes in enclosure
  • Fine point soldering iron

The dfPlayer module can be tricky to mount as it needs to have external access to a slot for getting at the SD card. For enclosures that have a flat panel I have used a 3D printed bracket designed to hold the module securely up against the panel

Step 2: Schematic

The schematic is fairly simple.

A LIPO battery charge module is used to charge the battery.

The battery feeds the dfPlayer module directly and the ESP-12F via a 3.3V regulator.

The dfPlayer is controlled over a serial interface so 2 pins on the ESP-12F module support this.

4 push buttons are tied to the ESP-12F GPIO for standalone operation.

The speaker and headphone jack are directly supported by the dfPlayer module.

Step 3: Construction

The details of the mechanical construction will vary with the type of enclosure to be used. The example here used computer speaker unit. This had plenty of room inside for the modules and electronics.

The picture shows the completed view for this example. The USB, power switch, and push buttons are on the right hand side. The LIPO is mounted on the back. The ESP-12F module, headphone jack and dfPlayer are mounted on the left hand side. The battery was mounted on the back.

The general steps after working out a layout that suits your enclosure are

  • Drill and file out holes to take USB input, slide switch, 4 push buttons, headphone jack and slot for micro SD card. The SD card slot needs to be done carefully to line up with where the dfPlayer module will be mounted.
  • If wanting speaker mute to allow headphone operation then the dfPlayer needs a small modification as illustrated. There is a mute on the little amplifier on board but it is wired to ground via a 0 Ohm resistor. Remove this resistor and replace with 10K resistor. Solder a lead on the pad as shown. This is the mute which can then be controlled from the ESP-12F
  • Note you may want to flash the ESP-12F module first before the final mechanicall construction. See the software step.
  • Make up the 3.3V regulator on a piece of scrap strip board. There are only 2 components and it can be made to be wired and mounted on to the ESP-12F module.
  • Mechanically mount the push button switches, secure with glue and solder a ground loop through one side of all the switches.
  • Solder 4 flying leads onto the USB connector and mount it in the enclosure and secure with glue
  • Solder leads from battery holder through to LIPO charger and power slide switch. Glue charger and slide switch in enclosure.
  • Solder flying leads onto headphone jack, mount and glue in place.
  • Add the 2.2K resistor, the ADC divider and the CH/Up connection tot the ESP-12F module
  • Solder flying leads on to ESP-12F module for serial interface, the 4 GPIO buttons.
  • Mount the dfPlayer in place taking care that the slot has access for the SD card.
  • Complete wiring from the ESP12-F to power connections, push buttons, serial interface and mute control on the dfPlayer
  • Complete wiring of power, USB data pair, headphone jack and speaker to dfPlayer

Double check the power wiring!

Step 4: Software and Installation

The ESP software is written in the Arduino environment. Source code is available at The library that controls the dfPlayer is there. The other libraries required and listed there are standard modules.

The ino sketch does not need much changed although you will want to change the WifiManager and firmware update passwords.

Compile in a Arduino ESP8266 environment and do the first flash over the standard serial connection. Further updates can be done by exporting a binary file in the Arduino IDE and doing an OTA (over the air) update direct to the unit without any wires.

On first use the software will not have the local wifi credentials but instead will create an Access point itself called dfPlayerSet up. Connect to this (e.g. from a phone or tablet) and then browse to This will bring up an interface to allow selection of the real network and enter its password. From then on this will be used automatically.

There is a simple file uploader which should be used to load basic files to the SPIFFS filing system on the ESP-12F (edit.htm.gz, index.html, basic.htm, favicon*.png and graphs.js.gz. Access this by using http://ip/upload

From then on you can use http://ip/edit to upload further data in a friendlier fashion.

You can edit the index.htm to refer to different favicon file and give it a different title if required.

The favicon will be used if adding a shortcut to the screen on say a phone.

Step 5: SD Card Preparation

The dfPlayer plays back files directly from the SD card but it has a limited folder and file naming scheme.

To make it easier to use and to control a script is provided with the software that can support this naming but also allow the original names to be sued on the web interface.

To use mount the SD card onto a PC and copy across folder with tracks with their original naming (e.g. albums for folders and tracknames for files).

Run the script (dfPlayer-makeSD.vbs). It will prompt for the SD card volume. Change this as necessary. It will then rename all the folders and files on the SD card and create mapping files from the simplified naming back to the original names. Folders.txt contains a list of the folder numbers and names. Individual Track.txt file contain the mapping within each folder. Only the Folders.txt is needed at this stage. Software enhancements may use the track lists in the future.

The Folders.txt file needs to be uploaded to the ESP-12F SPIFFS file system via the /edit uploader.

Note that you can delete folders and add new ones. When you add a new one with original naming just run the script again. It will rename just th enew folders and files and rebuild the maps. The new FOlders.txt would need to be uploaded again.

Step 6: Standalone Operation

The 4 buttons work as follows.

  • Volume Up. Short press increments volume, Long press unmutes the speaker
  • Volume Down Short press decrements the volume. Long press mutes the speaker
  • Select1 Short Press increments the folder number to be played. Long press starts playing selected folder
  • Select2 Short Press decrements the folder number. Long Press starts playing random tracks

Step 7: Normal Browser Operation

This is accessed at http://ip (index.htm default)

It brings up a simple web interface with a volume slider and a set of play controls

  • Pause
  • Play
  • Random
  • Stop
  • Skip to Next
  • Skip to Previous
  • UnMute Speaker
  • Mute Speaker

Below this is a set of buttons one per folder on the card populated with their original names. Clicking on one of these will start playing that folder.

Step 8: Basic Browser Operation

A simplified browser interface may be used primarily for test purposes. This is accessed at http://ip/basic.htm

It allows selection of the command and its parameters to send to the software.

These commands are sent to the ESP12-F using


The commands available are

  • ?cmd=play&p1=folder&p2=track
  • ?cmd=playmp3&p1=track
  • ?cmd=volume&p1=level (0-30)
  • ?cmd=stop
  • ?cmd=volumeup
  • ?cmd=volumedown
  • ?cmd=speaker&p1=offon (0/1)
  • ?cmd=pause
  • ?cmd=start
  • ?cmd=next
  • ?cmd=previous
  • ?cmd=mode&p1=type
  • ?cmd=loopFolder&p1=folder
  • ?cmd=random
  • ?cmd=eq&p1=type
  • ?cmd=device&p1=type
  • ?cmd=setting&p1=setting1&p2=setting2
  • ?cmd=sleep
  • ?cmd=reset
  • ?cmd=raw&p1=cmdcode&p2=par1&p3=par2
  • ?cmd=init

http://ip/dfPlayerStatus gives some basic status of the player including battery voltage

Be the First to Share


    • First Time Author Contest

      First Time Author Contest
    • Build a Tool Contest

      Build a Tool Contest
    • Eggs Challenge

      Eggs Challenge



    Question 4 days ago

    Hello the skech doesn't work,
    many errors in BaseSupport.h such as
    expected unqualified-id before´<´ token or stray '#' in program, it
    is possible to relay with 1 second delay the speakers and
    does it also work with the ESP32?


    Reply 3 days ago

    I have just compiled this under Arduino without any errors.

    Please give details of some of the errors you see and also how you are compiling.

    I do not understand relay with 1 second delay. Please clarify.

    It should be fairly straightforward to port it to ESP32 but some of the libraries have different names so some changes would be needed.


    2 years ago

    • Thank you for the project, how do I make it work with the router turned off??


    Reply 2 years ago

    There are 3 answers to this depending on what you want to do.

    a) If you want to always use this without a router but still use the browser interface then you need to change the way the wifi set up works so that it puts the ESP8266 into Access Point mode. That way you can access the device by connecting your browser device to the network set up by the player. To do this you need to change the call to the wifiConnect routine in set up to instead just put the device in AP mode. This is just a couple of simple instructions (search for ESP8266 AP mode).

    b) If you want to normally use this with a router but want to use the local buttons if the router is not available then remove the call to wifiConnect in the loop so that it only tries once to make the router connection in the call to wifiConnect from setup. You might want to reduce the timeout it spends allowing the AP to configure the network from its current 3 minutes.

    c) If you want to always use this from local buttons without a router then you can remove all calls to wifiConnect.


    Reply 10 months ago

    Just wanted to drop a reply about option A here. I tested that and there are some issues with it that people need to be aware of. The html pages use external JS libraries that are loaded from the internet, so if you go with AP mode, your phone/other connected device won't be able to load and use them. You should still be able to send commands directly or use the /basic.htm option, but /edit and the index.html pages won't work. Also, the performance was incredibly slow vs using an external router. My suggestion is to set up your phone as a hotspot and tell the ESP8266 to connect to that, instead of having the ESP go into AP mode.

    EDIT: One more tip, if you are using android device and go with the phone AP option, you can use the command "ip neigh" on your phone to get a list of the IP addresses of all of the connected devices so you know what to put in your browser/command. I'm currently looking into a way to set a hosename for dfplayer so you could just use http://dfplayer.local/ or something like that instead of having to find the IP.


    Reply 10 months ago

    Note that you can download the external files then upload them to the es8266 filing system then change the curls in index page to get them from there.


    Reply 10 months ago

    Ah good, glad to know that works! I hadn't downloaded the external libraries yet and was worried that the filesystem may not have enough space.


    Question 10 months ago

    So I have this all set up and running but I think something may be broken or it may be that I am expecting something that isn't implemented. My overall goal is to create shortcuts on my phone's home screen that send commands to http://ip/dfplayer and trigger specific MP3 files when I press them. I can't seem to get the "play" or "playmp3" commands to work at all (random, track forward, etc all work). Either using the basic.htm page play command or direct command calls to http://IP/dfplayer, neither seems to work with those two play commands. If I send a request to /dfplayer to just call "play" with no parameters, it will play the first file in the folder, but if I send params, nothing plays at all. Is there something I need to be doing first, or is there a reference for exactly how the command should look? I tried sending p1 as a string, as an int, i tried sending the string as both "1" and "01" and for p2 i tried things like 1,"1","001","001.mp3" and nothing seemed to work. Same issue with the basic.htm page, i can't seem to get the "play" command to do anything.

    EDIT: As another note, I was looking at the reference page for the dfplayer chip ( and don't see a reference to the 0x12 command that you use for playMp3Folder. Is there a better ref doc I should be looking at?


    Question 1 year ago

    Is there a full walkthrough on how to set this up with an ESP8266 in AP mode? The general directions on this it’s confusing for a new person.


    Answer 1 year ago

    Do you mean you want to use it on a separate network provided by the ESP8266 itself and then log on to that network from your phone or tablet?

    If so then the overall method is indicated in the reply to sergevn below (method a). I can try to add more detail on the changes needed if that is what you want..


    1 year ago

    I try to make it with a mini NodeMCU but i have a fail compilation.
    "Arduino\libraries\BaseSupport-master/BaseSupport.h:125:14: error: 'class WiFiManager' has no member named 'setFastConnectMode'
    I find the librarie WIFImanager but i don't know if it is actualy the good way to rebuild this project.
    Thank you for your help, see you.


    Reply 1 year ago

    There is a branch of WifiManger called feature_fastconnect that does support the setFastConnectMode call. What this does is reduce the connect time to the wifi network from about 3 seconds to less than 1 second. The standard master branch doesn't have that in yet.

    If you want to use the standard wifiManager then just change comment out the #define FASTCONNECT in BaseConfig which will prevent that call being made.


    2 years ago

    Would it be possible to get a listing of what the song directory looks like before and after running the script. I'm trying to get my head around the transformation of the filenames. Also what the content of the folders.txt files are?


    Reply 2 years ago

    The dfplayer module expects folders to be numbered 00,01,02,... and tracks within the folder to be 001.mp3,002.mp3,003.mp3...

    So the script expects to start from a collection of folders (albums or equivalent) each of which contains a set of tracks (mp3 files). The name of each folder should name the 'album' and the track filenames should name the track.

    The script processes each folder and renames the tracks within it to be 001.mp3,002.mp3 etc. It also creates a tracks.txt within that folder listing the original names together with their new track number. Each folder is renamed to be 00,01 etc and a folders.txt file is produced containing the original name of the folder and its new number.

    The web site uses the folders.txt file to produce the list of 'albums' which may be played and when one is selected then its folder number is used to select the correct one.

    There are host functions to play a particular track but the current client just plays folders and allows skipping tracks.


    Reply 2 years ago

    Thanks for the reply. I think I get it now.


    Question 3 years ago on Introduction


    Great project. The donwload contains design circuit?


    Answer 3 years ago

    The Github download contained a jpg of the schematic. I hav enow added the fritzing source file for this.


    Reply 3 years ago

    thank you