libsoundio  1.0.0
soundio.h File Reference

Go to the source code of this file.

Data Structures

struct  SoundIoChannelLayout
 The size of this struct is OK to use. More...
 
struct  SoundIoSampleRateRange
 The size of this struct is OK to use. More...
 
struct  SoundIoChannelArea
 The size of this struct is OK to use. More...
 
struct  SoundIo
 The size of this struct is not part of the API or ABI. More...
 
struct  SoundIoDevice
 The size of this struct is not part of the API or ABI. More...
 
struct  SoundIoOutStream
 The size of this struct is not part of the API or ABI. More...
 
struct  SoundIoInStream
 The size of this struct is not part of the API or ABI. More...
 

Macros

#define SoundIoFormatS16NE   SoundIoFormatS16LE
 
#define SoundIoFormatU16NE   SoundIoFormatU16LE
 
#define SoundIoFormatS24NE   SoundIoFormatS24LE
 
#define SoundIoFormatU24NE   SoundIoFormatU24LE
 
#define SoundIoFormatS32NE   SoundIoFormatS32LE
 
#define SoundIoFormatU32NE   SoundIoFormatU32LE
 
#define SoundIoFormatFloat32NE   SoundIoFormatFloat32LE
 
#define SoundIoFormatFloat64NE   SoundIoFormatFloat64LE
 
#define SoundIoFormatS16FE   SoundIoFormatS16BE
 
#define SoundIoFormatU16FE   SoundIoFormatU16BE
 
#define SoundIoFormatS24FE   SoundIoFormatS24BE
 
#define SoundIoFormatU24FE   SoundIoFormatU24BE
 
#define SoundIoFormatS32FE   SoundIoFormatS32BE
 
#define SoundIoFormatU32FE   SoundIoFormatU32BE
 
#define SoundIoFormatFloat32FE   SoundIoFormatFloat32BE
 
#define SoundIoFormatFloat64FE   SoundIoFormatFloat64BE
 
#define SOUNDIO_MAX_CHANNELS   24
 

Enumerations

enum  SoundIoError {
  SoundIoErrorNone, SoundIoErrorNoMem, SoundIoErrorInitAudioBackend, SoundIoErrorSystemResources,
  SoundIoErrorOpeningDevice, SoundIoErrorNoSuchDevice, SoundIoErrorInvalid, SoundIoErrorBackendUnavailable,
  SoundIoErrorStreaming, SoundIoErrorIncompatibleDevice, SoundIoErrorNoSuchClient, SoundIoErrorIncompatibleBackend,
  SoundIoErrorBackendDisconnected, SoundIoErrorInterrupted, SoundIoErrorUnderflow, SoundIoErrorEncodingString
}
 See also soundio_strerror. More...
 
enum  SoundIoChannelId {
  SoundIoChannelIdInvalid, SoundIoChannelIdFrontLeft, SoundIoChannelIdFrontRight, SoundIoChannelIdFrontCenter,
  SoundIoChannelIdLfe, SoundIoChannelIdBackLeft, SoundIoChannelIdBackRight, SoundIoChannelIdFrontLeftCenter,
  SoundIoChannelIdFrontRightCenter, SoundIoChannelIdBackCenter, SoundIoChannelIdSideLeft, SoundIoChannelIdSideRight,
  SoundIoChannelIdTopCenter, SoundIoChannelIdTopFrontLeft, SoundIoChannelIdTopFrontCenter, SoundIoChannelIdTopFrontRight,
  SoundIoChannelIdTopBackLeft, SoundIoChannelIdTopBackCenter, SoundIoChannelIdTopBackRight, SoundIoChannelIdBackLeftCenter,
  SoundIoChannelIdBackRightCenter, SoundIoChannelIdFrontLeftWide, SoundIoChannelIdFrontRightWide, SoundIoChannelIdFrontLeftHigh,
  SoundIoChannelIdFrontCenterHigh, SoundIoChannelIdFrontRightHigh, SoundIoChannelIdTopFrontLeftCenter, SoundIoChannelIdTopFrontRightCenter,
  SoundIoChannelIdTopSideLeft, SoundIoChannelIdTopSideRight, SoundIoChannelIdLeftLfe, SoundIoChannelIdRightLfe,
  SoundIoChannelIdLfe2, SoundIoChannelIdBottomCenter, SoundIoChannelIdBottomLeftCenter, SoundIoChannelIdBottomRightCenter,
  SoundIoChannelIdMsMid, SoundIoChannelIdMsSide, SoundIoChannelIdAmbisonicW, SoundIoChannelIdAmbisonicX,
  SoundIoChannelIdAmbisonicY, SoundIoChannelIdAmbisonicZ, SoundIoChannelIdXyX, SoundIoChannelIdXyY,
  SoundIoChannelIdHeadphonesLeft, SoundIoChannelIdHeadphonesRight, SoundIoChannelIdClickTrack, SoundIoChannelIdForeignLanguage,
  SoundIoChannelIdHearingImpaired, SoundIoChannelIdNarration, SoundIoChannelIdHaptic, SoundIoChannelIdDialogCentricMix,
  SoundIoChannelIdAux, SoundIoChannelIdAux0, SoundIoChannelIdAux1, SoundIoChannelIdAux2,
  SoundIoChannelIdAux3, SoundIoChannelIdAux4, SoundIoChannelIdAux5, SoundIoChannelIdAux6,
  SoundIoChannelIdAux7, SoundIoChannelIdAux8, SoundIoChannelIdAux9, SoundIoChannelIdAux10,
  SoundIoChannelIdAux11, SoundIoChannelIdAux12, SoundIoChannelIdAux13, SoundIoChannelIdAux14,
  SoundIoChannelIdAux15
}
 Specifies where a channel is physically located. More...
 
