Arduino Audio Tools

Some basic header-only C++ classes that can be used for Audio Processing provided as Arduino Library:

• a simple I2S class (to read and write to the internal I2S)
• a simple ADC class (to read analog data with the help of I2S)
• a simple PWM class (to write audio data with the help of PWM)
• Additional Stream implementations: MemoryStream, URLStream, I2SStream, A2DPStream, PrintStream,
• Converters
• Musical Notes (with frequencies of notes)
• SineWaveGenerator (to generate a sine tone) and Mozzi for more complex scenario
• NBuffer (Multi buffer for writing and reading of (audio) data)
• TimerAlarmRepeating (e.g. for sampling audio data using exact times) [ESP32 only]
• A Wav Encoder and Decoder
• AudioOutputWithCallback class to provide callback integration e.g. with ESP8266Audio

This functionality provides the glue which makes different audio processing components and libraries work together. We also provide plenty of examples that demonstrate how to implement the different scenarios. The design philosophy is based on the Arduino conventions: we use the begin() and end() methods to start and stop the processing and we propagate the use of Streams. We all know the Arduino Streams: We usually use them to write out print messages and sometimes we use them to read the output from Serial devices. The same thing applies to “Audio Streams”: You can read audio data from “Audio Sources” and you write them to “Audio Sinks”.

As “Audio Sources” we will have e.g.:

• Analog Microphones – AnalogAudioStream
• Digital Microphones – I2SStream
• Files on the Internet – URLStream
• Generated Sound – GeneratedSoundStream
• Mobile Phone A2DP Bluetooth – A2DPStream
• Binary Data in Flash Memory – MemoryStream
• Any other Arduino Classes implementing Streams: SD, Ethernet etc

As “Audio Sinks” we will have e.g:

• external DAC – I2SStream
• with an Amplifier – AnalogAudioStream
• with a Piezo Electric Element – PWMAudioStream
• Bluetooth Speakers – A2DPStream
• Serial to display the data as CSV – CsvStream
• Any other Arduino Classes implementing Streams: SD, Ethernet etc

Here is an simple example which streams a file from the Flash Memory and writes it to I2S:

#include "AudioTools.h"
#include "StarWars30.h"

using namespace audio_tools;  

uint8_t channels = 2;
uint16_t sample_rate = 22050;

MemoryStream music(StarWars30_raw, StarWars30_raw_len);
I2SStream i2s;  // Output to I2S
StreamCopyT<int16_t> copier(i2s, music); // copies sound into i2s

void setup(){
    Serial.begin(115200);

    I2SConfig config = i2s.defaultConfig(TX_MODE);
    config.sample_rate = sample_rate;
    config.channels = channels;
    config.bits_per_sample = 16;
    i2s.begin(config);
}

void loop(){
    if (!copier.copy2()){
      i2s.end();
      stop();
    }
}

A complete list of the supported Audio Stream classes and scenarios can be found in the Scenarios Document

Sound Output

• I2SStream: The best quality can be achieved with the help of I2S and an external DAC. I2S is supporting 2 channels only.
• AnalogAudioStream: Some processors are providing an analog output, this is usually an easy and good approach: The number of pins (and herewith output channels) however is usually very limited.
• PWMAudioStream: The last possibility is to simulate an analog output with the help of PWM by using a frequency which is beyond the audible range of 20 KHz. This method is supported by all processors and usually supports a bigger number of output pins. In terms of audio quality this is usually the worst option.

Examples

The examples follow the following naming convention: "scenario type"-"source"-"destination". For the scenario types we might have base (using basic api functionality), stream for examples using Streams and test for the test cases.

For the source we currently have adc for analog input devices like analog microphones, i2s for digital input devices (e.g. digital microphones), file for SD files and a2dp for input from Bluetooth A2DP (e.g. from a Mobile Phone).

For the destination we use dac for analog output (e.g. to an amplifier), i2s for digital output devices (e.g. an external DAC), file for SD files and a2dp for output to Bluetooth A2DP (e.g. a Bluetooth Speaker).

Here is the list of examples:

Stream API

Here are a couple of simple test sketches to demo different output destinations:

• streams-generator-serial Displaying generated sound on the Serial Plotter
• streams-generator-i2s Output of generated sound on external DAC via I2S
• streams-generator-dac Output of generated sound on ESP32 internal DAC via I2S
• streams-generator-a2dp Output of generated sound on Bluetooth Speaker using A2DP
• streams-generator-pwm Output of generated sound with PWM
• streams-adc-serial Displaying input from analog microphone on the Serial Plotter
• streams-memory_wav-serial Decoding of WAV from Flash memory and display on the Serial Plotter

And some more useful examples:

• streams-memory_raw-i2s - Play music form Flash Memory via I2S to External DAC
• streams-url_raw-serial Displaying a music file from the internet on the Serial Plotter
• streams-url_raw-I2S.ino Streaming a File from the Internet to on external DAC via I2S
• streams-url_wav-i2s Text to Speach example using Rhasspy

... these are just a few examples, but you can combine any Input Stream with any Output Stream as you like...

Basic API

• base-adc-serial - Sample analog sound and write it to Serial
• base-adc-a2dp - Sample analog sound and write it to a A2DP Bluetooth source
• base-file_raw-serial - Read Raw File from SD card to and write it to Serial
• base-file_raw-a2dp - Read Raw File from SD card write it A2DP Bluetooth
• base-file_mp3-a2dp - Stream MP3 File from SD card to A2DP Bluetooth using the ESP8266Audio library
• base-i2s-serial - Sample digital sound and write it to Serial
• base-i2s-a2dp - Sample analog sound and write it to a A2DP Bluetooth source

Listening to the Result with a Webbrowser

I am also providing a simple webserver which can render the audio data as wav result. Here are some examples:

• streams-generator-webserver_wav A Webserver which renders some generated sound
• streams-sam-webserver_wav A Webserver which renders the result from the SAM TTS engine
• streams-tts-webserver_wav A Webserver which renders the result from the Arduino TTS engine
• streams-flite-webserver_wav A Webserver which renders the result from the Flite TTS engine

Logging

The application uses a built in logger (see AudioLogger.h and AudioConfig.h). You can e.g. deactivate the logging by changing USE_AUDIO_LOGGING to false in the AudioConfig.h:

#define USE_AUDIO_LOGGING false
#define LOG_LEVEL AudioLogger::Warning
#define LOG_STREAM Serial

Per default we use the log level warning and the logging output is going to Serial. You can also change this in your sketch by calling AudioLogger begin with the output stream and the log level e.g:

AudioLogger::instance().begin(Serial, AudioLogger::Debug);

Optional Libraries

Dependent on the example you might need to install some of the following libraries:

• ESP32-A2DP Library to support A2DP Bluetooth Audio
• ESP8266Audio to play different audio Formats
• SD Library to read and write files.
• arduino-fdk-aac to encode or decode AAC
• Mozzi A sound synthesis library for Arduino
• SAM A Text to Speach Engine
• TTS A Text to Speach Engine
• flite A Text to Speach Engine

Installation

You can download the library as zip and call include Library -> zip library. Or you can git clone this project into the Arduino libraries folder e.g. with

cd  ~/Documents/Arduino/libraries
git clone pschatzmann/arduino-audio-tools.git

Documentation

Here is the generated Class documentation.

You also might find further information in one of my blogs

Project Status

This is currently work in progress:

Functionality	Status
Analog input - ADC	tested
I2S	tested
PWM Output	tested
Files (RAW, MP3...)	tested
Streams	tested
WAV encoding/deconding	tested
AAC encoding/deconding	open
int24_t	tested