cubeb: /build/cubeb/src/cubeb/include/cubeb/cubeb.h File Reference

cubeb 0.0.0

Loading...
Searching...
No Matches
cubeb.h File Reference

The libcubeb C API. More...

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

Go to the source code of this file.

## 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 | Requested stream latency in frames. Valid range is [1, 96000]. The actual latency may differ depending on the backend, platform, and hardware.
  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.