enum  SoundIoChannelLayoutId {
  SoundIoChannelLayoutIdMono, SoundIoChannelLayoutIdStereo, SoundIoChannelLayoutId2Point1, SoundIoChannelLayoutId3Point0,
  SoundIoChannelLayoutId3Point0Back, SoundIoChannelLayoutId3Point1, SoundIoChannelLayoutId4Point0, SoundIoChannelLayoutIdQuad,
  SoundIoChannelLayoutIdQuadSide, SoundIoChannelLayoutId4Point1, SoundIoChannelLayoutId5Point0Back, SoundIoChannelLayoutId5Point0Side,
  SoundIoChannelLayoutId5Point1, SoundIoChannelLayoutId5Point1Back, SoundIoChannelLayoutId6Point0Side, SoundIoChannelLayoutId6Point0Front,
  SoundIoChannelLayoutIdHexagonal, SoundIoChannelLayoutId6Point1, SoundIoChannelLayoutId6Point1Back, SoundIoChannelLayoutId6Point1Front,
  SoundIoChannelLayoutId7Point0, SoundIoChannelLayoutId7Point0Front, SoundIoChannelLayoutId7Point1, SoundIoChannelLayoutId7Point1Wide,
  SoundIoChannelLayoutId7Point1WideBack, SoundIoChannelLayoutIdOctagonal
}
 Built-in channel layouts for convenience. More...
 
enum  SoundIoBackend {
  SoundIoBackendNone, SoundIoBackendJack, SoundIoBackendPulseAudio, SoundIoBackendAlsa,
  SoundIoBackendCoreAudio, SoundIoBackendWasapi, SoundIoBackendDummy
}
 
enum  SoundIoDeviceAim { SoundIoDeviceAimInput, SoundIoDeviceAimOutput }
 
enum  SoundIoFormat {
  SoundIoFormatInvalid, SoundIoFormatS8, SoundIoFormatU8, SoundIoFormatS16LE,
  SoundIoFormatS16BE, SoundIoFormatU16LE, SoundIoFormatU16BE, SoundIoFormatS24LE,
  SoundIoFormatS24BE, SoundIoFormatU24LE, SoundIoFormatU24BE, SoundIoFormatS32LE,
  SoundIoFormatS32BE, SoundIoFormatU32LE, SoundIoFormatU32BE, SoundIoFormatFloat32LE,
  SoundIoFormatFloat32BE, SoundIoFormatFloat64LE, SoundIoFormatFloat64BE
}
 For your convenience, Native Endian and Foreign Endian constants are defined which point to the respective SoundIoFormat values. More...
 

Functions

struct SoundIosoundio_create (void)
 Create a SoundIo context. More...
 
void soundio_destroy (struct SoundIo *soundio)
 
int soundio_connect (struct SoundIo *soundio)
 Tries soundio_connect_backend on all available backends in order. More...
 
int soundio_connect_backend (struct SoundIo *soundio, enum SoundIoBackend backend)
 Instead of calling soundio_connect you may call this function to try a specific backend. More...
 
void soundio_disconnect (struct SoundIo *soundio)
 
const char * soundio_strerror (int error)
 Get a string representation of a SoundIoError. More...
 
const char * soundio_backend_name (enum SoundIoBackend backend)
 Get a string representation of a SoundIoBackend. More...
 
int soundio_backend_count (struct SoundIo *soundio)
 Returns the number of available backends. More...
 
enum SoundIoBackend soundio_get_backend (struct SoundIo *soundio, int index)
 get the available backend at the specified index (0 <= index < soundio_backend_count) More...
 
bool soundio_have_backend (enum SoundIoBackend backend)
 Returns whether libsoundio was compiled with backend. More...
 
void soundio_flush_events (struct SoundIo *soundio)
 Atomically update information for all connected devices. More...
 
void soundio_wait_events (struct SoundIo *soundio)
 This function calls soundio_flush_events then blocks until another event is ready or you call soundio_wakeup. More...
 
void soundio_wakeup (struct SoundIo *soundio)
 Makes soundio_wait_events stop blocking. More...
 
void soundio_force_device_scan (struct SoundIo *soundio)
 If necessary you can manually trigger a device rescan. More...
 
bool soundio_channel_layout_equal (const struct SoundIoChannelLayout *a, const struct SoundIoChannelLayout *b)
 Returns whether the channel count field and each channel id matches in the supplied channel layouts. More...
 
const char * soundio_get_channel_name (enum SoundIoChannelId id)
 
enum SoundIoChannelId soundio_parse_channel_id (const char *str, int str_len)
 Given UTF-8 encoded text which is the name of a channel such as "Front Left", "FL", or "front-left", return the corresponding SoundIoChannelId. More...
 
int soundio_channel_layout_builtin_count (void)
 Returns the number of builtin channel layouts. More...
 
const struct SoundIoChannelLayoutsoundio_channel_layout_get_builtin (int index)
 Returns a builtin channel layout. More...
 
const struct SoundIoChannelLayoutsoundio_channel_layout_get_default (int channel_count)
 Get the default builtin channel layout for the given number of channels. More...
 
int soundio_channel_layout_find_channel (const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel)
 Return the index of channel in layout, or -1 if not found. More...
 
bool soundio_channel_layout_detect_builtin (struct SoundIoChannelLayout *layout)
 Populates the name field of layout if it matches a builtin one. More...
 
const struct SoundIoChannelLayoutsoundio_best_matching_channel_layout (const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count, const struct SoundIoChannelLayout *available_layouts, int available_layout_count)
 Iterates over preferred_layouts. More...
 
