1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libcubeb/include/cubeb.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,268 @@
1.4 +/*
1.5 + * Copyright © 2011 Mozilla Foundation
1.6 + *
1.7 + * This program is made available under an ISC-style license. See the
1.8 + * accompanying file LICENSE for details.
1.9 + */
1.10 +#if !defined(CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382)
1.11 +#define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382
1.12 +
1.13 +#include <cubeb/cubeb-stdint.h>
1.14 +
1.15 +#if defined(__cplusplus)
1.16 +extern "C" {
1.17 +#endif
1.18 +
1.19 +/** @mainpage
1.20 +
1.21 + @section intro Introduction
1.22 +
1.23 + This is the documentation for the <tt>libcubeb</tt> C API.
1.24 + <tt>libcubeb</tt> is a callback-based audio API library allowing the
1.25 + authoring of portable multiplatform audio playback.
1.26 +
1.27 + @section example Example code
1.28 +
1.29 + @code
1.30 + cubeb * app_ctx;
1.31 + cubeb_init(&app_ctx, "Example Application");
1.32 +
1.33 + cubeb_stream_params params;
1.34 + params.format = CUBEB_SAMPLE_S16NE;
1.35 + params.rate = 48000;
1.36 + params.channels = 2;
1.37 +
1.38 + unsigned int latency_ms = 250;
1.39 +
1.40 + cubeb_stream * stm;
1.41 + cubeb_stream_init(app_ctx, &stm, "Example Stream 1", params,
1.42 + latency_ms, data_cb, state_cb, NULL);
1.43 +
1.44 + cubeb_stream_start(stm);
1.45 + for (;;) {
1.46 + cubeb_stream_get_position(stm, &ts);
1.47 + printf("time=%llu\n", ts);
1.48 + sleep(1);
1.49 + }
1.50 + cubeb_stream_stop(stm);
1.51 +
1.52 + cubeb_stream_destroy(stm);
1.53 + cubeb_destroy(app_ctx);
1.54 + @endcode
1.55 +
1.56 + @code
1.57 + long data_cb(cubeb_stream * stm, void * user, void * buffer, long nframes)
1.58 + {
1.59 + short * buf = buffer;
1.60 + for (i = 0; i < nframes; ++i) {
1.61 + for (c = 0; c < params.channels; ++c) {
1.62 + buf[i][c] = 0;
1.63 + }
1.64 + }
1.65 + return nframes;
1.66 + }
1.67 + @endcode
1.68 +
1.69 + @code
1.70 + void state_cb(cubeb_stream * stm, void * user, cubeb_state state)
1.71 + {
1.72 + printf("state=%d\n", state);
1.73 + }
1.74 + @endcode
1.75 +*/
1.76 +
1.77 +/** @file
1.78 + The <tt>libcubeb</tt> C API. */
1.79 +
1.80 +typedef struct cubeb cubeb; /**< Opaque handle referencing the application state. */
1.81 +typedef struct cubeb_stream cubeb_stream; /**< Opaque handle referencing the stream state. */
1.82 +
1.83 +/** Sample format enumeration. */
1.84 +typedef enum {
1.85 + /**< Little endian 16-bit signed PCM. */
1.86 + CUBEB_SAMPLE_S16LE,
1.87 + /**< Big endian 16-bit signed PCM. */
1.88 + CUBEB_SAMPLE_S16BE,
1.89 + /**< Little endian 32-bit IEEE floating point PCM. */
1.90 + CUBEB_SAMPLE_FLOAT32LE,
1.91 + /**< Big endian 32-bit IEEE floating point PCM. */
1.92 + CUBEB_SAMPLE_FLOAT32BE,
1.93 +#if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__)
1.94 + /**< Native endian 16-bit signed PCM. */
1.95 + CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16BE,
1.96 + /**< Native endian 32-bit IEEE floating point PCM. */
1.97 + CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE
1.98 +#else
1.99 + /**< Native endian 16-bit signed PCM. */
1.100 + CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE,
1.101 + /**< Native endian 32-bit IEEE floating point PCM. */
1.102 + CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE
1.103 +#endif
1.104 +} cubeb_sample_format;
1.105 +
1.106 +#if defined(__ANDROID__)
1.107 +typedef enum {
1.108 + CUBEB_STREAM_TYPE_VOICE_CALL = 0,
1.109 + CUBEB_STREAM_TYPE_SYSTEM = 1,
1.110 + CUBEB_STREAM_TYPE_RING = 2,
1.111 + CUBEB_STREAM_TYPE_MUSIC = 3,
1.112 + CUBEB_STREAM_TYPE_ALARM = 4,
1.113 + CUBEB_STREAM_TYPE_NOTIFICATION = 5,
1.114 + CUBEB_STREAM_TYPE_BLUETOOTH_SCO = 6,
1.115 + CUBEB_STREAM_TYPE_ENFORCED_AUDIBLE = 7,
1.116 + CUBEB_STREAM_TYPE_DTMF = 8,
1.117 + CUBEB_STREAM_TYPE_TTS = 9,
1.118 + CUBEB_STREAM_TYPE_FM = 10,
1.119 +
1.120 + CUBEB_STREAM_TYPE_MAX
1.121 +} cubeb_stream_type;
1.122 +#endif
1.123 +
1.124 +/** Stream format initialization parameters. */
1.125 +typedef struct {
1.126 + cubeb_sample_format format; /**< Requested sample format. One of
1.127 + #cubeb_sample_format. */
1.128 + unsigned int rate; /**< Requested sample rate. Valid range is [1, 192000]. */
1.129 + unsigned int channels; /**< Requested channel count. Valid range is [1, 32]. */
1.130 +#if defined(__ANDROID__)
1.131 + cubeb_stream_type stream_type; /**< Used to map Android audio stream types */
1.132 +#endif
1.133 +} cubeb_stream_params;
1.134 +
1.135 +/** Stream states signaled via state_callback. */
1.136 +typedef enum {
1.137 + CUBEB_STATE_STARTED, /**< Stream started. */
1.138 + CUBEB_STATE_STOPPED, /**< Stream stopped. */
1.139 + CUBEB_STATE_DRAINED, /**< Stream drained. */
1.140 + CUBEB_STATE_ERROR /**< Stream disabled due to error. */
1.141 +} cubeb_state;
1.142 +
1.143 +/** Result code enumeration. */
1.144 +enum {
1.145 + CUBEB_OK = 0, /**< Success. */
1.146 + CUBEB_ERROR = -1, /**< Unclassified error. */
1.147 + CUBEB_ERROR_INVALID_FORMAT = -2, /**< Unsupported #cubeb_stream_params requested. */
1.148 + CUBEB_ERROR_INVALID_PARAMETER = -3 /**< Invalid parameter specified. */
1.149 +};
1.150 +
1.151 +/** User supplied data callback.
1.152 + @param stream
1.153 + @param user_ptr
1.154 + @param buffer
1.155 + @param nframes
1.156 + @retval Number of frames written to buffer, which must equal nframes except at end of stream.
1.157 + @retval CUBEB_ERROR on error, in which case the data callback will stop
1.158 + and the stream will enter a shutdown state. */
1.159 +typedef long (* cubeb_data_callback)(cubeb_stream * stream,
1.160 + void * user_ptr,
1.161 + void * buffer,
1.162 + long nframes);
1.163 +
1.164 +/** User supplied state callback.
1.165 + @param stream
1.166 + @param user_ptr
1.167 + @param state */
1.168 +typedef void (* cubeb_state_callback)(cubeb_stream * stream,
1.169 + void * user_ptr,
1.170 + cubeb_state state);
1.171 +
1.172 +/** Initialize an application context. This will perform any library or
1.173 + application scoped initialization.
1.174 + @param context
1.175 + @param context_name
1.176 + @retval CUBEB_OK
1.177 + @retval CUBEB_ERROR */
1.178 +int cubeb_init(cubeb ** context, char const * context_name);
1.179 +
1.180 +/** Get a read-only string identifying this context's current backend.
1.181 + @param context
1.182 + @retval Read-only string identifying current backend. */
1.183 +char const * cubeb_get_backend_id(cubeb * context);
1.184 +
1.185 +/** Get the maximum possible number of channels.
1.186 + @param context
1.187 + @param max_channels The maximum number of channels.
1.188 + @retval CUBEB_OK
1.189 + @retval CUBEB_ERROR_INVALID_PARAMETER
1.190 + @retval CUBEB_ERROR */
1.191 +int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels);
1.192 +
1.193 +/** Get the minimal latency value, in milliseconds, that is guaranteed to work
1.194 + when creating a stream for the specified sample rate. This is platform and
1.195 + backend dependant.
1.196 + @param context
1.197 + @param params On some backends, the minimum achievable latency depends on
1.198 + the characteristics of the stream.
1.199 + @param latency The latency value, in ms, to pass to cubeb_stream_init.
1.200 + @retval CUBEB_ERROR_INVALID_PARAMETER
1.201 + @retval CUBEB_OK */
1.202 +int cubeb_get_min_latency(cubeb * context, cubeb_stream_params params, uint32_t * latency_ms);
1.203 +
1.204 +/** Get the preferred sample rate for this backend: this is hardware and platform
1.205 + dependant, and can avoid resampling, and/or trigger fastpaths.
1.206 + @param context
1.207 + @param samplerate The samplerate (in Hz) the current configuration prefers.
1.208 + @return CUBEB_ERROR_INVALID_PARAMETER
1.209 + @return CUBEB_OK */
1.210 +int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate);
1.211 +
1.212 +/** Destroy an application context.
1.213 + @param context */
1.214 +void cubeb_destroy(cubeb * context);
1.215 +
1.216 +/** Initialize a stream associated with the supplied application context.
1.217 + @param context
1.218 + @param stream
1.219 + @param stream_name
1.220 + @param stream_params
1.221 + @param latency Approximate stream latency in milliseconds. Valid range is [1, 2000].
1.222 + @param data_callback Will be called to preroll data before playback is
1.223 + started by cubeb_stream_start.
1.224 + @param state_callback
1.225 + @param user_ptr
1.226 + @retval CUBEB_OK
1.227 + @retval CUBEB_ERROR
1.228 + @retval CUBEB_ERROR_INVALID_FORMAT */
1.229 +int cubeb_stream_init(cubeb * context, cubeb_stream ** stream, char const * stream_name,
1.230 + cubeb_stream_params stream_params, unsigned int latency,
1.231 + cubeb_data_callback data_callback,
1.232 + cubeb_state_callback state_callback,
1.233 + void * user_ptr);
1.234 +
1.235 +/** Destroy a stream.
1.236 + @param stream */
1.237 +void cubeb_stream_destroy(cubeb_stream * stream);
1.238 +
1.239 +/** Start playback.
1.240 + @param stream
1.241 + @retval CUBEB_OK
1.242 + @retval CUBEB_ERROR */
1.243 +int cubeb_stream_start(cubeb_stream * stream);
1.244 +
1.245 +/** Stop playback.
1.246 + @param stream
1.247 + @retval CUBEB_OK
1.248 + @retval CUBEB_ERROR */
1.249 +int cubeb_stream_stop(cubeb_stream * stream);
1.250 +
1.251 +/** Get the current stream playback position.
1.252 + @param stream
1.253 + @param position Playback position in frames.
1.254 + @retval CUBEB_OK
1.255 + @retval CUBEB_ERROR */
1.256 +int cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position);
1.257 +
1.258 +/** Get the latency for this stream, in frames. This is the number of frames
1.259 + between the time cubeb acquires the data in the callback and the listener
1.260 + can hear the sound.
1.261 + @param stream
1.262 + @param latency Current approximate stream latency in ms
1.263 + @retval CUBEB_OK
1.264 + @retval CUBEB_ERROR */
1.265 +int cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * latency);
1.266 +
1.267 +#if defined(__cplusplus)
1.268 +}
1.269 +#endif
1.270 +
1.271 +#endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */
