AFwave Lib.


This documentation is for historical reference only!
AF_Wave is no longer supported or used, it does not work with the SDHC SD Cards, so we put it to pasture. Please use the superior WaveHC instead!

Get more RAM & Flash!

Before you try to play audio, you'll want to free up some Arduino RAM, so that you don't end up with a nasty stack-overflow.

Follow these instructions on how to get more RAM by reducing the input Serial library buffer. You dont need to do this if you're using an ATmega328.

Note that the library is pretty big (about 10K) so if you want to do a lot more, I suggest upgrading to an ATmega328. The shield was designed with the expectation that this part would be available.

A tour of the AF_Wave library

This is a description of the AF_Wave library, which is the 'default' library for the Wave shield. However, there is an 'updated' and superior library, WaveHC written by Mr Fat16 in the forums. This library is powerful, works with more cards and card formatting issues, and uses less space. This tutorial is here for those who want to use the classic AF_Wave library but we suggest you also check out WaveHC. It's very similar to AF_Wave so you can probably switch between the two.

We have a runthrough of WaveHC over here.

Initialize the card

The first thing that must be done is initializing the SD card for reading. You should copy & paste this code from the examples since there's really only one way to do it.

Note that this here is a snippet, use the examples in the library for the 'full listing.'
Download: file
AF_Wave card;

void setup() 
  if (!card.init_card()) {
    putstring_nl("Card init. failed!"); return;
  if (!card.open_partition()) {
    putstring_nl("No partition!"); return;
  if (!card.open_filesys()) {
    putstring_nl("Couldn't open filesys"); return;

 if (!card.open_rootdir()) {
    putstring_nl("Couldn't open dir"); return;

This code will try to initialize the card, open the partition table, open the FAT16 filesystem and finally open the root directory. If it fails it will print out an error message.

Looking for files

There isn't a lot of interface code for going through the root directory. Basically you can reset the directory (start over from beginning) and get the name of the next file. The files are not organized alphabetically but rather in the order that they were created on the card.

You'll need to make a character array 13 characters long to store the 8.3 + terminating 0 of the file. Here is an example of displaying the name of each file available. When done, it resets the directory.
Download: file
void ls() {
  char name[13];
  int ret;
  putstring_nl("Files found:");
  while (1) {
    ret = card.get_next_name_in_dir(name);
    if (!ret) {

Opening a file for playing

There are two steps to opening a file for playing. The first is to just open the file itself, then the file must be converted to a wavefile. That means the file is read and checked for a wavetable header. To open a file, you just need the name, you can pass in a string such as "MYSOUND.WAV" or read through the directory and use the name returned from get_next_name_in_dir(). Since long names arent supported (to keep the library smaller) you may want to use ls() function above to see what the 8.3 format name of the file is.
Download: file
AF_Wave card;
File f;
Wavefile wave;      // only one!

void playfile(char *name) {
   f = card.open_file(name);
   if (!f) {
      putstring_nl(" Couldn't open file"); return;
   if (!wave.create(f)) {
     putstring_nl(" Not a valid WAV"); return;


Playing the file

Finally we can play the file! It's quite easy, once the wavefile has been opened as above, simply call to being playback. The Arduino plays audio in an interrupt, which means that returns immediately. You can then mess with sensors, print feedback or buttons or whatever.

While the wavefile is playing, you can check its status with the variable wave.isplaying. If the variable is 1 then the audio is playing. If its 0 that means it has finished playing.

You can stop playback by calling wave.stop()

Closing the file

When you're done playing audio from a file, you must close it! You can close the file by calling card.close_file(f) where f is the file you created using card.open_file(name)

Changing sample rate

This is sort of strange, but may be useful if, say, you have a sine wave or sample that youd like to change the pitch of or if you'd like to 'fast forward' through some music.

The sample rate (i.g. 22kHz) is stored in wave.dwSamplesPerSec. It will be initially set to whatever the wave file is supposed to be. Simply assign a new sample rate to the variable to change it on the fly.

See here for more information.

Saving & restoring the play position

If, say, you want to know where along in the wave file you are, that information is also available in wave. in wave.getSize() (the number of bytes in the entire wave) and wave.remainingBytesInChunk (how many bytes are left to play).

You can set the current place to play from using, the Arduino will immediately start to fastforward to that location. For example, will take you to the beginning, will take you to the middle of the file.

Volume adjust

You can change the volume of the audio 'digitally' on the fly. Note that this doesn't change the volume control potentiometer, it actually just reduces the digital values going to the DAC. Thus the quality of the audio will be degraded. However, it may come in handy so it has been included. Since it slows down playback a bit, it is not enabled by default. To enable digital volume control, open up wave.cpp in the library folder and look for the line #define DVOLUME 0 and change the 0 to a 1. Then delete all the files in the library folder that end with .o, this will force the software to recompile the library when the sketch is compiled.

The volume is controlled by a variable in the Wavefile object. For example, if you have Wavefile wave at the top of your sketch, then you can set the volume by calling wave.volume = 4. The volume can be set from 0 to 12. A volume value of 0 is maximum, and 12 is silence. Anything higher than 12 will be the same as 12.

See here for more information.
This guide was first published on Jul 17, 2013. It was last updated on Jul 17, 2013. This page (AFwave Lib.) was last updated on Jun 06, 2018.