libsoundio  1.1.0
SoundIoInStream Struct Reference

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

Data Fields

struct SoundIoDevicedevice
 Populated automatically when you call soundio_outstream_create. More...
 
enum SoundIoFormat format
 Defaults to #SoundIoFormatFloat32NE, followed by the first one supported. More...
 
int sample_rate
 Sample rate is the number of frames per second. More...
 
struct SoundIoChannelLayout layout
 Defaults to Stereo, if available, followed by the first layout supported. More...
 
double software_latency
 Ignoring hardware latency, this is the number of seconds it takes for a captured sample to become available for reading. More...
 
void * userdata
 Defaults to NULL. Put whatever you want here. More...
 
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 necessary to read at minimum frame_count_min frames and at maximum frame_count_max frames. More...
 
void(* overflow_callback )(struct SoundIoInStream *)
 This optional callback happens when the sound device buffer is full, yet there is more captured audio to put in it. More...
 
void(* error_callback )(struct SoundIoInStream *, int err)
 Optional callback. More...
 
const char * name
 Optional: Name of the stream. More...
 
bool non_terminal_hint
 Optional: Hint that this input stream is nonterminal. More...
 
int bytes_per_frame
 computed automatically when you call soundio_instream_open More...
 
int bytes_per_sample
 computed automatically when you call soundio_instream_open More...
 
int layout_error
 If setting the channel layout fails for some reason, this field is set to an error code. More...
 

Detailed Description

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

Examples:
sio_microphone.c, and sio_record.c.

Field Documentation

int SoundIoInStream::bytes_per_frame

computed automatically when you call soundio_instream_open

Examples:
sio_microphone.c, and sio_record.c.
int SoundIoInStream::bytes_per_sample

computed automatically when you call soundio_instream_open

Examples:
sio_microphone.c, and sio_record.c.
struct SoundIoDevice* SoundIoInStream::device

Populated automatically when you call soundio_outstream_create.

void(* SoundIoInStream::error_callback)(struct SoundIoInStream *, int err)

Optional callback.

err is always SoundIoErrorStreaming. SoundIoErrorStreaming is an unrecoverable error. The stream is in an invalid state and must be destroyed. If you do not supply error_callback, the default callback will print a message to stderr and then abort(). This is called from the SoundIoInStream::read_callback thread context.

enum SoundIoFormat SoundIoInStream::format

Defaults to #SoundIoFormatFloat32NE, followed by the first one supported.

Examples:
sio_microphone.c, and sio_record.c.
struct SoundIoChannelLayout SoundIoInStream::layout

Defaults to Stereo, if available, followed by the first layout supported.

Examples:
sio_microphone.c, and sio_record.c.
int SoundIoInStream::layout_error

If setting the channel layout fails for some reason, this field is set to an error code.

Possible error codes are: SoundIoErrorIncompatibleDevice

const char* SoundIoInStream::name

Optional: Name of the stream.

Defaults to "SoundIoInStream"; PulseAudio uses this for the stream name. JACK uses this for the client name of the client that connects when you open the stream. WASAPI uses this for the session display name. Must not contain a colon (":").

bool SoundIoInStream::non_terminal_hint

Optional: Hint that this input stream is nonterminal.

This is used by JACK and it means that the data received by the stream will be passed on or made available to another stream. Defaults to false.

void(* SoundIoInStream::overflow_callback)(struct SoundIoInStream *)

This optional callback happens when the sound device buffer is full, yet there is more captured audio to put in it.

This is never fired for PulseAudio. This is called from the SoundIoInStream::read_callback thread context.

Examples:
sio_record.c.
void(* SoundIoInStream::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 necessary to read at minimum frame_count_min frames and at maximum frame_count_max frames.

If you return from read_callback without having read frame_count_min, the frames will be dropped. frame_count_max is how many frames are available to read.

The code in the supplied function must be suitable for real-time execution. That means that it cannot call functions that might block for a long time. This includes all I/O functions (disk, TTY, network), malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, pthread_join, pthread_cond_wait, etc.

Examples:
sio_microphone.c, and sio_record.c.
int SoundIoInStream::sample_rate

Sample rate is the number of frames per second.

Defaults to max(sample_rate_min, min(sample_rate_max, 48000))

Examples:
sio_microphone.c, and sio_record.c.
double SoundIoInStream::software_latency

Ignoring hardware latency, this is the number of seconds it takes for a captured sample to become available for reading.

After you call soundio_instream_open, this value is replaced with the actual software latency, as near to this value as possible. A higher value means less CPU usage. Defaults to a large value, potentially upwards of 2 seconds. If the device has unknown software latency min and max values, you may still set this, but you might not get the value you requested. For PulseAudio, if you set this value to non-default, it sets PA_STREAM_ADJUST_LATENCY and is the value used for fragsize. For JACK, this value is always equal to SoundIoDevice::software_latency_current

Examples:
sio_microphone.c.
void* SoundIoInStream::userdata

Defaults to NULL. Put whatever you want here.

Examples:
sio_record.c.

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