void soundio_sort_channel_layouts (struct SoundIoChannelLayout *layouts, int layout_count)
 Sorts by channel count, descending. More...
 
int soundio_get_bytes_per_sample (enum SoundIoFormat format)
 Returns -1 on invalid format. More...
 
static int soundio_get_bytes_per_frame (enum SoundIoFormat format, int channel_count)
 A frame is one sample per channel. More...
 
static int soundio_get_bytes_per_second (enum SoundIoFormat format, int channel_count, int sample_rate)
 Sample rate is the number of frames per second. More...
 
const char * soundio_format_string (enum SoundIoFormat format)
 Returns string representation of format. More...
 
int soundio_input_device_count (struct SoundIo *soundio)
 When you call soundio_flush_events, a snapshot of all device state is saved and these functions merely access the snapshot data. More...
 
int soundio_output_device_count (struct SoundIo *soundio)
 Get the number of output devices. More...
 
struct SoundIoDevicesoundio_get_input_device (struct SoundIo *soundio, int index)
 Always returns a device. More...
 
struct SoundIoDevicesoundio_get_output_device (struct SoundIo *soundio, int index)
 Always returns a device. More...
 
int soundio_default_input_device_index (struct SoundIo *soundio)
 returns the index of the default input device returns -1 if there are no devices or if you never called soundio_flush_events. More...
 
int soundio_default_output_device_index (struct SoundIo *soundio)
 returns the index of the default output device returns -1 if there are no devices or if you never called soundio_flush_events. More...
 
void soundio_device_ref (struct SoundIoDevice *device)
 Add 1 to the reference count of device. More...
 
void soundio_device_unref (struct SoundIoDevice *device)
 Remove 1 to the reference count of device. More...
 
bool soundio_device_equal (const struct SoundIoDevice *a, const struct SoundIoDevice *b)
 Return true if and only if the devices have the same SoundIoDevice::id, SoundIoDevice::is_raw, and SoundIoDevice::aim are the same. More...
 
void soundio_device_sort_channel_layouts (struct SoundIoDevice *device)
 Sorts channel layouts by channel count, descending. More...
 
bool soundio_device_supports_format (struct SoundIoDevice *device, enum SoundIoFormat format)
 Convenience function. More...
 
bool soundio_device_supports_layout (struct SoundIoDevice *device, const struct SoundIoChannelLayout *layout)
 Convenience function. More...
 
bool soundio_device_supports_sample_rate (struct SoundIoDevice *device, int sample_rate)
 Convenience function. More...
 
int soundio_device_nearest_sample_rate (struct SoundIoDevice *device, int sample_rate)
 Convenience function. More...
 
struct SoundIoOutStreamsoundio_outstream_create (struct SoundIoDevice *device)
 Allocates memory and sets defaults. More...
 
void soundio_outstream_destroy (struct SoundIoOutStream *outstream)
 You may not call this function from the SoundIoOutStream::write_callback thread context. More...
 
int soundio_outstream_open (struct SoundIoOutStream *outstream)
 After you call this function, SoundIoOutStream:software_latency is set to the correct value. More...
 
int soundio_outstream_start (struct SoundIoOutStream *outstream)
 After you call this function, SoundIoOutStream::write_callback will be called. More...
 
int soundio_outstream_begin_write (struct SoundIoOutStream *outstream, struct SoundIoChannelArea **areas, int *frame_count)
 Call this function when you are ready to begin writing to the device buffer. More...
 
int soundio_outstream_end_write (struct SoundIoOutStream *outstream)
 Commits the write that you began with soundio_outstream_begin_write. More...
 
int soundio_outstream_clear_buffer (struct SoundIoOutStream *outstream)
 Clears the output stream buffer. More...
 
int soundio_outstream_pause (struct SoundIoOutStream *outstream, bool pause)
 If the underlying device supports pausing, this pauses the stream. More...
 
int soundio_outstream_get_latency (struct SoundIoOutStream *outstream, double *out_latency)
 Obtain the total number of seconds that the next frame written after the last frame written with soundio_outstream_end_write will take to become audible. More...
 
struct SoundIoInStreamsoundio_instream_create (struct SoundIoDevice *device)
 Allocates memory and sets defaults. More...
 
void soundio_instream_destroy (struct SoundIoInStream *instream)
 You may not call this function from SoundIoInStream::read_callback. More...
 
int soundio_instream_open (struct SoundIoInStream *instream)
 After you call this function, SoundIoInStream::software_latency is set to the correct value. More...
 
int soundio_instream_start (struct SoundIoInStream *instream)
 After you call this function, SoundIoInStream::read_callback will be called. More...
 
int soundio_instream_begin_read (struct SoundIoInStream *instream, struct SoundIoChannelArea **areas, int *frame_count)
 Call this function when you are ready to begin reading from the device buffer. More...
 
int soundio_instream_end_read (struct SoundIoInStream *instream)
 This will drop all of the frames from when you called soundio_instream_begin_read. More...
 
int soundio_instream_pause (struct SoundIoInStream *instream, bool pause)
 If the underyling device supports pausing, this pauses the stream and prevents SoundIoInStream::read_callback from being called. More...
 
int soundio_instream_get_latency (struct SoundIoInStream *instream, double *out_latency)
 Obtain the number of seconds that the next frame of sound being captured will take to arrive in the buffer, plus the amount of time that is represented in the buffer. More...
 
struct SoundIoRingBuffer * soundio_ring_buffer_create (struct SoundIo *soundio, int requested_capacity)
 requested_capacity in bytes. More...
 
void soundio_ring_buffer_destroy (struct SoundIoRingBuffer *ring_buffer)
 
