libsoundio is a lightweight abstraction over various sound drivers. It provides a well-documented API that operates consistently regardless of the sound driver it connects to. It performs no buffering or processing on your behalf; instead exposing the raw power of the underlying backend.

libsoundio is appropriate for games, music players, digital audio workstations, and various utilities.

libsoundio is serious about robustness. It even handles out of memory conditions correctly.

Features & Limitations

Supported operating systems: Linux 3.7+ MacOS 10.10+ Windows 7+

Supported backends: JACK PulseAudio ALSA CoreAudio WASAPI Dummy (silence)

Exposes both raw devices and shared devices. Raw devices give you the best performance but prevent other applications from using them. Shared devices are default and usually provide sample rate conversion and format conversion.

Exposes both device id and friendly name. id you could save in a config file because it persists between devices becoming plugged and unplugged, while friendly name is suitable for exposing to users.

Supports optimal usage of each supported backend. The same API does the right thing whether the backend has a fixed buffer size, such as on JACK and CoreAudio, or whether it allows directly managing the buffer, such as on ALSA or PulseAudio.

C library. Depends only on the respective backend API libraries and libc. Does not depend on libstdc++, and does not have exceptions, run-time type information, or setjmp.

Errors are communicated via return codes, not logging to stdio.

Supports channel layouts (also known as channel maps), important for surround 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 when the 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 have an ALSA device open and a JACK device open at the same time.

Meticulously checks all return codes and memory allocations and uses meaningful error codes.

Compare libsoundio to: PortAudio, RtAudio, SDL2, or JUCE.

MIT licensed.

Basic Sine Wave Example

#include <soundio/soundio.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <math.h> static const float PI = 3.1415926535f; static float seconds_offset = 0.0f; static void write_callback(struct SoundIoOutStream *outstream, int frame_count_min, int frame_count_max) { const struct SoundIoChannelLayout *layout = &outstream->layout; float float_sample_rate = outstream->sample_rate; float seconds_per_frame = 1.0f / float_sample_rate; struct SoundIoChannelArea *areas; int frames_left = frame_count_max; int err; while (frames_left > 0) { int frame_count = frames_left; if ((err = soundio_outstream_begin_write(outstream, &areas, &frame_count))) { fprintf(stderr, "%s

", soundio_strerror(err)); exit(1); } if (!frame_count) break; 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; } } seconds_offset = fmod(seconds_offset + seconds_per_frame * frame_count, 1.0); if ((err = soundio_outstream_end_write(outstream))) { fprintf(stderr, "%s

", soundio_strerror(err)); exit(1); } frames_left -= frame_count; } } int main(int argc, char **argv) { int err; struct SoundIo *soundio = soundio_create(); if (!soundio) { fprintf(stderr, "out of memory

"); return 1; } if ((err = soundio_connect(soundio))) { fprintf(stderr, "error connecting: %s

", soundio_strerror(err)); return 1; } soundio_flush_events(soundio); int default_out_device_index = soundio_default_output_device_index(soundio); if (default_out_device_index < 0) { fprintf(stderr, "no output device found

"); return 1; } struct SoundIoDevice *device = soundio_get_output_device(soundio, default_out_device_index); if (!device) { fprintf(stderr, "out of memory

"); return 1; } fprintf(stderr, "Output device: %s

", device->name); struct SoundIoOutStream *outstream = soundio_outstream_create(device); if (!outstream) { fprintf(stderr, "out of memory

"); return 1; } outstream->format = SoundIoFormatFloat32NE; outstream->write_callback = write_callback; 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

", soundio_strerror(outstream->layout_error)); if ((err = soundio_outstream_start(outstream))) { fprintf(stderr, "unable to start device: %s

", soundio_strerror(err)); return 1; } for (;;) soundio_wait_events(soundio); soundio_outstream_destroy(outstream); soundio_device_unref(device); soundio_destroy(soundio); return 0; }

Releases

2.0.0

Source

Not yet available on libsound.io

Windows Binary

Not yet available on libsound.io

