libsoundio  1.0.1
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 <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(_WIN32)
22 #if defined(SOUNDIO_BUILDING_LIBRARY)
23 #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllexport)
24 #else
25 #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllimport)
26 #endif
27 #else
28 #define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __attribute__((visibility ("default")))
29 #endif
30 
67 enum SoundIoError {
99 };
100 
104 
123 
141 
145 
151 
155 
164 
182 };
183 
212 };
213 
222 };
223 
227 };
228 
251 };
252 
253 #if defined(SOUNDIO_OS_BIG_ENDIAN)
254 #define SoundIoFormatS16NE SoundIoFormatS16BE
255 #define SoundIoFormatU16NE SoundIoFormatU16BE
256 #define SoundIoFormatS24NE SoundIoFormatS24BE
257 #define SoundIoFormatU24NE SoundIoFormatU24BE
258 #define SoundIoFormatS32NE SoundIoFormatS32BE
259 #define SoundIoFormatU32NE SoundIoFormatU32BE
260 #define SoundIoFormatFloat32NE SoundIoFormatFloat32BE
261 #define SoundIoFormatFloat64NE SoundIoFormatFloat64BE
262 
263 #define SoundIoFormatS16FE SoundIoFormatS16LE
264 #define SoundIoFormatU16FE SoundIoFormatU16LE
265 #define SoundIoFormatS24FE SoundIoFormatS24LE
266 #define SoundIoFormatU24FE SoundIoFormatU24LE
267 #define SoundIoFormatS32FE SoundIoFormatS32LE
268 #define SoundIoFormatU32FE SoundIoFormatU32LE
269 #define SoundIoFormatFloat32FE SoundIoFormatFloat32LE
270 #define SoundIoFormatFloat64FE SoundIoFormatFloat64LE
271 
272 #elif defined(SOUNDIO_OS_LITTLE_ENDIAN)
273 
274 #define SoundIoFormatS16NE SoundIoFormatS16LE
275 #define SoundIoFormatU16NE SoundIoFormatU16LE
276 #define SoundIoFormatS24NE SoundIoFormatS24LE
277 #define SoundIoFormatU24NE SoundIoFormatU24LE
278 #define SoundIoFormatS32NE SoundIoFormatS32LE
279 #define SoundIoFormatU32NE SoundIoFormatU32LE
280 #define SoundIoFormatFloat32NE SoundIoFormatFloat32LE
281 #define SoundIoFormatFloat64NE SoundIoFormatFloat64LE
282 
283 #define SoundIoFormatS16FE SoundIoFormatS16BE
284 #define SoundIoFormatU16FE SoundIoFormatU16BE
285 #define SoundIoFormatS24FE SoundIoFormatS24BE
286 #define SoundIoFormatU24FE SoundIoFormatU24BE
287 #define SoundIoFormatS32FE SoundIoFormatS32BE
288 #define SoundIoFormatU32FE SoundIoFormatU32BE
289 #define SoundIoFormatFloat32FE SoundIoFormatFloat32BE
290 #define SoundIoFormatFloat64FE SoundIoFormatFloat64BE
291 
292 #else
293 #error unknown byte order
294 #endif
295 
296 #define SOUNDIO_MAX_CHANNELS 24
297 struct SoundIoChannelLayout {
299  const char *name;
302 };
303 
306  int min;
307  int max;
308 };
309 
313  char *ptr;
316  int step;
317 };
318 
320 struct SoundIo {
322  void *userdata;
325  void (*on_devices_change)(struct SoundIo *);
342  void (*on_backend_disconnect)(struct SoundIo *, int err);
346  void (*on_events_signal)(struct SoundIo *);
347 
351 
356  const char *app_name;
357 
363  void (*emit_rtprio_warning)(void);
364 
371  void (*jack_info_callback)(const char *msg);
374  void (*jack_error_callback)(const char *msg);
375 };
376 
380  struct SoundIo *soundio;
381 
390  char *id;
392  char *name;
393 
396 
406 
431 
446 
463 
469  bool is_raw;
470 
474 
485 };
486 
491 
494 
498 
501 
528 
530  void *userdata;
548  int frame_count_min, int frame_count_max);
560  void (*error_callback)(struct SoundIoOutStream *, int err);
561 
568  const char *name;
569 
574 
575 
580 
584 };
585 
590 
593 
597 
600 
614 
616  void *userdata;
629  void (*read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max);
641  void (*error_callback)(struct SoundIoInStream *, int err);
642 
649  const char *name;
650 
656 
661 
665 };
666 
667 // Main Context
668 
673 SOUNDIO_EXPORT struct SoundIo *soundio_create(void);
674 SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
675 
676 
684 SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
696 SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
697 SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
698 
700 SOUNDIO_EXPORT const char *soundio_strerror(int error);
702 SOUNDIO_EXPORT const char *soundio_backend_name(enum SoundIoBackend backend);
703 
705 SOUNDIO_EXPORT int soundio_backend_count(struct SoundIo *soundio);
708 SOUNDIO_EXPORT enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index);
709 
711 SOUNDIO_EXPORT bool soundio_have_backend(enum SoundIoBackend backend);
712 
735 SOUNDIO_EXPORT void soundio_flush_events(struct SoundIo *soundio);
736 
739 SOUNDIO_EXPORT void soundio_wait_events(struct SoundIo *soundio);
740 
742 SOUNDIO_EXPORT void soundio_wakeup(struct SoundIo *soundio);
743 
744 
759 SOUNDIO_EXPORT void soundio_force_device_scan(struct SoundIo *soundio);
760 
761 
762 // Channel Layouts
763 
766 SOUNDIO_EXPORT bool soundio_channel_layout_equal(
767  const struct SoundIoChannelLayout *a,
768  const struct SoundIoChannelLayout *b);
769 
770 SOUNDIO_EXPORT const char *soundio_get_channel_name(enum SoundIoChannelId id);
774 SOUNDIO_EXPORT enum SoundIoChannelId soundio_parse_channel_id(const char *str, int str_len);
775 
777 SOUNDIO_EXPORT int soundio_channel_layout_builtin_count(void);
782 SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_builtin(int index);
783 
786 
788 SOUNDIO_EXPORT int soundio_channel_layout_find_channel(
789  const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel);
790 
793 SOUNDIO_EXPORT bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout);
794 
799  const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count,
800  const struct SoundIoChannelLayout *available_layouts, int available_layout_count);
801 
803 SOUNDIO_EXPORT void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count);
804 
805 
806 // Sample Formats
807 
809 SOUNDIO_EXPORT int soundio_get_bytes_per_sample(enum SoundIoFormat format);
810 
812 static inline int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count) {
814 }
815 
817 static inline int soundio_get_bytes_per_second(enum SoundIoFormat format,
818  int channel_count, int sample_rate)
819 {
820  return soundio_get_bytes_per_frame(format, channel_count) * sample_rate;
821 }
822 
824 SOUNDIO_EXPORT const char * soundio_format_string(enum SoundIoFormat format);
825 
826 
827 
828 
829 // Devices
830 
837 
840 SOUNDIO_EXPORT int soundio_input_device_count(struct SoundIo *soundio);
843 SOUNDIO_EXPORT int soundio_output_device_count(struct SoundIo *soundio);
844 
849 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_input_device(struct SoundIo *soundio, int index);
854 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_output_device(struct SoundIo *soundio, int index);
855 
859 SOUNDIO_EXPORT int soundio_default_input_device_index(struct SoundIo *soundio);
860 
864 SOUNDIO_EXPORT int soundio_default_output_device_index(struct SoundIo *soundio);
865 
867 SOUNDIO_EXPORT void soundio_device_ref(struct SoundIoDevice *device);
870 SOUNDIO_EXPORT void soundio_device_unref(struct SoundIoDevice *device);
871 
874 SOUNDIO_EXPORT bool soundio_device_equal(
875  const struct SoundIoDevice *a,
876  const struct SoundIoDevice *b);
877 
879 SOUNDIO_EXPORT void soundio_device_sort_channel_layouts(struct SoundIoDevice *device);
880 
883 SOUNDIO_EXPORT bool soundio_device_supports_format(struct SoundIoDevice *device,
884  enum SoundIoFormat format);
885 
888 SOUNDIO_EXPORT bool soundio_device_supports_layout(struct SoundIoDevice *device,
889  const struct SoundIoChannelLayout *layout);
890 
893 SOUNDIO_EXPORT bool soundio_device_supports_sample_rate(struct SoundIoDevice *device,
894  int sample_rate);
895 
898 SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *device,
899  int sample_rate);
900 
901 
902 
903 // Output Streams
908 SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device);
910 SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
911 
933 SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
934 
942 SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
943 
974 SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
975  struct SoundIoChannelArea **areas, int *frame_count);
976 
986 SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
987 
1001 SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
1002 
1019 SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
1020 
1032 SOUNDIO_EXPORT int soundio_outstream_get_latency(struct SoundIoOutStream *outstream,
1033  double *out_latency);
1034 
1035 
1036 
1037 // Input Streams
1042 SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device);
1044 SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
1045 
1064 SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
1065 
1073 SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
1074 
1104 SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
1105  struct SoundIoChannelArea **areas, int *frame_count);
1114 SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
1115 
1127 SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
1128 
1137 SOUNDIO_EXPORT int soundio_instream_get_latency(struct SoundIoInStream *instream,
1138  double *out_latency);
1139 
1140 
1145 struct SoundIoRingBuffer;
1151 SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
1152 SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);
1153 
1156 SOUNDIO_EXPORT int soundio_ring_buffer_capacity(struct SoundIoRingBuffer *ring_buffer);
1157 
1159 SOUNDIO_EXPORT char *soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer);
1161 SOUNDIO_EXPORT void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1162 
1164 SOUNDIO_EXPORT char *soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer);
1166 SOUNDIO_EXPORT void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1167 
1169 SOUNDIO_EXPORT int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer);
1170 
1172 SOUNDIO_EXPORT int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer);
1173 
1175 SOUNDIO_EXPORT void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer);
1176 
1177 #endif
Definition: soundio.h:176
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:110
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:527
int sample_rate_current
See SoundIoDevice::current_format 0 if sample rate information is missing due to a probe error...
Definition: soundio.h:445
A system resource other than memory was not available.
Definition: soundio.h:75
libsoundio was compiled without support for that backend.
Definition: soundio.h:82
Definition: soundio.h:202
Backend server shutdown or became inactive.
Definition: soundio.h:93
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:159
Definition: soundio.h:119
Definition: soundio.h:195
void soundio_force_device_scan(struct SoundIo *soundio)
If necessary you can manually trigger a device rescan.
Definition: soundio.h:154
void(* on_events_signal)(struct SoundIo *)
Optional callback.
Definition: soundio.h:346
Unsigned 8 bit.
Definition: soundio.h:234
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:298
Definition: soundio.h:109
Definition: soundio.h:187
Definition: soundio.h:204
Definition: soundio.h:219
bool non_terminal_hint
Optional: Hint that this output stream is nonterminal.
Definition: soundio.h:573
Definition: soundio.h:180
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:456
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:114
Last of the "other" channel ids.
Definition: soundio.h:163
Definition: soundio.h:198
Definition: soundio.h:121
int format_count
How many formats are available in SoundIoDevice::formats.
Definition: soundio.h:411
Definition: soundio.h:134
Definition: soundio.h:139
Definition: soundio.h:210
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:85
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:160
int sample_rate
Sample rate is the number of frames per second.
Definition: soundio.h:596
Definition: soundio.h:113
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:316
void soundio_flush_events(struct SoundIo *soundio)
Atomically update information for all connected devices.
int min
Definition: soundio.h:306
void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count)
Sorts by channel count, descending.
int channel_count
Definition: soundio.h:300
Definition: soundio.h:144
Definition: soundio.h:158
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:649
struct SoundIoDevice * soundio_get_output_device(struct SoundIo *soundio, int index)
Always returns a device.
When JACK returns JackNoSuchClient
Definition: soundio.h:89
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:817
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:374
char * name
User-friendly UTF-8 encoded text to describe the device.
Definition: soundio.h:392
int bytes_per_sample
computed automatically when you call soundio_instream_open
Definition: soundio.h:660
Definition: soundio.h:196
struct SoundIoChannelLayout * layouts
Channel layouts are handled similarly to SoundIoDevice::formats.
Definition: soundio.h:402
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:247
Definition: soundio.h:216
Unsigned 32 bit Big Endian.
Definition: soundio.h:246
First of the more commonly supported ids.
Definition: soundio.h:105
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:165
First of the less commonly supported ids.
Definition: soundio.h:124
Unsigned 24 bit Little Endian using low three bytes in 32-bit word.
Definition: soundio.h:241
Definition: soundio.h:232
SoundIoFormat
For your convenience, Native Endian and Foreign Endian constants are defined which point to the respe...
Definition: soundio.h:231
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:634
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:589
enum SoundIoFormat * formats
List of formats this device supports.
Definition: soundio.h:409
Definition: soundio.h:117
Definition: soundio.h:161
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:201
Definition: soundio.h:186
void(* underflow_callback)(struct SoundIoOutStream *)
This optional callback happens when the sound device runs out of buffered audio data to play...
Definition: soundio.h:553
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:664
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:106
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:188
Definition: soundio.h:126
#define SOUNDIO_MAX_CHANNELS
Definition: soundio.h:296
Definition: soundio.h:128
const char * app_name
Optional: Application name.
Definition: soundio.h:356
int layout_count
Definition: soundio.h:403
Definition: soundio.h:129
Definition: soundio.h:191
The size of this struct is not part of the API or ABI.
Definition: soundio.h:320
Definition: soundio.h:133
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:322
Definition: soundio.h:107
Definition: soundio.h:179
int probe_error
This is set to a SoundIoError representing the result of the device probe.
Definition: soundio.h:484
Definition: soundio.h:131
int soundio_connect(struct SoundIo *soundio)
Tries soundio_connect_backend on all available backends in order.
Unsigned 16 bit Little Endian.
Definition: soundio.h:238
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:430
Definition: soundio.h:168
Definition: soundio.h:166
Definition: soundio.h:190
const char * name
Definition: soundio.h:299
Definition: soundio.h:175
The size of this struct is not part of the API or ABI.
Definition: soundio.h:378
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:150
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:577
void(* on_backend_disconnect)(struct SoundIo *, int err)
Optional callback.
Definition: soundio.h:342
Definition: soundio.h:132
Definition: soundio.h:209
Definition: soundio.h:157
Definition: soundio.h:111
const char * soundio_get_channel_name(enum SoundIoChannelId id)
Unsigned 32 bit Little Endian.
Definition: soundio.h:245
Definition: soundio.h:112
first order ambisonic channels
Definition: soundio.h:147
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:77
Definition: soundio.h:174
Definition: soundio.h:181
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition: soundio.h:599
Definition: soundio.h:192
Definition: soundio.h:178
The backend does not appear to be active or running.
Definition: soundio.h:73
int soundio_backend_count(struct SoundIo *soundio)
Returns the number of available backends.
Definition: soundio.h:148
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:530
struct SoundIoChannelLayout layout
Defaults to Stereo, if available, followed by the first layout supported.
Definition: soundio.h:500
Definition: soundio.h:177
Definition: soundio.h:118
enum SoundIoBackend current_backend
Read-only.
Definition: soundio.h:350
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:243
Definition: soundio.h:215
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:240
int ref_count
Devices are reference counted.
Definition: soundio.h:473
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:102
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:325
Out of memory.
Definition: soundio.h:71
Definition: soundio.h:193
Definition: soundio.h:200
struct SoundIoInStream * soundio_instream_create(struct SoundIoDevice *device)
Allocates memory and sets defaults.
Definition: soundio.h:206
Definition: soundio.h:169
int bytes_per_frame
computed automatically when you call soundio_instream_open
Definition: soundio.h:658
Definition: soundio.h:205
The programmer did not comply with the API.
Definition: soundio.h:80
void(* error_callback)(struct SoundIoInStream *, int err)
Optional callback.
Definition: soundio.h:641
double software_latency_current
Software latency in seconds.
Definition: soundio.h:462
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:233
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:185
Definition: soundio.h:115
Definition: soundio.h:197
Definition: soundio.h:171
Attempted to use a device with parameters it cannot support.
Definition: soundio.h:87
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:583
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:239
Definition: soundio.h:172
The size of this struct is not part of the API or ABI.
Definition: soundio.h:587
int max
Definition: soundio.h:307
enum SoundIoDeviceAim aim
Tells whether this device is an input device or an output device.
Definition: soundio.h:395
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:405
Definition: soundio.h:189
struct SoundIoSampleRateRange * sample_rates
Sample rate is the number of frames per second.
Definition: soundio.h:438
Float 64 bit Big Endian, Range -1.0 to 1.0.
Definition: soundio.h:250
Definition: soundio.h:208
void(* emit_rtprio_warning)(void)
Optional: Real time priority warning.
Definition: soundio.h:363
Definition: soundio.h:203
Definition: soundio.h:137
struct SoundIoRingBuffer * soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity)
requested_capacity in bytes.
Definition: soundio.h:149
void(* jack_info_callback)(const char *msg)
Optional: JACK info callback.
Definition: soundio.h:371
Definition: soundio.h:94
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:311
Float 32 bit Big Endian, Range -1.0 to 1.0.
Definition: soundio.h:248
Definition: soundio.h:116
Definition: soundio.h:211
Definition: soundio.h:207
char * id
A string of bytes that uniquely identifies this device.
Definition: soundio.h:390
Definition: soundio.h:173
Signed 16 bit Big Endian.
Definition: soundio.h:236
Float 64 bit Little Endian, Range -1.0 to 1.0.
Definition: soundio.h:249
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:125
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:547
bool soundio_device_supports_layout(struct SoundIoDevice *device, const struct SoundIoChannelLayout *layout)
Convenience function.
Definition: soundio.h:140
The size of this struct is not part of the API or ABI.
Definition: soundio.h:488
void soundio_destroy(struct SoundIo *soundio)
enum SoundIoFormat format
Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:493
Definition: soundio.h:78
Definition: soundio.h:199
Definition: soundio.h:194
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:629
int sample_rate
Sample rate is the number of frames per second.
Definition: soundio.h:497
Definition: soundio.h:69
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:242
int bytes_per_sample
computed automatically when you call soundio_outstream_open
Definition: soundio.h:579
struct SoundIo * soundio
Read-only. Set automatically.
Definition: soundio.h:380
const char * name
Optional: Name of the stream.
Definition: soundio.h:568
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:469
static int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count)
A frame is one sample per channel.
Definition: soundio.h:812
Definition: soundio.h:108
Definition: soundio.h:138
void soundio_disconnect(struct SoundIo *soundio)
const char * soundio_strerror(int error)
Get a string representation of a SoundIoError.
playback
Definition: soundio.h:226
Definition: soundio.h:120
Unsigned 16 bit Little Endian.
Definition: soundio.h:237
enum SoundIoChannelId channels[SOUNDIO_MAX_CHANNELS]
Definition: soundio.h:301
double software_latency
Ignoring hardware latency, this is the number of seconds it takes for a captured sample to become ava...
Definition: soundio.h:613
X-Y Recording.
Definition: soundio.h:153
enum SoundIoFormat format
Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:592
Definition: soundio.h:220
char * ptr
Base address of buffer.
Definition: soundio.h:313
void(* error_callback)(struct SoundIoOutStream *, int err)
Optional callback.
Definition: soundio.h:560
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:91
void * userdata
Defaults to NULL. Put whatever you want here.
Definition: soundio.h:616
First of the "other" channel ids.
Definition: soundio.h:156
double software_latency_min
Software latency minimum in seconds.
Definition: soundio.h:451
Definition: soundio.h:130
SoundIoDeviceAim
Definition: soundio.h:224
SoundIoBackend
Definition: soundio.h:214
Signed 32 bit Big Endian.
Definition: soundio.h:244
Definition: soundio.h:218
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:235
Definition: soundio.h:217
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:490
Mid/side recording.
Definition: soundio.h:143
Definition: soundio.h:162
Buffer underrun occurred.
Definition: soundio.h:96
Definition: soundio.h:127
The size of this struct is OK to use.
Definition: soundio.h:305
Unable to convert to or from UTF-8 to the native string format.
Definition: soundio.h:98
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:655
int sample_rate_count
How many sample rate ranges are available in SoundIoDevice::sample_rates.
Definition: soundio.h:442
int soundio_instream_start(struct SoundIoInStream *instream)
After you call this function, SoundIoInStream::read_callback will be called.
Definition: soundio.h:136
capture / recording
Definition: soundio.h:225
Definition: soundio.h:103
Last of the more commonly supported ids.
Definition: soundio.h:122
Definition: soundio.h:135
SoundIoError
See also soundio_strerror.
Definition: soundio.h:68
Definition: soundio.h:167
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:221
Definition: soundio.h:170
int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer)
Returns how many bytes of the buffer is used, ready for reading.