VS1053  1.03.00
Arduino Library for VS10xx shield
Arduino vs1053 Library

Table of Contents

Copyright © 2012


The Arduino vs1053 Library is a driver for VSLI's VS10xx, implemented as a slave co-processor to the hosting Arduino to decode audio streams of Ogg Vorbis/MP3/AAC/WMA/FLAC/WAVMIDI formats, across the SPI bus of the hosting Arduino. The vs1053 is capable of many other features including mixing, altering and measuring the audio streams by using PlugIn's for the vs1053's DSP. Principally this library is developed for the VS1053, where it is may be compatible with other VS10xx's. Additional there is support for other various Arduino base systems and Shields. Hardware and documentation is provided as to how to implement these.


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


  1. Initial development was implemented on an Arduino 328 UNO/Duemilanove with a SparkFun MP3 Player Shield under the title of "SFEMP3Shield".


IDE Library Manager

(1.3.+ and later)

  1. from the Arudino IDE select the "Sketch" tab,
    1. From the drop down list select the "Include Libary".
    2. From the to of the extended drop down list select "Manage Libraries" to display the list of supported libaries.
  2. wait for the window to finish its updates
  3. To install "vs1053 sdfat"
    1. type "vs1053 sdfat" into the dialog box initially showing "Filter your search..."
      1. As you type the below list of matching libraries will reduce.
    2. Select the entry titled "VS1053 for use with SdFat"
    3. Click the install button, to the lower right of the corresponding cell.
  4. Similiarly install the "SdFat" library using the Libary manager.
  5. Once the progress bar has completed close the "Library Manger" windows and you are basically ready.
  6. It is recommended to start with the demo.ino file.

Manual Method

(advanced method)

  1. from https://github.com/mpflaga/vs1053_for_SdFat either:
    1. clone the repo into your local Arduino Library directory
      1. 'C:/Users/{user name}/Documents/Arduino/libraries' folder
    2. download the ZIP file.
      1. expand its contents into your local Arduino Library directory
  2. Similiarly clone or download and expand the "SdFat" from https://github.com/greiman/SdFat
  3. restart the Arduino IDE.

Optional libraries

Not required for basic use. There are several advanced and alternate methods the vs1053 and audio streams may use. These alternate methods may be useful for different end users implementations. Within this library and provided examples are illustrations that can be enabled to demonstrate these optional libraries.

Initial Setup

  1. After correpsonding libraries are installed.
  2. Copy the contents of this projects the '..' 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 "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.

The example provided was developed to test and illustrate most all of the various common uses of the vs1053.


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 vs1053Config.h file.

Arduino Bare Touch

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

Reference Arduino Leonardo Board's note about example files.

Arduino Mega Board

Support for Arduino and Seeeduino Mega's are documented in vs1053Config.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 vs1053Config.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 VS1053_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 vs1053::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 vs1053::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 initially only supports 8.3 filenames. Long file names have not been implemented. 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 vs1053::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 vs1053::playTrack() or vs1053::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 vs1053::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.