SFEMP3Shield  1.02.15
Arduino Library for VS10xx shield
Arduino SFEMP3Shield Library

Table of Contents

Copyright © 2012


The Arduino SFEMP3Shield Library is a driver for VSLI's VS10xx, implemented as a Slave co-processor to audio decode streams of Ogg Vorbis/MP3/AAC/WMA/FLAC/WAVMIDI formats, across the SPI bus of the Arduino, along with mixing input signals. Principally this library is developed for the VS1053, where it may be compatible with other VS10xx's

Initial development was implemented on an Arduino 328 UNO/Duemilanove with a SparkFun MP3 Player Shield. Where additional support has been provided for Arduino base systems and Shields. Hardware and documentation is provided as to how to implement these. Where this driver is modular in concept to allow ready porting to other Arduino or Wiring platforms.


Nathan Seidle, www.sparkfun.com
Bill Porter, www.billporter.info
Michael Flaga, www.flaga.net
Wade Brainerd


This library was originally developed on IDE 0.2x, later ported to 1.x and best support on IDE 1.5.0+ going forward. Compatibility was lost with use of the Serial.print(F("...")) and can be restored by replacing it with SdFat's PgmPrint function


To install 1, 2, 3 !

  1. unzip and place './SFEMP3Shield' and './SdFat' folder into your 'C:/Users/{user name}/Documents/Arduino/libraries' folder or '{Arduino IDE path}/hardware/libraries" or {Arduino IDE path}/libraries" directory.
    • Along with SimpleTimer and or TimerOne if needed. Restart the Arduino IDE, and open up the example sketch.
  2. Copy the contents of this projects the './plugins' folder onto the root of the SdCard to be used. Along with desired audio files named appropriately; track001.mp3 through track009.mp3.
    • The plugins and audio files are not needed to be placed into the Arduino directories as they are not directly a part of the compiled project.
  3. Start IDE, load Example MP3Shield_Library_Demo.ino, select appropriate Board, Serial Port, Compile, load, run Serial Monitor at 115200 baud rate.
    • May need to Reset target Arduino and wait for Menu.

An example is provided in the SFEMP3Shield/examples folder. Which is developed to test SFEMP3Shield and illustrate its various common uses.


As mentioned the initial and principal support of this library is with Arduino 328 UNO/Duemilanove with a SparkFun MP3 Player Shield. Although various other boards and shields may be implemented by customing the SFEMP3ShieldConfig.h file.

Arduino Bare Touch

Support for Bare Conductive's Touch Board is provided and documented in SFEMP3ShieldConfig.h.

Reference Arduino Leonardo Board's note about example files.

Arduino Mega Board

Support for Arduino and Seeeduino Mega's are documented in SFEMP3ShieldConfig.h, which simply REQUIRES additional jumpers. As the SPI are not on the same pins as the UNO/Duemilanove.

Arduino Leonardo Board

Support for Arduino Leonardo's are afflicted by having the SPI and INT0 pins not routed to the same pins as the UNO/Duemilanove . This is similar to the Arduino Mega. Which simply REQUIRES additional jumpers, as documented in SFEMP3ShieldConfig.h to correct the SPI. The swapping of INT0/INT1 is automatically corrected based on the Leonardo's processor type of AVR_ATmega32U4 being detected.

While the Leonardo has the same amount of physical program space as the UNO, it actually has less space available for use. As it uses approximately 4K, for core library USB features. Where there is adaquate space available for typical applications, the provided example files MP3Shield_Library_Demo.ino and FilePlayer.ino will compile a reduced set of examples based on the processor type of AVR_ATmega32U4 being detected. This is only for the demonstration, and other sketchs may call any of these functions, given its environment.

Arduino Pro 5V vs 3V

SFE Arduino Pro's while similar to UNO/Duemilanove's pin outs, they are available in either 5V or 3.3V. Where the SFE MP3 Player Shield requires 5V and locally generating the needed 3.3V and 1.8V for the VS10xx chip. Noting that 3.3V Pro's do not supply 5V, this causes a problem. It is possible to modify the shield as to use base Arduino supplied 3V's.

SparkFun MP3 Player Shield

SparkFun MP3 Player Shield should just work out of the box (bag) with a Arduino 328 UNO/Duemilanove, with Interrupts.

Seeduino MP3 Player Shield

Support for Seeduino MP3 Player Shield please see SEEEDUINO and may require additional libraries, as per Requirements

MP3-4NANO Shield

Support for Gravitech MP3-4NANO shield please see GRAVITECH



Understanding that every byte streamed to the VS10xx needs also to be read from the SdCard over the same shared SPI bus, resulting in the SPI bus being less than half as efficient. Along with overhead. Depending upon the Bitrate of the file being streamed to the VSdsp, there is only so much Real Time available. This may impact the performance of high bit-rate audio files being streamed. Additionally the Play Speed Multiplier feature can be exhausted quickly. Where on a typical UNO there is plenty of real-time to transfer good quality files, with CPU to spare for other tasks, assuming they do not consume too much time either.

