The libcubeb C API. More...

#include "cubeb_export.h"
#include <stdint.h>
#include <stdlib.h>

Include dependency graph for cubeb.h:

Data Structures
struct	cubeb_stream_params
	Stream format initialization parameters. More...

struct	cubeb_device
	Audio device description. More...

struct	cubeb_device_info
	This structure holds the characteristics of an input or output audio device. More...

struct	cubeb_device_collection
	Device collection. More...

struct	cubeb_backend_names
	Array of compiled backends returned by `cubeb_get_backend_names`. More...

Macros
#define	CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16LE
	16-bit integers, native endianess, when on a Little Endian environment.

#define	CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32LE
	32-bit floating points, native endianess, when on a Little Endian environment.

#define	CUBEB_DEVICE_FMT_S16_MASK (CUBEB_DEVICE_FMT_S16LE \| CUBEB_DEVICE_FMT_S16BE)
	All the 16-bit integers types.

#define	CUBEB_DEVICE_FMT_F32_MASK (CUBEB_DEVICE_FMT_F32LE \| CUBEB_DEVICE_FMT_F32BE)
	All the 32-bit floating points types.

#define	CUBEB_DEVICE_FMT_ALL (CUBEB_DEVICE_FMT_S16_MASK \| CUBEB_DEVICE_FMT_F32_MASK)
	All the device formats types.

Typedefs
typedef struct cubeb	cubeb
	Opaque handle referencing the application state.

typedef struct cubeb_stream	cubeb_stream
	Opaque handle referencing the stream state.

typedef void const *	cubeb_devid
	An opaque handle used to refer a particular input or output device across calls.

typedef uint32_t	cubeb_channel_layout
	A bitmask representing the channel layout of a cubeb stream.

typedef long(*	cubeb_data_callback) (cubeb_stream stream, void user_ptr, void const input_buffer, void output_buffer, long nframes)
	User supplied data callback.

typedef void(*	cubeb_state_callback) (cubeb_stream stream, void user_ptr, cubeb_state state)
	User supplied state callback.

typedef void(*	cubeb_device_changed_callback) (void *user_ptr)
	User supplied callback called when the underlying device changed.

typedef void(*	cubeb_device_collection_changed_callback) (cubeb context, void user_ptr)
	User supplied callback called when the underlying device collection changed.

typedef void(*	cubeb_log_callback) (char const *fmt,...)
	User supplied callback called when a message needs logging.

Enumerations
enum	cubeb_sample_format { CUBEB_SAMPLE_S16LE , CUBEB_SAMPLE_S16BE , CUBEB_SAMPLE_FLOAT32LE , CUBEB_SAMPLE_FLOAT32BE , CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE , CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE }
	Sample format enumeration. More...

enum	cubeb_log_level { CUBEB_LOG_DISABLED = 0 , CUBEB_LOG_NORMAL , CUBEB_LOG_VERBOSE = 2 }
	Level (verbosity) of logging for a particular cubeb context. More...

enum	cubeb_channel { CHANNEL_UNKNOWN = 0 , CHANNEL_FRONT_LEFT = 1 << 0 , CHANNEL_FRONT_RIGHT = 1 << 1 , CHANNEL_FRONT_CENTER = 1 << 2 , CHANNEL_LOW_FREQUENCY = 1 << 3 , CHANNEL_BACK_LEFT = 1 << 4 , CHANNEL_BACK_RIGHT = 1 << 5 , CHANNEL_FRONT_LEFT_OF_CENTER = 1 << 6 , CHANNEL_FRONT_RIGHT_OF_CENTER = 1 << 7 , CHANNEL_BACK_CENTER = 1 << 8 , CHANNEL_SIDE_LEFT = 1 << 9 , CHANNEL_SIDE_RIGHT = 1 << 10 , CHANNEL_TOP_CENTER = 1 << 11 , CHANNEL_TOP_FRONT_LEFT = 1 << 12 , CHANNEL_TOP_FRONT_CENTER = 1 << 13 , CHANNEL_TOP_FRONT_RIGHT = 1 << 14 , CHANNEL_TOP_BACK_LEFT = 1 << 15 , CHANNEL_TOP_BACK_CENTER = 1 << 16 , CHANNEL_TOP_BACK_RIGHT = 1 << 17 }
	A single channel position, to be used in a bitmask.

