Artekit PropBoard: Audio API
Audio API documentation for the Artekit PropBoard.
Audio on the PropBoard
Audio on the PropBoard is very easy to use and is accessed through a series of classes that we document here. From now on, we refer to these classes as the Audio module.
The PropBoard Audio module currently supports playing WAV and RAW (PCM) files at several sampling frequencies and 16-bit bit depth. Many different sound files can played at the same time (quantity depends on audio format and processor load) and they are automatically mixed in real time.
Basically the Audio module is managed through the Audio object and is initialized by calling Audio.begin(). This is the only function you need to call to enable audio output.
The class dedicated to playing WAV files is the WavPlayer class. A series of advanced classes and methods can also be found in the PropBoard API: Advanced Audio document.
About audio formats
At the current version, the PropBoard software supports playing samples at 22050Hz, 32000Hz, 44100Hz, 48000Hz and 96000Hz sampling frequencies and 16-bit bit depth. The audio format is specified when initializing the Audio module through the Audio.begin() function.
The current Audio module implementation does not have a sampling rate or bit depth converter, so any attempt to play an audio file that has not the same sampling frequency and bit depth as specified to the Audio.begin() function will fail. The quantity of channels (mono/stereo) is not important.
This means that you can play (and mix) a mono, 16-bit, 22050fs WAV together with a stereo 16-bit, 22050fs WAV, but you can’t play a mono, 16-bit, 22050fs WAV together with a stereo 16-bit, 48000fs WAV.
As a rule of thumb, check that your audio files have the same sampling frequency and the same sample bit depth.
Audio object
class PropAudio;
PropAudio Audio;
The Audio object is responsible for audio initialization, mixing, output, and volume control. The object is already instantiated when the program begins.
Audio.begin
Call the Audio.begin() function to initialize audio. This is the sole function you need to call before playing any sound file.
Syntax
bool begin(uint32_t fs = 22050, uint8_t bps = 16);
Parameters
The fs parameter is the sampling frequency (for example 22050) and bps is the bit depth or bits-per-sample (for example 16).
The possible values for the fs parameter are:
- 22050
- 32000
- 44100
- 48000
- 96000
The possible value for the bps parameter is:
- 16
If the function is called without parameters it will initialize audio with a 22050Hz sampling frequency and 16-bit bit depth.
Returns
The function returns true if Audio was successfully initialized, false otherwise.
Examples
void setup()
{
Audio.begin(); // 22050Hz sampling frequency and 16-bit bit depth
}
The following code will initialize the audio for a 48000Hz sampling frequency and 16-bit bit depth:
void setup()
{
Audio.begin(48000, 16); // 48000Hz sampling frequency and 16-bit bit depth
}
Notes
Remember that from the moment Audio.begin() is called, all the audio files and/or samples must respect the sampling frequency and bit depth that was passed to the Audio.begin() function. The Audio module does not do any distinction regarding quantity of channels (mono/stereo).
Audio.end
Call Audio.end() to de-initialize the Audio module. Audio output is terminated and to play audio the Audio.begin() function must be called again.
Syntax
void end();
Parameters
None.
Returns
None.
Audio.setVolume
Call the Audio.setVolume() function to set the audio output volume. The volume is directly managed by the I2S codec, so audio volume does not have any impact in regards of computing power.
Syntax
bool setVolume(float decibels = 0);
Parameters
The decibels parameters is the volume in decibels. You can increase the volume up to a maximum 12db or decrease the volume down to a minimum of -100db.
Returns
The function returns true on success, false otherwise.
Notes
By default, the Audio module is initialized at 0db when the Audio.begin() function is called.
Audio.mute / Audio.unmute
Use the Audio.mute() function to mute the audio output and Audio.unmute() to restore it.
Syntax
bool mute();
bool unmute();
Parameters
None.
Returns
The functions return true on success, false otherwise.
WavPlayer Class
class WavPlayer : public RawPlayer
The WavPlayer class is used to play a WAV file from the microSD card. You can create a WavPlayer object by simply calling:
WavPlayer myWavPlayer; // Create a WavPlayer object
void setup()
{
// My program goes here
You can create several WavPlayer objects. It is wise to create them accordingly on how many WAV files you need to play at the same time. If you are not playing overlapping WAV files you can re-utilize the same WavPlayer object to play different WAV files at different moments.
Plan ahead in a way that you can save resources by re-utilizing the same WavPlayer objects.
For example, let’s imagine a lightsaber prop that needs to mix a background hum sound together with another overlapping sound (swing, hit, blaster). For example:
WavPlayer myHumSound; // To play a background hum sound
WavPlayer myFxSound; // To play any other sound on top of the hum sound
void setup()
{
// Initialize Audio
Audio.begin();
// Use myHumSound to play a background hum in loop mode
myHumSound.play("hum.wav", PlayModeLoop);
}
void loop()
{
// Detect hit condition
if (on_hit)
{
// Play hit.wav
myFxSound.play("hit.wav");
} else if (on_swing)
{
// Swing detected. Play swing.wav
myFxSound.play("swing.wav");
}
}
In above case we create and use myHumSound to play the background hum sound and reuse the myFxSound object to play any other WAV file that overlaps with the hum sound but does not overlap with each other.
WavPlayer::play
Call WavPlayer::play to play a WAV file from the microSD card.
Syntax
bool play(const char* filename, PlayMode mode = PlayModeNormal);
Parameters
The filename parameter is a string that indicates the WAV file to play.
The mode parameter indicates the playback mode and can be one of the following values:
- PlayModeNormal: the WAV file is played once
- PlayModeLoop: the WAV file is played in loop mode. Once it finishes, it will start playing again
- PlayModeBlocking: the WAV file is played once and the function returns after the WAV file is done playing
If the mode parameter is omitted, it is defaulted to PlayModeNormal.
Returns
The function returns true on success, false otherwise.
Notes
Playing a WAV file happens asynchronously (unless PlayModeBlocking is specified). This means that the function returns immediately and your program keeps running.
If the WavPlayer object was already playing a WAV file when WavPlayer::play is called, the previous WAV file playback is stopped.
Example
WavPlayer mySound;
WavPlayer myOtherSound;
void setup()
{
Audio.begin();
// Play music in loop mode
mySound.play("music.wav", PlayModeLoop);
// Play boom.wav (that's inside the folder 'sounds') in blocking mode
myOtherSound.play("sounds/boom.wav", PlayModeBlocking);
// After boom.wav is done playing, play roar.wav
myOtherSound.play("roar.wav"); // Normal mode
// Program continues ...
WavPlayer::playRandom
Call WavPlayer::playRandom to play a random WAV file from the microSD. This function randomly chooses a file that has the format nameX.WAV where the name part is the filename parameter and the X part is a random number between the min and max parameters.
When this function is called, a random number between min and max is chosen and it is appended to filename.
Syntax
bool playRandom(const char* filename, uint32_t min, uint32_t max, PlayMode mode = PlayModeNormal);
Parameters
The filename parameter is a string that indicates the WAV file to play without extension.
The min parameter is the minimum possible number that will be appended to the filename parameter, for example 0.
The max parameter is the maximum possible number that will be appended to the filename parameter, for example 10.
The mode parameter indicates the mode and can be one of the following values:
- PlayModeNormal: the WAV file is played once
- PlayModeLoop: the WAV file is played in loop mode. Once it finishes, it will start playing again
- PlayModeBlocking: the WAV file is played once and the function returns after the WAV file is done playing
If the mode parameter is omitted, it is defaulted to PlayModeNormal.
Returns
The function returns true on success, false otherwise.
Notes
Playing a WAV file happens asynchronously (unless PlayModeBlocking is specified). This means that the function returns immediately and your program keeps running.
If the WavPlayer object was already playing a WAV file when WavPlayer::playRandom is called, the previous WAV file playback is stopped.
Example
Let’s say you have a group of WAV files that are named from sound0.WAV to sound20.WAV and you want to pick a random file among them. In that case you can use:
WavPlayer mySound;
void setup()
{
Audio.begin();
// Play a random sound between sound0.WAV and sound20.WAV
// Note that the code here below doesn't specify the .WAV extension
mySound.playRandom("sound", 0, 20);
// Program continues
Now let’s imagine that the WAV files are located inside a folder named font1. In that case the code would be:
WavPlayer mySound;
void setup()
{
Audio.begin();
// Play a random sound between sound0.WAV and sound20.WAV
// Note that the code here below doesn't specify the .WAV extension
mySound.playRandom("font1/sound", 0, 20);
// Program continues
WavPlayer::stop
Use the WavPlayer::stop function to stop playing a WAV file. The corresponding WAV file is closed and. To play the same file (or other file) you need to call the WavPlayer::play function again.
Syntax
bool stop();
Parameters
None.
Returns
The function returns true on success, false otherwise.
Example
WavPlayer myHumSound; // To play a background hum sound
void setup()
{
// Initialize Audio
Audio.begin();
// Use myHumSound to play a background hum in loop mode
myHumSound.play("hum.wav", PlayModeLoop);
}
void loop()
{
// Detect power off condition
if (do_power_off)
{
// Stop playing the hum sound
myFxSound.stop();
do_power_off = false;
}
}
WavPlayer::pause
Call the WavPlayer::pause function to pause the playback of an audio file. Call WavPlayer::resume to resume playback.
Syntax
bool pause();
Parameters
None.
Returns
The function returns true on success. If the playback is already paused or stopped the function returns false.
Example
WavPlayer myHumSound; // To play a background hum sound
void setup()
{
// Initialize Audio
Audio.begin();
// Use myHumSound to play a background hum in loop mode
myHumSound.play("hum.wav", PlayModeLoop);
// Wait 1 second
delay(1000);
// Pause playback
myHumSound.pause();
// Pause 1 second
delay(1000);
// Resume playback
myHumSound.resume();
}
WavPlayer::resume
The WavPlayer::resume function resumes the playback of a WAV file previously paused with WavPlayer::pause.
Syntax
void resume();
Parameters
None.
Returns
The function returns true on success. If the playback is already playing or stopped the function returns false.
Example
See the example for WavPlayer::pause.
