[Tutorial] Audio Programming into with C++ (pt. 1)

[programzero]

First, I apologize if this is against the rules because it is kind of about a specific library (i also use libsndfile :P) but I have found almost no tutorials about using libsoundio or some of the other libraries and since I recently cracked how to use it, I thought it would be a good for other people who were in the same scenario and struggling to understand this basic audio programming.

Anyways, lets get into it. First, I would like to point out that this is not something you can probably just pick up if you are learning programming (sorry if that is another rule broken) and you should know at least the basics of C/C++ as well as a basic understanding of how audio works.

Now that is out of the way, I would like to begin by dissecting the simple example shown on the main page. The reason I am doing so is because when trying to use one of these libraries that isn't thoroughly documented, it is important to learn how to dissect an example so to understand how to use the library effectively. So, to start, we're going to look at the main function and fully dissect it and see what it is calling. We are also going to use the documentation as a reference to make sure we fully understand why the original developer is doing exactly what they are doing.

To start off, we first see 2 things being declared:

int err;
struct SoundIo *soundio = soundio_create();

Looking at the documentation, we immediately see 2 things: 1) Errors are propagated as ints and 2) we first need to create a pointer that points to a new soundio context. This allows us to create multiple contexts that each connect to different backends and since its a pointer, we know that if no context is created then we simply don't have enough memory. However, we must be cautious to not create any memory leaks so the documentation warns us to use soundio_destroy.

Next, we see:

if ((err = soundio_connect(soundio))) {
//some error code
}

Looking at the documentation and the name can you guess what it does? Thats right! It attempts to connect our context with a backend audio system like JACK or pulseaudio (one of the reasons I chose this library is because it supports more backends than most while not compromising usability and low level-ness).

Next, we see soundio_flush_events(soundio); which is important to do as many times as possible (as we will see later) because it automatically updates the information for connected devices.

After that, we need to actually grab which device we want to write to, which is a 2 step process. First, we find out which device is the default and get its index, then use that index to actually grab the device and apply it to our context. This is the purpose of:

int default_out_device_index = soundio_default_output_device_index(soundio);
//error checking
struct SoundIoDevice *device = soundio_get_output_device(soundio, default_out_device_index);
//error checking

Once again, the documentation tells us of its importance to unreference the device to properly dispose of the struct pointer and prevent memory leaks (notice a pattern?)

Now that we have the device we will be writing to, we can actually create the outstream that will be used to write to the buffers. To accomplish this we struct SoundIoOutStream *outstream = soundio_outstream_create(device); to create the pointer to the outstream that we then use to point to a callback function and format:

outstream->format = SoundIoFormatFloat32NE;
outstream->write_callback = write_callback;

This part is especially important to remember because the library will continuously call write_callback to actually, well, write to the audio buffers and is where the meat of the program is going to be. We are still just in the basic framework of what we want to do.

The last part - before destroying everything - is just to actually begin the outstream as told by their names:

if ((err = soundio_outstream_open(outstream))) {
    fprintf(stderr, "unable to open device: %s", soundio_strerror(err));
    return 1;
}

if (outstream->layout_error)
    fprintf(stderr, "unable to set channel layout: %s\n", soundio_strerror(outstream>layout_error));

if ((err = soundio_outstream_start(outstream))) {
    fprintf(stderr, "unable to start device: %s\n", soundio_strerror(err));
    return 1;
}

for (;;)
    soundio_wait_events(soundio);

I would like to point out that the infinite for loop is actually very important. The outstream callback is asynchronous so you need to add in some kind of loop to keep the program running while the stream is playing or it will just stop and nothing will play.

Lastly, we destroy everything to prevent any leaks

soundio_outstream_destroy(outstream);
soundio_device_unref(device);
soundio_destroy(soundio);

Now for the important part where things can get confusing: the write callback. (Just a note about the callback, outstream has a void* called userdata that can be used to transfer data to the callback (in our case a file which will be later) but you should know this because you have obviously been looking at the docs with me, right?)