enum	{ CUBEB_LAYOUT_UNDEFINED = 0 , CUBEB_LAYOUT_MONO = CHANNEL_FRONT_CENTER , CUBEB_LAYOUT_MONO_LFE = CUBEB_LAYOUT_MONO \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_STEREO = CHANNEL_FRONT_LEFT \| CHANNEL_FRONT_RIGHT , CUBEB_LAYOUT_STEREO_LFE = CUBEB_LAYOUT_STEREO \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_3F , CUBEB_LAYOUT_3F_LFE = CUBEB_LAYOUT_3F \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_2F1 , CUBEB_LAYOUT_2F1_LFE = CUBEB_LAYOUT_2F1 \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_3F1 , CUBEB_LAYOUT_3F1_LFE = CUBEB_LAYOUT_3F1 \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_2F2 , CUBEB_LAYOUT_2F2_LFE = CUBEB_LAYOUT_2F2 \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_QUAD , CUBEB_LAYOUT_QUAD_LFE = CUBEB_LAYOUT_QUAD \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_3F2 , CUBEB_LAYOUT_3F2_LFE = CUBEB_LAYOUT_3F2 \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_3F2_BACK = CUBEB_LAYOUT_QUAD \| CHANNEL_FRONT_CENTER , CUBEB_LAYOUT_3F2_LFE_BACK = CUBEB_LAYOUT_3F2_BACK \| CHANNEL_LOW_FREQUENCY , CUBEB_LAYOUT_3F3R_LFE , CUBEB_LAYOUT_3F4_LFE }

enum	cubeb_stream_prefs { CUBEB_STREAM_PREF_NONE = 0x00 , CUBEB_STREAM_PREF_LOOPBACK , CUBEB_STREAM_PREF_DISABLE_DEVICE_SWITCHING = 0x02 , CUBEB_STREAM_PREF_VOICE , CUBEB_STREAM_PREF_RAW , CUBEB_STREAM_PREF_PERSIST = 0x10 , CUBEB_STREAM_PREF_JACK_NO_AUTO_CONNECT = 0x20 }
	Miscellaneous stream preferences. More...

enum	cubeb_input_processing_params { CUBEB_INPUT_PROCESSING_PARAM_NONE = 0x00 , CUBEB_INPUT_PROCESSING_PARAM_ECHO_CANCELLATION = 0x01 , CUBEB_INPUT_PROCESSING_PARAM_NOISE_SUPPRESSION = 0x02 , CUBEB_INPUT_PROCESSING_PARAM_AUTOMATIC_GAIN_CONTROL = 0x04 , CUBEB_INPUT_PROCESSING_PARAM_VOICE_ISOLATION = 0x08 }
	Input stream audio processing parameters. More...

enum	cubeb_state { CUBEB_STATE_STARTED , CUBEB_STATE_STOPPED , CUBEB_STATE_DRAINED , CUBEB_STATE_ERROR }
	Stream states signaled via state_callback. More...

enum	{ CUBEB_OK = 0 , CUBEB_ERROR = -1 , CUBEB_ERROR_INVALID_FORMAT , CUBEB_ERROR_INVALID_PARAMETER = -3 , CUBEB_ERROR_NOT_SUPPORTED , CUBEB_ERROR_DEVICE_UNAVAILABLE }
	Result code enumeration. More...