int soundio_ring_buffer_capacity (struct SoundIoRingBuffer *ring_buffer)
 When you create a ring buffer, capacity might be more than the requested capacity for alignment purposes. More...
 
char * soundio_ring_buffer_write_ptr (struct SoundIoRingBuffer *ring_buffer)
 Do not write more than capacity. More...
 
void soundio_ring_buffer_advance_write_ptr (struct SoundIoRingBuffer *ring_buffer, int count)
 count in bytes. More...
 
char * soundio_ring_buffer_read_ptr (struct SoundIoRingBuffer *ring_buffer)
 Do not read more than capacity. More...
 
void soundio_ring_buffer_advance_read_ptr (struct SoundIoRingBuffer *ring_buffer, int count)
 count in bytes. More...
 
int soundio_ring_buffer_fill_count (struct SoundIoRingBuffer *ring_buffer)
 Returns how many bytes of the buffer is used, ready for reading. More...
 
int soundio_ring_buffer_free_count (struct SoundIoRingBuffer *ring_buffer)
 Returns how many bytes of the buffer is free, ready for writing. More...
 
void soundio_ring_buffer_clear (struct SoundIoRingBuffer *ring_buffer)
 Must be called by the writer. More...
 

Macro Definition Documentation

#define SOUNDIO_MAX_CHANNELS   24
#define SoundIoFormatFloat32FE   SoundIoFormatFloat32BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatFloat32NE   SoundIoFormatFloat32LE
#define SoundIoFormatFloat64FE   SoundIoFormatFloat64BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatFloat64NE   SoundIoFormatFloat64LE
#define SoundIoFormatS16FE   SoundIoFormatS16BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatS16NE   SoundIoFormatS16LE
#define SoundIoFormatS24FE   SoundIoFormatS24BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatS24NE   SoundIoFormatS24LE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatS32FE   SoundIoFormatS32BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatS32NE   SoundIoFormatS32LE
#define SoundIoFormatU16FE   SoundIoFormatU16BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatU16NE   SoundIoFormatU16LE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatU24FE   SoundIoFormatU24BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatU24NE   SoundIoFormatU24LE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatU32FE   SoundIoFormatU32BE
Examples:
sio_microphone.c, and sio_record.c.
#define SoundIoFormatU32NE   SoundIoFormatU32LE
Examples:
sio_microphone.c, and sio_record.c.

Enumeration Type Documentation

Enumerator
SoundIoBackendNone 
SoundIoBackendJack 
SoundIoBackendPulseAudio 
SoundIoBackendAlsa 
SoundIoBackendCoreAudio 
SoundIoBackendWasapi 
SoundIoBackendDummy 

Specifies where a channel is physically located.

Enumerator
SoundIoChannelIdInvalid 
SoundIoChannelIdFrontLeft 

First of the more commonly supported ids.

SoundIoChannelIdFrontRight 
SoundIoChannelIdFrontCenter 
SoundIoChannelIdLfe 
SoundIoChannelIdBackLeft 
SoundIoChannelIdBackRight 
SoundIoChannelIdFrontLeftCenter 
SoundIoChannelIdFrontRightCenter 
SoundIoChannelIdBackCenter 
SoundIoChannelIdSideLeft 
SoundIoChannelIdSideRight 
SoundIoChannelIdTopCenter 
SoundIoChannelIdTopFrontLeft 
SoundIoChannelIdTopFrontCenter 
SoundIoChannelIdTopFrontRight 
SoundIoChannelIdTopBackLeft 
SoundIoChannelIdTopBackCenter 
SoundIoChannelIdTopBackRight 

Last of the more commonly supported ids.

SoundIoChannelIdBackLeftCenter 

First of the less commonly supported ids.

SoundIoChannelIdBackRightCenter 
SoundIoChannelIdFrontLeftWide 
SoundIoChannelIdFrontRightWide 
SoundIoChannelIdFrontLeftHigh 
SoundIoChannelIdFrontCenterHigh 
SoundIoChannelIdFrontRightHigh 
SoundIoChannelIdTopFrontLeftCenter 
SoundIoChannelIdTopFrontRightCenter 
SoundIoChannelIdTopSideLeft 
SoundIoChannelIdTopSideRight 
SoundIoChannelIdLeftLfe 
SoundIoChannelIdRightLfe 
SoundIoChannelIdLfe2 
SoundIoChannelIdBottomCenter 
SoundIoChannelIdBottomLeftCenter 
SoundIoChannelIdBottomRightCenter 
SoundIoChannelIdMsMid 

Mid/side recording.

SoundIoChannelIdMsSide 
SoundIoChannelIdAmbisonicW 

first order ambisonic channels

SoundIoChannelIdAmbisonicX 
SoundIoChannelIdAmbisonicY 
SoundIoChannelIdAmbisonicZ 
SoundIoChannelIdXyX 

X-Y Recording.

SoundIoChannelIdXyY 
SoundIoChannelIdHeadphonesLeft 

First of the "other" channel ids.

SoundIoChannelIdHeadphonesRight 
SoundIoChannelIdClickTrack 
SoundIoChannelIdForeignLanguage 
SoundIoChannelIdHearingImpaired 
SoundIoChannelIdNarration 
SoundIoChannelIdHaptic 
SoundIoChannelIdDialogCentricMix 

Last of the "other" channel ids.

SoundIoChannelIdAux 
SoundIoChannelIdAux0 
SoundIoChannelIdAux1 
SoundIoChannelIdAux2 
SoundIoChannelIdAux3 
SoundIoChannelIdAux4 
SoundIoChannelIdAux5 
SoundIoChannelIdAux6 
SoundIoChannelIdAux7 
SoundIoChannelIdAux8 
SoundIoChannelIdAux9 
SoundIoChannelIdAux10 
SoundIoChannelIdAux11 
SoundIoChannelIdAux12 
SoundIoChannelIdAux13 
SoundIoChannelIdAux14 
SoundIoChannelIdAux15 

