Iterates over preferred_layouts. Returns the first channel layout in
preferred_layouts which matches one of the channel layouts in
available_layouts. Returns NULL if none matches.
Create a SoundIo context. You may create multiple instances of this to
connect to multiple backends. Sets all fields to defaults.
Returns NULL if and only if memory could not be allocated.
See also ::soundio_destroy
Atomically update information for all connected devices. Note that calling
this function merely flips a pointer; the actual work of collecting device
information is done elsewhere. It is performant to call this function many
times per second.
If necessary you can manually trigger a device rescan. Normally you will
not ever have to call this function, as libsoundio listens to system events
for device changes and responds to them by rescanning devices and preparing
the new device information for you to be atomically replaced when you call
::soundio_flush_events. However you might run into cases where you want to
force trigger a device rescan, for example if an ALSA device has a
SoundIoDevice::probe_error.
Always returns a device. Call ::soundio_device_unref when done.
index must be 0 <= index < ::soundio_input_device_count
Returns NULL if you never called ::soundio_flush_events or if you provide
invalid parameter values.
Always returns a device. Call ::soundio_device_unref when done.
index must be 0 <= index < ::soundio_output_device_count
Returns NULL if you never called ::soundio_flush_events or if you provide
invalid parameter values.
Allocates memory and sets defaults. Next you should fill out the struct fields
and then call ::soundio_instream_open. Sets all fields to defaults.
Returns NULL if and only if memory could not be allocated.
See also ::soundio_instream_destroy
This will drop all of the frames from when you called
::soundio_instream_begin_read.
You must call this function only from the SoundIoInStream::read_callback thread context.
You must call this function only after a successful call to
::soundio_instream_begin_read.
Obtain the number of seconds that the next frame of sound being
captured will take to arrive in the buffer, plus the amount of time that is
represented in the buffer. This includes both software and hardware latency.
After you call this function, SoundIoInStream::software_latency is set to the correct
value.
The next thing to do is call ::soundio_instream_start.
If this function returns an error, the instream is in an invalid state and
you must call ::soundio_instream_destroy on it.
If the underyling device supports pausing, this pauses the stream and
prevents SoundIoInStream::read_callback from being called. Otherwise this returns
#SoundIoErrorIncompatibleDevice.
This function may be called from any thread.
Pausing when already paused or unpausing when already unpaused has no
effect and always returns #SoundIoErrorNone.
Clears the output stream buffer.
This function can be called from any thread.
This function can be called regardless of whether the outstream is paused
or not.
Some backends do not support clearing the buffer. On these backends this
function will return SoundIoErrorIncompatibleBackend.
Some devices do not support clearing the buffer. On these devices this
function might return SoundIoErrorIncompatibleDevice.
Possible errors:
Allocates memory and sets defaults. Next you should fill out the struct fields
and then call ::soundio_outstream_open. Sets all fields to defaults.
Returns NULL if and only if memory could not be allocated.
See also ::soundio_outstream_destroy
Commits the write that you began with ::soundio_outstream_begin_write.
You must call this function only from the SoundIoOutStream::write_callback thread context.
Obtain the total number of seconds that the next frame written after the
last frame written with ::soundio_outstream_end_write will take to become
audible. This includes both software and hardware latency. In other words,
if you call this function directly after calling ::soundio_outstream_end_write,
this gives you the number of seconds that the next frame written will take
to become audible.
If the underlying backend and device support pausing, this pauses the
stream. SoundIoOutStream::write_callback may be called a few more times if
the buffer is not full.
Pausing might put the hardware into a low power state which is ideal if your
software is silent for some time.
This function may be called from any thread context, including
SoundIoOutStream::write_callback.
Pausing when already paused or unpausing when already unpaused has no
effect and returns #SoundIoErrorNone.
Given UTF-8 encoded text which is the name of a channel such as
“Front Left”, “FL”, or “front-left”, return the corresponding
SoundIoChannelId. Returns SoundIoChannelIdInvalid for no match.
A ring buffer is a single-reader single-writer lock-free fixed-size queue.
libsoundio ring buffers use memory mapping techniques to enable a
contiguous buffer when reading or writing across the boundary of the ring
buffer’s capacity.
requested_capacity in bytes.
Returns NULL if and only if memory could not be allocated.
Use ::soundio_ring_buffer_capacity to get the actual capacity, which might
be greater for alignment purposes.
See also ::soundio_ring_buffer_destroy