libsoundio  1.0.0
soundio.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015 Andrew Kelley
3  *
4  * This file is part of libsoundio, which is MIT licensed.
5  * See http://opensource.org/licenses/MIT
6  */
7 
8 #ifndef SOUNDIO_SOUNDIO_H
9 #define SOUNDIO_SOUNDIO_H
10 
11 #include "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;
541  int frame_count_min, int frame_count_max);
553  void (*error_callback)(struct SoundIoOutStream *, int err);
554 
561  const char *name;
562 
567 
568 
573 
577 };
578 
583 
586 
590 
593 
607 
609  void *userdata;
616  void (*read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max);
628  void (*error_callback)(struct SoundIoInStream *, int err);
629 
636  const char *name;
637 
643 
648 
652 };
653 
654 // Main Context
655 
660 SOUNDIO_EXPORT struct SoundIo *soundio_create(void);
661 SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
662 
663 
671 SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
683 SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
684 SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
685 
687 SOUNDIO_EXPORT const char *soundio_strerror(int error);
689 SOUNDIO_EXPORT const char *soundio_backend_name(enum SoundIoBackend backend);
690 
692 SOUNDIO_EXPORT int soundio_backend_count(struct SoundIo *soundio);
695 SOUNDIO_EXPORT enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index);
696 
698 SOUNDIO_EXPORT bool soundio_have_backend(enum SoundIoBackend backend);
699 
722 SOUNDIO_EXPORT void soundio_flush_events(struct SoundIo *soundio);
723 
726 SOUNDIO_EXPORT void soundio_wait_events(struct SoundIo *soundio);
727 
729 SOUNDIO_EXPORT void soundio_wakeup(struct SoundIo *soundio);
730 
731 
746 SOUNDIO_EXPORT void soundio_force_device_scan(struct SoundIo *soundio);
747 
748 
749 // Channel Layouts
750 
753 SOUNDIO_EXPORT bool soundio_channel_layout_equal(
754  const struct SoundIoChannelLayout *a,
755  const struct SoundIoChannelLayout *b);
756 
757 SOUNDIO_EXPORT const char *soundio_get_channel_name(enum SoundIoChannelId id);
761 SOUNDIO_EXPORT enum SoundIoChannelId soundio_parse_channel_id(const char *str, int str_len);
762 
764 SOUNDIO_EXPORT int soundio_channel_layout_builtin_count(void);
769 SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_builtin(int index);
770 
773 
775 SOUNDIO_EXPORT int soundio_channel_layout_find_channel(
776  const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel);
777 
780 SOUNDIO_EXPORT bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout);
781 
786  const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count,
787  const struct SoundIoChannelLayout *available_layouts, int available_layout_count);
788 
790 SOUNDIO_EXPORT void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count);
791 
792 
793 // Sample Formats
794 
796 SOUNDIO_EXPORT int soundio_get_bytes_per_sample(enum SoundIoFormat format);
797 
799 static inline int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count) {
801 }
802 
804 static inline int soundio_get_bytes_per_second(enum SoundIoFormat format,
805  int channel_count, int sample_rate)
806 {
807  return soundio_get_bytes_per_frame(format, channel_count) * sample_rate;
808 }
809 
811 SOUNDIO_EXPORT const char * soundio_format_string(enum SoundIoFormat format);
812 
813 
814 
815 
816 // Devices
817 
824 
827 SOUNDIO_EXPORT int soundio_input_device_count(struct SoundIo *soundio);
830 SOUNDIO_EXPORT int soundio_output_device_count(struct SoundIo *soundio);
831 
836 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_input_device(struct SoundIo *soundio, int index);
841 SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_output_device(struct SoundIo *soundio, int index);
842 
846 SOUNDIO_EXPORT int soundio_default_input_device_index(struct SoundIo *soundio);
847 
851 SOUNDIO_EXPORT int soundio_default_output_device_index(struct SoundIo *soundio);
852 
854 SOUNDIO_EXPORT void soundio_device_ref(struct SoundIoDevice *device);
857 SOUNDIO_EXPORT void soundio_device_unref(struct SoundIoDevice *device);
858 
861 SOUNDIO_EXPORT bool soundio_device_equal(
862  const struct SoundIoDevice *a,
863  const struct SoundIoDevice *b);
864 
866 SOUNDIO_EXPORT void soundio_device_sort_channel_layouts(struct SoundIoDevice *device);
867 
870 SOUNDIO_EXPORT bool soundio_device_supports_format(struct SoundIoDevice *device,
871  enum SoundIoFormat format);
872 
875 SOUNDIO_EXPORT bool soundio_device_supports_layout(struct SoundIoDevice *device,
876  const struct SoundIoChannelLayout *layout);
877 
880 SOUNDIO_EXPORT bool soundio_device_supports_sample_rate(struct SoundIoDevice *device,
881  int sample_rate);
882 
885 SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *device,
886  int sample_rate);
887 
888 
889 
890 // Output Streams
895 SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device);
897 SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
898 
920 SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
921 
929 SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
930 
961 SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
962  struct SoundIoChannelArea **areas, int *frame_count);
963 
973 SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
974 
988 SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
989 
1005 SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
1006 
1018 SOUNDIO_EXPORT int soundio_outstream_get_latency(struct SoundIoOutStream *outstream,
1019  double *out_latency);
1020 
1021 
1022 
1023 // Input Streams
1028 SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device);
1030 SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
1031 
1050 SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
1051 
1059 SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
1060 
1090 SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
1091  struct SoundIoChannelArea **areas, int *frame_count);
1100 SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
1101 
1113 SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
1114 
1123 SOUNDIO_EXPORT int soundio_instream_get_latency(struct SoundIoInStream *instream,
1124  double *out_latency);
1125 
1126 
1131 struct SoundIoRingBuffer;
1137 SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
1138 SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);
1139 
1142 SOUNDIO_EXPORT int soundio_ring_buffer_capacity(struct SoundIoRingBuffer *ring_buffer);
1143 
1145 SOUNDIO_EXPORT char *soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer);
1147 SOUNDIO_EXPORT void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1148 
1150 SOUNDIO_EXPORT char *soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer);
1152 SOUNDIO_EXPORT void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
1153 
1155 SOUNDIO_EXPORT int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer);
1156 
1158 SOUNDIO_EXPORT int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer);
1159 
1161 SOUNDIO_EXPORT void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer);
1162 
1163 #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:566
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:589
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:636
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:804
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:647
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:621
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:582
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:546
int layout_error
If setting the channel layout fails for some reason, this field is set to an error code...
Definition: soundio.h:651
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:570
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:592
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:645
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:628
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:576
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:580
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:540
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:616
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:572
struct SoundIo * soundio
Read-only. Set automatically.
Definition: soundio.h:380
const char * name
Optional: Name of the stream.
Definition: soundio.h:561
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:799
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:606
X-Y Recording.
Definition: soundio.h:153
enum SoundIoFormat format
Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
Definition: soundio.h:585
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:553
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:609
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:642
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.