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