Built-in channel layouts for convenience.

Enumerator
SoundIoChannelLayoutIdMono 
SoundIoChannelLayoutIdStereo 
SoundIoChannelLayoutId2Point1 
SoundIoChannelLayoutId3Point0 
SoundIoChannelLayoutId3Point0Back 
SoundIoChannelLayoutId3Point1 
SoundIoChannelLayoutId4Point0 
SoundIoChannelLayoutIdQuad 
SoundIoChannelLayoutIdQuadSide 
SoundIoChannelLayoutId4Point1 
SoundIoChannelLayoutId5Point0Back 
SoundIoChannelLayoutId5Point0Side 
SoundIoChannelLayoutId5Point1 
SoundIoChannelLayoutId5Point1Back 
SoundIoChannelLayoutId6Point0Side 
SoundIoChannelLayoutId6Point0Front 
SoundIoChannelLayoutIdHexagonal 
SoundIoChannelLayoutId6Point1 
SoundIoChannelLayoutId6Point1Back 
SoundIoChannelLayoutId6Point1Front 
SoundIoChannelLayoutId7Point0 
SoundIoChannelLayoutId7Point0Front 
SoundIoChannelLayoutId7Point1 
SoundIoChannelLayoutId7Point1Wide 
SoundIoChannelLayoutId7Point1WideBack 
SoundIoChannelLayoutIdOctagonal 
Enumerator
SoundIoDeviceAimInput 

capture / recording

SoundIoDeviceAimOutput 

playback

See also soundio_strerror.

Enumerator
SoundIoErrorNone 
SoundIoErrorNoMem 

Out of memory.

SoundIoErrorInitAudioBackend 

The backend does not appear to be active or running.

SoundIoErrorSystemResources 

A system resource other than memory was not available.

SoundIoErrorOpeningDevice 

Attempted to open a device and failed.

SoundIoErrorNoSuchDevice 
SoundIoErrorInvalid 

The programmer did not comply with the API.

SoundIoErrorBackendUnavailable 

libsoundio was compiled without support for that backend.

SoundIoErrorStreaming 

An open stream had an error that can only be recovered from by destroying the stream and creating it again.

SoundIoErrorIncompatibleDevice 

Attempted to use a device with parameters it cannot support.

SoundIoErrorNoSuchClient 

When JACK returns JackNoSuchClient

SoundIoErrorIncompatibleBackend 

Attempted to use parameters that the backend cannot support.

SoundIoErrorBackendDisconnected 

Backend server shutdown or became inactive.

SoundIoErrorInterrupted 
SoundIoErrorUnderflow 

Buffer underrun occurred.

SoundIoErrorEncodingString 

Unable to convert to or from UTF-8 to the native string format.

For your convenience, Native Endian and Foreign Endian constants are defined which point to the respective SoundIoFormat values.

Enumerator
SoundIoFormatInvalid 
SoundIoFormatS8 

Signed 8 bit.

SoundIoFormatU8 

Unsigned 8 bit.

SoundIoFormatS16LE 

Signed 16 bit Little Endian.

SoundIoFormatS16BE 

Signed 16 bit Big Endian.

SoundIoFormatU16LE 

Unsigned 16 bit Little Endian.

SoundIoFormatU16BE 

Unsigned 16 bit Little Endian.

SoundIoFormatS24LE 

Signed 24 bit Little Endian using low three bytes in 32-bit word.

SoundIoFormatS24BE 

Signed 24 bit Big Endian using low three bytes in 32-bit word.

SoundIoFormatU24LE 

Unsigned 24 bit Little Endian using low three bytes in 32-bit word.

SoundIoFormatU24BE 

Unsigned 24 bit Big Endian using low three bytes in 32-bit word.

SoundIoFormatS32LE 

Signed 32 bit Little Endian.

SoundIoFormatS32BE 

Signed 32 bit Big Endian.

SoundIoFormatU32LE 

Unsigned 32 bit Little Endian.

SoundIoFormatU32BE 

Unsigned 32 bit Big Endian.

SoundIoFormatFloat32LE 

Float 32 bit Little Endian, Range -1.0 to 1.0.

SoundIoFormatFloat32BE 

Float 32 bit Big Endian, Range -1.0 to 1.0.

SoundIoFormatFloat64LE 

Float 64 bit Little Endian, Range -1.0 to 1.0.

SoundIoFormatFloat64BE 

Float 64 bit Big Endian, Range -1.0 to 1.0.

Function Documentation

int soundio_backend_count ( struct SoundIo soundio)

Returns the number of available backends.

const char* soundio_backend_name ( enum SoundIoBackend  backend)

Get a string representation of a SoundIoBackend.

Examples:
backend_disconnect_recover.c, and sio_sine.c.
const struct SoundIoChannelLayout* soundio_best_matching_channel_layout ( const struct SoundIoChannelLayout preferred_layouts,
int  preferred_layout_count,
const struct SoundIoChannelLayout available_layouts,
int  available_layout_count 
)

Iterates over preferred_layouts.

Returns the first channel layout in preferred_layouts which matches one of the channel layouts in available_layouts. Returns NULL if none matches.

Examples:
sio_microphone.c.
int soundio_channel_layout_builtin_count ( void  )

Returns the number of builtin channel layouts.

bool soundio_channel_layout_detect_builtin ( struct SoundIoChannelLayout layout)

Populates the name field of layout if it matches a builtin one.

returns whether it found a match

bool soundio_channel_layout_equal ( const struct SoundIoChannelLayout a,
const struct SoundIoChannelLayout b 
)

Returns whether the channel count field and each channel id matches in the supplied channel layouts.

int soundio_channel_layout_find_channel ( const struct SoundIoChannelLayout layout,
enum SoundIoChannelId  channel 
)

Return the index of channel in layout, or -1 if not found.

const struct SoundIoChannelLayout* soundio_channel_layout_get_builtin ( int  index)

Returns a builtin channel layout.

0 <= index < soundio_channel_layout_builtin_count

Although index is of type int, it should be a valid SoundIoChannelLayoutId enum value.

const struct SoundIoChannelLayout* soundio_channel_layout_get_default ( int  channel_count)

Get the default builtin channel layout for the given number of channels.

int soundio_connect ( struct SoundIo soundio)

Tries soundio_connect_backend on all available backends in order.

Possible errors:

Examples:
backend_disconnect_recover.c, sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.
int soundio_connect_backend ( struct SoundIo soundio,
enum SoundIoBackend  backend 
)

Instead of calling soundio_connect you may call this function to try a specific backend.

Possible errors:

Examples:
backend_disconnect_recover.c, sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.
struct SoundIo* soundio_create ( void  )

Create a SoundIo context.

You may create multiple instances of this to connect to multiple backends. Sets all fields to defaults. Returns NULL if and only if memory could not be allocated. See also soundio_destroy

Examples:
backend_disconnect_recover.c, sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.
int soundio_default_input_device_index ( struct SoundIo soundio)

returns the index of the default input device returns -1 if there are no devices or if you never called soundio_flush_events.

Examples:
sio_list_devices.c, sio_microphone.c, and sio_record.c.
int soundio_default_output_device_index ( struct SoundIo soundio)

returns the index of the default output device returns -1 if there are no devices or if you never called soundio_flush_events.

Examples:
sio_list_devices.c, sio_microphone.c, and sio_sine.c.
void soundio_destroy ( struct SoundIo soundio)
bool soundio_device_equal ( const struct SoundIoDevice a,
const struct SoundIoDevice b 
)

Return true if and only if the devices have the same SoundIoDevice::id, SoundIoDevice::is_raw, and SoundIoDevice::aim are the same.

int soundio_device_nearest_sample_rate ( struct SoundIoDevice device,
int  sample_rate 
)

Convenience function.

Returns the available sample rate nearest to sample_rate, rounding up.

void soundio_device_ref ( struct SoundIoDevice device)

Add 1 to the reference count of device.

void soundio_device_sort_channel_layouts ( struct SoundIoDevice device)

Sorts channel layouts by channel count, descending.

Examples:
sio_microphone.c, and sio_record.c.
bool soundio_device_supports_format ( struct SoundIoDevice device,
enum SoundIoFormat  format 
)

Convenience function.

Returns whether format is included in the device's supported formats.

Examples:
sio_microphone.c, sio_record.c, and sio_sine.c.
bool soundio_device_supports_layout ( struct SoundIoDevice device,
const struct SoundIoChannelLayout layout 
)

Convenience function.

Returns whether layout is included in the device's supported channel layouts.

bool soundio_device_supports_sample_rate ( struct SoundIoDevice device,
int  sample_rate 
)

Convenience function.

Returns whether sample_rate is included in the device's supported sample rates.

Examples:
sio_microphone.c, and sio_record.c.
void soundio_device_unref ( struct SoundIoDevice device)

Remove 1 to the reference count of device.

Clean up if it was the last reference.

Examples:
sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.
void soundio_disconnect ( struct SoundIo soundio)
void soundio_flush_events ( struct SoundIo soundio)

Atomically update information for all connected devices.

Note that calling this function merely flips a pointer; the actual work of collecting device information is done elsewhere. It is performant to call this function many times per second.

When you call this, the following callbacks might be called:

This must be called from the same thread as the thread in which you call these functions:

Note that if you do not care about learning about updated devices, you might call this function only once ever and never call soundio_wait_events.

Examples:
backend_disconnect_recover.c, sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.
void soundio_force_device_scan ( struct SoundIo soundio)

If necessary you can manually trigger a device rescan.

Normally you will not ever have to call this function, as libsoundio listens to system events for device changes and responds to them by rescanning devices and preparing the new device information for you to be atomically replaced when you call soundio_flush_events. However you might run into cases where you want to force trigger a device rescan, for example if an ALSA device has a SoundIoDevice::probe_error.

After you call this you still have to use soundio_flush_events or soundio_wait_events and then wait for the SoundIo::on_devices_change callback.

This can be called from any thread context except for SoundIoOutStream::write_callback and SoundIoInStream::read_callback

const char* soundio_format_string ( enum SoundIoFormat  format)

Returns string representation of format.

Examples:
sio_list_devices.c, and sio_record.c.
enum SoundIoBackend soundio_get_backend ( struct SoundIo soundio,
int  index 
)

get the available backend at the specified index (0 <= index < soundio_backend_count)

static int soundio_get_bytes_per_frame ( enum SoundIoFormat  format,
int  channel_count 
)
inlinestatic

A frame is one sample per channel.

References SoundIoChannelLayout::channel_count, and soundio_get_bytes_per_sample().

Referenced by soundio_get_bytes_per_second().

int soundio_get_bytes_per_sample ( enum SoundIoFormat  format)

Returns -1 on invalid format.

Referenced by soundio_get_bytes_per_frame().

static int soundio_get_bytes_per_second ( enum SoundIoFormat  format,
int  channel_count,
int  sample_rate 
)
inlinestatic

Sample rate is the number of frames per second.

References soundio_get_bytes_per_frame().

