Stream support

Author: pschatzmann

.DS_Store

@@ -1,43 +1,119 @@
 # Arduino Audio Tools
 
-Some basic C++ classes that can be used for Audio Processing privided as Arduino Library
+Some basic __header-only C++ classes__ that can be used for __Audio Processing__ provided as __Arduino Library__:
 
-- Additional Stream implementations: MemoryStream - ESP32 only: UrlStream, I2SStream
-- a simple I2S class (to read and write to the internal I2S) [ESP32 only]
-- a simple ADC class (to read analog data with the help of I2S) [ESP32 only]
+- 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) 
+- Additional Stream implementations: MemoryStream, UrlStream, I2SStream, A2DPStream, PrintStream
 - Converters
-- Musical Notes (with Frequencies of notes)
+- Musical Notes (with frequencies of notes)
 - SineWaveGenerator (to generate some sine tone)
 - 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 with ESP8266Audio
+- 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. 
+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 use them to write out print messages and sometimes we use them to read the output from Serial devices. The same thing applies to my “Audio Streams”: You can read audio data from “Audio Sources” and you write them to “Audio Sinks”.
 
-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.
+As “Audio Sources” we will have e.g.:
 
+- Analog Microphones – AnalogStream
+- Digital Microphonse – I2SStream
+- Files on the Internet – UrlStream
+- Generated Sound – GeneratedSoundStream
+- Mobile Phone A2DP Bluetooth – A2DPStream
+- Binary Data in Flash Memory – MemoryStream
+- SD Files
 
-## Optional Libraries
+As “Audio Sinks” we will have e.g:
 
-Dependent on the example you might need to install some of the following libraries:
+- external DAC – I2SStream
+- an Amplifier – AnalogStream
+- Bluetooth Speakers – A2DPStream
+- Serial to display the data as CSV – CsvStream.
+- SD Files
+
+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](Scenarios.md)
+
+
+## Examples
 
