The Tor Browser / file comparison
comparison: media/libcubeb/include/cubeb.h
media/libcubeb/include/cubeb.h
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:671043a4f45f |
|---|---|
| 1 /* | |
| 2 * Copyright © 2011 Mozilla Foundation | |
| 3 * | |
| 4 * This program is made available under an ISC-style license. See the | |
| 5 * accompanying file LICENSE for details. | |
| 6 */ | |
| 7 #if !defined(CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382) | |
| 8 #define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 | |
| 9 | |
| 10 #include <cubeb/cubeb-stdint.h> | |
| 11 | |
| 12 #if defined(__cplusplus) | |
| 13 extern "C" { | |
| 14 #endif | |
| 15 | |
| 16 /** @mainpage | |
| 17 | |
| 18 @section intro Introduction | |
| 19 | |
| 20 This is the documentation for the <tt>libcubeb</tt> C API. | |
| 21 <tt>libcubeb</tt> is a callback-based audio API library allowing the | |
| 22 authoring of portable multiplatform audio playback. | |
| 23 | |
| 24 @section example Example code | |
| 25 | |
| 26 @code | |
| 27 cubeb * app_ctx; | |
| 28 cubeb_init(&app_ctx, "Example Application"); | |
| 29 | |
| 30 cubeb_stream_params params; | |
| 31 params.format = CUBEB_SAMPLE_S16NE; | |
| 32 params.rate = 48000; | |
| 33 params.channels = 2; | |
| 34 | |
| 35 unsigned int latency_ms = 250; | |
| 36 | |
| 37 cubeb_stream * stm; | |
| 38 cubeb_stream_init(app_ctx, &stm, "Example Stream 1", params, | |
| 39 latency_ms, data_cb, state_cb, NULL); | |
| 40 | |
| 41 cubeb_stream_start(stm); | |
| 42 for (;;) { | |
| 43 cubeb_stream_get_position(stm, &ts); | |
| 44 printf("time=%llu\n", ts); | |
| 45 sleep(1); | |
| 46 } | |
| 47 cubeb_stream_stop(stm); | |
| 48 | |
| 49 cubeb_stream_destroy(stm); | |
| 50 cubeb_destroy(app_ctx); | |
| 51 @endcode | |
| 52 | |
| 53 @code | |
| 54 long data_cb(cubeb_stream * stm, void * user, void * buffer, long nframes) | |
| 55 { | |
| 56 short * buf = buffer; | |
| 57 for (i = 0; i < nframes; ++i) { | |
| 58 for (c = 0; c < params.channels; ++c) { | |
| 59 buf[i][c] = 0; | |
| 60 } | |
| 61 } | |
| 62 return nframes; | |
| 63 } | |
| 64 @endcode | |
| 65 | |
| 66 @code | |
| 67 void state_cb(cubeb_stream * stm, void * user, cubeb_state state) | |
| 68 { | |
| 69 printf("state=%d\n", state); | |
| 70 } | |
| 71 @endcode | |
| 72 */ | |
| 73 | |
| 74 /** @file | |
| 75 The <tt>libcubeb</tt> C API. */ | |
| 76 | |
| 77 typedef struct cubeb cubeb; /**< Opaque handle referencing the application state. */ | |
| 78 typedef struct cubeb_stream cubeb_stream; /**< Opaque handle referencing the stream state. */ | |
| 79 | |
| 80 /** Sample format enumeration. */ | |
| 81 typedef enum { | |
| 82 /**< Little endian 16-bit signed PCM. */ | |
| 83 CUBEB_SAMPLE_S16LE, | |
| 84 /**< Big endian 16-bit signed PCM. */ | |
| 85 CUBEB_SAMPLE_S16BE, | |
| 86 /**< Little endian 32-bit IEEE floating point PCM. */ | |
| 87 CUBEB_SAMPLE_FLOAT32LE, | |
| 88 /**< Big endian 32-bit IEEE floating point PCM. */ | |
| 89 CUBEB_SAMPLE_FLOAT32BE, | |
| 90 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) | |
| 91 /**< Native endian 16-bit signed PCM. */ | |
| 92 CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16BE, | |
| 93 /**< Native endian 32-bit IEEE floating point PCM. */ | |
| 94 CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE | |
| 95 #else | |
| 96 /**< Native endian 16-bit signed PCM. */ | |
| 97 CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE, | |
| 98 /**< Native endian 32-bit IEEE floating point PCM. */ | |
| 99 CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE | |
| 100 #endif | |
| 101 } cubeb_sample_format; | |
| 102 | |
| 103 #if defined(__ANDROID__) | |
| 104 typedef enum { | |
| 105 CUBEB_STREAM_TYPE_VOICE_CALL = 0, | |
| 106 CUBEB_STREAM_TYPE_SYSTEM = 1, | |
| 107 CUBEB_STREAM_TYPE_RING = 2, | |
| 108 CUBEB_STREAM_TYPE_MUSIC = 3, | |
| 109 CUBEB_STREAM_TYPE_ALARM = 4, | |
| 110 CUBEB_STREAM_TYPE_NOTIFICATION = 5, | |
| 111 CUBEB_STREAM_TYPE_BLUETOOTH_SCO = 6, | |
| 112 CUBEB_STREAM_TYPE_ENFORCED_AUDIBLE = 7, | |
| 113 CUBEB_STREAM_TYPE_DTMF = 8, | |
| 114 CUBEB_STREAM_TYPE_TTS = 9, | |
| 115 CUBEB_STREAM_TYPE_FM = 10, | |
| 116 | |
| 117 CUBEB_STREAM_TYPE_MAX | |
| 118 } cubeb_stream_type; | |
| 119 #endif | |
| 120 | |
| 121 /** Stream format initialization parameters. */ | |
| 122 typedef struct { | |
| 123 cubeb_sample_format format; /**< Requested sample format. One of | |
| 124 #cubeb_sample_format. */ | |
| 125 unsigned int rate; /**< Requested sample rate. Valid range is [1, 192000]. */ | |
| 126 unsigned int channels; /**< Requested channel count. Valid range is [1, 32]. */ | |
| 127 #if defined(__ANDROID__) | |
| 128 cubeb_stream_type stream_type; /**< Used to map Android audio stream types */ | |
| 129 #endif | |
| 130 } cubeb_stream_params; | |
| 131 | |
| 132 /** Stream states signaled via state_callback. */ | |
| 133 typedef enum { | |
| 134 CUBEB_STATE_STARTED, /**< Stream started. */ | |
| 135 CUBEB_STATE_STOPPED, /**< Stream stopped. */ | |
| 136 CUBEB_STATE_DRAINED, /**< Stream drained. */ | |
| 137 CUBEB_STATE_ERROR /**< Stream disabled due to error. */ | |
| 138 } cubeb_state; | |
| 139 | |
| 140 /** Result code enumeration. */ | |
| 141 enum { | |
| 142 CUBEB_OK = 0, /**< Success. */ | |
| 143 CUBEB_ERROR = -1, /**< Unclassified error. */ | |
| 144 CUBEB_ERROR_INVALID_FORMAT = -2, /**< Unsupported #cubeb_stream_params requested. */ | |
| 145 CUBEB_ERROR_INVALID_PARAMETER = -3 /**< Invalid parameter specified. */ | |
| 146 }; | |
| 147 | |
| 148 /** User supplied data callback. | |
| 149 @param stream | |
| 150 @param user_ptr | |
| 151 @param buffer | |
| 152 @param nframes | |
| 153 @retval Number of frames written to buffer, which must equal nframes except at end of stream. | |
| 154 @retval CUBEB_ERROR on error, in which case the data callback will stop | |
| 155 and the stream will enter a shutdown state. */ | |
| 156 typedef long (* cubeb_data_callback)(cubeb_stream * stream, | |
| 157 void * user_ptr, | |
| 158 void * buffer, | |
| 159 long nframes); | |
| 160 | |
| 161 /** User supplied state callback. | |
| 162 @param stream | |
| 163 @param user_ptr | |
| 164 @param state */ | |
| 165 typedef void (* cubeb_state_callback)(cubeb_stream * stream, | |
| 166 void * user_ptr, | |
| 167 cubeb_state state); | |
| 168 | |
| 169 /** Initialize an application context. This will perform any library or | |
| 170 application scoped initialization. | |
| 171 @param context | |
| 172 @param context_name | |
| 173 @retval CUBEB_OK | |
| 174 @retval CUBEB_ERROR */ | |
| 175 int cubeb_init(cubeb ** context, char const * context_name); | |
| 176 | |
| 177 /** Get a read-only string identifying this context's current backend. | |
| 178 @param context | |
| 179 @retval Read-only string identifying current backend. */ | |
| 180 char const * cubeb_get_backend_id(cubeb * context); | |
| 181 | |
| 182 /** Get the maximum possible number of channels. | |
| 183 @param context | |
| 184 @param max_channels The maximum number of channels. | |
| 185 @retval CUBEB_OK | |
| 186 @retval CUBEB_ERROR_INVALID_PARAMETER | |
| 187 @retval CUBEB_ERROR */ | |
| 188 int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels); | |
| 189 | |
| 190 /** Get the minimal latency value, in milliseconds, that is guaranteed to work | |
| 191 when creating a stream for the specified sample rate. This is platform and | |
| 192 backend dependant. | |
| 193 @param context | |
| 194 @param params On some backends, the minimum achievable latency depends on | |
| 195 the characteristics of the stream. | |
| 196 @param latency The latency value, in ms, to pass to cubeb_stream_init. | |
| 197 @retval CUBEB_ERROR_INVALID_PARAMETER | |
| 198 @retval CUBEB_OK */ | |
| 199 int cubeb_get_min_latency(cubeb * context, cubeb_stream_params params, uint32_t * latency_ms); | |
| 200 | |
| 201 /** Get the preferred sample rate for this backend: this is hardware and platform | |
| 202 dependant, and can avoid resampling, and/or trigger fastpaths. | |
| 203 @param context | |
| 204 @param samplerate The samplerate (in Hz) the current configuration prefers. | |
| 205 @return CUBEB_ERROR_INVALID_PARAMETER | |
| 206 @return CUBEB_OK */ | |
| 207 int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate); | |
| 208 | |
| 209 /** Destroy an application context. | |
| 210 @param context */ | |
| 211 void cubeb_destroy(cubeb * context); | |
| 212 | |
| 213 /** Initialize a stream associated with the supplied application context. | |
| 214 @param context | |
| 215 @param stream | |
| 216 @param stream_name | |
| 217 @param stream_params | |
| 218 @param latency Approximate stream latency in milliseconds. Valid range is [1, 2000]. | |
| 219 @param data_callback Will be called to preroll data before playback is | |
| 220 started by cubeb_stream_start. | |
| 221 @param state_callback | |
| 222 @param user_ptr | |
| 223 @retval CUBEB_OK | |
| 224 @retval CUBEB_ERROR | |
| 225 @retval CUBEB_ERROR_INVALID_FORMAT */ | |
| 226 int cubeb_stream_init(cubeb * context, cubeb_stream ** stream, char const * stream_name, | |
| 227 cubeb_stream_params stream_params, unsigned int latency, | |
| 228 cubeb_data_callback data_callback, | |
| 229 cubeb_state_callback state_callback, | |
| 230 void * user_ptr); | |
| 231 | |
| 232 /** Destroy a stream. | |
| 233 @param stream */ | |
| 234 void cubeb_stream_destroy(cubeb_stream * stream); | |
| 235 | |
| 236 /** Start playback. | |
| 237 @param stream | |
| 238 @retval CUBEB_OK | |
| 239 @retval CUBEB_ERROR */ | |
| 240 int cubeb_stream_start(cubeb_stream * stream); | |
| 241 | |
| 242 /** Stop playback. | |
| 243 @param stream | |
| 244 @retval CUBEB_OK | |
| 245 @retval CUBEB_ERROR */ | |
| 246 int cubeb_stream_stop(cubeb_stream * stream); | |
| 247 | |
| 248 /** Get the current stream playback position. | |
| 249 @param stream | |
| 250 @param position Playback position in frames. | |
| 251 @retval CUBEB_OK | |
| 252 @retval CUBEB_ERROR */ | |
| 253 int cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position); | |
| 254 | |
| 255 /** Get the latency for this stream, in frames. This is the number of frames | |
| 256 between the time cubeb acquires the data in the callback and the listener | |
| 257 can hear the sound. | |
| 258 @param stream | |
| 259 @param latency Current approximate stream latency in ms | |
| 260 @retval CUBEB_OK | |
| 261 @retval CUBEB_ERROR */ | |
| 262 int cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * latency); | |
| 263 | |
| 264 #if defined(__cplusplus) | |
| 265 } | |
| 266 #endif | |
| 267 | |
| 268 #endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */ |
