libsoundio 2.0.0
soundio.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2015 Andrew Kelley
3 *
4 * This file is part of libsoundio, which is MIT licensed.
5 * See http://opensource.org/licenses/MIT
6 */
7
8#ifndef SOUNDIO_SOUNDIO_H
9#define SOUNDIO_SOUNDIO_H
10
11#include "endian.h"
12#include <stdbool.h>
13
15#ifdef __cplusplus
16#define SOUNDIO_EXTERN_C extern "C"
17#else
18#define SOUNDIO_EXTERN_C
19#endif
20
21#if defined(SOUNDIO_STATIC_LIBRARY)
22# define SOUNDIO_EXPORT SOUNDIO_EXTERN_C
23#else
24# if defined(_WIN32)
25# if defined(SOUNDIO_BUILDING_LIBRARY)
26# define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllexport)
27# else
28# define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllimport)
29# endif
30# else
31# define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __attribute__((visibility ("default")))
32# endif
33#endif
35
103};
104
108
127
145
149
155
159
168
186};
187
216};
217
226};
227
231};
232
255};
256
257#if defined(SOUNDIO_OS_BIG_ENDIAN)
258#define SoundIoFormatS16NE SoundIoFormatS16BE
259#define SoundIoFormatU16NE SoundIoFormatU16BE
260#define SoundIoFormatS24NE SoundIoFormatS24BE
261#define SoundIoFormatU24NE SoundIoFormatU24BE
262#define SoundIoFormatS32NE SoundIoFormatS32BE
263#define SoundIoFormatU32NE SoundIoFormatU32BE
264#define SoundIoFormatFloat32NE SoundIoFormatFloat32BE
265#define SoundIoFormatFloat64NE SoundIoFormatFloat64BE
266
267#define SoundIoFormatS16FE SoundIoFormatS16LE
268#define SoundIoFormatU16FE SoundIoFormatU16LE
269#define SoundIoFormatS24FE SoundIoFormatS24LE
270#define SoundIoFormatU24FE SoundIoFormatU24LE
271#define SoundIoFormatS32FE SoundIoFormatS32LE
272#define SoundIoFormatU32FE SoundIoFormatU32LE
273#define SoundIoFormatFloat32FE SoundIoFormatFloat32LE
274#define SoundIoFormatFloat64FE SoundIoFormatFloat64LE
275
276#elif defined(SOUNDIO_OS_LITTLE_ENDIAN)
277
282#define SoundIoFormatS16NE SoundIoFormatS16LE
283#define SoundIoFormatU16NE SoundIoFormatU16LE
284#define SoundIoFormatS24NE SoundIoFormatS24LE
285#define SoundIoFormatU24NE SoundIoFormatU24LE
286#define SoundIoFormatS32NE SoundIoFormatS32LE
287#define SoundIoFormatU32NE SoundIoFormatU32LE
288#define SoundIoFormatFloat32NE SoundIoFormatFloat32LE
289#define SoundIoFormatFloat64NE SoundIoFormatFloat64LE
290
291#define SoundIoFormatS16FE SoundIoFormatS16BE
292#define SoundIoFormatU16FE SoundIoFormatU16BE
293#define SoundIoFormatS24FE SoundIoFormatS24BE
294#define SoundIoFormatU24FE SoundIoFormatU24BE
295#define SoundIoFormatS32FE SoundIoFormatS32BE
296#define SoundIoFormatU32FE SoundIoFormatU32BE
297#define SoundIoFormatFloat32FE SoundIoFormatFloat32BE
298#define SoundIoFormatFloat64FE SoundIoFormatFloat64BE
299
300#else
301#error unknown byte order
302#endif
303
304#define SOUNDIO_MAX_CHANNELS 24
307 const char *name;
310};
311
314 int min;
315 int max;
316};
317
321 char *ptr;
324 int step;
325};
326
328struct SoundIo {
330 void *userdata;
333 void (*on_devices_change)(struct SoundIo *);
350 void (*on_backend_disconnect)(struct SoundIo *, int err);
354 void (*on_events_signal)(struct SoundIo *);
355
359
364 const char *app_name;
365
372 void (*emit_rtprio_warning)(void);
373
380 void (*jack_info_callback)(const char *msg);
383 void (*jack_error_callback)(const char *msg);
384};
385
390
399 char *id;
401 char *name;
402
405
415
440
455
472
478 bool is_raw;
479
483
494};
495
500
504
508
512
540 float volume;
542 void *userdata;
560 int frame_count_min, int frame_count_max);
572 void (*error_callback)(struct SoundIoOutStream *, int err);
573
580 const char *name;
581
586
587
592
597};
598
603
607
611
615
629
631 void *userdata;
644 void (*read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max);
656 void (*error_callback)(struct SoundIoInStream *, int err);
657
664 const char *name;
665
670
675
679};
680
682SOUNDIO_EXPORT const char *soundio_version_string(void);
684SOUNDIO_EXPORT int soundio_version_major(void);
686SOUNDIO_EXPORT int soundio_version_minor(void);
688SOUNDIO_EXPORT int soundio_version_patch(void);
689
694SOUNDIO_EXPORT struct SoundIo *soundio_create(void);
695SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
696
697
705SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
717SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
718SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
719
721SOUNDIO_EXPORT const char *soundio_strerror(int error);
723SOUNDIO_EXPORT const char *soundio_backend_name(enum SoundIoBackend backend);
724
726SOUNDIO_EXPORT int soundio_backend_count(struct SoundIo *soundio);
729SOUNDIO_EXPORT enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index);
730
732SOUNDIO_EXPORT bool soundio_have_backend(enum SoundIoBackend backend);
733
756SOUNDIO_EXPORT void soundio_flush_events(struct SoundIo *soundio);
757
760SOUNDIO_EXPORT void soundio_wait_events(struct SoundIo *soundio);
761
763SOUNDIO_EXPORT void soundio_wakeup(struct SoundIo *soundio);
764
765
780SOUNDIO_EXPORT void soundio_force_device_scan(struct SoundIo *soundio);
781
782
783// Channel Layouts
784
788 const struct SoundIoChannelLayout *a,
789 const struct SoundIoChannelLayout *b);
790
791SOUNDIO_EXPORT const char *soundio_get_channel_name(enum SoundIoChannelId id);
795SOUNDIO_EXPORT enum SoundIoChannelId soundio_parse_channel_id(const char *str, int str_len);
796
803SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_builtin(int index);
804
807
810 const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel);
811
815
820 const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count,
821 const struct SoundIoChannelLayout *available_layouts, int available_layout_count);
822
824SOUNDIO_EXPORT void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count);
825
826
827// Sample Formats
828
830SOUNDIO_EXPORT int soundio_get_bytes_per_sample(enum SoundIoFormat format);
831
833static inline int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count) {
835}
836
838static inline int soundio_get_bytes_per_second(enum SoundIoFormat format,
839 int channel_count, int sample_rate)
840{
841 return soundio_get_bytes_per_frame(format, channel_count) * sample_rate;
842}
843
845SOUNDIO_EXPORT const char * soundio_format_string(enum SoundIoFormat format);
846
847
848
849
850// Devices
851
858
861SOUNDIO_EXPORT int soundio_input_device_count(struct SoundIo *soundio);
864SOUNDIO_EXPORT int soundio_output_device_count(struct SoundIo *soundio);
865
870SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_input_device(struct SoundIo *soundio, int index);
875SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_output_device(struct SoundIo *soundio, int index);
876
881
886
888SOUNDIO_EXPORT void soundio_device_ref(struct SoundIoDevice *device);
891SOUNDIO_EXPORT void soundio_device_unref(struct SoundIoDevice *device);
892
895SOUNDIO_EXPORT bool soundio_device_equal(
896 const struct SoundIoDevice *a,
897 const struct SoundIoDevice *b);
898
900SOUNDIO_EXPORT void soundio_device_sort_channel_layouts(struct SoundIoDevice *device);
901
904SOUNDIO_EXPORT bool soundio_device_supports_format(struct SoundIoDevice *device,
905 enum SoundIoFormat format);
906
909SOUNDIO_EXPORT bool soundio_device_supports_layout(struct SoundIoDevice *device,
910 const struct SoundIoChannelLayout *layout);
911
914SOUNDIO_EXPORT bool soundio_device_supports_sample_rate(struct SoundIoDevice *device,
915 int sample_rate);
916
919SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *device,
920 int sample_rate);
921
922
923
924// Output Streams
931SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
932
954SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
955
965SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
966
997SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
998 struct SoundIoChannelArea **areas, int *frame_count);
999
1009SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
1010
1024SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
1025
1045SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
1046
1058SOUNDIO_EXPORT int soundio_outstream_get_latency(struct SoundIoOutStream *outstream,
1059 double *out_latency);
1060
1061SOUNDIO_EXPORT int soundio_outstream_set_volume(struct SoundIoOutStream *outstream,
1062 double volume);
1063
1064
1065
1066// Input Streams
1073SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
1074
1093SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
1094
1102SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
1103
1133SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
1134 struct SoundIoChannelArea **areas, int *frame_count);
1143SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
1144
1156SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
1157
1166SOUNDIO_EXPORT int soundio_instream_get_latency(struct SoundIoInStream *instream,
1167 double *out_latency);
1168
1169
1170struct SoundIoRingBuffer;
1171
1181SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
1182SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);
1183
1186SOUNDIO_EXPORT int soundio_ring_buffer_capacity(struct SoundIoRingBuffer *ring_buffer);
1187
1189SOUNDIO_EXPORT char *soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer);
1191SOUNDIO_EXPORT void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1192
1194SOUNDIO_EXPORT char *soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer);
1196SOUNDIO_EXPORT void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1197
1199SOUNDIO_EXPORT int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer);
1200
1202SOUNDIO_EXPORT int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer);
1203
1205SOUNDIO_EXPORT void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer);
1206
1207#endif
SoundIoChannelLayoutId
Built-in channel layouts for convenience.
Definition soundio.h:189
@ SoundIoChannelLayoutId4Point1
Definition soundio.h:199
@ SoundIoChannelLayoutId7Point1Wide
Definition soundio.h:213
@ SoundIoChannelLayoutId5Point0Side
Definition soundio.h:201
@ SoundIoChannelLayoutId5Point0Back
Definition soundio.h:200
@ SoundIoChannelLayoutId6Point1Back
Definition soundio.h:208
@ SoundIoChannelLayoutIdOctagonal
Definition soundio.h:215
@ SoundIoChannelLayoutId3Point0Back
Definition soundio.h:194
@ SoundIoChannelLayoutIdQuad
Definition soundio.h:197
@ SoundIoChannelLayoutIdHexagonal
Definition soundio.h:206
@ SoundIoChannelLayoutId7Point0
Definition soundio.h:210
@ SoundIoChannelLayoutId6Point1Front
Definition soundio.h:209
@ SoundIoChannelLayoutId6Point0Side
Definition soundio.h:204
@ SoundIoChannelLayoutId3Point0
Definition soundio.h:193
@ SoundIoChannelLayoutId7Point1
Definition soundio.h:212
@ SoundIoChannelLayoutIdQuadSide
Definition soundio.h:198
@ SoundIoChannelLayoutId4Point0
Definition soundio.h:196
@ SoundIoChannelLayoutIdMono
Definition soundio.h:190
@ SoundIoChannelLayoutId2Point1
Definition soundio.h:192
@ SoundIoChannelLayoutId5Point1
Definition soundio.h:202
@ SoundIoChannelLayoutId7Point1WideBack
Definition soundio.h:214
@ SoundIoChannelLayoutId6Point0Front
Definition soundio.h:205
@ SoundIoChannelLayoutId5Point1Back
Definition soundio.h:203
@ SoundIoChannelLayoutIdStereo
Definition soundio.h:191
@ SoundIoChannelLayoutId7Point0Front
Definition soundio.h:211
@ SoundIoChannelLayoutId6Point1
Definition soundio.h:207
@ SoundIoChannelLayoutId3Point1
Definition soundio.h:195
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.
void soundio_device_ref(struct SoundIoDevice *device)
Add 1 to the reference count of device.
void soundio_wait_events(struct SoundIo *soundio)
This function calls soundio_flush_events then blocks until another event is ready or you call soundio...
int soundio_channel_layout_builtin_count(void)
Returns the number of builtin channel layouts.
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 purpo...
int soundio_version_major(void)
See also soundio_version_string, soundio_version_minor, soundio_version_patch.
char * soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer)
Do not write more than capacity.
#define SOUNDIO_MAX_CHANNELS
Definition soundio.h:304
struct SoundIoOutStream * soundio_outstream_create(struct SoundIoDevice *device)
Allocates memory and sets defaults.
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.
void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer)
SoundIoBackend
Definition soundio.h:218
@ SoundIoBackendNone
Definition soundio.h:219
@ SoundIoBackendPulseAudio
Definition soundio.h:221
@ SoundIoBackendCoreAudio
Definition soundio.h:223
@ SoundIoBackendWasapi
Definition soundio.h:224
@ SoundIoBackendJack
Definition soundio.h:220
@ SoundIoBackendDummy
Definition soundio.h:225
@ SoundIoBackendAlsa
Definition soundio.h:222
const char * soundio_version_string(void)
See also soundio_version_major, soundio_version_minor, soundio_version_patch.
int soundio_device_nearest_sample_rate(struct SoundIoDevice *device, int sample_rate)
Convenience function.
bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout)
Populates the name field of layout if it matches a builtin one.
int soundio_output_device_count(struct SoundIo *soundio)
Get the number of output devices.
struct SoundIoDevice * soundio_get_output_device(struct SoundIo *soundio, int index)
Always returns a device.
SoundIoChannelId
Specifies where a channel is physically located.
Definition soundio.h:106
@ SoundIoChannelIdTopFrontLeft
Definition soundio.h:121
@ SoundIoChannelIdBottomRightCenter
Definition soundio.h:144
@ SoundIoChannelIdAmbisonicZ
Definition soundio.h:154
@ SoundIoChannelIdRightLfe
Definition soundio.h:140
@ SoundIoChannelIdHearingImpaired
Definition soundio.h:164
@ SoundIoChannelIdTopSideRight
Definition soundio.h:138
@ SoundIoChannelIdBackLeft
Definition soundio.h:113
@ SoundIoChannelIdMsMid
Mid/side recording.
Definition soundio.h:147
@ SoundIoChannelIdAux11
Definition soundio.h:181
@ SoundIoChannelIdClickTrack
Definition soundio.h:162
@ SoundIoChannelIdAux7
Definition soundio.h:177
@ SoundIoChannelIdTopFrontRight
Definition soundio.h:123
@ SoundIoChannelIdSideRight
Definition soundio.h:119
@ SoundIoChannelIdAux6
Definition soundio.h:176
@ SoundIoChannelIdTopBackCenter
Definition soundio.h:125
@ SoundIoChannelIdMsSide
Definition soundio.h:148
@ SoundIoChannelIdDialogCentricMix
Last of the "other" channel ids.
Definition soundio.h:167
@ SoundIoChannelIdBottomLeftCenter
Definition soundio.h:143
@ SoundIoChannelIdAux12
Definition soundio.h:182
@ SoundIoChannelIdFrontLeftHigh
Definition soundio.h:132
@ SoundIoChannelIdFrontCenterHigh
Definition soundio.h:133
@ SoundIoChannelIdTopFrontRightCenter
Definition soundio.h:136
@ SoundIoChannelIdForeignLanguage
Definition soundio.h:163
@ SoundIoChannelIdNarration
Definition soundio.h:165
@ SoundIoChannelIdAux
Definition soundio.h:169
@ SoundIoChannelIdFrontRightWide
Definition soundio.h:131
@ SoundIoChannelIdTopFrontLeftCenter
Definition soundio.h:135
@ SoundIoChannelIdFrontRightCenter
Definition soundio.h:116
@ SoundIoChannelIdAux13
Definition soundio.h:183
@ SoundIoChannelIdTopBackRight
Last of the more commonly supported ids.
Definition soundio.h:126
@ SoundIoChannelIdAux8
Definition soundio.h:178
@ SoundIoChannelIdAux5
Definition soundio.h:175
@ SoundIoChannelIdFrontLeftCenter
Definition soundio.h:115
@ SoundIoChannelIdAux2
Definition soundio.h:172
@ SoundIoChannelIdXyY
Definition soundio.h:158
@ SoundIoChannelIdFrontRightHigh
Definition soundio.h:134
@ SoundIoChannelIdSideLeft
Definition soundio.h:118
@ SoundIoChannelIdBottomCenter
Definition soundio.h:142
@ SoundIoChannelIdInvalid
Definition soundio.h:107
@ SoundIoChannelIdLfe
Definition soundio.h:112
@ SoundIoChannelIdTopBackLeft
Definition soundio.h:124
@ SoundIoChannelIdFrontLeft
First of the more commonly supported ids.
Definition soundio.h:109
@ SoundIoChannelIdFrontCenter
Definition soundio.h:111
@ SoundIoChannelIdBackRight
Definition soundio.h:114
@ SoundIoChannelIdBackCenter
Definition soundio.h:117
@ SoundIoChannelIdFrontLeftWide
Definition soundio.h:130
@ SoundIoChannelIdAmbisonicW
first order ambisonic channels
Definition soundio.h:151
@ SoundIoChannelIdAux0
Definition soundio.h:170
@ SoundIoChannelIdLfe2
Definition soundio.h:141
@ SoundIoChannelIdBackRightCenter
Definition soundio.h:129
@ SoundIoChannelIdAmbisonicX
Definition soundio.h:152
@ SoundIoChannelIdAux10
Definition soundio.h:180
@ SoundIoChannelIdAux9
Definition soundio.h:179
@ SoundIoChannelIdAux3
Definition soundio.h:173
@ SoundIoChannelIdAux4
Definition soundio.h:174
@ SoundIoChannelIdHeadphonesRight
Definition soundio.h:161
@ SoundIoChannelIdAmbisonicY
Definition soundio.h:153
@ SoundIoChannelIdBackLeftCenter
First of the less commonly supported ids.
Definition soundio.h:128
@ SoundIoChannelIdHaptic
Definition soundio.h:166
@ SoundIoChannelIdAux14
Definition soundio.h:184
@ SoundIoChannelIdHeadphonesLeft
First of the "other" channel ids.
Definition soundio.h:160
@ SoundIoChannelIdLeftLfe
Definition soundio.h:139
@ SoundIoChannelIdXyX
X-Y Recording.
Definition soundio.h:157
@ SoundIoChannelIdFrontRight
Definition soundio.h:110
@ SoundIoChannelIdTopFrontCenter
Definition soundio.h:122
@ SoundIoChannelIdTopSideLeft
Definition soundio.h:137
@ SoundIoChannelIdAux1
Definition soundio.h:171
@ SoundIoChannelIdAux15
Definition soundio.h:185
@ SoundIoChannelIdTopCenter
Definition soundio.h:120
const char * soundio_get_channel_name(enum SoundIoChannelId id)
int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer)
Returns how many bytes of the buffer is used, ready for reading.
bool soundio_device_supports_sample_rate(struct SoundIoDevice *device, int sample_rate)
Convenience function.
void soundio_device_unref(struct SoundIoDevice *device)
Remove 1 to the reference count of device.
void soundio_destroy(struct SoundIo *soundio)
bool soundio_device_supports_format(struct SoundIoDevice *device, enum SoundIoFormat format)
Convenience function.
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",...
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.
void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count)
count in bytes.
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.
int soundio_outstream_open(struct SoundIoOutStream *outstream)
After you call this function, SoundIoOutStream::software_latency is set to the correct value.
const char * soundio_backend_name(enum SoundIoBackend backend)
Get a string representation of a SoundIoBackend.
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,...
void soundio_flush_events(struct SoundIo *soundio)
Atomically update information for all connected devices.
struct SoundIoRingBuffer * soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity)
A ring buffer is a single-reader single-writer lock-free fixed-size queue.
int soundio_backend_count(struct SoundIo *soundio)
Returns the number of available backends.
void soundio_force_device_scan(struct SoundIo *soundio)
If necessary you can manually trigger a device rescan.
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 call...
void soundio_instream_destroy(struct SoundIoInStream *instream)
You may not call this function from SoundIoInStream::read_callback.
void soundio_outstream_destroy(struct SoundIoOutStream *outstream)
You may not call this function from the SoundIoOutStream::write_callback thread context.
int soundio_instream_end_read(struct SoundIoInStream *instream)
This will drop all of the frames from when you called soundio_instream_begin_read.
struct SoundIoDevice * soundio_get_input_device(struct SoundIo *soundio, int index)
Always returns a device.
int soundio_instream_pause(struct SoundIoInStream *instream, bool pause)
If the underyling device supports pausing, this pauses the stream and prevents SoundIoInStream::read_...
struct SoundIoInStream * soundio_instream_create(struct SoundIoDevice *device)
Allocates memory and sets defaults.
void soundio_device_sort_channel_layouts(struct SoundIoDevice *device)
Sorts channel layouts by channel count, descending.
int soundio_instream_open(struct SoundIoInStream *instream)
After you call this function, SoundIoInStream::software_latency is set to the correct value.
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 cal...
char * soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer)
Do not read more than capacity.
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 merel...
SoundIoError
See also soundio_strerror.
Definition soundio.h:72
@ SoundIoErrorNoSuchClient
When JACK returns JackNoSuchClient
Definition soundio.h:93
@ SoundIoErrorBackendUnavailable
libsoundio was compiled without support for that backend.
Definition soundio.h:86
@ SoundIoErrorInvalid
The programmer did not comply with the API.
Definition soundio.h:84
@ SoundIoErrorNone
Definition soundio.h:73
@ SoundIoErrorNoMem
Out of memory.
Definition soundio.h:75
@ SoundIoErrorNoSuchDevice
Definition soundio.h:82
@ SoundIoErrorStreaming
An open stream had an error that can only be recovered from by destroying the stream and creating it ...
Definition soundio.h:89
@ SoundIoErrorIncompatibleDevice
Attempted to use a device with parameters it cannot support.
Definition soundio.h:91
@ SoundIoErrorEncodingString
Unable to convert to or from UTF-8 to the native string format.
Definition soundio.h:102
@ SoundIoErrorBackendDisconnected
Backend server shutdown or became inactive.
Definition soundio.h:97
@ SoundIoErrorUnderflow
Buffer underrun occurred.
Definition soundio.h:100
@ SoundIoErrorSystemResources
A system resource other than memory was not available.
Definition soundio.h:79
@ SoundIoErrorIncompatibleBackend
Attempted to use parameters that the backend cannot support.
Definition soundio.h:95
@ SoundIoErrorInterrupted
Definition soundio.h:98
@ SoundIoErrorOpeningDevice
Attempted to open a device and failed.
Definition soundio.h:81
@ SoundIoErrorInitAudioBackend
The backend does not appear to be active or running.
Definition soundio.h:77
const char * soundio_strerror(int error)
Get a string representation of a SoundIoError.
int soundio_instream_start(struct SoundIoInStream *instream)
After you call this function, SoundIoInStream::read_callback will be called.
const struct SoundIoChannelLayout * soundio_channel_layout_get_builtin(int index)
Returns a builtin channel layout.
int soundio_outstream_start(struct SoundIoOutStream *outstream)
After you call this function, SoundIoOutStream::write_callback will be called.
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 soun...
int soundio_get_bytes_per_sample(enum SoundIoFormat format)
Returns -1 on invalid format.
int soundio_outstream_set_volume(struct SoundIoOutStream *outstream, double volume)
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.
void soundio_disconnect(struct SoundIo *soundio)
int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause)
If the underlying backend and device support pausing, this pauses the stream.
static int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count)
A frame is one sample per channel.
Definition soundio.h:833
int soundio_connect(struct SoundIo *soundio)
Tries soundio_connect_backend on all available backends in order.
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.
Definition soundio.h:838
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_outstream_end_write(struct SoundIoOutStream *outstream)
Commits the write that you began with soundio_outstream_begin_write.
int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer)
Returns how many bytes of the buffer is free, ready for writing.
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.
bool soundio_device_supports_layout(struct SoundIoDevice *device, const struct SoundIoChannelLayout *layout)
Convenience function.
void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer)
Must be called by the writer.
int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream)
Clears the output stream buffer.
struct SoundIo * soundio_create(void)
Create a SoundIo context.
enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index)
get the available backend at the specified index (0 <= index < soundio_backend_count)
int soundio_version_patch(void)
See also soundio_version_major, soundio_version_minor, soundio_version_string.
void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count)
Sorts by channel count, descending.
SoundIoDeviceAim
Definition soundio.h:228
@ SoundIoDeviceAimOutput
playback
Definition soundio.h:230
@ SoundIoDeviceAimInput
capture / recording
Definition soundio.h:229
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 b...
bool soundio_have_backend(enum SoundIoBackend backend)
Returns whether libsoundio was compiled with backend.
SoundIoFormat
For your convenience, Native Endian and Foreign Endian constants are defined which point to the respe...
Definition soundio.h:235
@ SoundIoFormatFloat64LE
Float 64 bit Little Endian, Range -1.0 to 1.0.
Definition soundio.h:253
@ SoundIoFormatFloat32BE
Float 32 bit Big Endian, Range -1.0 to 1.0.
Definition soundio.h:252
@ SoundIoFormatU32BE
Unsigned 32 bit Big Endian.
Definition soundio.h:250
@ SoundIoFormatS16BE
Signed 16 bit Big Endian.
Definition soundio.h:240
@ SoundIoFormatU16LE
Unsigned 16 bit Little Endian.
Definition soundio.h:241
@ SoundIoFormatS24LE
Signed 24 bit Little Endian using low three bytes in 32-bit word.
Definition soundio.h:243
@ SoundIoFormatS16LE
Signed 16 bit Little Endian.
Definition soundio.h:239
@ SoundIoFormatFloat64BE
Float 64 bit Big Endian, Range -1.0 to 1.0.
Definition soundio.h:254
@ SoundIoFormatS8
Signed 8 bit.
Definition soundio.h:237
@ SoundIoFormatU24LE
Unsigned 24 bit Little Endian using low three bytes in 32-bit word.
Definition soundio.h:245
@ SoundIoFormatU8
Unsigned 8 bit.
Definition soundio.h:238
@ SoundIoFormatU24BE
Unsigned 24 bit Big Endian using low three bytes in 32-bit word.
Definition soundio.h:246
@ SoundIoFormatInvalid
Definition soundio.h:236
@ SoundIoFormatFloat32LE
Float 32 bit Little Endian, Range -1.0 to 1.0.
Definition soundio.h:251
@ SoundIoFormatS32BE
Signed 32 bit Big Endian.
Definition soundio.h:248
@ SoundIoFormatS32LE
Signed 32 bit Little Endian.
Definition soundio.h:247
@ SoundIoFormatU16BE
Unsigned 16 bit Big Endian.
Definition soundio.h:242
@ SoundIoFormatU32LE
Unsigned 32 bit Little Endian.
Definition soundio.h:249
@ SoundIoFormatS24BE
Signed 24 bit Big Endian using low three bytes in 32-bit word.
Definition soundio.h:244
void soundio_wakeup(struct SoundIo *soundio)
Makes soundio_wait_events stop blocking.
void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count)
count in bytes.
const char * soundio_format_string(enum SoundIoFormat format)
Returns string representation of format.
int soundio_version_minor(void)
See also soundio_version_major, soundio_version_string, soundio_version_patch.
The size of this struct is OK to use.
Definition soundio.h:319
char * ptr
Base address of buffer.
Definition soundio.h:321
int step
How many bytes it takes to get from the beginning of one sample to the beginning of the next sample.
Definition soundio.h:324
The size of this struct is OK to use.
Definition soundio.h:306
enum SoundIoChannelId channels[SOUNDIO_MAX_CHANNELS]
Definition soundio.h:309
const char * name
Definition soundio.h:307
int channel_count
Definition soundio.h:308
The size of this struct is not part of the API or ABI.
Definition soundio.h:387
double software_latency_min
Software latency minimum in seconds.
Definition soundio.h:460
int ref_count
Devices are reference counted.
Definition soundio.h:482
int probe_error
This is set to a SoundIoError representing the result of the device probe.
Definition soundio.h:493
int format_count
How many formats are available in SoundIoDevice::formats.
Definition soundio.h:420
int layout_count
Definition soundio.h:412
char * name
User-friendly UTF-8 encoded text to describe the device.
Definition soundio.h:401
double software_latency_max
Software latency maximum in seconds.
Definition soundio.h:465
struct SoundIoChannelLayout * layouts
Channel layouts are handled similarly to SoundIoDevice::formats.
Definition soundio.h:411
struct SoundIoSampleRateRange * sample_rates
Sample rate is the number of frames per second.
Definition soundio.h:447
int sample_rate_current
See SoundIoDevice::current_format 0 if sample rate information is missing due to a probe error.
Definition soundio.h:454
struct SoundIoChannelLayout current_layout
See SoundIoDevice::current_format.
Definition soundio.h:414
char * id
A string of bytes that uniquely identifies this device.
Definition soundio.h:399
struct SoundIo * soundio
Read-only. Set automatically.
Definition soundio.h:389
int sample_rate_count
How many sample rate ranges are available in SoundIoDevice::sample_rates.
Definition soundio.h:451
double software_latency_current
Software latency in seconds.
Definition soundio.h:471
enum SoundIoFormat current_format
A device is either a raw device or it is a virtual device that is provided by a software mixing servi...
Definition soundio.h:439
enum SoundIoFormat * formats
List of formats this device supports.
Definition soundio.h:418
enum SoundIoDeviceAim aim
Tells whether this device is an input device or an output device.
Definition soundio.h:404
bool is_raw
Raw means that you are directly opening the hardware device and not going through a proxy such as dmi...
Definition soundio.h:478
The size of this struct is not part of the API or ABI.
Definition soundio.h:600
int sample_rate
Sample rate is the number of frames per second.
Definition soundio.h:610
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition soundio.h:614
const char * name
Optional: Name of the stream.
Definition soundio.h:664
double software_latency
Ignoring hardware latency, this is the number of seconds it takes for a captured sample to become ava...
Definition soundio.h:628
void(* read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max)
In this function call soundio_instream_begin_read and soundio_instream_end_read as many times as nece...
Definition soundio.h:644
int bytes_per_frame
computed automatically when you call soundio_instream_open
Definition soundio.h:672
enum SoundIoFormat format
Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
Definition soundio.h:606
struct SoundIoDevice * device
Populated automatically when you call soundio_outstream_create.
Definition soundio.h:602
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code.
Definition soundio.h:678
int bytes_per_sample
computed automatically when you call soundio_instream_open
Definition soundio.h:674
void * userdata
Defaults to NULL. Put whatever you want here.
Definition soundio.h:631
void(* error_callback)(struct SoundIoInStream *, int err)
Optional callback.
Definition soundio.h:656
void(* overflow_callback)(struct SoundIoInStream *)
This optional callback happens when the sound device buffer is full, yet there is more captured audio...
Definition soundio.h:649
bool non_terminal_hint
Optional: Hint that this input stream is nonterminal.
Definition soundio.h:669
The size of this struct is not part of the API or ABI.
Definition soundio.h:497
void * userdata
Defaults to NULL. Put whatever you want here.
Definition soundio.h:542
enum SoundIoFormat format
Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
Definition soundio.h:503
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code.
Definition soundio.h:596
double software_latency
Ignoring hardware latency, this is the number of seconds it takes for the last sample in a full buffe...
Definition soundio.h:538
struct SoundIoDevice * device
Populated automatically when you call soundio_outstream_create.
Definition soundio.h:499
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition soundio.h:511
const char * name
Optional: Name of the stream.
Definition soundio.h:580
float volume
Core Audio and WASAPI only: current output Audio Unit volume. Float, 0.0-1.0.
Definition soundio.h:540
void(* underflow_callback)(struct SoundIoOutStream *)
This optional callback happens when the sound device runs out of buffered audio data to play.
Definition soundio.h:565
bool non_terminal_hint
Optional: Hint that this output stream is nonterminal.
Definition soundio.h:585
int bytes_per_frame
computed automatically when you call soundio_outstream_open
Definition soundio.h:589
int sample_rate
Sample rate is the number of frames per second.
Definition soundio.h:507
void(* write_callback)(struct SoundIoOutStream *, int frame_count_min, int frame_count_max)
In this callback, you call soundio_outstream_begin_write and soundio_outstream_end_write as many time...
Definition soundio.h:559
int bytes_per_sample
computed automatically when you call soundio_outstream_open
Definition soundio.h:591
void(* error_callback)(struct SoundIoOutStream *, int err)
Optional callback.
Definition soundio.h:572
The size of this struct is OK to use.
Definition soundio.h:313
int max
Definition soundio.h:315
int min
Definition soundio.h:314
The size of this struct is not part of the API or ABI.
Definition soundio.h:328
void(* on_devices_change)(struct SoundIo *)
Optional callback.
Definition soundio.h:333
const char * app_name
Optional: Application name.
Definition soundio.h:364
void(* jack_info_callback)(const char *msg)
Optional: JACK info callback.
Definition soundio.h:380
void(* on_backend_disconnect)(struct SoundIo *, int err)
Optional callback.
Definition soundio.h:350
void(* on_events_signal)(struct SoundIo *)
Optional callback.
Definition soundio.h:354
void(* emit_rtprio_warning)(void)
Optional: Real time priority warning.
Definition soundio.h:372
void * userdata
Optional. Put whatever you want here. Defaults to NULL.
Definition soundio.h:330
enum SoundIoBackend current_backend
Read-only.
Definition soundio.h:358
void(* jack_error_callback)(const char *msg)
Optional: JACK error callback.
Definition soundio.h:383