Repository files navigation

C library providing cross-platform audio input and output. The API issuitable for real-time software such as digital audio workstations as wellas consumer software such as music players.

This library is an abstraction; however in the delicate balance betweenperformance and power, and API convenience, the scale is tipped closer tothe former. Features that only exist in some sound backends are exposed.

• Supported operating systems:
  • Windows 7+
  • MacOS 10.10+
  • Linux 3.7+
• Supported backends:
  • JACK
  • PulseAudio
  • ALSA
  • CoreAudio
  • WASAPI
  • Dummy (silence)
• Exposes both raw devices and shared devices. Raw devices give you the bestperformance but prevent other applications from using them. Shared devicesare default and usually provide sample rate conversion and formatconversion.
• Exposes both device id and friendly name. id you could save in a config filebecause it persists between devices becoming plugged and unplugged, whilefriendly name is suitable for exposing to users.
• Supports optimal usage of each supported backend. The same API does theright thing whether the backend has a fixed buffer size, such as on JACK andCoreAudio, or whether it allows directly managing the buffer, such as onALSA, PulseAudio, and WASAPI.
• C library. Depends only on the respective backend API libraries and libc.Doesnot depend on libstdc++, and doesnot have exceptions, run-time typeinformation, orsetjmp.
• Errors are communicated via return codes, not logging to stdio.
• Supports channel layouts (also known as channel maps), important forsurround sound applications.
• Ability to monitor devices and get an event when available devices change.
• Ability to get an event when the backend is disconnected, for example whenthe JACK server or PulseAudio server shuts down.
• Detects which input device is default and which output device is default.
• Ability to connect to multiple backends at once. For example you could havean ALSA device open and a JACK device open at the same time.
• Meticulously checks all return codes and memory allocations and usesmeaningful error codes.
• Exposes extra API that is only available on some backends. For example youcan provide application name and stream names which is used by JACK andPulseAudio.

Complete program to emit a sine wave over the default device using the bestbackend:

#include<soundio/soundio.h>#include<stdio.h>#include<stdlib.h>#include<string.h>#include<math.h>staticconstfloatPI=3.1415926535f;staticfloatseconds_offset=0.0f;staticvoidwrite_callback(structSoundIoOutStream*outstream,intframe_count_min,intframe_count_max){conststructSoundIoChannelLayout*layout=&outstream->layout;floatfloat_sample_rate=outstream->sample_rate;floatseconds_per_frame=1.0f /float_sample_rate;structSoundIoChannelArea*areas;intframes_left=frame_count_max;interr;while (frames_left>0) {intframe_count=frames_left;if ((err=soundio_outstream_begin_write(outstream,&areas,&frame_count))) {fprintf(stderr,"%s\n",soundio_strerror(err));exit(1);        }if (!frame_count)break;floatpitch=440.0f;floatradians_per_second=pitch*2.0f*PI;for (intframe=0;frame<frame_count;frame+=1) {floatsample=sinf((seconds_offset+frame*seconds_per_frame)*radians_per_second);for (intchannel=0;channel<layout->channel_count;channel+=1) {float*ptr= (float*)(areas[channel].ptr+areas[channel].step*frame);*ptr=sample;            }        }seconds_offset=fmodf(seconds_offset+seconds_per_frame*frame_count,1.0f);if ((err=soundio_outstream_end_write(outstream))) {fprintf(stderr,"%s\n",soundio_strerror(err));exit(1);        }frames_left-=frame_count;    }}intmain(intargc,char**argv) {interr;structSoundIo*soundio=soundio_create();if (!soundio) {fprintf(stderr,"out of memory\n");return1;    }if ((err=soundio_connect(soundio))) {fprintf(stderr,"error connecting: %s",soundio_strerror(err));return1;    }soundio_flush_events(soundio);intdefault_out_device_index=soundio_default_output_device_index(soundio);if (default_out_device_index<0) {fprintf(stderr,"no output device found");return1;    }structSoundIoDevice*device=soundio_get_output_device(soundio,default_out_device_index);if (!device) {fprintf(stderr,"out of memory");return1;    }fprintf(stderr,"Output device: %s\n",device->name);structSoundIoOutStream*outstream=soundio_outstream_create(device);outstream->format=SoundIoFormatFloat32NE;outstream->write_callback=write_callback;if ((err=soundio_outstream_open(outstream))) {fprintf(stderr,"unable to open device: %s",soundio_strerror(err));return1;    }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",soundio_strerror(err));return1;    }for (;;)soundio_wait_events(soundio);soundio_outstream_destroy(outstream);soundio_device_unref(device);soundio_destroy(soundio);return0;}

When you usesoundio_connect, libsoundio tries these backends in order.If unable to connect to that backend, due to the backend not being installed,or the server not running, or the platform is wrong, the next backend is tried.

0. JACK
1. PulseAudio
2. ALSA (Linux)
3. CoreAudio (OSX)
4. WASAPI (Windows)
5. Dummy

If you don't like this order, you can usesoundio_connect_backend toexplicitly choose a backend to connect to. You can usesoundio_backend_countandsoundio_get_backend to get the list of available backends.

API Documentation

Install the dependencies:

• cmake
• ALSA library (optional)
• libjack2 (optional)
• libpulseaudio (optional)

mkdir buildcd buildcmake ..makesudo make install

You can build libsoundio withmxe. Follow therequirements section to install thepackages necessary on your system. Then somewhere on your file system:

git clone https://github.com/mxe/mxecd mxemake MXE_TARGETS='x86_64-w64-mingw32.static i686-w64-mingw32.static' gcc

Then in the libsoundio source directory (replace "/path/to/mxe" with theappropriate path):

mkdir build-win32cd build-win32cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/mxe/usr/i686-w64-mingw32.static/share/cmake/mxe-conf.cmakemake

mkdir build-win64cd build-win64cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/mxe/usr/x86_64-w64-mingw32.static/share/cmake/mxe-conf.cmakemake

For each backend, do the following:

0. Run the unit tests:./unit_tests. To see test coverage, install lcov, runmake coverage, and then viewcoverage/index.html in a browser.
1. Run the example./sio_list_devices and make sure it does not crash, andthe output looks good. If valgrind is available, use it.
2. Run./sio_list_devices --watch and make sure it detects when you plug andunplug a USB microphone.
3. Run./sio_sine and make sure you hear a sine wave. For backends with rawdevices, run./sio_sine --device id --raw (where 'id' is a device id yougot fromsio_list_devices and make sure you hear a sine wave.
   • Use 'p' to test pausing, 'u' to test unpausing, 'q' to test cleanup.
   • 'c' for clear buffer. Clear buffer should not pause the stream and itshould also not cause an underflow.
   • Use 'P' to test pausing from the callback, and then 'u' to unpause.
4. Run./underflow and read the testing instructions that it prints.
5. Run./sio_microphone and ensure that it is both recording and playingback correctly. If possible use the--in-device and--out-deviceparameters to test a USB microphone in raw mode.
6. Run./backend_disconnect_recover and read the testing instructions thatit prints.
7. Run./latency and make sure the printed beeps line up with the beeps thatyou hear.

Ensure thatdoxygen is installed,then:

make doc

Then look athtml/index.html in a browser.