libsoundio  1.1.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
34 
71 enum SoundIoError {
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 
278 #define SoundIoFormatS16NE SoundIoFormatS16LE
279 #define SoundIoFormatU16NE SoundIoFormatU16LE
280 #define SoundIoFormatS24NE SoundIoFormatS24LE
281 #define SoundIoFormatU24NE SoundIoFormatU24LE
282 #define SoundIoFormatS32NE SoundIoFormatS32LE
283 #define SoundIoFormatU32NE SoundIoFormatU32LE
284 #define SoundIoFormatFloat32NE SoundIoFormatFloat32LE
285 #define SoundIoFormatFloat64NE SoundIoFormatFloat64LE
286 
287 #define SoundIoFormatS16FE SoundIoFormatS16BE
288 #define SoundIoFormatU16FE SoundIoFormatU16BE
289 #define SoundIoFormatS24FE SoundIoFormatS24BE
290 #define SoundIoFormatU24FE SoundIoFormatU24BE
291 #define SoundIoFormatS32FE SoundIoFormatS32BE
292 #define SoundIoFormatU32FE SoundIoFormatU32BE
293 #define SoundIoFormatFloat32FE SoundIoFormatFloat32BE
294 #define SoundIoFormatFloat64FE SoundIoFormatFloat64BE
295 
296 #else
297 #error unknown byte order
298 #endif
299 
300 #define SOUNDIO_MAX_CHANNELS 24
301 struct SoundIoChannelLayout {
303  const char *name;
306 };
307 
310  int min;
311  int max;
312 };
313 
317  char *ptr;
320  int step;
321 };
322 
324 struct SoundIo {
326  void *userdata;
329  void (*on_devices_change)(struct SoundIo *);
346  void (*on_backend_disconnect)(struct SoundIo *, int err);
350  void (*on_events_signal)(struct SoundIo *);
351 
355 
360  const char *app_name;
361 
368  void (*emit_rtprio_warning)(void);
369 
376  void (*jack_info_callback)(const char *msg);
379  void (*jack_error_callback)(const char *msg);
380 };
381 
385  struct SoundIo *soundio;
386 
395  char *id;
397  char *name;
398 
401 
411 
436 
451 
468 
474  bool is_raw;
475 
479 
490 };
491 
496 
500 
504 
508 
535 
537  void *userdata;
555  int frame_count_min, int frame_count_max);
567  void (*error_callback)(struct SoundIoOutStream *, int err);
568 
575  const char *name;
576 
581 
582 
587 
592 };
593 
598 
602 
606 
610 
624 
626  void *userdata;
639  void (*read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max);
651  void (*error_callback)(struct SoundIoInStream *, int err);
652 
659  const char *name;
660 
665 
670 
674 };
675 
677 SOUNDIO_EXPORT const char *soundio_version_string(void);
679 SOUNDIO_EXPORT int soundio_version_major(void);
681 SOUNDIO_EXPORT int soundio_version_minor(void);
683 SOUNDIO_EXPORT int soundio_version_patch(void);
684 
689 SOUNDIO_EXPORT struct SoundIo *soundio_create(void);
690 SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
691 
692 
700 SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
712 SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
713 SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
714 
716 SOUNDIO_EXPORT const char *soundio_strerror(int error);
718 SOUNDIO_EXPORT const char *soundio_backend_name(enum SoundIoBackend backend);
719 
721 SOUNDIO_EXPORT int soundio_backend_count(struct SoundIo *soundio);
724 SOUNDIO_EXPORT enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index);
725 
727 SOUNDIO_EXPORT bool soundio_have_backend(enum SoundIoBackend backend);
728 
751 SOUNDIO_EXPORT void soundio_flush_events(struct SoundIo *soundio);
752 
755 SOUNDIO_EXPORT void soundio_wait_events(struct SoundIo *soundio);
756 
758 SOUNDIO_EXPORT void soundio_wakeup(struct SoundIo *soundio);
759 
760 
775 SOUNDIO_EXPORT void soundio_force_device_scan(struct SoundIo *soundio);
776 
777 
778 // Channel Layouts
779 
782 SOUNDIO_EXPORT bool soundio_channel_layout_equal(
783  const struct SoundIoChannelLayout *a,
784  const struct SoundIoChannelLayout *b);
785 
786 SOUNDIO_EXPORT const char *soundio_get_channel_name(enum SoundIoChannelId id);
790 SOUNDIO_EXPORT enum SoundIoChannelId soundio_parse_channel_id(const char *str, int str_len);
791 
793 SOUNDIO_EXPORT int soundio_channel_layout_builtin_count(void);
798 SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_builtin(int index);
799 
802 
804 SOUNDIO_EXPORT int soundio_channel_layout_find_channel(
805  const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel);
806 
809 SOUNDIO_EXPORT bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout);
810 
815  const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count,
816  const struct SoundIoChannelLayout *available_layouts, int available_layout_count);
817 
819 SOUNDIO_EXPORT void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count);
820 
821 
822 // Sample Formats
823 
825 SOUNDIO_EXPORT int soundio_get_bytes_per_sample(enum SoundIoFormat format);
826 
828 static inline int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count) {
830 }
831 
833 static inline int soundio_get_bytes_per_second(enum SoundIoFormat format,
834  int channel_count, int sample_rate)
835 {
836  return soundio_get_bytes_per_frame(format, channel_count) * sample_rate;
837 }
838 
840 SOUNDIO_EXPORT const char * soundio_format_string(enum SoundIoFormat format);
841 
842 
843 
844 
845 // Devices
846 
853 
856 SOUNDIO_EXPORT int soundio_input_device_count(struct SoundIo *soundio);
859 SOUNDIO_EXPORT int soundio_output_device_count(struct SoundIo *soundio);
860 
865 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_input_device(struct SoundIo *soundio, int index);
870 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_output_device(struct SoundIo *soundio, int index);
871 
875 SOUNDIO_EXPORT int soundio_default_input_device_index(struct SoundIo *soundio);
876 
880 SOUNDIO_EXPORT int soundio_default_output_device_index(struct SoundIo *soundio);
881 
883 SOUNDIO_EXPORT void soundio_device_ref(struct SoundIoDevice *device);
886 SOUNDIO_EXPORT void soundio_device_unref(struct SoundIoDevice *device);
887 
890 SOUNDIO_EXPORT bool soundio_device_equal(
891  const struct SoundIoDevice *a,
892  const struct SoundIoDevice *b);
893 
895 SOUNDIO_EXPORT void soundio_device_sort_channel_layouts(struct SoundIoDevice *device);
896 
899 SOUNDIO_EXPORT bool soundio_device_supports_format(struct SoundIoDevice *device,
900  enum SoundIoFormat format);
901 
904 SOUNDIO_EXPORT bool soundio_device_supports_layout(struct SoundIoDevice *device,
905  const struct SoundIoChannelLayout *layout);
906 
909 SOUNDIO_EXPORT bool soundio_device_supports_sample_rate(struct SoundIoDevice *device,
910  int sample_rate);
911 
914 SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *device,
915  int sample_rate);
916 
917 
918 
919 // Output Streams
924 SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device);
926 SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
927 
950 SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
951 
961 SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
962 
993 SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
994  struct SoundIoChannelArea **areas, int *frame_count);
995 
1005 SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
1006 
1020 SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
1021 
1041 SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
1042 
1054 SOUNDIO_EXPORT int soundio_outstream_get_latency(struct SoundIoOutStream *outstream,
1055  double *out_latency);
1056 
1057 
1058 
1059 // Input Streams
1064 SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device);
1066 SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
1067 
1086 SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
1087 
1095 SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
1096 
1126 SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
1127  struct SoundIoChannelArea **areas, int *frame_count);
1136 SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
1137 
1149 SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
1150 
1159 SOUNDIO_EXPORT int soundio_instream_get_latency(struct SoundIoInStream *instream,
1160  double *out_latency);
1161 
1162 
1167 struct SoundIoRingBuffer;
1173 SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
1174 SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);
1175 
1178 SOUNDIO_EXPORT int soundio_ring_buffer_capacity(struct SoundIoRingBuffer *ring_buffer);
1179 
1181 SOUNDIO_EXPORT char *soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer);
1183 SOUNDIO_EXPORT void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1184 
1186 SOUNDIO_EXPORT char *soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer);
1188 SOUNDIO_EXPORT void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1189 
1191 SOUNDIO_EXPORT int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer);
1192 
1194 SOUNDIO_EXPORT int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer);
1195 
1197 SOUNDIO_EXPORT void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer);
1198 
1199 #endif
Definition: soundio.h:180
int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer)
Returns how many bytes of the buffer is free, ready for writing.
Definition: soundio.h:114
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:534
int sample_rate_current
See SoundIoDevice::current_format 0 if sample rate information is missing due to a probe error...
Definition: soundio.h:450
A system resource other than memory was not available.
Definition: soundio.h:79
libsoundio was compiled without support for that backend.
Definition: soundio.h:86
Definition: soundio.h:206
Backend server shutdown or became inactive.
Definition: soundio.h:97
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.
Definition: soundio.h:163
Definition: soundio.h:123
Definition: soundio.h:199
void soundio_force_device_scan(struct SoundIo *soundio)
If necessary you can manually trigger a device rescan.
Definition: soundio.h:158
void(* on_events_signal)(struct SoundIo *)
Optional callback.
Definition: soundio.h:350
Unsigned 8 bit.
Definition: soundio.h:238
int soundio_get_bytes_per_sample(enum SoundIoFormat format)
Returns -1 on invalid format.
int soundio_instream_pause(struct SoundIoInStream *instream, bool pause)
If the underyling device supports pausing, this pauses the stream and prevents SoundIoInStream::read_...
The size of this struct is OK to use.
Definition: soundio.h:302
Definition: soundio.h:113
Definition: soundio.h:191
Definition: soundio.h:208
Definition: soundio.h:223
bool non_terminal_hint
Optional: Hint that this output stream is nonterminal.
Definition: soundio.h:580
Definition: soundio.h:184
int soundio_outstream_open(struct SoundIoOutStream *outstream)
After you call this function, SoundIoOutStream::software_latency is set to the correct value...
double software_latency_max
Software latency maximum in seconds.
Definition: soundio.h:461
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.
Definition: soundio.h:118
Last of the "other" channel ids.
Definition: soundio.h:167
Definition: soundio.h:202
Definition: soundio.h:125
int format_count
How many formats are available in SoundIoDevice::formats.
Definition: soundio.h:416
Definition: soundio.h:138
Definition: soundio.h:143
Definition: soundio.h:214
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.
An open stream had an error that can only be recovered from by destroying the stream and creating it ...
Definition: soundio.h:89
struct SoundIoDevice * soundio_get_input_device(struct SoundIo *soundio, int index)
Always returns a device.
bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout)
Populates the name field of layout if it matches a builtin one.
Definition: soundio.h:164
int sample_rate
Sample rate is the number of frames per second.
Definition: soundio.h:605
Definition: soundio.h:117
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:320
int soundio_version_major(void)
See also soundio_version_string, soundio_version_minor, soundio_version_patch.
void soundio_flush_events(struct SoundIo *soundio)
Atomically update information for all connected devices.
int min
Definition: soundio.h:310
void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count)
Sorts by channel count, descending.
int channel_count
Definition: soundio.h:304
Definition: soundio.h:148
Definition: soundio.h:162
char * soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer)
Do not read more than capacity.
const char * name
Optional: Name of the stream.
Definition: soundio.h:659
struct SoundIoDevice * soundio_get_output_device(struct SoundIo *soundio, int index)
Always returns a device.
When JACK returns JackNoSuchClient
Definition: soundio.h:93
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:833
bool soundio_device_supports_format(struct SoundIoDevice *device, enum SoundIoFormat format)
Convenience function.
void(* jack_error_callback)(const char *msg)
Optional: JACK error callback.
Definition: soundio.h:379
char * name
User-friendly UTF-8 encoded text to describe the device.
Definition: soundio.h:397
int bytes_per_sample
computed automatically when you call soundio_instream_open
Definition: soundio.h:669
Definition: soundio.h:200
struct SoundIoChannelLayout * layouts
Channel layouts are handled similarly to SoundIoDevice::formats.
Definition: soundio.h:407
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.
Float 32 bit Little Endian, Range -1.0 to 1.0.
Definition: soundio.h:251
Definition: soundio.h:220
Unsigned 32 bit Big Endian.
Definition: soundio.h:250
First of the more commonly supported ids.
Definition: soundio.h:109
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.
Definition: soundio.h:169
First of the less commonly supported ids.
Definition: soundio.h:128
Unsigned 24 bit Little Endian using low three bytes in 32-bit word.
Definition: soundio.h:245
Definition: soundio.h:236
SoundIoFormat
For your convenience, Native Endian and Foreign Endian constants are defined which point to the respe...
Definition: soundio.h:235
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:644
const char * soundio_format_string(enum SoundIoFormat format)
Returns string representation of format.
struct SoundIoDevice * device
Populated automatically when you call soundio_outstream_create.
Definition: soundio.h:597
enum SoundIoFormat * formats
List of formats this device supports.
Definition: soundio.h:414
Definition: soundio.h:121
Definition: soundio.h:165
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_channel_layout_builtin_count(void)
Returns the number of builtin channel layouts.
Definition: soundio.h:205
Definition: soundio.h:190
void(* underflow_callback)(struct SoundIoOutStream *)
This optional callback happens when the sound device runs out of buffered audio data to play...
Definition: soundio.h:560
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:673
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...
Definition: soundio.h:110
void soundio_device_unref(struct SoundIoDevice *device)
Remove 1 to the reference count of device.
int soundio_outstream_end_write(struct SoundIoOutStream *outstream)
Commits the write that you began with soundio_outstream_begin_write.
const struct SoundIoChannelLayout * soundio_channel_layout_get_builtin(int index)
Returns a builtin channel layout.
Definition: soundio.h:192
Definition: soundio.h:130
#define SOUNDIO_MAX_CHANNELS
Definition: soundio.h:300
Definition: soundio.h:132
const char * app_name
Optional: Application name.
Definition: soundio.h:360
int layout_count
Definition: soundio.h:408
Definition: soundio.h:133
Definition: soundio.h:195
The size of this struct is not part of the API or ABI.
Definition: soundio.h:324
Definition: soundio.h:137
void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer)
Must be called by the writer.
void * userdata
Optional. Put whatever you want here. Defaults to NULL.
Definition: soundio.h:326
Definition: soundio.h:111
Definition: soundio.h:183
int probe_error
This is set to a SoundIoError representing the result of the device probe.
Definition: soundio.h:489
Definition: soundio.h:135
int soundio_connect(struct SoundIo *soundio)
Tries soundio_connect_backend on all available backends in order.
Unsigned 16 bit Little Endian.
Definition: soundio.h:242
void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer)
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:435
Definition: soundio.h:172
Definition: soundio.h:170
Definition: soundio.h:194
const char * name
Definition: soundio.h:303
Definition: soundio.h:179
The size of this struct is not part of the API or ABI.
Definition: soundio.h:383
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...
Definition: soundio.h:154
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...
int bytes_per_frame
computed automatically when you call soundio_outstream_open
Definition: soundio.h:584
void(* on_backend_disconnect)(struct SoundIo *, int err)
Optional callback.
Definition: soundio.h:346
Definition: soundio.h:136
Definition: soundio.h:213
Definition: soundio.h:161
Definition: soundio.h:115
const char * soundio_get_channel_name(enum SoundIoChannelId id)
Unsigned 32 bit Little Endian.
Definition: soundio.h:249
Definition: soundio.h:116
first order ambisonic channels
Definition: soundio.h:151
void soundio_instream_destroy(struct SoundIoInStream *instream)
You may not call this function from SoundIoInStream::read_callback.
int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream)
Clears the output stream buffer.
Attempted to open a device and failed.
Definition: soundio.h:81
Definition: soundio.h:178
Definition: soundio.h:185
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition: soundio.h:609
Definition: soundio.h:196
Definition: soundio.h:182
The backend does not appear to be active or running.
Definition: soundio.h:77
int soundio_backend_count(struct SoundIo *soundio)
Returns the number of available backends.
Definition: soundio.h:152
void soundio_wakeup(struct SoundIo *soundio)
Makes soundio_wait_events stop blocking.
void * userdata
Defaults to NULL. Put whatever you want here.
Definition: soundio.h:537
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition: soundio.h:507
Definition: soundio.h:181
Definition: soundio.h:122
enum SoundIoBackend current_backend
Read-only.
Definition: soundio.h:354
int soundio_device_nearest_sample_rate(struct SoundIoDevice *device, int sample_rate)
Convenience function.
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_instream_end_read(struct SoundIoInStream *instream)
This will drop all of the frames from when you called soundio_instream_begin_read.
Signed 32 bit Little Endian.
Definition: soundio.h:247
Definition: soundio.h:219
void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count)
count in bytes.
Signed 24 bit Big Endian using low three bytes in 32-bit word.
Definition: soundio.h:244
int ref_count
Devices are reference counted.
Definition: soundio.h:478
enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index)
get the available backend at the specified index (0 <= index < soundio_backend_count) ...
SoundIoChannelId
Specifies where a channel is physically located.
Definition: soundio.h:106
void soundio_outstream_destroy(struct SoundIoOutStream *outstream)
You may not call this function from the SoundIoOutStream::write_callback thread context.
void(* on_devices_change)(struct SoundIo *)
Optional callback.
Definition: soundio.h:329
Out of memory.
Definition: soundio.h:75
Definition: soundio.h:197
Definition: soundio.h:204
struct SoundIoInStream * soundio_instream_create(struct SoundIoDevice *device)
Allocates memory and sets defaults.
Definition: soundio.h:210
Definition: soundio.h:173
int bytes_per_frame
computed automatically when you call soundio_instream_open
Definition: soundio.h:667
Definition: soundio.h:209
The programmer did not comply with the API.
Definition: soundio.h:84
void(* error_callback)(struct SoundIoInStream *, int err)
Optional callback.
Definition: soundio.h:651
double software_latency_current
Software latency in seconds.
Definition: soundio.h:467
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.
Signed 8 bit.
Definition: soundio.h:237
void soundio_wait_events(struct SoundIo *soundio)
This function calls soundio_flush_events then blocks until another event is ready or you call soundio...
SoundIoChannelLayoutId
Built-in channel layouts for convenience.
Definition: soundio.h:189
Definition: soundio.h:119
Definition: soundio.h:201
Definition: soundio.h:175
Attempted to use a device with parameters it cannot support.
Definition: soundio.h:91
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:591
char * soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer)
Do not write more than capacity.
Signed 24 bit Little Endian using low three bytes in 32-bit word.
Definition: soundio.h:243
Definition: soundio.h:176
The size of this struct is not part of the API or ABI.
Definition: soundio.h:595
int max
Definition: soundio.h:311
enum SoundIoDeviceAim aim
Tells whether this device is an input device or an output device.
Definition: soundio.h:400
int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause)
If the underlying backend and device support pausing, this pauses the stream.
struct SoundIoChannelLayout current_layout
See SoundIoDevice::current_format.
Definition: soundio.h:410
Definition: soundio.h:193
struct SoundIoSampleRateRange * sample_rates
Sample rate is the number of frames per second.
Definition: soundio.h:443
Float 64 bit Big Endian, Range -1.0 to 1.0.
Definition: soundio.h:254
Definition: soundio.h:212
void(* emit_rtprio_warning)(void)
Optional: Real time priority warning.
Definition: soundio.h:368
int soundio_version_minor(void)
See also soundio_version_major, soundio_version_string, soundio_version_patch.
Definition: soundio.h:207
Definition: soundio.h:141
struct SoundIoRingBuffer * soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity)
requested_capacity in bytes.
Definition: soundio.h:153
void(* jack_info_callback)(const char *msg)
Optional: JACK info callback.
Definition: soundio.h:376
Definition: soundio.h:98
int soundio_output_device_count(struct SoundIo *soundio)
Get the number of output devices.
The size of this struct is OK to use.
Definition: soundio.h:315
Float 32 bit Big Endian, Range -1.0 to 1.0.
Definition: soundio.h:252
Definition: soundio.h:120
Definition: soundio.h:215
Definition: soundio.h:211
char * id
A string of bytes that uniquely identifies this device.
Definition: soundio.h:395
Definition: soundio.h:177
Signed 16 bit Big Endian.
Definition: soundio.h:240
Float 64 bit Little Endian, Range -1.0 to 1.0.
Definition: soundio.h:253
const char * soundio_backend_name(enum SoundIoBackend backend)
Get a string representation of a SoundIoBackend.
bool soundio_have_backend(enum SoundIoBackend backend)
Returns whether libsoundio was compiled with backend.
Definition: soundio.h:129
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:554
bool soundio_device_supports_layout(struct SoundIoDevice *device, const struct SoundIoChannelLayout *layout)
Convenience function.
Definition: soundio.h:144
The size of this struct is not part of the API or ABI.
Definition: soundio.h:493
void soundio_destroy(struct SoundIo *soundio)
enum SoundIoFormat format
Defaults to #SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:499
Definition: soundio.h:82
Definition: soundio.h:203
Definition: soundio.h:198
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:639
int sample_rate
Sample rate is the number of frames per second.
Definition: soundio.h:503
Definition: soundio.h:73
void soundio_device_ref(struct SoundIoDevice *device)
Add 1 to the reference count of device.
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.
Unsigned 24 bit Big Endian using low three bytes in 32-bit word.
Definition: soundio.h:246
int bytes_per_sample
computed automatically when you call soundio_outstream_open
Definition: soundio.h:586
struct SoundIo * soundio
Read-only. Set automatically.
Definition: soundio.h:385
const char * name
Optional: Name of the stream.
Definition: soundio.h:575
bool soundio_device_supports_sample_rate(struct SoundIoDevice *device, int sample_rate)
Convenience function.
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:474
static int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count)
A frame is one sample per channel.
Definition: soundio.h:828
Definition: soundio.h:112
Definition: soundio.h:142
void soundio_disconnect(struct SoundIo *soundio)
const char * soundio_strerror(int error)
Get a string representation of a SoundIoError.
playback
Definition: soundio.h:230
Definition: soundio.h:124
Unsigned 16 bit Little Endian.
Definition: soundio.h:241
enum SoundIoChannelId channels[SOUNDIO_MAX_CHANNELS]
Definition: soundio.h:305
double software_latency
Ignoring hardware latency, this is the number of seconds it takes for a captured sample to become ava...
Definition: soundio.h:623
int soundio_version_patch(void)
See also soundio_version_major, soundio_version_minor, soundio_version_string.
X-Y Recording.
Definition: soundio.h:157
enum SoundIoFormat format
Defaults to #SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:601
Definition: soundio.h:224
char * ptr
Base address of buffer.
Definition: soundio.h:317
void(* error_callback)(struct SoundIoOutStream *, int err)
Optional callback.
Definition: soundio.h:567
const struct SoundIoChannelLayout * soundio_channel_layout_get_default(int channel_count)
Get the default builtin channel layout for the given number of channels.
Attempted to use parameters that the backend cannot support.
Definition: soundio.h:95
void * userdata
Defaults to NULL. Put whatever you want here.
Definition: soundio.h:626
First of the "other" channel ids.
Definition: soundio.h:160
double software_latency_min
Software latency minimum in seconds.
Definition: soundio.h:456
Definition: soundio.h:134
SoundIoDeviceAim
Definition: soundio.h:228
SoundIoBackend
Definition: soundio.h:218
Signed 32 bit Big Endian.
Definition: soundio.h:248
Definition: soundio.h:222
int soundio_instream_open(struct SoundIoInStream *instream)
After you call this function, SoundIoInStream::software_latency is set to the correct value...
int soundio_outstream_start(struct SoundIoOutStream *outstream)
After you call this function, SoundIoOutStream::write_callback will be called.
void soundio_device_sort_channel_layouts(struct SoundIoDevice *device)
Sorts channel layouts by channel count, descending.
Signed 16 bit Little Endian.
Definition: soundio.h:239
const char * soundio_version_string(void)
See also soundio_version_major, soundio_version_minor, soundio_version_patch.
Definition: soundio.h:221
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...
struct SoundIoDevice * device
Populated automatically when you call soundio_outstream_create.
Definition: soundio.h:495
Mid/side recording.
Definition: soundio.h:147
Definition: soundio.h:166
Buffer underrun occurred.
Definition: soundio.h:100
Definition: soundio.h:131
The size of this struct is OK to use.
Definition: soundio.h:309
Unable to convert to or from UTF-8 to the native string format.
Definition: soundio.h:102
struct SoundIo * soundio_create(void)
Create a SoundIo context.
struct SoundIoOutStream * soundio_outstream_create(struct SoundIoDevice *device)
Allocates memory and sets defaults.
bool non_terminal_hint
Optional: Hint that this input stream is nonterminal.
Definition: soundio.h:664
int sample_rate_count
How many sample rate ranges are available in SoundIoDevice::sample_rates.
Definition: soundio.h:447
int soundio_instream_start(struct SoundIoInStream *instream)
After you call this function, SoundIoInStream::read_callback will be called.
Definition: soundio.h:140
capture / recording
Definition: soundio.h:229
Definition: soundio.h:107
Last of the more commonly supported ids.
Definition: soundio.h:126
Definition: soundio.h:139
SoundIoError
See also soundio_strerror.
Definition: soundio.h:72
Definition: soundio.h:171
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...
Definition: soundio.h:225
Definition: soundio.h:174
int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer)
Returns how many bytes of the buffer is used, ready for reading.