diff options
Diffstat (limited to 'media/libcubeb/include')
| -rw-r--r-- | media/libcubeb/include/cubeb.h | 255 |
1 files changed, 166 insertions, 89 deletions
diff --git a/media/libcubeb/include/cubeb.h b/media/libcubeb/include/cubeb.h index 449b39c55..e6cf8dd87 100644 --- a/media/libcubeb/include/cubeb.h +++ b/media/libcubeb/include/cubeb.h @@ -8,6 +8,7 @@ #define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 #include <stdint.h> +#include <stdlib.h> #include "cubeb_export.h" #if defined(__cplusplus) @@ -32,11 +33,11 @@ extern "C" { cubeb * app_ctx; cubeb_init(&app_ctx, "Example Application"); int rv; - int rate; - int latency_frames; + uint32_t rate; + uint32_t 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; @@ -52,16 +53,20 @@ 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; - output_params.format = CUBEB_SAMPLE_FLOAT32NE; - output_params.rate = rate; - output_params.channels = 1; + 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, + NULL, &input_params, + NULL, &output_params, latency_frames, data_cb, state_cb, NULL); @@ -99,7 +104,7 @@ extern "C" { for (i = 0; i < nframes; ++i) { for (c = 0; c < 2; ++c) { - buf[i][c] = in[i]; + out[i][c] = in[i]; } } return nframes; @@ -143,31 +148,9 @@ 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 * cubeb_devid; +typedef void const * cubeb_devid; /** Level (verbosity) of logging for a particular cubeb context. */ typedef enum { @@ -176,15 +159,93 @@ 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. */ - 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_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_stream_params; /** Audio device description */ @@ -271,15 +332,16 @@ typedef enum { } cubeb_device_pref; /** This structure holds the characteristics - * of an input or output audio device. It can be obtained using - * `cubeb_enumerate_devices`, and must be destroyed using - * `cubeb_device_info_destroy`. */ + * 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 * 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. */ + 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. */ @@ -287,19 +349,21 @@ typedef struct { cubeb_device_fmt format; /**< Sample format supported. */ cubeb_device_fmt default_format; /**< The default sample format for this device. */ - 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 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 latency_lo; /**< Lowest possible latency in frames. */ - unsigned int latency_hi; /**< Higest possible latency in frames. */ + uint32_t latency_lo; /**< Lowest possible latency in frames. */ + uint32_t latency_hi; /**< Higest possible latency in frames. */ } cubeb_device_info; -/** Device collection. */ +/** Device collection. + * Returned by `cubeb_enumerate_devices` and destroyed by + * `cubeb_device_collection_destroy`. */ typedef struct { - uint32_t count; /**< Device count in collection. */ - cubeb_device_info * device[1]; /**< Array of pointers to device info. */ + cubeb_device_info * device; /**< Array of pointers to device info. */ + size_t count; /**< Device count in collection. */ } cubeb_device_collection; /** User supplied data callback. @@ -316,13 +380,17 @@ 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 Number of frames written to the output buffer. If this number is - less than nframes, then the stream will start to drain. + @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, - const void * input_buffer, + void const * input_buffer, void * output_buffer, long nframes); @@ -342,23 +410,33 @@ 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_stream_init. */ + * @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)(const char * fmt, ...); +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); +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. @@ -376,7 +454,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 dependant. + 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. @@ -386,11 +464,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 dependant, and can avoid resampling, and/or trigger fastpaths. + 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 @@ -434,7 +512,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, - unsigned int latency_frames, + uint32_t latency_frames, cubeb_data_callback data_callback, cubeb_state_callback state_callback, void * user_ptr); @@ -456,6 +534,14 @@ 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. @@ -482,20 +568,6 @@ 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. @@ -526,6 +598,11 @@ 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 @@ -535,26 +612,26 @@ CUBEB_EXPORT int cubeb_stream_register_device_changed_callback(cubeb_stream * st @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_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); +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 + @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 + 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 */ |