diff options
Diffstat (limited to 'media/libcubeb/include/cubeb/cubeb.h')
| -rw-r--r-- | media/libcubeb/include/cubeb/cubeb.h | 777 |
1 files changed, 777 insertions, 0 deletions
diff --git a/media/libcubeb/include/cubeb/cubeb.h b/media/libcubeb/include/cubeb/cubeb.h new file mode 100644 index 0000000000..c970246283 --- /dev/null +++ b/media/libcubeb/include/cubeb/cubeb.h @@ -0,0 +1,777 @@ +/* + * Copyright © 2011 Mozilla Foundation + * + * This program is made available under an ISC-style license. See the + * accompanying file LICENSE for details. + */ +#if !defined(CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382) +#define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 + +#include "cubeb_export.h" +#include <stdint.h> +#include <stdlib.h> + +#if defined(__cplusplus) +extern "C" { +#endif + +/** @mainpage + + @section intro Introduction + + This is the documentation for the <tt>libcubeb</tt> C API. + <tt>libcubeb</tt> is a callback-based audio API library allowing the + authoring of portable multiplatform audio playback and recording. + + @section example Example code + + This example shows how to create a duplex stream that pipes the microphone + to the speakers, with minimal latency and the proper sample-rate for the + platform. + + @code + cubeb * app_ctx; + cubeb_init(&app_ctx, "Example Application", NULL); + int rv; + uint32_t rate; + uint32_t latency_frames; + uint64_t ts; + + rv = cubeb_get_preferred_sample_rate(app_ctx, &rate); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not get preferred sample-rate"); + return rv; + } + + cubeb_stream_params output_params; + output_params.format = CUBEB_SAMPLE_FLOAT32NE; + output_params.rate = rate; + output_params.channels = 2; + output_params.layout = CUBEB_LAYOUT_UNDEFINED; + output_params.prefs = CUBEB_STREAM_PREF_NONE; + + rv = cubeb_get_min_latency(app_ctx, &output_params, &latency_frames); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not get minimum latency"); + return rv; + } + + cubeb_stream_params input_params; + input_params.format = CUBEB_SAMPLE_FLOAT32NE; + input_params.rate = rate; + input_params.channels = 1; + input_params.layout = CUBEB_LAYOUT_UNDEFINED; + input_params.prefs = CUBEB_STREAM_PREF_NONE; + + cubeb_stream * stm; + rv = cubeb_stream_init(app_ctx, &stm, "Example Stream 1", + NULL, &input_params, + NULL, &output_params, + latency_frames, + data_cb, state_cb, + NULL); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not open the stream"); + return rv; + } + + rv = cubeb_stream_start(stm); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not start the stream"); + return rv; + } + for (;;) { + cubeb_stream_get_position(stm, &ts); + printf("time=%llu\n", ts); + sleep(1); + } + rv = cubeb_stream_stop(stm); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not stop the stream"); + return rv; + } + + cubeb_stream_destroy(stm); + cubeb_destroy(app_ctx); + @endcode + + @code + long data_cb(cubeb_stream * stm, void * user, + const void * input_buffer, void * output_buffer, long nframes) + { + const float * in = input_buffer; + float * out = output_buffer; + + for (int i = 0; i < nframes; ++i) { + for (int c = 0; c < 2; ++c) { + out[2 * i + c] = in[i]; + } + } + return nframes; + } + @endcode + + @code + void state_cb(cubeb_stream * stm, void * user, cubeb_state state) + { + printf("state=%d\n", state); + } + @endcode +*/ + +/** @file + The <tt>libcubeb</tt> C API. */ + +typedef struct cubeb + cubeb; /**< Opaque handle referencing the application state. */ +typedef struct cubeb_stream + cubeb_stream; /**< Opaque handle referencing the stream state. */ + +/** Sample format enumeration. */ +typedef enum { + /**< Little endian 16-bit signed PCM. */ + CUBEB_SAMPLE_S16LE, + /**< 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, +#if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) + /**< Native endian 16-bit signed PCM. */ + CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16BE, + /**< Native endian 32-bit IEEE floating point PCM. */ + CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE +#else + /**< Native endian 16-bit signed PCM. */ + CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE, + /**< Native endian 32-bit IEEE floating point PCM. */ + CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE +#endif +} cubeb_sample_format; + +/** An opaque handle used to refer a particular input or output device + * across calls. */ +typedef void const * cubeb_devid; + +/** Level (verbosity) of logging for a particular cubeb context. */ +typedef enum { + CUBEB_LOG_DISABLED = 0, /** < Logging disabled */ + CUBEB_LOG_NORMAL = + 1, /**< Logging lifetime operation (creation/destruction). */ + CUBEB_LOG_VERBOSE = 2, /**< Verbose logging of callbacks, can have performance + implications. */ +} cubeb_log_level; + +/// A single channel position, to be used in a bitmask. +typedef enum { + 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 +} cubeb_channel; + +/// 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. +typedef uint32_t cubeb_channel_layout; +// Some common layout definitions. +enum { + CUBEB_LAYOUT_UNDEFINED = 0, // Indicate the speaker's layout is undefined. + 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 = + CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | CHANNEL_FRONT_CENTER, + CUBEB_LAYOUT_3F_LFE = CUBEB_LAYOUT_3F | CHANNEL_LOW_FREQUENCY, + CUBEB_LAYOUT_2F1 = + CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | CHANNEL_BACK_CENTER, + CUBEB_LAYOUT_2F1_LFE = CUBEB_LAYOUT_2F1 | CHANNEL_LOW_FREQUENCY, + CUBEB_LAYOUT_3F1 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | + CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER, + CUBEB_LAYOUT_3F1_LFE = CUBEB_LAYOUT_3F1 | CHANNEL_LOW_FREQUENCY, + CUBEB_LAYOUT_2F2 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | + CHANNEL_SIDE_LEFT | CHANNEL_SIDE_RIGHT, + CUBEB_LAYOUT_2F2_LFE = CUBEB_LAYOUT_2F2 | CHANNEL_LOW_FREQUENCY, + CUBEB_LAYOUT_QUAD = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | + CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT, + CUBEB_LAYOUT_QUAD_LFE = CUBEB_LAYOUT_QUAD | CHANNEL_LOW_FREQUENCY, + CUBEB_LAYOUT_3F2 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | + CHANNEL_FRONT_CENTER | CHANNEL_SIDE_LEFT | + CHANNEL_SIDE_RIGHT, + 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 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | + CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | + CHANNEL_BACK_CENTER | CHANNEL_SIDE_LEFT | + CHANNEL_SIDE_RIGHT, + CUBEB_LAYOUT_3F4_LFE = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | + CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | + CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT | + CHANNEL_SIDE_LEFT | CHANNEL_SIDE_RIGHT, +}; + +/** Miscellaneous stream preferences. */ +typedef enum { + CUBEB_STREAM_PREF_NONE = 0x00, /**< No stream preferences are requested. */ + CUBEB_STREAM_PREF_LOOPBACK = + 0x01, /**< 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 = 0x02, /**< Disable switching + default device on OS + changes. */ + CUBEB_STREAM_PREF_VOICE = + 0x04, /**< 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 = + 0x08, /**< Windows only. Bypass all signal processing + except for always on APO, driver and hardware. */ + CUBEB_STREAM_PREF_PERSIST = 0x10, /**< 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 = 0x20 /**< Don't automatically try to + connect ports. Only affects + the jack backend. */ +} cubeb_stream_prefs; + +/** + * Input stream audio processing parameters. Only applicable with + * CUBEB_STREAM_PREF_VOICE. + */ +typedef enum { + 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, +} cubeb_input_processing_params; + +/** Stream format initialization parameters. */ +typedef struct { + cubeb_sample_format format; /**< Requested sample format. One of + #cubeb_sample_format. */ + uint32_t rate; /**< Requested sample rate. Valid range is [1000, 384000]. */ + uint32_t channels; /**< Requested channel count. Valid range is [1, 8]. */ + cubeb_channel_layout + layout; /**< Requested channel layout. This must be consistent with the + provided channels. CUBEB_LAYOUT_UNDEFINED if unknown */ + cubeb_stream_prefs prefs; /**< Requested preferences. */ +} cubeb_stream_params; + +/** Audio device description */ +typedef struct { + char * output_name; /**< The name of the output device */ + char * input_name; /**< The name of the input device */ +} cubeb_device; + +/** Stream states signaled via state_callback. */ +typedef enum { + CUBEB_STATE_STARTED, /**< Stream started. */ + CUBEB_STATE_STOPPED, /**< Stream stopped. */ + CUBEB_STATE_DRAINED, /**< Stream drained. */ + CUBEB_STATE_ERROR /**< Stream disabled due to error. */ +} cubeb_state; + +/** Result code enumeration. */ +enum { + CUBEB_OK = 0, /**< Success. */ + CUBEB_ERROR = -1, /**< Unclassified error. */ + CUBEB_ERROR_INVALID_FORMAT = + -2, /**< Unsupported #cubeb_stream_params requested. */ + CUBEB_ERROR_INVALID_PARAMETER = -3, /**< Invalid parameter specified. */ + CUBEB_ERROR_NOT_SUPPORTED = + -4, /**< Optional function not implemented in current backend. */ + CUBEB_ERROR_DEVICE_UNAVAILABLE = + -5 /**< Device specified by #cubeb_devid not available. */ +}; + +/** + * Whether a particular device is an input device (e.g. a microphone), or an + * output device (e.g. headphones). */ +typedef enum { + CUBEB_DEVICE_TYPE_UNKNOWN, + CUBEB_DEVICE_TYPE_INPUT, + CUBEB_DEVICE_TYPE_OUTPUT +} cubeb_device_type; + +/** + * The state of a device. + */ +typedef enum { + 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_state; + +/** + * Architecture specific sample type. + */ +typedef enum { + CUBEB_DEVICE_FMT_S16LE = 0x0010, /**< 16-bit integers, Little Endian. */ + CUBEB_DEVICE_FMT_S16BE = 0x0020, /**< 16-bit integers, Big Endian. */ + CUBEB_DEVICE_FMT_F32LE = 0x1000, /**< 32-bit floating point, Little Endian. */ + CUBEB_DEVICE_FMT_F32BE = 0x2000 /**< 32-bit floating point, Big Endian. */ +} cubeb_device_fmt; + +#if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) +/** 16-bit integers, native endianess, when on a Big Endian environment. */ +#define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16BE +/** 32-bit floating points, native endianess, when on a Big Endian environment. + */ +#define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32BE +#else +/** 16-bit integers, native endianess, when on a Little Endian environment. */ +#define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16LE +/** 32-bit floating points, native endianess, when on a Little Endian + * environment. */ +#define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32LE +#endif +/** All the 16-bit integers types. */ +#define CUBEB_DEVICE_FMT_S16_MASK \ + (CUBEB_DEVICE_FMT_S16LE | CUBEB_DEVICE_FMT_S16BE) +/** All the 32-bit floating points types. */ +#define CUBEB_DEVICE_FMT_F32_MASK \ + (CUBEB_DEVICE_FMT_F32LE | CUBEB_DEVICE_FMT_F32BE) +/** All the device formats types. */ +#define CUBEB_DEVICE_FMT_ALL \ + (CUBEB_DEVICE_FMT_S16_MASK | CUBEB_DEVICE_FMT_F32_MASK) + +/** Channel type for a `cubeb_stream`. Depending on the backend and platform + * used, this can control inter-stream interruption, ducking, and volume + * control. + */ +typedef enum { + 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 +} cubeb_device_pref; + +/** This structure holds the characteristics + * of an input or output audio device. It is obtained using + * `cubeb_enumerate_devices`, which returns these structures via + * `cubeb_device_collection` and must be destroyed via + * `cubeb_device_collection_destroy`. */ +typedef struct { + cubeb_devid devid; /**< Device identifier handle. */ + char const * + device_id; /**< Device identifier which might be presented in a UI. */ + char const * friendly_name; /**< Friendly device name which might be presented + in a UI. */ + char const * group_id; /**< Two devices have the same group identifier if they + belong to the same physical device; for example a + headset and microphone. */ + char const * vendor_name; /**< Optional vendor name, may be NULL. */ + + cubeb_device_type type; /**< Type of device (Input/Output). */ + cubeb_device_state state; /**< State of device disabled/enabled/unplugged. */ + cubeb_device_pref preferred; /**< Preferred device. */ + + cubeb_device_fmt format; /**< Sample format supported. */ + cubeb_device_fmt + default_format; /**< The default sample format for this device. */ + uint32_t max_channels; /**< Channels. */ + uint32_t default_rate; /**< Default/Preferred sample rate. */ + uint32_t max_rate; /**< Maximum sample rate supported. */ + uint32_t min_rate; /**< Minimum sample rate supported. */ + + uint32_t latency_lo; /**< Lowest possible latency in frames. */ + uint32_t latency_hi; /**< Higest possible latency in frames. */ +} cubeb_device_info; + +/** Device collection. + * Returned by `cubeb_enumerate_devices` and destroyed by + * `cubeb_device_collection_destroy`. */ +typedef struct { + cubeb_device_info * device; /**< Array of pointers to device info. */ + size_t count; /**< Device count in collection. */ +} cubeb_device_collection; + +/** 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. + @param stream The stream for which this callback fired. + @param user_ptr The pointer passed to cubeb_stream_init. + @param input_buffer A pointer containing the input data, or nullptr + if this is an output-only stream. + @param output_buffer A pointer to a buffer to be filled with audio samples, + or nullptr if this is an input-only stream. + @param nframes The number of frames of the two buffer. + @retval 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. + @retval CUBEB_ERROR on error, in which case the data callback will stop + and the stream will enter a shutdown state. */ +typedef long (*cubeb_data_callback)(cubeb_stream * stream, void * user_ptr, + void const * input_buffer, + void * output_buffer, long nframes); + +/** User supplied state callback. + @param stream The stream for this this callback fired. + @param user_ptr The pointer passed to cubeb_stream_init. + @param state The new state of the stream. */ +typedef void (*cubeb_state_callback)(cubeb_stream * stream, void * user_ptr, + cubeb_state state); + +/** + * User supplied callback called when the underlying device changed. + * @param user_ptr The pointer passed to cubeb_stream_init. */ +typedef void (*cubeb_device_changed_callback)(void * user_ptr); + +/** + * User supplied callback called when the underlying device collection changed. + * @param context A pointer to the cubeb context. + * @param user_ptr The pointer passed to + * cubeb_register_device_collection_changed. */ +typedef void (*cubeb_device_collection_changed_callback)(cubeb * context, + void * user_ptr); + +/** User supplied callback called when a message needs logging. */ +typedef void (*cubeb_log_callback)(char const * fmt, ...); + +/** 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. + + @param context A out param where an opaque pointer to the application + context will be returned. + @param context_name A name for the context. Depending on the platform this + can appear in different locations. + @param 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. + @retval CUBEB_OK in case of success. + @retval CUBEB_ERROR in case of error, for example because the host + has no audio hardware. */ +CUBEB_EXPORT int +cubeb_init(cubeb ** context, char const * context_name, + char const * backend_name); + +/** Get a read-only string identifying this context's current backend. + @param context A pointer to the cubeb context. + @retval Read-only string identifying current backend. */ +CUBEB_EXPORT char const * +cubeb_get_backend_id(cubeb * context); + +/** Get the maximum possible number of channels. + @param context A pointer to the cubeb context. + @param max_channels The maximum number of channels. + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER + @retval CUBEB_ERROR_NOT_SUPPORTED + @retval CUBEB_ERROR */ +CUBEB_EXPORT int +cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels); + +/** 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. + @param context A pointer to the cubeb context. + @param params On some backends, the minimum achievable latency depends on + the characteristics of the stream. + @param latency_frames The latency value, in frames, to pass to + cubeb_stream_init. + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_get_min_latency(cubeb * context, cubeb_stream_params * params, + uint32_t * latency_frames); + +/** Get the preferred sample rate for this backend: this is hardware and + platform dependent, and can avoid resampling, and/or trigger fastpaths. + @param context A pointer to the cubeb context. + @param rate The samplerate (in Hz) the current configuration prefers. + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate); + +/** 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. + @param context A pointer to the cubeb context. + @param params Out parameter for the input processing params supported by + this backend. + @retval CUBEB_OK + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_get_supported_input_processing_params( + cubeb * context, cubeb_input_processing_params * params); + +/** Destroy an application context. This must be called after all stream have + * been destroyed. + @param context A pointer to the cubeb context.*/ +CUBEB_EXPORT void +cubeb_destroy(cubeb * context); + +/** Initialize a stream associated with the supplied application context. + @param context A pointer to the cubeb context. + @param stream An out parameter to be filled with the an opaque pointer to a + cubeb stream. + @param stream_name A name for this stream. + @param 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. + @param input_stream_params Parameters for the input side of the stream, or + NULL if this stream is output only. + @param 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. + @param 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. + @param latency_frames Stream latency in frames. Valid range + is [1, 96000]. + @param data_callback Will be called to preroll data before playback is + started by cubeb_stream_start. + @param state_callback A pointer to a state callback. + @param user_ptr A pointer that will be passed to the callbacks. This pointer + must outlive the life time of the stream. + @retval CUBEB_OK + @retval CUBEB_ERROR + @retval CUBEB_ERROR_INVALID_FORMAT + @retval CUBEB_ERROR_DEVICE_UNAVAILABLE */ +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); + +/** Destroy a stream. `cubeb_stream_stop` MUST be called before destroying a + stream. + @param stream The stream to destroy. */ +CUBEB_EXPORT void +cubeb_stream_destroy(cubeb_stream * stream); + +/** Start playback. + @param stream + @retval CUBEB_OK + @retval CUBEB_ERROR */ +CUBEB_EXPORT int +cubeb_stream_start(cubeb_stream * stream); + +/** Stop playback. + @param stream + @retval CUBEB_OK + @retval CUBEB_ERROR */ +CUBEB_EXPORT int +cubeb_stream_stop(cubeb_stream * stream); + +/** Get the current stream playback position. + @param stream + @param position Playback position in frames. + @retval CUBEB_OK + @retval CUBEB_ERROR */ +CUBEB_EXPORT int +cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position); + +/** 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. + @param stream + @param latency Current approximate stream latency in frames. + @retval CUBEB_OK + @retval CUBEB_ERROR_NOT_SUPPORTED + @retval CUBEB_ERROR */ +CUBEB_EXPORT int +cubeb_stream_get_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. + @param stream + @param latency Current approximate stream latency in frames. + @retval CUBEB_OK + @retval CUBEB_ERROR_NOT_SUPPORTED + @retval CUBEB_ERROR */ +CUBEB_EXPORT int +cubeb_stream_get_input_latency(cubeb_stream * stream, uint32_t * latency); +/** Set the volume for a stream. + @param stream the stream for which to adjust the volume. + @param volume a float between 0.0 (muted) and 1.0 (maximum volume) + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER volume is outside [0.0, 1.0] or + stream is an invalid pointer + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_set_volume(cubeb_stream * stream, float volume); + +/** Change a stream's name. + @param stream the stream for which to set the name. + @param stream_name the new name for the stream + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER if any pointer is invalid + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_set_name(cubeb_stream * stream, char const * stream_name); + +/** Get the current output device for this stream. + @param stm the stream for which to query the current output device + @param device a pointer in which the current output device will be stored. + @retval CUBEB_OK in case of success + @retval CUBEB_ERROR_INVALID_PARAMETER if either stm, device or count are + invalid pointers + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_get_current_device(cubeb_stream * stm, + cubeb_device ** const device); + +/** 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. + @param stream the stream for which to set input mute state + @param muted whether the input should mute or not + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER if this stream does not have an input + device + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_set_input_mute(cubeb_stream * stream, int mute); + +/** Set what input processing features to enable for this stream. + @param stream the stream for which to set input processing features. + @param params what input processing features to use + @retval CUBEB_OK + @retval CUBEB_ERROR if params could not be applied + @retval CUBEB_ERROR_INVALID_PARAMETER if a given param is not supported by + this backend, or if this stream does not have an input device + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_set_input_processing_params(cubeb_stream * stream, + cubeb_input_processing_params params); + +/** Destroy a cubeb_device structure. + @param stream the stream passed in cubeb_stream_get_current_device + @param devices the devices to destroy + @retval CUBEB_OK in case of success + @retval CUBEB_ERROR_INVALID_PARAMETER if devices is an invalid pointer + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_device_destroy(cubeb_stream * stream, cubeb_device * devices); + +/** Set a callback to be notified when the output device changes. + @param stream the stream for which to set the callback. + @param device_changed_callback a function called whenever the device has + changed. Passing NULL allow to unregister a function + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER if either stream or + device_changed_callback are invalid pointers. + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_stream_register_device_changed_callback( + cubeb_stream * stream, + cubeb_device_changed_callback device_changed_callback); + +/** Return the user data pointer registered with the stream with + cubeb_stream_init. + @param stream the stream for which to retrieve user data pointer. + @retval user data pointer */ +CUBEB_EXPORT void * +cubeb_stream_user_ptr(cubeb_stream * stream); + +/** Returns enumerated devices. + @param context + @param devtype device type to include + @param collection output collection. Must be destroyed with + cubeb_device_collection_destroy + @retval CUBEB_OK in case of success + @retval CUBEB_ERROR_INVALID_PARAMETER if collection is an invalid pointer + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_enumerate_devices(cubeb * context, cubeb_device_type devtype, + cubeb_device_collection * collection); + +/** Destroy a cubeb_device_collection, and its `cubeb_device_info`. + @param context + @param collection collection to destroy + @retval CUBEB_OK + @retval CUBEB_ERROR_INVALID_PARAMETER if collection is an invalid pointer */ +CUBEB_EXPORT int +cubeb_device_collection_destroy(cubeb * context, + cubeb_device_collection * collection); + +/** Registers a callback which is called when the system detects + a new device or a device is removed. + @param context + @param 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. + @param callback a function called whenever the system device list changes. + Passing NULL allow to unregister a function. You have to unregister + first before you register a new callback. + @param user_ptr pointer to user specified data which will be present in + subsequent callbacks. + @retval CUBEB_ERROR_NOT_SUPPORTED */ +CUBEB_EXPORT int +cubeb_register_device_collection_changed( + cubeb * context, cubeb_device_type devtype, + cubeb_device_collection_changed_callback callback, void * user_ptr); + +/** Set a callback to be called with a message. + @param log_level CUBEB_LOG_VERBOSE, CUBEB_LOG_NORMAL. + @param log_callback A function called with a message when there is + something to log. Pass NULL to unregister. + @retval CUBEB_OK in case of success. + @retval CUBEB_ERROR_INVALID_PARAMETER if either context or log_callback are + invalid pointers, or if level is not + in cubeb_log_level. */ +CUBEB_EXPORT int +cubeb_set_log_callback(cubeb_log_level log_level, + cubeb_log_callback log_callback); + +#if defined(__cplusplus) +} +#endif + +#endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */ |