libsoundio  1.0.3
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 "config.h"
12 #include "endian.h"
13 #include <stdbool.h>
14 
16 #ifdef __cplusplus
17 #define SOUNDIO_EXTERN_C extern "C"
18 #else
19 #define SOUNDIO_EXTERN_C
20 #endif
21 
22 #if defined(_WIN32)
23 #if defined(SOUNDIO_BUILDING_LIBRARY)
24 #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllexport)
25 #else
26 #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllimport)
27 #endif
28 #else
29 #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __attribute__((visibility ("default")))
30 #endif
31 
68 enum SoundIoError {
100 };
101 
105 
124 
142 
146 
152 
156 
165 
183 };
184 
213 };
214 
223 };
224 
228 };
229 
252 };
253 
254 #if defined(SOUNDIO_OS_BIG_ENDIAN)
255 #define SoundIoFormatS16NE SoundIoFormatS16BE
256 #define SoundIoFormatU16NE SoundIoFormatU16BE
257 #define SoundIoFormatS24NE SoundIoFormatS24BE
258 #define SoundIoFormatU24NE SoundIoFormatU24BE
259 #define SoundIoFormatS32NE SoundIoFormatS32BE
260 #define SoundIoFormatU32NE SoundIoFormatU32BE
261 #define SoundIoFormatFloat32NE SoundIoFormatFloat32BE
262 #define SoundIoFormatFloat64NE SoundIoFormatFloat64BE
263 
264 #define SoundIoFormatS16FE SoundIoFormatS16LE
265 #define SoundIoFormatU16FE SoundIoFormatU16LE
266 #define SoundIoFormatS24FE SoundIoFormatS24LE
267 #define SoundIoFormatU24FE SoundIoFormatU24LE
268 #define SoundIoFormatS32FE SoundIoFormatS32LE
269 #define SoundIoFormatU32FE SoundIoFormatU32LE
270 #define SoundIoFormatFloat32FE SoundIoFormatFloat32LE
271 #define SoundIoFormatFloat64FE SoundIoFormatFloat64LE
272 
273 #elif defined(SOUNDIO_OS_LITTLE_ENDIAN)
274 
275 #define SoundIoFormatS16NE SoundIoFormatS16LE
276 #define SoundIoFormatU16NE SoundIoFormatU16LE
277 #define SoundIoFormatS24NE SoundIoFormatS24LE
278 #define SoundIoFormatU24NE SoundIoFormatU24LE
279 #define SoundIoFormatS32NE SoundIoFormatS32LE
280 #define SoundIoFormatU32NE SoundIoFormatU32LE
281 #define SoundIoFormatFloat32NE SoundIoFormatFloat32LE
282 #define SoundIoFormatFloat64NE SoundIoFormatFloat64LE
283 
284 #define SoundIoFormatS16FE SoundIoFormatS16BE
285 #define SoundIoFormatU16FE SoundIoFormatU16BE
286 #define SoundIoFormatS24FE SoundIoFormatS24BE
287 #define SoundIoFormatU24FE SoundIoFormatU24BE
288 #define SoundIoFormatS32FE SoundIoFormatS32BE
289 #define SoundIoFormatU32FE SoundIoFormatU32BE
290 #define SoundIoFormatFloat32FE SoundIoFormatFloat32BE
291 #define SoundIoFormatFloat64FE SoundIoFormatFloat64BE
292 
293 #else
294 #error unknown byte order
295 #endif
296 
297 #define SOUNDIO_MAX_CHANNELS 24
298 struct SoundIoChannelLayout {
300  const char *name;
303 };
304 
307  int min;
308  int max;
309 };
310 
314  char *ptr;
317  int step;
318 };
319 
321 struct SoundIo {
323  void *userdata;
326  void (*on_devices_change)(struct SoundIo *);
343  void (*on_backend_disconnect)(struct SoundIo *, int err);
347  void (*on_events_signal)(struct SoundIo *);
348 
352 
357  const char *app_name;
358 
365  void (*emit_rtprio_warning)(void);
366 
373  void (*jack_info_callback)(const char *msg);
376  void (*jack_error_callback)(const char *msg);
377 };
378 
382  struct SoundIo *soundio;
383 
392  char *id;
394  char *name;
395 
398 
408 
433 
448 
465 
471  bool is_raw;
472 
476 
487 };
488 
493 
497 
501 
505 
532 
534  void *userdata;
552  int frame_count_min, int frame_count_max);
564  void (*error_callback)(struct SoundIoOutStream *, int err);
565 
572  const char *name;
573 
578 
579 
584 
589 };
590 
595 
599 
603 
607 
621 
623  void *userdata;
636  void (*read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max);
648  void (*error_callback)(struct SoundIoInStream *, int err);
649 
656  const char *name;
657 
662 
667 
671 };
672 
673 // Main Context
674 
679 SOUNDIO_EXPORT struct SoundIo *soundio_create(void);
680 SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
681 
682 
690 SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
702 SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
703 SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
704 
706 SOUNDIO_EXPORT const char *soundio_strerror(int error);
708 SOUNDIO_EXPORT const char *soundio_backend_name(enum SoundIoBackend backend);
709 
711 SOUNDIO_EXPORT int soundio_backend_count(struct SoundIo *soundio);
714 SOUNDIO_EXPORT enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index);
715 
717 SOUNDIO_EXPORT bool soundio_have_backend(enum SoundIoBackend backend);
718 
741 SOUNDIO_EXPORT void soundio_flush_events(struct SoundIo *soundio);
742 
745 SOUNDIO_EXPORT void soundio_wait_events(struct SoundIo *soundio);
746 
748 SOUNDIO_EXPORT void soundio_wakeup(struct SoundIo *soundio);
749 
750 
765 SOUNDIO_EXPORT void soundio_force_device_scan(struct SoundIo *soundio);
766 
767 
768 // Channel Layouts
769 
772 SOUNDIO_EXPORT bool soundio_channel_layout_equal(
773  const struct SoundIoChannelLayout *a,
774  const struct SoundIoChannelLayout *b);
775 
776 SOUNDIO_EXPORT const char *soundio_get_channel_name(enum SoundIoChannelId id);
780 SOUNDIO_EXPORT enum SoundIoChannelId soundio_parse_channel_id(const char *str, int str_len);
781 
783 SOUNDIO_EXPORT int soundio_channel_layout_builtin_count(void);
788 SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_builtin(int index);
789 
792 
794 SOUNDIO_EXPORT int soundio_channel_layout_find_channel(
795  const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel);
796 
799 SOUNDIO_EXPORT bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout);
800 
805  const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count,
806  const struct SoundIoChannelLayout *available_layouts, int available_layout_count);
807 
809 SOUNDIO_EXPORT void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count);
810 
811 
812 // Sample Formats
813 
815 SOUNDIO_EXPORT int soundio_get_bytes_per_sample(enum SoundIoFormat format);
816 
818 static inline int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count) {
820 }
821 
823 static inline int soundio_get_bytes_per_second(enum SoundIoFormat format,
824  int channel_count, int sample_rate)
825 {
826  return soundio_get_bytes_per_frame(format, channel_count) * sample_rate;
827 }
828 
830 SOUNDIO_EXPORT const char * soundio_format_string(enum SoundIoFormat format);
831 
832 
833 
834 
835 // Devices
836 
843 
846 SOUNDIO_EXPORT int soundio_input_device_count(struct SoundIo *soundio);
849 SOUNDIO_EXPORT int soundio_output_device_count(struct SoundIo *soundio);
850 
855 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_input_device(struct SoundIo *soundio, int index);
860 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_output_device(struct SoundIo *soundio, int index);
861 
865 SOUNDIO_EXPORT int soundio_default_input_device_index(struct SoundIo *soundio);
866 
870 SOUNDIO_EXPORT int soundio_default_output_device_index(struct SoundIo *soundio);
871 
873 SOUNDIO_EXPORT void soundio_device_ref(struct SoundIoDevice *device);
876 SOUNDIO_EXPORT void soundio_device_unref(struct SoundIoDevice *device);
877 
880 SOUNDIO_EXPORT bool soundio_device_equal(
881  const struct SoundIoDevice *a,
882  const struct SoundIoDevice *b);
883 
885 SOUNDIO_EXPORT void soundio_device_sort_channel_layouts(struct SoundIoDevice *device);
886 
889 SOUNDIO_EXPORT bool soundio_device_supports_format(struct SoundIoDevice *device,
890  enum SoundIoFormat format);
891 
894 SOUNDIO_EXPORT bool soundio_device_supports_layout(struct SoundIoDevice *device,
895  const struct SoundIoChannelLayout *layout);
896 
899 SOUNDIO_EXPORT bool soundio_device_supports_sample_rate(struct SoundIoDevice *device,
900  int sample_rate);
901 
904 SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *device,
905  int sample_rate);
906 
907 
908 
909 // Output Streams
914 SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device);
916 SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
917 
939 SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
940 
948 SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
949 
980 SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
981  struct SoundIoChannelArea **areas, int *frame_count);
982 
992 SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
993 
1007 SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
1008 
1025 SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
1026 
1038 SOUNDIO_EXPORT int soundio_outstream_get_latency(struct SoundIoOutStream *outstream,
1039  double *out_latency);
1040 
1041 
1042 
1043 // Input Streams
1048 SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device);
1050 SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
1051 
1070 SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
1071 
1079 SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
1080 
1110 SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
1111  struct SoundIoChannelArea **areas, int *frame_count);
1120 SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
1121 
1133 SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
1134 
1143 SOUNDIO_EXPORT int soundio_instream_get_latency(struct SoundIoInStream *instream,
1144  double *out_latency);
1145 
1146 
1151 struct SoundIoRingBuffer;
1157 SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
1158 SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);
1159 
1162 SOUNDIO_EXPORT int soundio_ring_buffer_capacity(struct SoundIoRingBuffer *ring_buffer);
1163 
1165 SOUNDIO_EXPORT char *soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer);
1167 SOUNDIO_EXPORT void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1168 
1170 SOUNDIO_EXPORT char *soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer);
1172 SOUNDIO_EXPORT void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1173 
1175 SOUNDIO_EXPORT int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer);
1176 
1178 SOUNDIO_EXPORT int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer);
1179 
1181 SOUNDIO_EXPORT void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer);
1182 
1183 #endif
Definition: soundio.h:177
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:111
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:531
int sample_rate_current
See SoundIoDevice::current_format 0 if sample rate information is missing due to a probe error...
Definition: soundio.h:447
A system resource other than memory was not available.
Definition: soundio.h:76
libsoundio was compiled without support for that backend.
Definition: soundio.h:83
Definition: soundio.h:203
Backend server shutdown or became inactive.
Definition: soundio.h:94
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:160
Definition: soundio.h:120
Definition: soundio.h:196
void soundio_force_device_scan(struct SoundIo *soundio)
If necessary you can manually trigger a device rescan.
Definition: soundio.h:155
void(* on_events_signal)(struct SoundIo *)
Optional callback.
Definition: soundio.h:347
Unsigned 8 bit.
Definition: soundio.h:235
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:299
Definition: soundio.h:110
Definition: soundio.h:188
Definition: soundio.h:205
Definition: soundio.h:220
bool non_terminal_hint
Optional: Hint that this output stream is nonterminal.
Definition: soundio.h:577
Definition: soundio.h:181
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:458
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:115
Last of the "other" channel ids.
Definition: soundio.h:164
Definition: soundio.h:199
Definition: soundio.h:122
int format_count
How many formats are available in SoundIoDevice::formats.
Definition: soundio.h:413
Definition: soundio.h:135
Definition: soundio.h:140
Definition: soundio.h:211
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:86
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:161
int sample_rate
Sample rate is the number of frames per second.
Definition: soundio.h:602
Definition: soundio.h:114
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:317
void soundio_flush_events(struct SoundIo *soundio)
Atomically update information for all connected devices.
int min
Definition: soundio.h:307
void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count)
Sorts by channel count, descending.
int channel_count
Definition: soundio.h:301
Definition: soundio.h:145
Definition: soundio.h:159
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:656
struct SoundIoDevice * soundio_get_output_device(struct SoundIo *soundio, int index)
Always returns a device.
When JACK returns JackNoSuchClient
Definition: soundio.h:90
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:823
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:376
char * name
User-friendly UTF-8 encoded text to describe the device.
Definition: soundio.h:394
int bytes_per_sample
computed automatically when you call soundio_instream_open
Definition: soundio.h:666
Definition: soundio.h:197
struct SoundIoChannelLayout * layouts
Channel layouts are handled similarly to SoundIoDevice::formats.
Definition: soundio.h:404
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:248
Definition: soundio.h:217
Unsigned 32 bit Big Endian.
Definition: soundio.h:247
First of the more commonly supported ids.
Definition: soundio.h:106
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:166
First of the less commonly supported ids.
Definition: soundio.h:125
Unsigned 24 bit Little Endian using low three bytes in 32-bit word.
Definition: soundio.h:242
Definition: soundio.h:233
SoundIoFormat
For your convenience, Native Endian and Foreign Endian constants are defined which point to the respe...
Definition: soundio.h:232
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:641
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:594
enum SoundIoFormat * formats
List of formats this device supports.
Definition: soundio.h:411
Definition: soundio.h:118
Definition: soundio.h:162
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:202
Definition: soundio.h:187
void(* underflow_callback)(struct SoundIoOutStream *)
This optional callback happens when the sound device runs out of buffered audio data to play...
Definition: soundio.h:557
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:670
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:107
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:189
Definition: soundio.h:127
#define SOUNDIO_MAX_CHANNELS
Definition: soundio.h:297
Definition: soundio.h:129
const char * app_name
Optional: Application name.
Definition: soundio.h:357
int layout_count
Definition: soundio.h:405
Definition: soundio.h:130
Definition: soundio.h:192
The size of this struct is not part of the API or ABI.
Definition: soundio.h:321
Definition: soundio.h:134
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:323
Definition: soundio.h:108
Definition: soundio.h:180
int probe_error
This is set to a SoundIoError representing the result of the device probe.
Definition: soundio.h:486
Definition: soundio.h:132
int soundio_connect(struct SoundIo *soundio)
Tries soundio_connect_backend on all available backends in order.
Unsigned 16 bit Little Endian.
Definition: soundio.h:239
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:432
Definition: soundio.h:169
Definition: soundio.h:167
Definition: soundio.h:191
const char * name
Definition: soundio.h:300
Definition: soundio.h:176
The size of this struct is not part of the API or ABI.
Definition: soundio.h:380
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:151
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:581
void(* on_backend_disconnect)(struct SoundIo *, int err)
Optional callback.
Definition: soundio.h:343
Definition: soundio.h:133
Definition: soundio.h:210
Definition: soundio.h:158
Definition: soundio.h:112
const char * soundio_get_channel_name(enum SoundIoChannelId id)
Unsigned 32 bit Little Endian.
Definition: soundio.h:246
Definition: soundio.h:113
first order ambisonic channels
Definition: soundio.h:148
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:78
Definition: soundio.h:175
Definition: soundio.h:182
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition: soundio.h:606
Definition: soundio.h:193
Definition: soundio.h:179
The backend does not appear to be active or running.
Definition: soundio.h:74
int soundio_backend_count(struct SoundIo *soundio)
Returns the number of available backends.
Definition: soundio.h:149
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:534
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition: soundio.h:504
Definition: soundio.h:178
Definition: soundio.h:119
enum SoundIoBackend current_backend
Read-only.
Definition: soundio.h:351
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:244
Definition: soundio.h:216
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:241
int ref_count
Devices are reference counted.
Definition: soundio.h:475
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:103
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:326
Out of memory.
Definition: soundio.h:72
Definition: soundio.h:194
Definition: soundio.h:201
struct SoundIoInStream * soundio_instream_create(struct SoundIoDevice *device)
Allocates memory and sets defaults.
Definition: soundio.h:207
Definition: soundio.h:170
int bytes_per_frame
computed automatically when you call soundio_instream_open
Definition: soundio.h:664
Definition: soundio.h:206
The programmer did not comply with the API.
Definition: soundio.h:81
void(* error_callback)(struct SoundIoInStream *, int err)
Optional callback.
Definition: soundio.h:648
double software_latency_current
Software latency in seconds.
Definition: soundio.h:464
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:234
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:186
Definition: soundio.h:116
Definition: soundio.h:198
Definition: soundio.h:172
Attempted to use a device with parameters it cannot support.
Definition: soundio.h:88
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:588
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:240
Definition: soundio.h:173
The size of this struct is not part of the API or ABI.
Definition: soundio.h:592
int max
Definition: soundio.h:308
enum SoundIoDeviceAim aim
Tells whether this device is an input device or an output device.
Definition: soundio.h:397
int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause)
If the underlying device supports pausing, this pauses the stream.
struct SoundIoChannelLayout current_layout
See SoundIoDevice::current_format.
Definition: soundio.h:407
Definition: soundio.h:190
struct SoundIoSampleRateRange * sample_rates
Sample rate is the number of frames per second.
Definition: soundio.h:440
Float 64 bit Big Endian, Range -1.0 to 1.0.
Definition: soundio.h:251
Definition: soundio.h:209
void(* emit_rtprio_warning)(void)
Optional: Real time priority warning.
Definition: soundio.h:365
Definition: soundio.h:204
Definition: soundio.h:138
struct SoundIoRingBuffer * soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity)
requested_capacity in bytes.
Definition: soundio.h:150
void(* jack_info_callback)(const char *msg)
Optional: JACK info callback.
Definition: soundio.h:373
Definition: soundio.h:95
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:312
Float 32 bit Big Endian, Range -1.0 to 1.0.
Definition: soundio.h:249
Definition: soundio.h:117
Definition: soundio.h:212
Definition: soundio.h:208
char * id
A string of bytes that uniquely identifies this device.
Definition: soundio.h:392
Definition: soundio.h:174
Signed 16 bit Big Endian.
Definition: soundio.h:237
Float 64 bit Little Endian, Range -1.0 to 1.0.
Definition: soundio.h:250
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:126
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:551
bool soundio_device_supports_layout(struct SoundIoDevice *device, const struct SoundIoChannelLayout *layout)
Convenience function.
Definition: soundio.h:141
The size of this struct is not part of the API or ABI.
Definition: soundio.h:490
void soundio_destroy(struct SoundIo *soundio)
enum SoundIoFormat format
Defaults to #SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:496
Definition: soundio.h:79
Definition: soundio.h:200
Definition: soundio.h:195
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:636
int sample_rate
Sample rate is the number of frames per second.
Definition: soundio.h:500
Definition: soundio.h:70
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:243
int bytes_per_sample
computed automatically when you call soundio_outstream_open
Definition: soundio.h:583
struct SoundIo * soundio
Read-only. Set automatically.
Definition: soundio.h:382
const char * name
Optional: Name of the stream.
Definition: soundio.h:572
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:471
static int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count)
A frame is one sample per channel.
Definition: soundio.h:818
Definition: soundio.h:109
Definition: soundio.h:139
void soundio_disconnect(struct SoundIo *soundio)
const char * soundio_strerror(int error)
Get a string representation of a SoundIoError.
playback
Definition: soundio.h:227
Definition: soundio.h:121
Unsigned 16 bit Little Endian.
Definition: soundio.h:238
enum SoundIoChannelId channels[SOUNDIO_MAX_CHANNELS]
Definition: soundio.h:302
double software_latency
Ignoring hardware latency, this is the number of seconds it takes for a captured sample to become ava...
Definition: soundio.h:620
X-Y Recording.
Definition: soundio.h:154
enum SoundIoFormat format
Defaults to #SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:598
Definition: soundio.h:221
char * ptr
Base address of buffer.
Definition: soundio.h:314
void(* error_callback)(struct SoundIoOutStream *, int err)
Optional callback.
Definition: soundio.h:564
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:92
void * userdata
Defaults to NULL. Put whatever you want here.
Definition: soundio.h:623
First of the "other" channel ids.
Definition: soundio.h:157
double software_latency_min
Software latency minimum in seconds.
Definition: soundio.h:453
Definition: soundio.h:131
SoundIoDeviceAim
Definition: soundio.h:225
SoundIoBackend
Definition: soundio.h:215
Signed 32 bit Big Endian.
Definition: soundio.h:245
Definition: soundio.h:219
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:236
Definition: soundio.h:218
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:492
Mid/side recording.
Definition: soundio.h:144
Definition: soundio.h:163
Buffer underrun occurred.
Definition: soundio.h:97
Definition: soundio.h:128
The size of this struct is OK to use.
Definition: soundio.h:306
Unable to convert to or from UTF-8 to the native string format.
Definition: soundio.h:99
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:661
int sample_rate_count
How many sample rate ranges are available in SoundIoDevice::sample_rates.
Definition: soundio.h:444
int soundio_instream_start(struct SoundIoInStream *instream)
After you call this function, SoundIoInStream::read_callback will be called.
Definition: soundio.h:137
capture / recording
Definition: soundio.h:226
Definition: soundio.h:104
Last of the more commonly supported ids.
Definition: soundio.h:123
Definition: soundio.h:136
SoundIoError
See also soundio_strerror.
Definition: soundio.h:69
Definition: soundio.h:168
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:222
Definition: soundio.h:171
int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer)
Returns how many bytes of the buffer is used, ready for reading.