gtkIOStream is a versatile software for signal processing and audio processing, amongst other features (such as GUI programming).

In this tutorial we will focus on loading audio from file (almost any type of audio file format) and saving it back to file (almost any audio file format).

Before we start, you have to have compiled and installed gtkIOStream. For certain components of gtkIOStream its compilation and installation isn't necessary, but for certain parts of audio processing it is necessary. Tutorial 0 guides you through how to install and test the installation of gtkIOStream. Before you start this tutorial, you must have it installed first.

Our first step is to open the standard lightweight Raspberry Pi IDE with a blank file for us to code up in ... like so :

Here we tell it to use type int, because that is 32 bits and Sox's internal type is 32 bits as well. This typename is used mainly for working out the word size (a sox requirement) when opening write files.

Now here we open the first input argument "argv[1]" and test for standard errors. You will also notice that we ignore the SOX_READ_MAXSCALE_ERROR error. This MAXSCALE_ERROR is thrown when Sox can't fund the inputFile.max text file. This text file is used to rescale the sox input data according to the scale factor in that file. If that file exists and say the factor is 0.0001, then sox will load in audio data from the audio file and rescale it from maxscale down to a maxscale value of 0.0001. This is rather significant, because 0.0001 represents around 13 bits of data! That means, say you processed a file and its highest value was 0.0001, then by saving it to an audio file, you may loose 13 bits of data ... wow ! Say for example you were using 16 bit audio file formats - that leaves 3 bits for audio dynamic range ... now I think you start to understand the problem I am getting at here - we need to preserve low noise levels and still be able to capture audio waveforms at their original sound level - a very improtant thing for signal processing - particularly when the system is calibrated.

We now make an buffer to hold audio data (perhaps you want to do computations on that buffer before writing back out to file) :

int N=100*1024; // number of frames to load in each time
ret=sox.read(x, N);
if ((ret=sox.read(x, N))!=0) // read in again
return SoxDebug().evaluateError(ret);

We set N to 100k samples per channel and we ask sox to read that audio data in (sox.read). We check if there was an error, and if so then we report the error and return it - exiting. The SoxDebug class prints out error information and allows you to print error info and return the error in one command. It is currently out of the scope of this tutorial and will be left there.

Now we know the sample rate of the input audio file (the sox.getFSIn method), the number of channels (x.cols) and we can open the output file for writing :

Actially Sox will close them for you when the class destructs, but what if we wanted to open a new file again ? Actually if you call openWeite or openRead again it will first close an open file ... just for robustness - it also allows you to simplify your code base minimising calls.

The pkg-config statement tells g++ about preprocessor flags and what libraries to link against - you can type this into the command line and see it for yourself : pkg-config --cflags --libs gtkIOStream
We compile and create the output file SoxInOut. It will print a couple of warnings like so :

I feel like I'm missing somthing very small but i've tried everything i can think of. when I try to compile the program I get this error "g++: error: SoxInOut.C: No such file or directory". (similar issue when i try tutorial 2)

my ./configure output is the same. I've located /usr/include/gtkIOStream/Sox.H and it exists. If i hard code its location i get the same error but with debug.h

this is the output of pkg-config --cflags --libs gtkIOStream. I don't see Sox.h but im not sure thats the issue.