Sparkfun MP3 Shield Arduino Library

Posted in Arduino Libraries by Bill
28 Jan 2012

The Sparkfun MP3 Player Shield for Arduino is a inexpensive and easy way to add MP3 playback capability to your Arduino project. But it was lacking an easy to use Arduino Library to go along, so I fixed that. Introducing the SFEMP3Shield library just for this shield. Now playing an MP3 files is as easy as MP3player.playTrack(5); and all the work is done behind the scenes.

Most of this library comes from the existing example code, with the major new feature of being interrupt driven. So no need to worry about feeding the MP3 chip, whenever it’s ready for more the library will be ready to feed it. This allows the Arduino to perform other tasks while music is playing. The most basic use of the library is as follows:


#include <SPI.h>
#include <SdFat.h>
#include <SdFatUtil.h> 
#include <SFEMP3Shield.h>

SdFat sd;
SFEMP3Shield MP3player;

void setup() {


  //start the shield
  sd.begin(SD_SEL, SPI_HALF_SPEED);

  //start playing track 1

//do something else now
void loop() {

  Serial.println("I'm bored!");


That’s all it takes to get your Arduino to play an MP3 file using the shield.  How easy is that?

The library does have more functions and even error reporting. All of which can be found in the ReadMe file or in the Example Sketch included with the Library.

Source Code available on GitHub project pages: Sparkfun MP3 Player Shield Arduino Library

Or Direct Download here.

Using the SPI bus for something else as well?

I added some functions to make sure there will be no data collisions on the SPI bus caused by the MP3 decoder asking for more data at the wrong time. You need to wrap any SPI code you add to your project with these two functions. Here’s an example from my project that also has a shift register on the SPI bus:

  //disable interrupts to avoid collisions on the SPI bus between this code //and the MP3player library

  //shift data
  tempIO = SPI.transfer(HIBYTE(output));
  tempIO = SPI.transfer(LOBYTE(output));

  //latch output on shift registers

  //enable interrupts

But you can’t stop the data stream to the MP3 Shield for too long before it runs out of data so be careful and try not to do too much stuff in between the functions.


Wanna be your own DJ?

New features! Requested in the comments below, there are now functions to skip around a playing track. You could fast forward, rewind, create loops, etc.

Here’s an example that will just open a file, jump to the 30 second mark (measured in milliseconds, 30 seconds = 30000 ms), and loop the song back every 750 ms:


for(;;) {

If you want to know where you are in the current playback, do this:

time = MP3player.currentPosition();

Both functions are not super accurate and depend on the bitrate of the file. The library should auto-detect the bitrate of the file but may fail on some MP3 files. If that happens, you have to set the bitrate manually like this:


I can already see the cool DIY DJ equipment that could be made with this. Let me know if you have problems, and comment below if you ever make something cool with the library.


Pulled from the GitHub Project Page

The below is a list of basic questions to ask when attempting to determine the problem.

  • Did it initially PRINT the available RAM and Full Help Menu?
    • The MP3Shield_Library_Demo.ino example should initially provide a opening print indicating the amount of available SRAM and full menu help. If you don’t see this the problem is between your Target and IDE. And likely not this library
    • Is Serial Monitor set to the correct tty or com port and 115200 baud rate? Did you change the baud rate?
    • Reset the Arduino after Serial Monitor is open or send any key. It may have printed these prior to the Serial Monitor being started.
  • WHAT is the Error reported?
    • Is the Error Code is indicating a file problem.
    • Are the filenames 8.3 format? See below warning.
    • See also Error Codes
  • Did the SdCard LOAD?
    • Try reseating your SdCard.
  • Is it FAT(FAT16 or FAT32)?
    • If the Error Code is indicating problems with the INIT, VOLUME or Track not being successful. It is recommend to use SdFat Example Library’s QuickStart.ino as to see if it can access the card. Additionaly, SdInfo.ino may indicate if it can mount the card. Which may then need to formatted in FAT16 or FAT32. Where SdFormatter.ino can do this for you.
  • Are the needed files on the root?
    • Remember to put patch and audio track files on the SdCard after formatting.
    • Are the filenames 8.3 format? See below warning.
  • "Error code: 1 when \b trying to play track"
    • See the above Limitations. about Non-Blocking.
    • Remember to check your audio cables and volume.
  • Why do I only hear1 second of music, or less?
    • This symptom is typical of the interrupt not triggering the SFEMP3Shield::refill(). I bet repeatidly sendnig a track number will advance the play about one second at a time, then stop.
    • What board is it? Check Hardware Limitations. about Interrupts.
    • Are you trying the SFE provided test files ? Or some homemade mp3 files? The SFE test files are nice as they are Immediately LOUD.
    • Interrupt problems may cause mp3 files that have a quiet lead in (or ramp up of volume) to be falsely diagnosed as not playing at all. Where the first 1 second may not be loud enough to be heard.
  • Free RAM = 1090 Should be a base line of 1094
    • As a courtesy and good practice the provided example MP3Shield_Library_Demo.ino prints out the available remaining RAM, not statically allocated. And the actual available amount may depend on specific processor, IDE version, libraries and or other factors. A Uno built with IDE version 1.0.2 should have approximately 1094 bytes available from the example as is. And a Mega using a 2560 may show 6713, as it has more RAM.


This library makes extensive use of SdFat Library as to retrieve the stream of audio data from the SdCard. Notably this is where most failures occur. Where some SdCard types and manufacturers are not supported by SdFat. Though SdFat Lib is at this time, supporting most known cards.



SdFatLib only supports 8.3 filenames. Long file names will not work. Use the 'd' menu command to display directory contents of the SdCard. "longfilename.mp3" will be converted to "longfi~1.mp3" . Where one can not predict the value of the 1. The DOS command of "dir \c /x" will list a cross reference, so that you know exactly, what is what.

Still Need Help?

Use the support forum to look for a solution or ask for help. Please don’t use the comments below to ask for help.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.


Trackbacks / Pingbacks

  1. 1Sheeld Music Player Vs. SparkFun MP3 Player Shield - 1Sheeld | All Arduino shields on your Smartphone

Warning: count(): Parameter must be an array or an object that implements Countable in /homepages/46/d285670699/htdocs/bill/wp-includes/comment.php on line 879
  1. 590 Comments.

    • Jun JieNo Gravatar says:

      may i know if there is a demo for mp3 where the music is able to have layer on top one another?

      Example: when e3 is pressed, beat A is looping.
      when e6 is pressed, beat D will play on top of beat A in a loop.
      when e0 is pressed, everything stop.

      • Michael P. FlagaNo Gravatar says:

        There are some more advanced plugins for the VS1053 that allow two streams to be mixed. However, this library or others that I have seen support it. As it is quite complicated.

        Alternatively, if you are looking to play Notes, I recommend using the realtime MIDI plugin or mode. You can simply send the MIDI command for each of the notes, as you wish to play or stop them.

    • Wan Muhammad Najmie Wan SabriNo Gravatar says:

      i copied the code with the “I’m bored” part, but I cannot hear any sound. When I pull the serial monitor out, it displays “I’m bored”, which I assumed that the code is working and that there’s nothing wrong with it. But, I still can’t hear anything.

      • Michael P. FlagaNo Gravatar says:

        Please refer trouble shooting questions to the forum. Where as this library nor it examples do not have any code with …”bored”… in it. So I have no idea what you are referring to.

        • davidNo Gravatar says:

          a little help , fist i posted to blog no response to my questions
          i have 2 if you don’t mind answering them question 1 can a pickit 3 be used to program lillypad question 2 is there code out there to cause the lillypad to continuously loop one mp3 file after power is applied thanks for help up front

    • sorry about the confusion. This is the code I am referring to:


      SdFat sd;
      SFEMP3Shield MP3player;

      void setup() {


      //start the shield
      sd.begin(SD_SEL, SPI_HALF_SPEED);

      //start playing track 1

      //do something else now
      void loop() {

      Serial.println(“I’m bored!”);


    • hello.

      I’m having some problem with the FilePlayer example codes. So I don’t understand why is it that when I used MP3player.playTrack(“track001.mp3”) it doesn’t work but when I use MP3player.playMP3(filename) it worked.

      And also, how does the process works? Can we just play the “filename”, or do we have to check whether the files exist or not first?

    • MathieuNo Gravatar says:

      I have a problem.
      SFEMP3Shield\SFEMP3Shield.cpp.o: In function `SFEMP3Shield::begin()’:
      SFEMP3Shield.cpp:141: undefined reference to `sd’

      any idea? I use to be able to run it and now no more?

    • AndréNo Gravatar says:


      Apparently I’m getting a weird error, because I checked all over the web and couldn’t find someone complaining about the same thing. I’m using arduino UNO, which should work out of the box, but on the first examples I get just the SRAM message:

      Free RAM = 1035 Should be a base line of 1028, on ATmega328 when using INTx

      (The free RAM varies depending on the arduino compiler version).

      And everything stops there. I tried to use other examples and I seen that the SD library works fine, but everything stops when I call the function MP3.begin() .

      I getting really frustrated, any hints on what’s going on?


    • […] SFEMP3Shield Arduino library, it is written by Bill Porter and it’s an amazing library for that shield and combined with the SdFat library which also […]

    • JulienNo Gravatar says:

      I would like to know which modification should I make to this library so I can read WAV Files ?

      Thank you in advance for your answer 🙂

    • aliNo Gravatar says:

      Hello sir i am ali base in nigeria final year student from university of maiduguri. Please sir with due respect sir i need your attention . sir i am writting project on anniken mp3 player which i saw here in your website . please sir i am a nigeria and we are proud of you people the way you are so creative and intelligent thats why i am requesting for your help to asist me with comprehensive details and libraries on this specific project (anniken mp3 player control by smartphone) please and please help me out i defend on you .
      Thank you and i will be very glad if my request is considered please.

    • GugunNo Gravatar says:

      Hello sir, is sparkfun mp3 shield can play multiple file at the same time

      I want to build piano
      Sorry for my english

    • HelenNo Gravatar says:

      Sometimes driver is being corrupted when it is not updated.

    • InaNo Gravatar says:

      You need to download ISP bus.

    • vevimiliNo Gravatar says:

      Make my sketch on the board with paint.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.