-- [ESP32-A2DP Library](https://github.com/pschatzmann/ESP32-A2DP)
-- [ESP8266Audio](https://github.com/earlephilhower/ESP8266Audio)
-- [SD Library](https://www.arduino.cc/en/reference/SD)
-- [arduino-fdk-aac](https://github.com/pschatzmann/arduino-fdk-aac)
+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).
 
-# Examples
+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
+
+- [streams-url_raw-serial](/examples/streams-url_raw-serial) Displaying a music file from the internet on the Serial Plotter
+- [streams-generator-serial](/examples/streams-generator-serial) Displaying generated sound on the Serial Plotter
+- [streams-adc-serial](/examples/streams-adc-serial) Displaying input from analog microphone on the Serial Plotter
+- [streams-i2s-a2dp](examples/streams-i2s-a2dp) - Sample analog sound and write it to a A2DP Bluetooth source 
+- [streams-file_raw-a2dp](examples/streams-file_raw-a2dp) - Read Raw File from SD card write it A2DP Bluetooth 
+- [streams-adc-a2dp](examples/streams-adc-a2dp) - Sample analog sound from analog microphone and send it to Bluetooth Speaker 
+- [streams-memory_raw-i2s_external_dac](examples/streams-memory_raw-i2s_external_dac) - Play music form Flash Memory via I2S to External DAC
+
+... 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](examples/base-adc-serial) - Sample analog sound and write it to Serial
+- [base-adc-a2dp](examples/base-adc-a2dp) - Sample analog sound and write it to a A2DP Bluetooth source 
+- [base-file_raw-serial](examples/base-file_raw-serial) - Read Raw File from SD card to and write it to Serial
+- [base-file_raw-a2dp](examples/base-file_raw-a2dp) - Read Raw File from SD card write it A2DP Bluetooth
+- [base-file_mp3-a2dp](examples/base-file_mp3-a2dp) - Stream MP3 File from SD card to A2DP Bluetooth using the ESP8266Audio library
+- [base-i2s-serial](examples/base-i2s-serial) - Sample digital sound and write it to Serial
+- [base-i2s-a2dp](examples/base-i2s-a2dp) - Sample analog sound and write it to a A2DP Bluetooth source 
+
+
+
+## Optional Libraries
+
+Dependent on the example you might need to install some of the following libraries:
+
+- [ESP32-A2DP Library](https://github.com/pschatzmann/ESP32-A2DP) to support A2DP Bluetooth Audio
+- [ESP8266Audio]( ) to play different audio Formats
+- [SD Library](https://www.arduino.cc/en/reference/SD) to read and write files.
+- [arduino-fdk-aac](https://github.com/pschatzmann/arduino-fdk-aac) to encode or decode AAC 
 
-- [adc-a2dp](examples/adc-a2dp) - Stream Analog input to A2DP Bluetooth 
-- [adc-serial](examples/adc-serial) - Stream Analog input to Serial
-- [file_raw-a2dp](examples/file_raw-a2dp) - Stream Row File from SD card to A2DP Bluetooth
-- [file_raw-serial](examples/file_raw-serial) - Stream Raw File from SD card to Serial
-- [file_mp3-a2dp](examples/file_mp3-a2dp) - Stream MP3 File from SD card to A2DP Bluetooth using the ESP8266Audio library
-- [i2s-a2dp](examples/i2s-a2dp) - Stream I2S Input to A2DP Bluetooth
-- [i2s-serial](examples/i2s-serial) - Stream I2S Input to Serial
 
 
 ## Installation
@@ -52,7 +128,9 @@ git clone pschatzmann/arduino-audio-tools.git
 
 ## Documentation
 
-Here is the generated [Class documentation](https://pschatzmann.github.io/arduino-audio-tools/html/annotated.html). You might find further information in [one of my blogs](https://www.pschatzmann.ch/home/category/machine-sound/)
+Here is the generated [Class documentation](https://pschatzmann.github.io/arduino-audio-tools/html/annotated.html). 
+
+You also might find further information in [one of my blogs](https://www.pschatzmann.ch/home/category/machine-sound/)
 
 ## Project Status
 
@@ -63,7 +141,7 @@ This is currently work in progress:
 | Analog input - ADC     | tested  |
 | I2S                    | tested  |
 | Files (RAW, MP3...)    | tested  |
-| Streams                | open    |
+| Streams                | tested  |
 | WAV encoding/deconding | open    |          
 | AAC encoding/deconding | open    |          
 | int24_t                | tested  |           

README.md

@@ -0,0 +1,53 @@
+# Schenarios
+
+### Supported Architectures
+
+Unfortunatly Arduino does not provide an I2S functionality which is standrdized acress the different processors. There is only an official documentation for SAMD21 processors. The full functionality of the library is currently only available on the ESP32: 
+
+
+| Processor      | I2SStream | ADCStream | A2DP   | UrlStream | Other  |
+|----------------|-----------|-----------|--------|-----------|--------|
+| ESP32          |  +        |  +        |   +    |   +       |   +    |
+| ESP8266        |  *        |  *        |        |           |   +    |
+| SAMD21         |  *        |           |        |           |   +    |
+| Raspberry Pico |           |           |        |           |   +    |
+ 
+
++ supported
+* not tested
+
+
+### Supported Schenarios
+
+Here are the related Stream classes with their supported operations that can be used:
+
+| Class                   | Read | Write | Comments           |
+|-------------------------|------|-------|--------------------|
+| I2SStream               |   +  |   +   | i2s                |
+| AnalogAudioStream       |   +  |   +   | adc, dac           |
+| MemoryStream            |   +  |   +   | memory             |
+| UrlStream               |   +  |       | url                |
+| A2DPStream              |   +  |   +   | a2dp               |
+| GeneratedSoundStream    |   +  |       | gen                |
+| AudioOutputWithCallback |   +  |   +   |                    |
+| CsvStream               |      |   +   | csv                |
+| File                    |   +  |   +   | From SD library    |
+| Serial, ...             |   +  |   +   | Std Arduino        |
+
+
+
+In theory we should be able to support the following scenarios:
+
+| Input  | dac  | i2s | file | a2dp | Serial | csv  |
+|--------|------|-----|------|------|--------|------|
+| adc    |  +   |  +  |   +  |  +   |   +    |  +   |
+| i2s    |  +   |  +  |   +  |  +   |   +    |  +   |
+| file   |  +   |  +  |   +  |  +   |   +    |  +   |
+| a2dp   |  +   |  +  |   +  |  -   |   +    |  +   |
+| Serial |  +   |  +  |   +  |  +   |   +    |  +   |
+| memory |  +   |  +  |   +  |  +   |   +    |  +   |
+| url    |  +   |  +  |   +  |  -   |   +    |  +   |
+| gen    |  +   |  +  |   +  |  +   |   +    |  +   |
+
+
+

Scenarios.md

@@ -17,17 +17,17 @@ using namespace audio_tools;
  * @brief We use a mcp6022 analog microphone as input and send the data to A2DP
  */ 
 
-ADC adc;
+AnalogAudio adc;
 BluetoothA2DPSource a2dp_source;
 // The data has a center of around 26427, so we we need to shift it down to bring the center to 0
-FilterScaler<int16_t> scaler(1.0, -26427, 32700 );
+ConverterScaler<int16_t> scaler(1.0, -26427, 32700 );
 
 // callback used by A2DP to provide the sound data
 int32_t get_sound_data(Channels* data, int32_t len) {
     arrayOf2int16_t *data_arrays = (arrayOf2int16_t *) data;
    // the ADC provides data in 16 bits
     size_t result_len = adc.read(data_arrays, len);   
-    scaler.process(data_arrays, result_len);
+    scaler.convert(data_arrays, result_len);
     return result_len;
 }
 
@@ -37,7 +37,7 @@ void setup(void) {
 
   // start i2s input with default configuration
   Serial.println("starting I2S-ADC...");
-  adc.begin(adc.defaultConfig());
+  adc.begin(adc.defaultConfig(RX_MODE));
 
   // start the bluetooth
   Serial.println("starting A2DP...");

docs/.DS_Store

@@ -17,27 +17,27 @@ using namespace audio_tools;
  * @brief We use a mcp6022 analog microphone on GPIO34 and write it to Serial
  */ 
 
-ADC adc;
+AnalogAudio adc;
 const int32_t max_buffer_len = 512;
 int16_t buffer[max_buffer_len][2];
 // The data has a center of around 26427, so we we need to shift it down to bring the center to 0
-FilterScaler<int16_t> scaler(1.0, -26427, 32700 );
+ConverterScaler<int16_t> scaler(1.0, -26427, 32700 );
 
 // Arduino Setup
 void setup(void) {
   Serial.begin(115200);
 
   // start i2s input with default configuration
   Serial.println("starting I2S-ADC...");
-  adc.begin(adc.defaultConfig());
+  adc.begin(adc.defaultConfig(RX_MODE));
 
 }
 
 // Arduino loop - repeated processing 
 void loop() {
   size_t len = adc.read(buffer, max_buffer_len); 
   // move center to 0 and scale the values
-  scaler.process(buffer, len);
+  scaler.convert(buffer, len);
 
   for (int j=0;j<len;j++){
     Serial.print(buffer[j][0]);

examples/adc-a2dp/README.md renamed to examples/base-adc-a2dp/README.md

@@ -11,7 +11,7 @@
 #include <SD.h>
 #include "AudioFileSourceSD.h"
 #include "AudioGeneratorMP3.h"
-#include "ESP8266AudioSupport.h"
+#include "AudioESP8266.h"
 #include "BluetoothA2DPSource.h"
 #include "AudioTools.h"