summaryrefslogtreecommitdiffstats
path: root/media/libcubeb/include
diff options
context:
space:
mode:
Diffstat (limited to 'media/libcubeb/include')
-rw-r--r--media/libcubeb/include/cubeb.h255
1 files changed, 89 insertions, 166 deletions
diff --git a/media/libcubeb/include/cubeb.h b/media/libcubeb/include/cubeb.h
index e6cf8dd87..449b39c55 100644
--- a/media/libcubeb/include/cubeb.h
+++ b/media/libcubeb/include/cubeb.h
@@ -8,7 +8,6 @@
#define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382
#include <stdint.h>
-#include <stdlib.h>
#include "cubeb_export.h"
#if defined(__cplusplus)
@@ -33,11 +32,11 @@ extern "C" {
cubeb * app_ctx;
cubeb_init(&app_ctx, "Example Application");
int rv;
- uint32_t rate;
- uint32_t latency_frames;
+ int rate;
+ int latency_frames;
uint64_t ts;
- rv = cubeb_get_min_latency(app_ctx, &output_params, &latency_frames);
+ rv = cubeb_get_min_latency(app_ctx, output_params, &latency_frames);
if (rv != CUBEB_OK) {
fprintf(stderr, "Could not get minimum latency");
return rv;
@@ -53,20 +52,16 @@ extern "C" {
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;
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;
+ output_params.format = CUBEB_SAMPLE_FLOAT32NE;
+ output_params.rate = rate;
+ output_params.channels = 1;
cubeb_stream * stm;
rv = cubeb_stream_init(app_ctx, &stm, "Example Stream 1",
- NULL, &input_params,
- NULL, &output_params,
+ NULL, input_params,
+ NULL, output_params,
latency_frames,
data_cb, state_cb,
NULL);
@@ -104,7 +99,7 @@ extern "C" {
for (i = 0; i < nframes; ++i) {
for (c = 0; c < 2; ++c) {
- out[i][c] = in[i];
+ buf[i][c] = in[i];
}
}
return nframes;
@@ -148,9 +143,31 @@ typedef enum {
#endif
} cubeb_sample_format;
+#if defined(__ANDROID__)
+/**
+ * This maps to the underlying stream types on supported platforms, e.g.
+ * Android.
+ */
+typedef enum {
+ CUBEB_STREAM_TYPE_VOICE_CALL = 0,
+ CUBEB_STREAM_TYPE_SYSTEM = 1,
+ CUBEB_STREAM_TYPE_RING = 2,
+ CUBEB_STREAM_TYPE_MUSIC = 3,
+ CUBEB_STREAM_TYPE_ALARM = 4,
+ CUBEB_STREAM_TYPE_NOTIFICATION = 5,
+ CUBEB_STREAM_TYPE_BLUETOOTH_SCO = 6,
+ CUBEB_STREAM_TYPE_SYSTEM_ENFORCED = 7,
+ CUBEB_STREAM_TYPE_DTMF = 8,
+ CUBEB_STREAM_TYPE_TTS = 9,
+ CUBEB_STREAM_TYPE_FM = 10,
+
+ CUBEB_STREAM_TYPE_MAX
+} cubeb_stream_type;
+#endif
+
/** An opaque handle used to refer a particular input or output device
* across calls. */
-typedef void const * cubeb_devid;
+typedef void * cubeb_devid;
/** Level (verbosity) of logging for a particular cubeb context. */
typedef enum {
@@ -159,93 +176,15 @@ typedef enum {
CUBEB_LOG_VERBOSE = 2, /**< Verbose logging of callbacks, can have performance implications. */
} cubeb_log_level;
-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;
-
-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_prefs;
-
/** 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, 192000]. */
- 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_sample_format format; /**< Requested sample format. One of
+ #cubeb_sample_format. */
+ unsigned int rate; /**< Requested sample rate. Valid range is [1000, 192000]. */
+ unsigned int channels; /**< Requested channel count. Valid range is [1, 8]. */
+#if defined(__ANDROID__)
+ cubeb_stream_type stream_type; /**< Used to map Android audio stream types */
+#endif
} cubeb_stream_params;
/** Audio device description */
@@ -332,16 +271,15 @@ typedef enum {
} 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`. */
+ * of an input or output audio device. It can be obtained using
+ * `cubeb_enumerate_devices`, and must be destroyed using
+ * `cubeb_device_info_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. */
+ char * device_id; /**< Device identifier which might be presented in a UI. */
+ char * friendly_name; /**< Friendly device name which might be presented in a UI. */
+ char * group_id; /**< Two devices have the same group identifier if they belong to the same physical device; for example a headset and microphone. */
+ char * 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. */
@@ -349,21 +287,19 @@ typedef struct {
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. */
+ unsigned int max_channels; /**< Channels. */
+ unsigned int default_rate; /**< Default/Preferred sample rate. */
+ unsigned int max_rate; /**< Maximum sample rate supported. */
+ unsigned int min_rate; /**< Minimum sample rate supported. */
- uint32_t latency_lo; /**< Lowest possible latency in frames. */
- uint32_t latency_hi; /**< Higest possible latency in frames. */
+ unsigned int latency_lo; /**< Lowest possible latency in frames. */
+ unsigned int latency_hi; /**< Higest possible latency in frames. */
} cubeb_device_info;
-/** Device collection.
- * Returned by `cubeb_enumerate_devices` and destroyed by
- * `cubeb_device_collection_destroy`. */
+/** Device collection. */
typedef struct {
- cubeb_device_info * device; /**< Array of pointers to device info. */
- size_t count; /**< Device count in collection. */
+ uint32_t count; /**< Device count in collection. */
+ cubeb_device_info * device[1]; /**< Array of pointers to device info. */
} cubeb_device_collection;
/** User supplied data callback.
@@ -380,17 +316,13 @@ typedef struct {
@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 Number of frames written to the output buffer. If this number is
+ less than nframes, then the stream will start to drain.
@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,
+ const void * input_buffer,
void * output_buffer,
long nframes);
@@ -410,33 +342,23 @@ 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. */
+ * @param user_ptr The pointer passed to cubeb_stream_init. */
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, ...);
+typedef void (* cubeb_log_callback)(const char * 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);
+CUBEB_EXPORT int cubeb_init(cubeb ** context, char const * context_name);
/** Get a read-only string identifying this context's current backend.
@param context A pointer to the cubeb context.
@@ -454,7 +376,7 @@ CUBEB_EXPORT int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_cha
/** 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.
+ hardware and backend dependant.
@param context A pointer to the cubeb context.
@param params On some backends, the minimum achievable latency depends on
the characteristics of the stream.
@@ -464,11 +386,11 @@ CUBEB_EXPORT int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_cha
@retval CUBEB_ERROR_INVALID_PARAMETER
@retval CUBEB_ERROR_NOT_SUPPORTED */
CUBEB_EXPORT int cubeb_get_min_latency(cubeb * context,
- cubeb_stream_params * params,
+ 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.
+ platform dependant, 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
@@ -512,7 +434,7 @@ CUBEB_EXPORT int cubeb_stream_init(cubeb * context,
cubeb_stream_params * input_stream_params,
cubeb_devid output_device,
cubeb_stream_params * output_stream_params,
- uint32_t latency_frames,
+ unsigned int latency_frames,
cubeb_data_callback data_callback,
cubeb_state_callback state_callback,
void * user_ptr);
@@ -534,14 +456,6 @@ CUBEB_EXPORT int cubeb_stream_start(cubeb_stream * stream);
@retval CUBEB_ERROR */
CUBEB_EXPORT int cubeb_stream_stop(cubeb_stream * stream);
-/** Reset stream to the default device.
- @param stream
- @retval CUBEB_OK
- @retval CUBEB_ERROR_INVALID_PARAMETER
- @retval CUBEB_ERROR_NOT_SUPPORTED
- @retval CUBEB_ERROR */
-CUBEB_EXPORT int cubeb_stream_reset_default_device(cubeb_stream * stream);
-
/** Get the current stream playback position.
@param stream
@param position Playback position in frames.
@@ -568,6 +482,20 @@ CUBEB_EXPORT int cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * late
@retval CUBEB_ERROR_NOT_SUPPORTED */
CUBEB_EXPORT int cubeb_stream_set_volume(cubeb_stream * stream, float volume);
+/** If the stream is stereo, set the left/right panning. If the stream is mono,
+ this has no effect.
+ @param stream the stream for which to change the panning
+ @param panning a number from -1.0 to 1.0. -1.0 means that the stream is
+ fully mixed in the left channel, 1.0 means the stream is fully
+ mixed in the right channel. 0.0 is equal power in the right and
+ left channel (default).
+ @retval CUBEB_OK
+ @retval CUBEB_ERROR_INVALID_PARAMETER if stream is null or if panning is
+ outside the [-1.0, 1.0] range.
+ @retval CUBEB_ERROR_NOT_SUPPORTED
+ @retval CUBEB_ERROR stream is not mono nor stereo */
+CUBEB_EXPORT int cubeb_stream_set_panning(cubeb_stream * stream, float panning);
+
/** 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.
@@ -598,11 +526,6 @@ CUBEB_EXPORT int cubeb_stream_device_destroy(cubeb_stream * stream,
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
@@ -612,26 +535,26 @@ CUBEB_EXPORT void * cubeb_stream_user_ptr(cubeb_stream * stream);
@retval CUBEB_ERROR_NOT_SUPPORTED */
CUBEB_EXPORT int cubeb_enumerate_devices(cubeb * context,
cubeb_device_type devtype,
- cubeb_device_collection * collection);
+ 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);
+CUBEB_EXPORT int cubeb_device_collection_destroy(cubeb_device_collection * collection);
+
+/** Destroy a cubeb_device_info structure.
+ @param info pointer to device info structure
+ @retval CUBEB_OK
+ @retval CUBEB_ERROR_INVALID_PARAMETER if info is an invalid pointer */
+CUBEB_EXPORT int cubeb_device_info_destroy(cubeb_device_info * info);
/** 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 devtype device type to include
@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.
+ Passing NULL allow to unregister a function
@param user_ptr pointer to user specified data which will be present in
subsequent callbacks.
@retval CUBEB_ERROR_NOT_SUPPORTED */