const char* soundio_get_channel_name ( enum SoundIoChannelId  id)
Examples:
sio_list_devices.c.
struct SoundIoDevice* soundio_get_input_device ( struct SoundIo soundio,
int  index 
)

Always returns a device.

Call soundio_device_unref when done. index must be 0 <= index < soundio_input_device_count Returns NULL if you never called soundio_flush_events or if you provide invalid parameter values.

Examples:
sio_list_devices.c, sio_microphone.c, and sio_record.c.
struct SoundIoDevice* soundio_get_output_device ( struct SoundIo soundio,
int  index 
)

Always returns a device.

Call soundio_device_unref when done. index must be 0 <= index < soundio_output_device_count Returns NULL if you never called soundio_flush_events or if you provide invalid parameter values.

Examples:
sio_list_devices.c, sio_microphone.c, and sio_sine.c.
bool soundio_have_backend ( enum SoundIoBackend  backend)

Returns whether libsoundio was compiled with backend.

int soundio_input_device_count ( struct SoundIo soundio)

When you call soundio_flush_events, a snapshot of all device state is saved and these functions merely access the snapshot data.

When you want to check for new devices, call soundio_flush_events. Or you can call soundio_wait_events to block until devices change. If an error occurs scanning devices in a background thread, SoundIo::on_backend_disconnect is called with the error code. Get the number of input devices. Returns -1 if you never called soundio_flush_events.

Examples:
sio_list_devices.c, sio_microphone.c, and sio_record.c.
int soundio_instream_begin_read ( struct SoundIoInStream instream,
struct SoundIoChannelArea **  areas,
int *  frame_count 
)