2.0.0 API Documentation

release notes not yet available on libsound.io

1.1.0

Source

libsoundio-1.1.0.tar.gz

Windows Binary

libsoundio-1.1.0.zip

1.1.0 API Documentation

JACK: delete broken pause implementation. Previously, calling soundio_outstream_pause or soundio_instream_pause during the write_callback or read_callback would cause a deadlock. Now, attempting to pause always results in SoundIoErrorBackendIncompatible .

or during the or would cause a deadlock. Now, attempting to pause always results in . PulseAudio: improve latency handling code. It now passes the latency test along with all the other backends.

PulseAudio: fix incorrect outstream software_latency .

. libsoundio source code is now pure C, no C++ mixed in.

ALSA: better device detection. No longer suppress sysdefault. If default and sysdefault are missing, use the first device as the default device.

Workaround for Raspberry Pi driver that incorrectly reports itself as Output when it is actually Input.

ALSA: let alsa lib choose period settings. Fixes behavior with many ALSA devices.

ALSA: fix potential cleanup deadlock.

ALSA: fix crash for devices with null description, thanks to Charles Lehner.

CoreAudio: drop support for MacOS 10.9. There was a bug for this system that was never resolved, so it did not work in the first place.

Record example handles device not found and probe errors gracefully.

Fix typo in microphone example, thanks to James Dyson.

Improve documentation.

New functions available: soundio_version_string , soundio_version_major , soundio_version_minor , soundio_version_patch .

, , , . libsoundio source code now builds with MSVC, thanks to Raphaël Londeix.

1.0.3

Source

libsoundio-1.0.3.tar.gz

Windows Binary

libsoundio-1.0.3.zip

1.0.3 API Documentation

Architecture independent header files.

Add --latency and --sample-rate to sine example.

ALSA: fix deadlock under some circumstances.

dummy: fix deadlock when pause called from write_callback .

. Fix double clean-up corruption when opening stream fails.

Add --device and --raw to underflow test.

ALSA: use period size to calculate buffer size, fixes opening output stream sometimes resulting in an error.

1.0.2

Source

libsoundio-1.0.2.tar.gz

Windows Binary

libsoundio-1.0.2.zip

1.0.2 API Documentation

build: fix GNUInstallDirs not working.

docs: fix incorrect docs for soundio_instream_pause .

. PulseAudio: fix soundio_outstream_pause triggering assertion when called from within write_callback .

triggering assertion when called from within . fix mirrored memory not working on Linux (fixes corrupted data in ring buffer).

os: fix crash when creating non high priority thread fails.

docs: fix typos and cleanup.

fix and add test for soundio_device_nearest_sample_rate .

1.0.1

Source

libsoundio-1.0.1.tar.gz

Windows Binary

libsoundio-1.0.1.zip

1.0.1 API Documentation

libsoundio no longer depends on or links against libm.

ALSA: treat ALSA as unavailable when /dev/snd does not exist.

ALSA: remove duplicate assert.

ALSA: remove stray print statement.

ALSA: pausing returns error code when state is invalid instead of reaching assertion failure in pcm.c.

JACK: fix infinite loop when refreshing devices.

PulseAudio: better clear buffer implementation.

dummy backend: fix sometimes calling write_callback with frame_count_max equal to 0.

with equal to 0. os: fix some variables accidentally not declared static.

macos: fix not cleaning up condition variables.

macos: avoid allocation when getting time.

docs: note that read_callback and write_callback must be real time safe.

and must be real time safe. docs: record example demonstrates proper real time safety by not calling fwrite in read_callback .

. docs: add note to record example about shutting down.

docs: make microphone example latency a command line argument.

build: fix build on linux with clang.

build: static libs, examples, and tests are optional.

1.0.0

Source

libsoundio-1.0.0.tar.gz

Windows Binary

libsoundio-1.0.0.zip

1.0.0 API Documentation

Initial public release.

Projects Using libsoundio

About

The primary developer of libsoundio is Andrew Kelley, who can be found on GitHub. Consider donating $1 per month.