The available CPU can be increased by either or both increasing the speed of the SPI and or the Arduino F_CPU. Where the Speed of the SPI is individually maintained by both this driver and SdFatLib. As not to or be interfered with each other and or other libraries using the same SPI bus. The SdCard can be increased from SPI_HALF_SPEED to SPI_FULL_SPEED argument in the SD.begin. Where this library will set the Read and Write speeds to the VSdsp correspondingly, based on F_CPU of the Arduino.

The actual consumed CPU utilization can be measured by defining the PERF_MON_PIN to a valid pin, which generates a low signal on configured pin while servicing the VSdsp. This is inclusive of the SdCard reads.

The below table show's typical average CPU utilizations of the same MP3 file that has been resampled to various bit rates and using different configurations. Where a significant difference is observed in performance.

BitRate SdCard Refilling IDLE
128K Half 12% 88%
128K Full 10% 90%
96K Full 7% 93%
56K Full 4% 96%
Only F_CPU of 8MgHz and 16Hz are suppored. Others will default to SPI_CLOCK_DIV2, assuming 4MgHz.

Plug Ins and Patches

The VS10xx chips are DSP's that run firmware out of ROM, that is internal to the VS10xx chip itself. Where the VSdsp's RAM can additionally be loaded with externally provided firmware and executed, also known as patches or plug-ins, over the SPI port and executed. This allows the VSdsp to have a method for both fixing problems that may exist in the factory ROM's firmware and or add new features provided by VLSI's website. It is even possible to write your own custom VSdsp code, using there Integrated Development Tools (VSIDE).

vs_plg_to_bin.pl is a perl script, that is provided in this library to run on your PC, to read and digest the .plg files converting them to raw binary as to be read by SFEMP3Shield::VSLoadUserCode() from the SdCard. Allowing updates to the VSDsp into its volatile memory after each reset. These updates may be custom features or accumulated patches.

By storing them on the SdCard these plug-ins do not consume the Arduino's limited Flash spaces

Below are pre-compiled binary's of corresponding provided VSLI patches/plugins. The filenames are kept short as SdCard only support 8.3.

.\pcm.053       .\vs1053-pcm110\vs1053pcm.plg
.\admxleft.053  .\vs1053b-admix130\admix-left.plg
.\admxmono.053  .\vs1053b-admix130\admix-mono.plg
.\admxrght.053  .\vs1053b-admix130\admix-right.plg
.\admxster.053  .\vs1053b-admix130\admix-stereo.plg
.\admxswap.053  .\vs1053b-admix130\admix-swap.plg
.\patchesf.053  .\vs1053b-patches195\vs1053b-patches-flac.plg
.\patches.053   .\vs1053b-patches195\vs1053b-patches.plg
.\rtmidi.053    .\vs1053b-rtmidistart\rtmidistart.plg
.\eq5.053       .\vs1053b-eq5-090\vs1053b-eq5.plg
All plugins should be placed in the root of the SdCard.
patches.053 is a cumulative update correcting many known troublesome issues. Hence patches.053 is attempted in SFEMP3Shield::vs_init.
VSLI may post periodic updates on there software website
Perl is natively provided on Linux systems, and may be downloaded from Active Perl for windows systems.
See also
about Analog to Digital Mixer (e.g. admx____.053) please note Limitations.


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

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.

Error Codes

Error Codes typically are returned from this Library's object's in place of Serial.print messages. As to both save Flash space and Serial devices may not always be present. Where it becomes the responsibility of the calling sketch of the library's object to appropiately react or display corresponding messages.

begin function:

The following error codes return from the SFEMP3Shield::begin() member function.

0 OK
1 *Failure of SdFat to initialize physical contact with the SdCard
2 *Failure of SdFat to start the SdCard's volume
3 *Failure of SdFat to mount the root directory on the volume of the SdCard
4 Other than default values were found in the SCI_MODE register.
5 SCI_CLOCKF did not read back and verify the configured value.
6 Patch was not loaded successfully. This may result in playTrack errors
Error codes 1,2,3 due to use of sd.begin() as global, starting version 1.1.0

Playing functions:

The following error codes return from the SFEMP3Shield::playTrack() or SFEMP3Shield::playMP3() member functions.

0 OK
1 Already playing track
2 File not found
3 indicates that the VSdsp is in reset.

Skip function:

The following error codes return from the SFEMP3Shield::skipTo()member function.

0 OK
1 Not Playing track
2 Failed to skip to new file location


The code has been written with plenty of appropiate comments, describing key components, features and reasonings in Doxygen markdown style as to autogenerate this html suppoting document. Which is loaded into the repositories' gh-page branch to be displayed on the projects's GitHub Page.

Additional support may be reached from any of the following: Please read through this document and refering linked resources.

Problems with SdCard initializing is outside the scope of this library. SdFatLib' repository was selected being the best choice.


See also

VS1053 Datasheet.

VLSI's DSP support Forum.

VLSI's software download of Apps, Patches, Plugins and tools.

VS10XX AppNote: Connecting analog outputs.

Sparkfun Electonics

MP3 Player Shield DEV-10628.

MP3 Player Shield Landing Page / Tutorials.

SFE's Schematic.

Adafruit Industries:.

The Arduino site.

The ATmega328 datasheet.