Specifies where a channel is physically located.
Built-in channel layouts for convenience.
Whether a device is an input device or output device
See also ::soundio_strerror
For your convenience, Native Endian and Foreign Endian constants are defined which point to the respective SoundIoFormat values.
Returns the number of available backends.
Get a string representation of a #SoundIoBackend
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.
Returns the number of builtin channel layouts.
Populates the name field of layout if it matches a builtin one. returns whether it found a match
Returns whether the channel count field and each channel id matches in the supplied channel layouts.
Return the index of channel in layout, or -1 if not found.
Returns a builtin channel layout. 0 <= index < ::soundio_channel_layout_builtin_count
Get the default builtin channel layout for the given number of channels.
Tries ::soundio_connect_backend on all available backends in order. Possible errors: * #SoundIoErrorInvalid - already connected * #SoundIoErrorNoMem * #SoundIoErrorSystemResources * #SoundIoErrorNoSuchClient - when JACK returns JackNoSuchClient See also ::soundio_disconnect
Instead of calling ::soundio_connect you may call this function to try a specific backend. Possible errors: * #SoundIoErrorInvalid - already connected or invalid backend parameter * #SoundIoErrorNoMem * #SoundIoErrorBackendUnavailable - backend was not compiled in * #SoundIoErrorSystemResources * #SoundIoErrorNoSuchClient - when JACK returns JackNoSuchClient * #SoundIoErrorInitAudioBackend - requested backend is not active * #SoundIoErrorBackendDisconnected - backend disconnected while connecting See also ::soundio_disconnect
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
returns the index of the default input device returns -1 if there are no devices or if you never called ::soundio_flush_events.
returns the index of the default output device returns -1 if there are no devices or if you never called ::soundio_flush_events.
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
Return true if and only if the devices have the same SoundIoDevice::id, SoundIoDevice::is_raw, and SoundIoDevice::aim are the same.
Convenience function. Returns the available sample rate nearest to sample_rate, rounding up.
Add 1 to the reference count of device.
Sorts channel layouts by channel count, descending.
Convenience function. Returns whether format is included in the device's supported formats.
Convenience function. Returns whether layout is included in the device's supported channel layouts.
Convenience function. Returns whether sample_rate is included in the device's supported sample rates.
Remove 1 to the reference count of device. Clean up if it was the last reference.
Instead of calling ::soundio_connect you may call this function to try a specific backend. Possible errors: * #SoundIoErrorInvalid - already connected or invalid backend parameter * #SoundIoErrorNoMem * #SoundIoErrorBackendUnavailable - backend was not compiled in * #SoundIoErrorSystemResources * #SoundIoErrorNoSuchClient - when JACK returns JackNoSuchClient * #SoundIoErrorInitAudioBackend - requested backend is not active * #SoundIoErrorBackendDisconnected - backend disconnected while connecting See also ::soundio_disconnect
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.
Returns string representation of format.
get the available backend at the specified index (0 <= index < ::soundio_backend_count)
A frame is one sample per channel.
Returns -1 on invalid format.
Sample rate is the number of frames per second.
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.
Returns whether libsoundio was compiled with backend.
When you call ::soundio_flush_events, a snapshot of all device state is saved and these functions merely access the snapshot data. When you want to check for new devices, call ::soundio_flush_events. Or you can call ::soundio_wait_events to block until devices change. If an error occurs scanning devices in a background thread, SoundIo::on_backend_disconnect is called with the error code. Get the number of input devices. Returns -1 if you never called ::soundio_flush_events.
Call this function when you are ready to begin reading from the device buffer. * instream - (in) The input stream you want to read from. * areas - (out) The memory addresses you can read data from. It is OK to modify the pointers if that helps you iterate. There might be a "hole" in the buffer. To indicate this, areas will be NULL and frame_count tells how big the hole is in frames. * frame_count - (in/out) - Provide the number of frames you want to read; returns the number of frames you can actually read. The returned value will always be less than or equal to the provided value. If the provided value is less than frame_count_min from SoundIoInStream::read_callback this function returns with #SoundIoErrorInvalid. It is your responsibility to call this function no more and no fewer than the correct number of times according to the frame_count_min and frame_count_max criteria from SoundIoInStream::read_callback. You must call this function only from the SoundIoInStream::read_callback thread context. After calling this function, read data from areas and then use ::soundio_instream_end_read` to actually remove the data from the buffer and move the read index forward. ::soundio_instream_end_read should not be called if the buffer is empty (frame_count == 0), but it should be called if there is a hole.
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
You may not call this function from SoundIoInStream::read_callback.
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.
After you call this function, SoundIoInStream::read_callback will be called.
Get the number of output devices. Returns -1 if you never called ::soundio_flush_events.
Call this function when you are ready to begin writing to the device buffer. * outstream - (in) The output stream you want to write to. * areas - (out) The memory addresses you can write data to, one per channel. It is OK to modify the pointers if that helps you iterate. * frame_count - (in/out) Provide the number of frames you want to write. Returned will be the number of frames you can actually write, which is also the number of frames that will be written when you call ::soundio_outstream_end_write. The value returned will always be less than or equal to the value provided. It is your responsibility to call this function exactly as many times as necessary to meet the frame_count_min and frame_count_max criteria from SoundIoOutStream::write_callback. You must call this function only from the SoundIoOutStream::write_callback thread context. After calling this function, write data to areas and then call ::soundio_outstream_end_write. If this function returns an error, do not call ::soundio_outstream_end_write.
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
You may not call this function from the SoundIoOutStream::write_callback thread context.
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.
After you call this function, SoundIoOutStream::software_latency is set to the correct value.
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.
After you call this function, SoundIoOutStream::write_callback will be called.
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.
count in bytes.
count in bytes.
When you create a ring buffer, capacity might be more than the requested capacity for alignment purposes. This function returns the actual capacity.
Must be called by the writer.
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
Do not read more than capacity.
Do not write more than capacity.
Sorts by channel count, descending.
Get a string representation of a #SoundIoError
See also ::soundio_version_string, ::soundio_version_minor, ::soundio_version_patch
See also ::soundio_version_major, ::soundio_version_string, ::soundio_version_patch
See also ::soundio_version_major, ::soundio_version_minor, ::soundio_version_string
See also ::soundio_version_major, ::soundio_version_minor, ::soundio_version_patch
This function calls ::soundio_flush_events then blocks until another event is ready or you call ::soundio_wakeup. Be ready for spurious wakeups.
Makes ::soundio_wait_events stop blocking.
Whether a device is an input device or output device
See also ::soundio_strerror
For your convenience, Native Endian and Foreign Endian constants are defined which point to the respective SoundIoFormat values.
The size of this struct is not part of the API or ABI.
The size of this struct is OK to use.
The size of this struct is OK to use.
The size of this struct is not part of the API or ABI.
The size of this struct is not part of the API or ABI.
The size of this struct is not part of the API or ABI.
The size of this struct is OK to use.