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. Arduino mp3 player shield by Sparkfun | A Bidouille World

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.

    • Michael P. FlagaNo Gravatar says:

      refer to the WebPlayer Example at along with the Documentation at and read the support forum. Like an issue with a Chip Select conflict between the two shields.

    • Brendan WertanenNo Gravatar says:

      Hey Bill,

      We recently purchased the MP3 shield for a project to use with an Arduino Mega. I have read through all of the comments and suggestions about the proper way to unzip and place the libraries that you have created.

      For some reason we cannot get the example code to compile and we only receive multiple errors with the SdSpi not having a type and the SD_CHIP_SELECT_PIN not being declared in the scope. When the libraries are included, only the SPI library is recognized and turns orange. Any ideas?

      • BillNo Gravatar says:

        Sorry Brendan, there was an issue in the (lack of) files included with the library. Delete everything you downloaded, download the library and unzip it again, it should compile now.

        • Brendan WertanenNo Gravatar says:

          Thanks, that definitely got it to compile. I am still having an issue with it recognizing the SFMP3Shield.h whereas in your demo sketch it turns orange. Below where your libraries are included, the SdFat sd; SFMP3Shield MP3player are all still black.

          I placed the updated libraries into the correct folder as the directions specified. Am I making another mistake somewhere?

    • Michael P. FlagaNo Gravatar says:

      If you are still having problem. Can you please move to the forum. Please include your IDE’s results output. It will specify the exact error. As your description is confusing, in that you say it is compiling, but an orange line indicates a problem, with the compile.

    • EricNo Gravatar says:

      I believe I have the same problem as Brendan. I am using the basic code above. The code will compile but when it uploads to the board and I open the serial port it says the sd.begin wasn’t defined. I think it is because
      the libraries are not getting imported. The SPI is turning orange in the include statement but the SFEMP3Shield is not orange in the include statement.

      SPI is orange:

      Everything is black:

      This is all black as well:
      SdFat sd;
      SFEMP3Shield MP3player;

      Did I import something wrong or can you give me any suggestions as to what is happening?

      • Some GuyNo Gravatar says:

        If SdFat sd; and SFEMP3Shield MP3player; is not compiling it most likely (like 99% of the time) means that you messed up importing the library to your Arduino libraries file. The correct way is to first download the zip, when you download the zip file you can right click it and it should say Extract. (Again the zip file itself, not inside the zip file because downloading the file sometimes opens up the file with you in it already)

        Once you do that you want to move or copy all of the files and documents inside it into your Arduino library file which is probably on your c drive, on your c drive inside Program Files or on your c drive inside Program Files (x86). (Or where ever else you decide to put it when you first downloaded Arduino)

        There you will find your Arduino program file, inside it will be a file called libraries and inside there is where you want everything in the file extracted to go. Another thing is you might want to open the Arduino.exe file the Arduino file you are in, in case you have another version of Arduino or even the same version else where by accident.

      • Steven MorelNo Gravatar says:

        Did you ever get this figured out?

    • […] contrôler le lecteur mp3: – La bibliothèque officielle mise à disposition par Sparkfun. – La bibliothèque de Bill Porter qui facilite grandement l’utilisation avec sa […]

    • ctb123No Gravatar says:

      I plan to use the Sparkfun MP3 player for an art installation where a pull cord attached to a switch activates different sounds. Is it possible to use your library to play sounds at random? And, to have the audio stop at the end of each track? Any assistance will be greatly appreciated. Thank you.

      • Michael P. FlagaNo Gravatar says:

        Yes, there are plenty of examples. Along with MP3random.ino (

        • ctb123No Gravatar says:

          Thanks for the reply, Michael. I’m novice in this arena, so i appreciate the insight. I’m having trouble figuring out exactly where to add this set of code. I assume I need to combine it with some other code.. ? Ideally, I’m looking to have a track play at random each time a switch is activated that leads to one of the analog pins. One track plays, then stops, and awaits another signal to the same analog pin from the same switch. I see that 9 tracks are used in the standard code. I’d like to use more if possible.. Any assistance from you or anyone out there would be a huge help. Thanks!

    • ctb123No Gravatar says:

      Thanks Michael. It’s making more sense now. I’m getting some errors that I can’t seem to beat:
      sketch_aug31a:78: error: ‘Bounce’ does not name a type
      sketch_aug31a:83: error: ‘Bounce’ does not name a type
      sketch_aug31a:88: error: ‘Bounce’ does not name a type
      sketch_aug31a:93: error: ‘Bounce’ does not name a type
      sketch_aug31a.ino: In function ‘void loop()’:
      sketch_aug31a:149: error: ‘b_Play’ was not declared in this scope
      sketch_aug31a:157: error: ‘b_Stop’ was not declared in this scope
      sketch_aug31a:165: error: ‘b_Next’ was not declared in this scope
      sketch_aug31a:174: error: ‘r_Play’ was not declared in this scope

      any tips?

      • ctb123No Gravatar says:

        I think the issue surrounds my bounce.h library. First, it wasn’t installed correctly. Second, I think its version bounce2.h. I’m having trouble locating a zip of bounce.h..
        Any leads?

    • ctb123No Gravatar says:

      OK i think i got it. I found the bounce libraries you had posted, and they’re doing the trick! now for some sounds! I sincerely appreciate the help.

    • CassiusNo Gravatar says:

      Hello ,
      I am trying to use the mp3 sparkfun and Arduino Due.
      My question:
      Everything is ok , no errors message, but I can´t heard anything !

      All commands from MP3Shield_Library_Demo are working. But no sound out !

      Any idea ?

      Messages when I reset :
      Free RAM = 93463 Should be a base line of 1040, on ATmega328 when using INTx

      Try to play:
      Enter 1-9,f,F,s,d,+,-,i,>,<,p,r,R,t,m,M,g,k,h,O,o,D,S,V :
      Received command: 3

    • Dan LNo Gravatar says:


      I’m really struggling to get any sound out of the Mp3 Shield with any sketch which plays or triggers a sound. I can activate the tracks via the serial monitor with file player and Mp3 shield demo no problem, but whenever I try uploading a sketch, I get no sound whatsoever. Tracks are named correctly, sd card has the patches on also. Library is in the right directory, and the code uploads with no errors.
      I’m using a sainsmart Uno with a sparkfun mp3 shield.
      Any ideas? It driving me insane..!
      Many thanks in advance


    • Don J BorchertNo Gravatar says:

      Does this code support MP4?

      • Michael P. FlagaNo Gravatar says:

        It can. Note that MP4 is a wrapper around the actual encoded audio track. And as such there are some formats that are not supported. Try it and if it does not work refer to the VS1053 data sheet. As it provides more detailed explanations and some workarounds.

    • Steven MorelNo Gravatar says:

      the program stops after MP3player.begin();? what would cause that ad how can I fix it?

    • Steven MorelNo Gravatar says:

      the program stops after MP3player.begin();? what would cause that and how can I fix it?

      • Steven MorelNo Gravatar says:

        I went through all of that. Should SFEMP3Shield.h be in orange letters or black? When I run the example “MP3Shield_Library_Demo I get
        F_CPU = 16000000
        Free RAM = 1062 Should be a base line of 1028, on ATmega328 when using INTx

        then nothing else?

        • Michael P. FlagaNo Gravatar says:

          sounds like the MP3player.begin() is not getting a response from your VS1053 chip. There are several discussions in the forum about such. In short put prints in the code, to see where it is stopping. Just a guess of off soo little info, the SPI is not talking to the VS1053. There are ALOT of error # that usually pop up, for NO or bad responses. So the game is to figure out where it is stuck. Then read the forums and if needed submit a Question to the forum.

    • Mandeep SinghNo Gravatar says:

      Your Library for MPS shield works perfectly, thanks. However, I faced a problem while using a GSM SIM900 module simultaneously on Mega 2560. I was trying to play a track triggered by a SMS message. I am using the Serial1 Port for the GSM Module and standard pins for MP3 Shield( of course changing the reqd pins for MEga 2560). I noticed that the GSM Module does not work properly while the MP3 Player is playing, it does work properly when the MP3 Player is not playing. I am also using a DS1307 Module simultaneously on SCL and SDA Pins. I need help for this purpose pl. thanks

Leave a Reply

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