libsoundio  2.0.0
SoundIoDevice Struct Reference

The size of this struct is not part of the API or ABI. More...

Data Fields

struct SoundIosoundio
 Read-only. Set automatically. More...
 
char * id
 A string of bytes that uniquely identifies this device. More...
 
char * name
 User-friendly UTF-8 encoded text to describe the device. More...
 
enum SoundIoDeviceAim aim
 Tells whether this device is an input device or an output device. More...
 
struct SoundIoChannelLayoutlayouts
 Channel layouts are handled similarly to SoundIoDevice::formats. More...
 
int layout_count
 
struct SoundIoChannelLayout current_layout
 See SoundIoDevice::current_format. More...
 
enum SoundIoFormatformats
 List of formats this device supports. More...
 
int format_count
 How many formats are available in SoundIoDevice::formats. More...
 
enum SoundIoFormat current_format
 A device is either a raw device or it is a virtual device that is provided by a software mixing service such as dmix or PulseAudio (see SoundIoDevice::is_raw). More...
 
struct SoundIoSampleRateRangesample_rates
 Sample rate is the number of frames per second. More...
 
int sample_rate_count
 How many sample rate ranges are available in SoundIoDevice::sample_rates. More...
 
int sample_rate_current
 See SoundIoDevice::current_format 0 if sample rate information is missing due to a probe error. More...
 
double software_latency_min
 Software latency minimum in seconds. More...
 
double software_latency_max
 Software latency maximum in seconds. More...
 
double software_latency_current
 Software latency in seconds. More...
 
bool is_raw
 Raw means that you are directly opening the hardware device and not going through a proxy such as dmix, PulseAudio, or JACK. More...
 
int ref_count
 Devices are reference counted. More...
 
int probe_error
 This is set to a SoundIoError representing the result of the device probe. More...
 

Detailed Description

The size of this struct is not part of the API or ABI.

Examples
sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.

Field Documentation

◆ aim

enum SoundIoDeviceAim SoundIoDevice::aim

Tells whether this device is an input device or an output device.

◆ current_format

enum SoundIoFormat SoundIoDevice::current_format

A device is either a raw device or it is a virtual device that is provided by a software mixing service such as dmix or PulseAudio (see SoundIoDevice::is_raw).

If it is a raw device, current_format is meaningless; the device has no current format until you open it. On the other hand, if it is a virtual device, current_format describes the destination sample format that your audio will be converted to. Or, if you're the lucky first application to open the device, you might cause the current_format to change to your format. Generally, you want to ignore current_format and use whatever format is most convenient for you which is supported by the device, because when you are the only application left, the mixer might decide to switch current_format to yours. You can learn the supported formats via formats and SoundIoDevice::format_count. If this information is missing due to a probe error, formats will be NULL. If current_format is unavailable, it will be set to SoundIoFormatInvalid. Devices are guaranteed to have at least 1 format available.

Examples
sio_list_devices.c.

◆ current_layout

struct SoundIoChannelLayout SoundIoDevice::current_layout

◆ format_count

int SoundIoDevice::format_count

How many formats are available in SoundIoDevice::formats.

Examples
sio_list_devices.c.

◆ formats

enum SoundIoFormat* SoundIoDevice::formats

List of formats this device supports.

See also SoundIoDevice::current_format.

Examples
sio_list_devices.c, and sio_record.c.

◆ id

char* SoundIoDevice::id

A string of bytes that uniquely identifies this device.

If the same physical device supports both input and output, that makes one SoundIoDevice for the input and one SoundIoDevice for the output. In this case, the id of each SoundIoDevice will be the same, and SoundIoDevice::aim will be different. Additionally, if the device supports raw mode, there may be up to four devices with the same id: one for each value of SoundIoDevice::is_raw and one for each value of SoundIoDevice::aim.

Examples
sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.

◆ is_raw

bool SoundIoDevice::is_raw

Raw means that you are directly opening the hardware device and not going through a proxy such as dmix, PulseAudio, or JACK.

When you open a raw device, other applications on the computer are not able to simultaneously access the device. Raw devices do not perform automatic resampling and thus tend to have fewer formats available.

Examples
sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.

◆ layout_count

int SoundIoDevice::layout_count

◆ layouts

struct SoundIoChannelLayout* SoundIoDevice::layouts

Channel layouts are handled similarly to SoundIoDevice::formats.

If this information is missing due to a SoundIoDevice::probe_error, layouts will be NULL. It's OK to modify this data, for example calling soundio_sort_channel_layouts on it. Devices are guaranteed to have at least 1 channel layout.

Examples
sio_list_devices.c, and sio_microphone.c.

◆ name

char* SoundIoDevice::name

User-friendly UTF-8 encoded text to describe the device.

Examples
sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.

◆ probe_error

int SoundIoDevice::probe_error

This is set to a SoundIoError representing the result of the device probe.

Ideally this will be SoundIoErrorNone in which case all the fields of the device will be populated. If there is an error code here then information about formats, sample rates, and channel layouts might be missing.

Possible errors:

Examples
sio_list_devices.c, sio_record.c, and sio_sine.c.

◆ ref_count

int SoundIoDevice::ref_count

Devices are reference counted.

See soundio_device_ref and soundio_device_unref.

◆ sample_rate_count

int SoundIoDevice::sample_rate_count

How many sample rate ranges are available in SoundIoDevice::sample_rates.

0 if sample rate information is missing due to a probe error.

Examples
sio_list_devices.c.

◆ sample_rate_current

int SoundIoDevice::sample_rate_current

See SoundIoDevice::current_format 0 if sample rate information is missing due to a probe error.

Examples
sio_list_devices.c.

◆ sample_rates

struct SoundIoSampleRateRange* SoundIoDevice::sample_rates

Sample rate is the number of frames per second.

Sample rate is handled very similar to SoundIoDevice::formats. If sample rate information is missing due to a probe error, the field will be set to NULL. Devices which have SoundIoDevice::probe_error set to SoundIoErrorNone are guaranteed to have at least 1 sample rate available.

Examples
sio_list_devices.c, and sio_record.c.

◆ software_latency_current

double SoundIoDevice::software_latency_current

Software latency in seconds.

If this value is unknown or irrelevant, it is set to 0.0. For PulseAudio and WASAPI this value is unknown until you open a stream. See SoundIoDevice::current_format

Examples
sio_list_devices.c.

◆ software_latency_max

double SoundIoDevice::software_latency_max

Software latency maximum in seconds.

If this value is unknown or irrelevant, it is set to 0.0. For PulseAudio and WASAPI this value is unknown until you open a stream.

Examples
sio_list_devices.c.

◆ software_latency_min

double SoundIoDevice::software_latency_min

Software latency minimum in seconds.

If this value is unknown or irrelevant, it is set to 0.0. For PulseAudio and WASAPI this value is unknown until you open a stream.

Examples
sio_list_devices.c.

◆ soundio

struct SoundIo* SoundIoDevice::soundio

Read-only. Set automatically.

Examples
sio_list_devices.c, sio_microphone.c, sio_record.c, and sio_sine.c.

The documentation for this struct was generated from the following file: