media/libcubeb/include/cubeb.h@b8a032363ba2
media/libcubeb/include/cubeb.h
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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
10 #include <cubeb/cubeb-stdint.h>
12 #if defined(__cplusplus)
13 extern "C" {
14 #endif
16 /** @mainpage
18 @section intro Introduction
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.
24 @section example Example code
26 @code
27 cubeb * app_ctx;
28 cubeb_init(&app_ctx, "Example Application");
30 cubeb_stream_params params;
31 params.format = CUBEB_SAMPLE_S16NE;
32 params.rate = 48000;
33 params.channels = 2;
35 unsigned int latency_ms = 250;
37 cubeb_stream * stm;
38 cubeb_stream_init(app_ctx, &stm, "Example Stream 1", params,
39 latency_ms, data_cb, state_cb, NULL);
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);
49 cubeb_stream_destroy(stm);
50 cubeb_destroy(app_ctx);
51 @endcode
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
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 */
74 /** @file
75 The <tt>libcubeb</tt> C API. */
77 typedef struct cubeb cubeb; /**< Opaque handle referencing the application state. */
78 typedef struct cubeb_stream cubeb_stream; /**< Opaque handle referencing the stream state. */
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;
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,
117 CUBEB_STREAM_TYPE_MAX
118 } cubeb_stream_type;
119 #endif
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;
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;
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 };
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);
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);
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);
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);
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);
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);
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);
209 /** Destroy an application context.
210 @param context */
211 void cubeb_destroy(cubeb * context);
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);
232 /** Destroy a stream.
233 @param stream */
234 void cubeb_stream_destroy(cubeb_stream * stream);
236 /** Start playback.
237 @param stream
238 @retval CUBEB_OK
239 @retval CUBEB_ERROR */
240 int cubeb_stream_start(cubeb_stream * stream);
242 /** Stop playback.
243 @param stream
244 @retval CUBEB_OK
245 @retval CUBEB_ERROR */
246 int cubeb_stream_stop(cubeb_stream * stream);
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);
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);
264 #if defined(__cplusplus)
265 }
266 #endif
268 #endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */
