Introduction

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.

Contributors

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

Requirements

Software
- Arduino 1.0 IDE or greater.
- The most current vs1053 Driver
- SdFat Driver, while included a newer version may retrieved from SdFatLib' repository .
- Optionally, used if Hardware Interrupts are not supported:
  - SimpleTimer.h . library can be downloaded from for library.
  - TimerOne.h . library can be downloaded from for library.
Hardware
- 5V Arduino 328 UNO/Duemilanove or better.
- Shield or break out with appropiate pins wired up.
- Shield or break out for SdCard
- SdCard FAT formatted with valid Audio files and filenames
- See Hardware for alternative solutions.

Note

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

Installation

IDE Library Manager

(1.3.+ and later)

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.
wait for the window to finish its updates
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.
Similiarly install the "SdFat" library using the Libary manager.
Once the progress bar has completed close the "Library Manger" windows and you are basically ready.
It is recommended to start with the demo.ino file.

Manual Method

(advanced method)

from https://github.com/mpflaga/Arduino_Library-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
Similiarly clone or download and expand the "SdFat" from https://github.com/greiman/SdFat
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.

TimerOne
- is available from the Library Manager
- or can be found at http://playground.arduino.cc/Code/Timer1
SimpleTimer can be manually installed as a library, from https://playground.arduino.cc/Code/SimpleTimer
Bounce2 is required for the ButtonPlayer.ino, exampling a method of deboucing inputs.
- is available from the Library Manager

Initial Setup

After correpsonding libraries are installed.
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.
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.

Hardware

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.

Note: 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.

Note: 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

Limitations.

The SPI Bus: The configuration of the VS10xx chip as a Slave on the SPI bus, along with the SdCard on that same bus master hosted by the Arduino. See Performance
Non-Blocking: The controlling sketch needs to enquire via vs1053::isPlaying as to determine if the current audio stream is finished or still playing. This is actually good and a result of the library being non-blocking, allowing the calling sketch to simply initiate the play of a desired audio stream from SdCard by simply calling playTrack or playMP3, of the desired file, and move on with other RealTime issues.
Multi-Chip VS10xx support: Not at this time. There are too many issues with member functions of the vs1053 class requiring to be static.
Audio Input Most commericially available shields at this time do not support either Line Level or Microphone Input. With the exception of the Seeeduino MP3 Shield and other home made shields. Where as the below admx____.053 and vs1053::ADMixerLoad and vs1053::ADMixerVol are provided for such devices. Otherwise the example VS1053_Library_Demo.ino has these lines commented out in setup(). As to reduce complications. To re-enable simply uncomment.
Recording As most commericially available shields do not support audio input this feature has not been implemented.
Todo:
Support Audio Recording.

Performance

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%

Note: 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

Note: 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.

Troubleshooting

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 VS1053_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 MP3player.begin() locking up, in setup()?
Are you trying to update from a version prior to 1.01.00?
Why does my Serial Monitor display: "...do not have a sd.begin in the main sketch, See Trouble Shooting Guide."
Compiler Error: "...undefined reference to `sd'"
Is the last thing printed to the Serial Monitor: "Free RAM = 1097 Should be a base line of 1095, on ATmega328 when using INTx" then nothing...
- Versions after 1.01.00 require the SdFat::begin() to be initialized in the main sketch.ino, as shown in the below example. This provides more immediate access to the SdCard's files by the main sketch. However, if not done there is no immediate compiler error and the sketch will lock up after as it attempts vs1053::begin.
  ...
  SdFat sd; // newly required in 1.01.00 and higher
  void setup() {
  if(!sd.begin(SD_SEL, SPI_HALF_SPEED)) sd.initErrorHalt(); // newly required in 1.01.00 and higher
  if(MP3player.begin() != 0) {Serial.print(F("ERROR"));
  ...
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.
"Warning: patch file not found, skipping."
- See the Plug Ins and Patches
Why do I only hear 1 second of music, or less?
- This symptom is typical of the interrupt not triggering the vs1053::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 VS1053_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.

Note: 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.

Warning: 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

Deprecated:: 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

Support

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.