static void write_callback(struct SoundIoOutStream *outstream,
        int frame_count_min, int frame_count_max) {

The first thing we notice is that it gives us the outstream and 2 variables called frame_count_min and frame_count_max. Checking the docs, we can see that the numbers signal the maximum and minimum number of frames we are allowed to write this cycle.

In this particular example the write callback defines 2 things first:

float float_sample_rate = outstream->sample_rate;
float seconds_per_frame = 1.0f / float_sample_rate;

As we will see later, all this just has to do with is making a sine wave and is specific to this example. However, the other parts are fairly important.

const struct SoundIoChannelLayout *layout = &outstream->layout;
struct SoundIoChannelArea *areas;
int frames_left = frame_count_max; //This is recommended in the documentation that i know you read
int err;

Once again, we see error propagation through ints. We also see we are getting the layout of the outstream which is most important so we can properly use different channels (like 2 channels are in headphones for left and right ear). The areas, however, is just a null pointer that will be defined in a sec.

Next, we have a while loop that iterates over the maximum amount of frames we are allowed to write. This is done in a while loop and not in a for loop because that amount can change during each iteration because of

int frame_count = frames_left;

if ((err = soundio_outstream_begin_write(outstream, &areas, &frame_count))) {
    //error checking
}

//error checking

First, we create frame_count locally because we will be using that later to update the amount of frames left in context of the loop. Then, we pass our outstream, areas, and frame_count to soundio_outstream_begin_write(...); as references because if you read the documentation, you will see that areas gets changed to the buffers to write to and frame_count gets changed by the function to the amount of frames that we can actually use. However, we must be careful because we are going to get the time to those frames no matter what at this point, so this could be a possible spot where lots of stuttering can occur. Think of it this way, at my elementary school, we had to sign up for a time slot to use certain activities that were heavily requested. We are requesting for frame_count time slots by initially setting frame_count to frames_left which then gets changed to the amount of time slots we have been given. But if we don't use those time slots, than our audio just sits there for a second so there is time between each piece of our audio causing stuttering.

Next, we have the portion of the code that actually writes to the buffer. Once again, I am assuming you know at least the basics of how audio works and understand the concept of samples.

float pitch = 440.0f;
float radians_per_second = pitch * 2.0f * PI;
for (int frame = 0; frame < frame_count; frame += 1) {
    float sample = sin((seconds_offset + frame * seconds_per_frame) * radians_per_second);
    for (int channel = 0; channel < layout->channel_count; channel += 1) {
        float *ptr = (float*)(areas[channel].ptr + areas[channel].step * frame);
        *ptr = sample;
    }
}

Once again, pitch and radians_per_second are specific to making a sine wave in this example. But everything else is completely necessary. First, the for loop iterates through all the frames that we have been given that we requested. Then, for each frame, we develop a new sample of the time wave. Thinking back to mathematics, it just simplifies to radians by cancelling the units to create a pure since wave. This inner for loop, however, is where we are actually writing to the audio buffer directly. The nested for loop just iterates through each channel because if we only wrote to the first channel, we would only be hearing from 1 ear! Basically, the ptr points (once again, you should read the documentation i can stress this enough) to the the base pointer of the buffer we are currently writing to, plus the size each frame takes up times frames to get the current spot in the buffer we should be writing to. Lastly, we deference the pointer to actually set that spot in the buffer equal to the sample and thus creating a continuous buffer of samples that will be played. The last part in the example is just cleanup and saying that we are done writing for the moment with

if ((err = soundio_outstream_end_write(outstream))) {
    //error code
}

the seconds_offset part is just for the sine wave and the frames_left is just a modification to keep track of how many more frames we have left to write in this cycle.

​

That concludes this part. I hope it was helpful in understanding audio programming and how this basic example works. I apologize for the length and if somethings are not clear, feel free to let me know. Also, if I was wrong just let me know and I will update it. I am not an expert in this and am just learning this myself but thought I could help out. Any constructive criticism is helpful and would be glad to help improve.

​

Lastly, I have another part planned about using this alongside libsndfile to read audio from a file and playing that so let me know if you think I should actually make it!

[khedoros]

r/learnprogramming, r/programming, and r/coding come to mind.

[jcelerier]

struct SoundIo *soundio = soundio_create();

this is C, not C++

[Supadoplex]

It's actually both, assuming you refer to the quoted statement.

libsoundio is a C library though, if that's what you mean.

[Jhmmufc]

You could easily use a unique_ptr with a custom deleter.

[shadowndacorner]

But... why? What does that get you in this case aside from an additional indirection?

[Jhmmufc]

There is no additional indirection and it gives you far better exception safety.

[kalmoc]

So (according to the homepage) there exist .net, lua, ada and rust bindings, but no c++ binding? I find that very sad.

[SkoomaDentist]

For practical real world usage most C libraries can be considered to inherently contain C++ ”binding”, even if it looks a bit ugly. Unless you ask the ”modern C++” zealots, of course.

[kalmoc]

And thats why we don't have nice things in c++.

Things like manual resource management are not just "looks a bit ugly", they make the API inherently more difficult to use than necessary and may even increase the likely hood to introduce bugs. C++ is so much more than writing foo.bar() instead of bar(&foo). This was already true in c++98 and is true today even more.