enum	cubeb_device_type { CUBEB_DEVICE_TYPE_UNKNOWN , CUBEB_DEVICE_TYPE_INPUT , CUBEB_DEVICE_TYPE_OUTPUT }
	Whether a particular device is an input device (e.g. More...

enum	cubeb_device_state { CUBEB_DEVICE_STATE_DISABLED , CUBEB_DEVICE_STATE_UNPLUGGED , CUBEB_DEVICE_STATE_ENABLED }
	The state of a device. More...

enum	cubeb_device_fmt { CUBEB_DEVICE_FMT_S16LE = 0x0010 , CUBEB_DEVICE_FMT_S16BE = 0x0020 , CUBEB_DEVICE_FMT_F32LE = 0x1000 , CUBEB_DEVICE_FMT_F32BE = 0x2000 }
	Architecture specific sample type. More...

enum	cubeb_device_pref { CUBEB_DEVICE_PREF_NONE = 0x00 , CUBEB_DEVICE_PREF_MULTIMEDIA = 0x01 , CUBEB_DEVICE_PREF_VOICE = 0x02 , CUBEB_DEVICE_PREF_NOTIFICATION = 0x04 , CUBEB_DEVICE_PREF_ALL = 0x0F }
	Channel type for a `cubeb_stream`. More...

Functions
CUBEB_EXPORT int	cubeb_init (cubeb *context, char const context_name, char const *backend_name)
	Initialize an application context.

CUBEB_EXPORT char const *	cubeb_get_backend_id (cubeb *context)
	Get a read-only string identifying this context's current backend.

CUBEB_EXPORT cubeb_backend_names	cubeb_get_backend_names ()
	Get a read-only array of strings identifying available backends.

CUBEB_EXPORT int	cubeb_get_max_channel_count (cubeb context, uint32_t max_channels)
	Get the maximum possible number of channels.

CUBEB_EXPORT int	cubeb_get_min_latency (cubeb context, cubeb_stream_params params, uint32_t *latency_frames)
	Get the minimal latency value, in frames, that is guaranteed to work when creating a stream for the specified sample rate.

CUBEB_EXPORT int	cubeb_get_preferred_sample_rate (cubeb context, uint32_t rate)
	Get the preferred sample rate for this backend: this is hardware and platform dependent, and can avoid resampling, and/or trigger fastpaths.

CUBEB_EXPORT int	cubeb_get_supported_input_processing_params (cubeb context, cubeb_input_processing_params params)
	Get the supported input processing features for this backend.

CUBEB_EXPORT void	cubeb_destroy (cubeb *context)
	Destroy an application context.

CUBEB_EXPORT int	cubeb_stream_init (cubeb context, cubeb_stream stream, char const stream_name, cubeb_devid input_device, cubeb_stream_params input_stream_params, cubeb_devid output_device, cubeb_stream_params output_stream_params, uint32_t latency_frames, cubeb_data_callback data_callback, cubeb_state_callback state_callback, void *user_ptr)
	Initialize a stream associated with the supplied application context.

CUBEB_EXPORT void	cubeb_stream_destroy (cubeb_stream *stream)
	Destroy a stream.

CUBEB_EXPORT int	cubeb_stream_start (cubeb_stream *stream)
	Start playback.

CUBEB_EXPORT int	cubeb_stream_stop (cubeb_stream *stream)
	Stop playback.

CUBEB_EXPORT int	cubeb_stream_get_position (cubeb_stream stream, uint64_t position)
	Get the current stream playback position.

CUBEB_EXPORT int	cubeb_stream_get_latency (cubeb_stream stream, uint32_t latency)
	Get the latency for this stream, in frames.

CUBEB_EXPORT int	cubeb_stream_get_input_latency (cubeb_stream stream, uint32_t latency)
	Get the input latency for this stream, in frames.

CUBEB_EXPORT int	cubeb_stream_set_volume (cubeb_stream *stream, float volume)
	Set the volume for a stream.

CUBEB_EXPORT int	cubeb_stream_set_name (cubeb_stream stream, char const stream_name)
	Change a stream's name.

CUBEB_EXPORT int	cubeb_stream_get_current_device (cubeb_stream stm, cubeb_device *const device)
	Get the current output device for this stream.

CUBEB_EXPORT int	cubeb_stream_set_input_mute (cubeb_stream *stream, int mute)
	Set input mute state for this stream.

CUBEB_EXPORT int	cubeb_stream_set_input_processing_params (cubeb_stream *stream, cubeb_input_processing_params params)
	Set what input processing features to enable for this stream.

CUBEB_EXPORT int	cubeb_stream_device_destroy (cubeb_stream stream, cubeb_device devices)
	Destroy a cubeb_device structure.

CUBEB_EXPORT int	cubeb_stream_register_device_changed_callback (cubeb_stream *stream, cubeb_device_changed_callback device_changed_callback)
	Set a callback to be notified when the output device changes.

CUBEB_EXPORT void *	cubeb_stream_user_ptr (cubeb_stream *stream)
	Return the user data pointer registered with the stream with cubeb_stream_init.

CUBEB_EXPORT int	cubeb_enumerate_devices (cubeb context, cubeb_device_type devtype, cubeb_device_collection collection)
	Returns enumerated devices.

CUBEB_EXPORT int	cubeb_device_collection_destroy (cubeb context, cubeb_device_collection collection)
	Destroy a cubeb_device_collection, and its `cubeb_device_info`.

CUBEB_EXPORT int	cubeb_register_device_collection_changed (cubeb context, cubeb_device_type devtype, cubeb_device_collection_changed_callback callback, void user_ptr)
	Registers a callback which is called when the system detects a new device or a device is removed, or when the default device changes for the specified device type.

CUBEB_EXPORT int	cubeb_set_log_callback (cubeb_log_level log_level, cubeb_log_callback log_callback)
	Set a callback to be called with a message.

Detailed Description

The libcubeb C API.

Typedef Documentation

◆ cubeb_channel_layout

typedef uint32_t cubeb_channel_layout

A bitmask representing the channel layout of a cubeb stream.

This is bit-compatible with WAVEFORMATEXENSIBLE and in the same order as the SMPTE ordering.

◆ cubeb_data_callback

typedef long(* cubeb_data_callback) (cubeb_stream *stream, void *user_ptr, void const *input_buffer, void *output_buffer, long nframes)

User supplied data callback.

Calling other cubeb functions from this callback is unsafe.
The code in the callback should be non-blocking.

Returning less than the number of frames this callback asks for or provides puts the stream in drain mode. This callback will not be called again, and the state callback will be called with CUBEB_STATE_DRAINED when all the frames have been output.

Parameters

stream	The stream for which this callback fired.
user_ptr	The pointer passed to cubeb_stream_init.
input_buffer	A pointer containing the input data, or nullptr if this is an output-only stream.
output_buffer	A pointer to a buffer to be filled with audio samples, or nullptr if this is an input-only stream.
nframes	The number of frames of the two buffer.

Return values

If	the stream has output, this is the number of frames written to the output buffer. In this case, if this number is less than nframes then the stream will start to drain. If the stream is input only, then returning nframes indicates data has been read. In this case, a value less than nframes will result in the stream being stopped.
CUBEB_ERROR	on error, in which case the data callback will stop and the stream will enter a shutdown state.

◆ cubeb_state_callback

typedef void(* cubeb_state_callback) (cubeb_stream *stream, void *user_ptr, cubeb_state state)

User supplied state callback.

Parameters

stream	The stream for this this callback fired.
user_ptr	The pointer passed to cubeb_stream_init.
state	The new state of the stream.

◆ cubeb_device_changed_callback

typedef void(* cubeb_device_changed_callback) (void *user_ptr)

User supplied callback called when the underlying device changed.

Parameters

user_ptr The pointer passed to cubeb_stream_init.

◆ cubeb_device_collection_changed_callback

typedef void(* cubeb_device_collection_changed_callback) (cubeb *context, void *user_ptr)

User supplied callback called when the underlying device collection changed.

This callback will be called when devices are added or removed from the system, or when the default device changes for the specified device type.

Parameters

context	A pointer to the cubeb context.
user_ptr	The pointer passed to cubeb_register_device_collection_changed.

Enumeration Type Documentation

◆ cubeb_sample_format

enum cubeb_sample_format

Sample format enumeration.

Enumerator
CUBEB_SAMPLE_S16LE	Little endian 16-bit signed PCM. Big endian 16-bit signed PCM.
CUBEB_SAMPLE_S16BE	Little endian 32-bit IEEE floating point PCM.
CUBEB_SAMPLE_FLOAT32LE	Big endian 32-bit IEEE floating point PCM.
CUBEB_SAMPLE_FLOAT32BE	Native endian 16-bit signed PCM.
CUBEB_SAMPLE_S16NE	Native endian 32-bit IEEE floating point PCM.

◆ cubeb_log_level

enum cubeb_log_level

Level (verbosity) of logging for a particular cubeb context.

Enumerator

CUBEB_LOG_NORMAL

< Logging disabled

Logging lifetime operation (creation/destruction).

CUBEB_LOG_VERBOSE

Verbose logging of callbacks, can have performance implications.

◆ cubeb_stream_prefs

enum cubeb_stream_prefs

Miscellaneous stream preferences.

Enumerator
CUBEB_STREAM_PREF_NONE	No stream preferences are requested.
CUBEB_STREAM_PREF_LOOPBACK	Request a loopback stream. Should be specified on the input params and an output device to loopback from should be passed in place of an input device.
CUBEB_STREAM_PREF_DISABLE_DEVICE_SWITCHING	Disable switching default device on OS changes.
CUBEB_STREAM_PREF_VOICE	This stream is going to transport voice data. Depending on the backend and platform, this can change the audio input or output devices selected, as well as the quality of the stream, for example to accomodate bluetooth SCO modes on bluetooth devices.
CUBEB_STREAM_PREF_RAW	Windows only. Bypass all signal processing except for always on APO, driver and hardware.
CUBEB_STREAM_PREF_PERSIST	Request that the volume and mute settings should persist across restarts of the stream and/or application. This is obsolete and ignored by all backends.
CUBEB_STREAM_PREF_JACK_NO_AUTO_CONNECT	Don't automatically try to connect ports. Only affects the jack backend.

◆ cubeb_input_processing_params

enum cubeb_input_processing_params

Input stream audio processing parameters.

Only applicable with CUBEB_STREAM_PREF_VOICE.

◆ cubeb_state

enum cubeb_state

Stream states signaled via state_callback.

Enumerator
CUBEB_STATE_STARTED	Stream started.
CUBEB_STATE_STOPPED	Stream stopped.
CUBEB_STATE_DRAINED	Stream drained.
CUBEB_STATE_ERROR	Stream disabled due to error.

◆ anonymous enum

anonymous enum

Result code enumeration.

Enumerator
CUBEB_OK	Success.
CUBEB_ERROR	Unclassified error.
CUBEB_ERROR_INVALID_FORMAT	Unsupported cubeb_stream_params requested.
CUBEB_ERROR_INVALID_PARAMETER	Invalid parameter specified.
CUBEB_ERROR_NOT_SUPPORTED	Optional function not implemented in current backend.
CUBEB_ERROR_DEVICE_UNAVAILABLE	Device specified by cubeb_devid not available.

◆ cubeb_device_type

enum cubeb_device_type

Whether a particular device is an input device (e.g.

a microphone), or an output device (e.g. headphones).

◆ cubeb_device_state

enum cubeb_device_state

The state of a device.

Enumerator
CUBEB_DEVICE_STATE_DISABLED	The device has been disabled at the system level.
CUBEB_DEVICE_STATE_UNPLUGGED	The device is enabled, but nothing is plugged into it.
CUBEB_DEVICE_STATE_ENABLED	The device is enabled.

◆ cubeb_device_fmt

enum cubeb_device_fmt

Architecture specific sample type.

Enumerator
CUBEB_DEVICE_FMT_S16LE	16-bit integers, Little Endian.
CUBEB_DEVICE_FMT_S16BE	16-bit integers, Big Endian.
CUBEB_DEVICE_FMT_F32LE	32-bit floating point, Little Endian.
CUBEB_DEVICE_FMT_F32BE	32-bit floating point, Big Endian.

◆ cubeb_device_pref

enum cubeb_device_pref

Channel type for a cubeb_stream.

Depending on the backend and platform used, this can control inter-stream interruption, ducking, and volume control.

Function Documentation

◆ cubeb_init()

CUBEB_EXPORT int cubeb_init	(	cubeb **	context,
		char const *	context_name,
		char const *	backend_name
	)

Initialize an application context.

This will perform any library or application scoped initialization.

Note: On Windows platforms, COM must be initialized in MTA mode on any thread that will call the cubeb API.

Parameters

context	A out param where an opaque pointer to the application context will be returned.
context_name	A name for the context. Depending on the platform this can appear in different locations.
backend_name	The name of the cubeb backend user desires to select. Accepted values self-documented in cubeb.c: init_oneshot If NULL, a default ordering is used for backend choice. A valid choice overrides all other possible backends, so long as the backend was included at compile time.

Return values

CUBEB_OK	in case of success.
CUBEB_ERROR	in case of error, for example because the host has no audio hardware.

◆ cubeb_get_backend_id()

CUBEB_EXPORT char const * cubeb_get_backend_id ( cubeb * context )

Get a read-only string identifying this context's current backend.

Parameters

context A pointer to the cubeb context.

Return values

Read-only string identifying current backend.

◆ cubeb_get_backend_names()

CUBEB_EXPORT cubeb_backend_names cubeb_get_backend_names ( )

Get a read-only array of strings identifying available backends.

These can be passed as backend_name parameter to cubeb_init.

Return values

Struct containing the array with backend names.

◆ cubeb_get_max_channel_count()

CUBEB_EXPORT int cubeb_get_max_channel_count	(	cubeb *	context,
		uint32_t *	max_channels
	)

Get the maximum possible number of channels.

Parameters

context	A pointer to the cubeb context.
max_channels	The maximum number of channels.

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER
CUBEB_ERROR_NOT_SUPPORTED
CUBEB_ERROR

◆ cubeb_get_min_latency()

CUBEB_EXPORT int cubeb_get_min_latency	(	cubeb *	context,
		cubeb_stream_params *	params,
		uint32_t *	latency_frames
	)

Get the minimal latency value, in frames, that is guaranteed to work when creating a stream for the specified sample rate.

This is platform, hardware and backend dependent.

Parameters

context	A pointer to the cubeb context.
params	On some backends, the minimum achievable latency depends on the characteristics of the stream.
latency_frames	The latency value, in frames, to pass to cubeb_stream_init.

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_get_preferred_sample_rate()

CUBEB_EXPORT int cubeb_get_preferred_sample_rate	(	cubeb *	context,
		uint32_t *	rate
	)

Get the preferred sample rate for this backend: this is hardware and platform dependent, and can avoid resampling, and/or trigger fastpaths.

Parameters

context	A pointer to the cubeb context.
rate	The samplerate (in Hz) the current configuration prefers.

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_get_supported_input_processing_params()

CUBEB_EXPORT int cubeb_get_supported_input_processing_params	(	cubeb *	context,
		cubeb_input_processing_params *	params
	)

Get the supported input processing features for this backend.

See cubeb_stream_set_input_processing for how to set them for a particular input stream.

Parameters

context	A pointer to the cubeb context.
params	Out parameter for the input processing params supported by this backend.

Return values

CUBEB_OK
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_destroy()

CUBEB_EXPORT void cubeb_destroy ( cubeb * context )

Destroy an application context.

This must be called after all stream have been destroyed.

Parameters

context A pointer to the cubeb context.

◆ cubeb_stream_init()

CUBEB_EXPORT int cubeb_stream_init	(	cubeb *	context,
		cubeb_stream **	stream,
		char const *	stream_name,
		cubeb_devid	input_device,
		cubeb_stream_params *	input_stream_params,
		cubeb_devid	output_device,
		cubeb_stream_params *	output_stream_params,
		uint32_t	latency_frames,
		cubeb_data_callback	data_callback,
		cubeb_state_callback	state_callback,
		void *	user_ptr
	)

Initialize a stream associated with the supplied application context.

Parameters

context	A pointer to the cubeb context.
stream	An out parameter to be filled with the an opaque pointer to a cubeb stream.
stream_name	A name for this stream.
input_device	Device for the input side of the stream. If NULL the default input device is used. Passing a valid cubeb_devid means the stream only ever uses that device. Passing a NULL cubeb_devid allows the stream to follow that device type's OS default.
input_stream_params	Parameters for the input side of the stream, or NULL if this stream is output only.
output_device	Device for the output side of the stream. If NULL the default output device is used. Passing a valid cubeb_devid means the stream only ever uses that device. Passing a NULL cubeb_devid allows the stream to follow that device type's OS default.
output_stream_params	Parameters for the output side of the stream, or NULL if this stream is input only. When input and output stream parameters are supplied, their rate has to be the same.
latency_frames	Stream latency in frames. Valid range is [1, 96000].
data_callback	Will be called to preroll data before playback is started by cubeb_stream_start.
state_callback	A pointer to a state callback.
user_ptr	A pointer that will be passed to the callbacks. This pointer must outlive the life time of the stream.

Return values

CUBEB_OK
CUBEB_ERROR
CUBEB_ERROR_INVALID_FORMAT
CUBEB_ERROR_DEVICE_UNAVAILABLE

◆ cubeb_stream_destroy()

CUBEB_EXPORT void cubeb_stream_destroy ( cubeb_stream * stream )

Destroy a stream.

cubeb_stream_stop MUST be called before destroying a stream.

Parameters

stream The stream to destroy.

◆ cubeb_stream_start()

CUBEB_EXPORT int cubeb_stream_start ( cubeb_stream * stream )

Start playback.

Parameters

stream

Return values

CUBEB_OK
CUBEB_ERROR

◆ cubeb_stream_stop()

CUBEB_EXPORT int cubeb_stream_stop ( cubeb_stream * stream )

Stop playback.

Parameters

stream

Return values

CUBEB_OK
CUBEB_ERROR

◆ cubeb_stream_get_position()

CUBEB_EXPORT int cubeb_stream_get_position	(	cubeb_stream *	stream,
		uint64_t *	position
	)

Get the current stream playback position.

Parameters

stream
position	Playback position in frames.

Return values

CUBEB_OK
CUBEB_ERROR

◆ cubeb_stream_get_latency()

CUBEB_EXPORT int cubeb_stream_get_latency	(	cubeb_stream *	stream,
		uint32_t *	latency
	)

Get the latency for this stream, in frames.

This is the number of frames between the time cubeb acquires the data in the callback and the listener can hear the sound.

Parameters

stream
latency	Current approximate stream latency in frames.

Return values

CUBEB_OK
CUBEB_ERROR_NOT_SUPPORTED
CUBEB_ERROR

◆ cubeb_stream_get_input_latency()

CUBEB_EXPORT int cubeb_stream_get_input_latency	(	cubeb_stream *	stream,
		uint32_t *	latency
	)

Get the input latency for this stream, in frames.

This is the number of frames between the time the audio input devices records the data, and they are available in the data callback. This returns CUBEB_ERROR when the stream is output-only.

Parameters

stream
latency	Current approximate stream latency in frames.

Return values

CUBEB_OK
CUBEB_ERROR_NOT_SUPPORTED
CUBEB_ERROR

◆ cubeb_stream_set_volume()

CUBEB_EXPORT int cubeb_stream_set_volume	(	cubeb_stream *	stream,
		float	volume
	)

Set the volume for a stream.

Parameters

stream	the stream for which to adjust the volume.
volume	a float between 0.0 (muted) and 1.0 (maximum volume)

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER	volume is outside [0.0, 1.0] or stream is an invalid pointer
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_set_name()

CUBEB_EXPORT int cubeb_stream_set_name	(	cubeb_stream *	stream,
		char const *	stream_name
	)

Change a stream's name.

Parameters

stream	the stream for which to set the name.
stream_name	the new name for the stream

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER	if any pointer is invalid
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_get_current_device()

CUBEB_EXPORT int cubeb_stream_get_current_device	(	cubeb_stream *	stm,
		cubeb_device **const	device
	)

Get the current output device for this stream.

Parameters

stm	the stream for which to query the current output device
device	a pointer in which the current output device will be stored.

Return values

CUBEB_OK	in case of success
CUBEB_ERROR_INVALID_PARAMETER	if either stm, device or count are invalid pointers
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_set_input_mute()

CUBEB_EXPORT int cubeb_stream_set_input_mute	(	cubeb_stream *	stream,
		int	mute
	)

Set input mute state for this stream.

Some platforms notify the user when an application is accessing audio input. When all inputs are muted they can prove to the user that the application is not actively capturing any input.

Parameters

stream	the stream for which to set input mute state
mute	whether the input should mute or not

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER	if this stream does not have an input device
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_set_input_processing_params()

CUBEB_EXPORT int cubeb_stream_set_input_processing_params	(	cubeb_stream *	stream,
		cubeb_input_processing_params	params
	)

Set what input processing features to enable for this stream.

Parameters

stream	the stream for which to set input processing features.
params	what input processing features to use

Return values

CUBEB_OK
CUBEB_ERROR	if params could not be applied
CUBEB_ERROR_INVALID_PARAMETER	if a given param is not supported by this backend, or if this stream does not have an input device
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_device_destroy()

CUBEB_EXPORT int cubeb_stream_device_destroy	(	cubeb_stream *	stream,
		cubeb_device *	devices
	)

Destroy a cubeb_device structure.

Parameters

stream	the stream passed in cubeb_stream_get_current_device
devices	the devices to destroy

Return values

CUBEB_OK	in case of success
CUBEB_ERROR_INVALID_PARAMETER	if devices is an invalid pointer
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_register_device_changed_callback()

CUBEB_EXPORT int cubeb_stream_register_device_changed_callback	(	cubeb_stream *	stream,
		cubeb_device_changed_callback	device_changed_callback
	)

Set a callback to be notified when the output device changes.

Parameters

stream	the stream for which to set the callback.
device_changed_callback	a function called whenever the device has changed. Passing NULL allow to unregister a function

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER	if either stream or device_changed_callback are invalid pointers.
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_stream_user_ptr()

CUBEB_EXPORT void * cubeb_stream_user_ptr ( cubeb_stream * stream )

Return the user data pointer registered with the stream with cubeb_stream_init.

Parameters

stream the stream for which to retrieve user data pointer.

Return values

user	data pointer

◆ cubeb_enumerate_devices()

CUBEB_EXPORT int cubeb_enumerate_devices	(	cubeb *	context,
		cubeb_device_type	devtype,
		cubeb_device_collection *	collection
	)

Returns enumerated devices.

Parameters

context
devtype	device type to include
collection	output collection. Must be destroyed with cubeb_device_collection_destroy

Return values

CUBEB_OK	in case of success
CUBEB_ERROR_INVALID_PARAMETER	if collection is an invalid pointer
CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_device_collection_destroy()

CUBEB_EXPORT int cubeb_device_collection_destroy	(	cubeb *	context,
		cubeb_device_collection *	collection
	)

Destroy a cubeb_device_collection, and its cubeb_device_info.

Parameters

context
collection	collection to destroy

Return values

CUBEB_OK
CUBEB_ERROR_INVALID_PARAMETER	if collection is an invalid pointer

◆ cubeb_register_device_collection_changed()

CUBEB_EXPORT int cubeb_register_device_collection_changed	(	cubeb *	context,
		cubeb_device_type	devtype,
		cubeb_device_collection_changed_callback	callback,
		void *	user_ptr
	)

Registers a callback which is called when the system detects a new device or a device is removed, or when the default device changes for the specified device type.

Parameters

context
devtype	device type to include. Different callbacks and user pointers can be registered for each devtype. The hybrid devtype `CUBEB_DEVICE_TYPE_INPUT \| CUBEB_DEVICE_TYPE_OUTPUT` is also valid and will register the provided callback and user pointer in both sides.
callback	a function called whenever the system device list changes, including when default devices change. Passing NULL allow to unregister a function. You have to unregister first before you register a new callback.
user_ptr	pointer to user specified data which will be present in subsequent callbacks.

Return values

CUBEB_ERROR_NOT_SUPPORTED

◆ cubeb_set_log_callback()

CUBEB_EXPORT int cubeb_set_log_callback	(	cubeb_log_level	log_level,
		cubeb_log_callback	log_callback
	)

Set a callback to be called with a message.

Parameters

log_level	CUBEB_LOG_VERBOSE, CUBEB_LOG_NORMAL.
log_callback	A function called with a message when there is something to log. Pass NULL to unregister.

Return values

CUBEB_OK	in case of success.
CUBEB_ERROR_INVALID_PARAMETER	if either context or log_callback are invalid pointers, or if level is not in cubeb_log_level.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cubeb_channel_layout

◆ cubeb_data_callback

◆ cubeb_state_callback

◆ cubeb_device_changed_callback

◆ cubeb_device_collection_changed_callback

Enumeration Type Documentation

◆ cubeb_sample_format

◆ cubeb_log_level

◆ cubeb_stream_prefs

◆ cubeb_input_processing_params

◆ cubeb_state

◆ anonymous enum

◆ cubeb_device_type

◆ cubeb_device_state

◆ cubeb_device_fmt

◆ cubeb_device_pref

Function Documentation

◆ cubeb_init()

◆ cubeb_get_backend_id()

◆ cubeb_get_backend_names()

◆ cubeb_get_max_channel_count()

◆ cubeb_get_min_latency()

◆ cubeb_get_preferred_sample_rate()

◆ cubeb_get_supported_input_processing_params()

◆ cubeb_destroy()

◆ cubeb_stream_init()

◆ cubeb_stream_destroy()

◆ cubeb_stream_start()

◆ cubeb_stream_stop()

◆ cubeb_stream_get_position()

◆ cubeb_stream_get_latency()

◆ cubeb_stream_get_input_latency()

◆ cubeb_stream_set_volume()

◆ cubeb_stream_set_name()

◆ cubeb_stream_get_current_device()

◆ cubeb_stream_set_input_mute()

◆ cubeb_stream_set_input_processing_params()

◆ cubeb_stream_device_destroy()

◆ cubeb_stream_register_device_changed_callback()

◆ cubeb_stream_user_ptr()

◆ cubeb_enumerate_devices()

◆ cubeb_device_collection_destroy()

◆ cubeb_register_device_collection_changed()

◆ cubeb_set_log_callback()