Call this function when you are ready to begin reading from the device buffer.

  • instream - (in) The input stream you want to read from.
  • areas - (out) The memory addresses you can read data from. It is OK to modify the pointers if that helps you iterate. There might be a "hole" in the buffer. To indicate this, areas will be NULL and frame_count tells how big the hole is in frames.
  • frame_count - (in/out) - Provide the number of frames you want to read; returns the number of frames you can actually read. The returned value will always be less than or equal to the provided value. If the provided value is less than frame_count_min from SoundIoInStream::read_callback this function returns with SoundIoErrorInvalid. It is your responsibility to call this function no more and no fewer than the correct number of times according to the frame_count_min and frame_count_max criteria from SoundIoInStream::read_callback. You must call this function only from the SoundIoInStream::read_callback thread context. After calling this function, read data from areas and then use soundio_instream_end_read` to actually remove the data from the buffer and move the read index forward. soundio_instream_end_read should not be called if the buffer is empty (frame_count == 0), but it should be called if there is a hole.

Possible errors:

Examples:
sio_microphone.c, and sio_record.c.
struct SoundIoInStream* soundio_instream_create ( struct SoundIoDevice device)

Allocates memory and sets defaults.

Next you should fill out the struct fields and then call soundio_instream_open. Sets all fields to defaults. Returns NULL if and only if memory could not be allocated. See also soundio_instream_destroy

Examples:
sio_microphone.c, and sio_record.c.
void soundio_instream_destroy ( struct SoundIoInStream instream)

You may not call this function from SoundIoInStream::read_callback.

Examples:
sio_microphone.c, and sio_record.c.
int soundio_instream_end_read ( struct SoundIoInStream instream)

This will drop all of the frames from when you called soundio_instream_begin_read.

You must call this function only from the SoundIoInStream::read_callback thread context. You must call this function only after a successful call to soundio_instream_begin_read.

Possible errors:

Examples:
sio_microphone.c, and sio_record.c.
int soundio_instream_get_latency ( struct SoundIoInStream instream,
double *  out_latency 
)

Obtain the number of seconds that the next frame of sound being captured will take to arrive in the buffer, plus the amount of time that is represented in the buffer.

This includes both software and hardware latency.

This function must be called only from within SoundIoInStream::read_callback.

Possible errors:

int soundio_instream_open ( struct SoundIoInStream instream)

After you call this function, SoundIoInStream::software_latency is set to the correct value.

The next thing to do is call soundio_instream_start. If this function returns an error, the instream is in an invalid state and you must call soundio_instream_destroy on it.

Possible errors:

Examples:
sio_microphone.c, and sio_record.c.
int soundio_instream_pause ( struct SoundIoInStream instream,
bool  pause 
)

If the underyling device supports pausing, this pauses the stream and prevents SoundIoInStream::read_callback from being called.

Otherwise this returns SoundIoErrorIncompatibleDevice. You must call this function only from the SoundIoInStream::read_callback thread context. Pausing when already paused or unpausing when already unpaused has no effect and always returns SoundIoErrorNone.

Possible errors:

int soundio_instream_start ( struct SoundIoInStream instream)
int soundio_output_device_count ( struct SoundIo soundio)

Get the number of output devices.

Returns -1 if you never called soundio_flush_events.

Examples:
sio_list_devices.c, sio_microphone.c, and sio_sine.c.
int soundio_outstream_begin_write ( struct SoundIoOutStream outstream,
struct SoundIoChannelArea **  areas,
int *  frame_count 
)

Call this function when you are ready to begin writing to the device buffer.

  • outstream - (in) The output stream you want to write to.
  • areas - (out) The memory addresses you can write data to, one per channel. It is OK to modify the pointers if that helps you iterate.
  • frame_count - (in/out) Provide the number of frames you want to write. Returned will be the number of frames you can actually write, which is also the number of frames that will be written when you call soundio_outstream_end_write. The value returned will always be less than or equal to the value provided. It is your responsibility to call this function exactly as many times as necessary to meet the frame_count_min and frame_count_max criteria from SoundIoOutStream::write_callback. You must call this function only from the SoundIoOutStream::write_callback thread context. After calling this function, write data to areas and then call soundio_outstream_end_write. If this function returns an error, do not call soundio_outstream_end_write.

Possible errors:

Examples:
sio_microphone.c, and sio_sine.c.
int soundio_outstream_clear_buffer ( struct SoundIoOutStream outstream)

Clears the output stream buffer.

This function can be called from any thread. This function can be called regardless of whether the outstream is paused or not. Some backends do not support clearing the buffer. On these backends this function will return SoundIoErrorIncompatibleBackend. Some devices do not support clearing the buffer. On these devices this function might return SoundIoErrorIncompatibleDevice. Possible errors:

Examples:
sio_sine.c.
struct SoundIoOutStream* soundio_outstream_create ( struct SoundIoDevice device)

Allocates memory and sets defaults.

Next you should fill out the struct fields and then call soundio_outstream_open. Sets all fields to defaults. Returns NULL if and only if memory could not be allocated. See also soundio_outstream_destroy

Examples:
sio_microphone.c, and sio_sine.c.
void soundio_outstream_destroy ( struct SoundIoOutStream outstream)

You may not call this function from the SoundIoOutStream::write_callback thread context.

Examples:
sio_microphone.c, and sio_sine.c.
int soundio_outstream_end_write ( struct SoundIoOutStream outstream)

Commits the write that you began with soundio_outstream_begin_write.

You must call this function only from the SoundIoOutStream::write_callback thread context.

Possible errors:

Examples:
sio_microphone.c, and sio_sine.c.
int soundio_outstream_get_latency ( struct SoundIoOutStream outstream,
double *  out_latency 
)

Obtain the total number of seconds that the next frame written after the last frame written with soundio_outstream_end_write will take to become audible.

This includes both software and hardware latency. In other words, if you call this function directly after calling soundio_outstream_end_write, this gives you the number of seconds that the next frame written will take to become audible.

This function must be called only from within SoundIoOutStream::write_callback.

Possible errors:

int soundio_outstream_open ( struct SoundIoOutStream outstream)

After you call this function, SoundIoOutStream:software_latency is set to the correct value.

The next thing to do is call soundio_instream_start. If this function returns an error, the outstream is in an invalid state and you must call soundio_outstream_destroy on it.

Possible errors:

Examples:
sio_microphone.c, and sio_sine.c.
int soundio_outstream_pause ( struct SoundIoOutStream outstream,
bool  pause 
)

If the underlying device supports pausing, this pauses the stream.

SoundIoOutStream::write_callback may be called a few more times if the buffer is not full. Pausing might put the hardware into a low power state which is ideal if your software is silent for some time. This function may be called any thread. Pausing when already paused or unpausing when already unpaused has no effect and always returns SoundIoErrorNone.

Possible errors:

Examples:
sio_sine.c.
int soundio_outstream_start ( struct SoundIoOutStream outstream)
enum SoundIoChannelId soundio_parse_channel_id ( const char *  str,
int  str_len 
)

Given UTF-8 encoded text which is the name of a channel such as "Front Left", "FL", or "front-left", return the corresponding SoundIoChannelId.

Returns SoundIoChannelIdInvalid for no match.

void soundio_ring_buffer_advance_read_ptr ( struct SoundIoRingBuffer *  ring_buffer,
int  count 
)

count in bytes.

Examples:
sio_microphone.c.
void soundio_ring_buffer_advance_write_ptr ( struct SoundIoRingBuffer *  ring_buffer,
int  count 
)

count in bytes.

Examples:
sio_microphone.c.
int soundio_ring_buffer_capacity ( struct SoundIoRingBuffer *  ring_buffer)

When you create a ring buffer, capacity might be more than the requested capacity for alignment purposes.

This function returns the actual capacity.

void soundio_ring_buffer_clear ( struct SoundIoRingBuffer *  ring_buffer)

Must be called by the writer.

struct SoundIoRingBuffer* soundio_ring_buffer_create ( struct SoundIo soundio,
int  requested_capacity 
)

requested_capacity in bytes.

Returns NULL if and only if memory could not be allocated. Use soundio_ring_buffer_capacity to get the actual capacity, which might be greater for alignment purposes. See also soundio_ring_buffer_destroy

Examples:
sio_microphone.c.
void soundio_ring_buffer_destroy ( struct SoundIoRingBuffer *  ring_buffer)
int soundio_ring_buffer_fill_count ( struct SoundIoRingBuffer *  ring_buffer)

Returns how many bytes of the buffer is used, ready for reading.

Examples:
sio_microphone.c.
int soundio_ring_buffer_free_count ( struct SoundIoRingBuffer *  ring_buffer)

Returns how many bytes of the buffer is free, ready for writing.

Examples:
sio_microphone.c.
char* soundio_ring_buffer_read_ptr ( struct SoundIoRingBuffer *  ring_buffer)

Do not read more than capacity.

Examples:
sio_microphone.c.
char* soundio_ring_buffer_write_ptr ( struct SoundIoRingBuffer *  ring_buffer)

Do not write more than capacity.

Examples:
sio_microphone.c.
void soundio_sort_channel_layouts ( struct SoundIoChannelLayout layouts,
int  layout_count 
)

Sorts by channel count, descending.

const char* soundio_strerror ( int  error)
void soundio_wait_events ( struct SoundIo soundio)

This function calls soundio_flush_events then blocks until another event is ready or you call soundio_wakeup.

Be ready for spurious wakeups.

Examples:
backend_disconnect_recover.c, sio_list_devices.c, sio_microphone.c, and sio_record.c.
void soundio_wakeup ( struct SoundIo soundio)

Makes soundio_wait_events stop blocking.