diff options
author | Paul Adenot <[email protected]> | 2016-07-01 14:28:44 +0200 |
---|---|---|
committer | Paul Adenot <[email protected]> | 2016-07-01 14:29:10 +0200 |
commit | 4b4e6e3db126ee62af7514fff65a7f6bd7346aeb (patch) | |
tree | 94067574f8e34b3aa919b5cbec1119081fedd26a /include | |
parent | de4940260e197592faaed7d3818e85c6aca56197 (diff) | |
download | cubeb-4b4e6e3db126ee62af7514fff65a7f6bd7346aeb.tar.gz cubeb-4b4e6e3db126ee62af7514fff65a7f6bd7346aeb.zip |
Update cubeb documentation for duplex streams.
Diffstat (limited to 'include')
-rw-r--r-- | include/cubeb/cubeb.h | 155 |
1 files changed, 107 insertions, 48 deletions
diff --git a/include/cubeb/cubeb.h b/include/cubeb/cubeb.h index d1db0c9..06ed5fa 100644 --- a/include/cubeb/cubeb.h +++ b/include/cubeb/cubeb.h @@ -19,44 +19,86 @@ extern "C" { This is the documentation for the <tt>libcubeb</tt> C API. <tt>libcubeb</tt> is a callback-based audio API library allowing the - authoring of portable multiplatform audio playback. + authoring of portable multiplatform audio playback and recording. @section example Example code + This example shows how to create a duplex stream that pipes the microphone + to the speakers, with minimal latency and the proper sample-rate for the + platform. + @code cubeb * app_ctx; cubeb_init(&app_ctx, "Example Application"); + int rv; + int rate; + int latency_ms; + uint64_t ts; + + rv = cubeb_get_min_latency(app_ctx, output_params, &latency_ms); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not get minimum latency"); + return rv; + } - cubeb_stream_params params; - params.format = CUBEB_SAMPLE_S16NE; - params.rate = 48000; - params.channels = 2; + rv = cubeb_get_preferred_sample_rate(app_ctx, output_params, &rate); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not get preferred sample-rate"); + return rv; + } - unsigned int latency_ms = 250; + cubeb_stream_params output_params; + output_params.format = CUBEB_SAMPLE_FLOAT32NE; + output_params.rate = rate; + output_params.channels = 2; + + cubeb_stream_params input_params; + output_params.format = CUBEB_SAMPLE_FLOAT32NE; + output_params.rate = rate; + output_params.channels = 1; cubeb_stream * stm; - cubeb_stream_init(app_ctx, &stm, "Example Stream 1", params, - latency_ms, data_cb, state_cb, NULL); + rv = cubeb_stream_init(app_ctx, &stm, "Example Stream 1", + NULL, input_params, + NULL, output_params, + latency_ms, + data_cb, state_cb, + NULL); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not open the stream"); + return rv; + } - cubeb_stream_start(stm); + rv = cubeb_stream_start(stm); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not start the stream"); + return rv; + } for (;;) { cubeb_stream_get_position(stm, &ts); printf("time=%llu\n", ts); sleep(1); } - cubeb_stream_stop(stm); + rv = cubeb_stream_stop(stm); + if (rv != CUBEB_OK) { + fprintf(stderr, "Could not stop the stream"); + return rv; + } cubeb_stream_destroy(stm); cubeb_destroy(app_ctx); @endcode @code - long data_cb(cubeb_stream * stm, void * user, void * buffer, long nframes) + long data_cb(cubeb_stream * stm, void * user, + void * input_buffer, void * output_buffer, long nframes) { - short * buf = buffer; + float * in = input_buffer; + float * out = output_buffer; + for (i = 0; i < nframes; ++i) { - for (c = 0; c < params.channels; ++c) { - buf[i][c] = 0; + for (c = 0; c < 2; ++c) { + buf[i][c] = in[i]; } } return nframes; @@ -101,6 +143,10 @@ typedef enum { } 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, @@ -133,7 +179,7 @@ typedef struct { #endif } cubeb_stream_params; -/** Output device description */ +/** Audio device description */ typedef struct { char * output_name; /**< The name of the output device */ char * input_name; /**< The name of the input device */ @@ -249,15 +295,21 @@ typedef struct { } cubeb_device_collection; /** User supplied data callback. - @param stream The stream for which this callback fired - @param user_ptr The pointer passed to cubeb_stream_create + - Calling other cubeb functions from this callback is unsafe. + - The code in the callback should be non-blocking. + - Returning less than the number of frames this callback asks for or + provides puts the stream in drain mode. This callback will not be called + again, and the state callback will be called with CUBEB_STATE_DRAINED when + all the frames have been output. + @param stream The stream for which this callback fired. + @param user_ptr The pointer passed to cubeb_stream_init. @param input_buffer A pointer containing the input data, or nullptr if this is an output-only stream. - @param output_buffer A pointer containing the output data, or nullptr - if this is an input -only stream. + @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, which must equal - nframes except at end of stream. + @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, @@ -267,39 +319,43 @@ typedef long (* cubeb_data_callback)(cubeb_stream * stream, long nframes); /** User supplied state callback. - @param stream - @param user_ptr - @param state */ + @param stream The stream for this this callback fired. + @param user_ptr The pointer passed to cubeb_stream_init. + @param state The new state of the stream. */ typedef void (* cubeb_state_callback)(cubeb_stream * stream, void * user_ptr, cubeb_state state); /** * User supplied callback called when the underlying device changed. - * @param user */ + * @param user THe pointer passed to cubeb_stream_init. */ typedef void (* cubeb_device_changed_callback)(void * user_ptr); /** * User supplied callback called when the underlying device collection changed. - * @param context - * @param user_ptr */ -typedef void (* cubeb_device_collection_changed_callback)(cubeb * context, void * user_ptr); + * @param context A pointer to the cubeb context. + * @param user_ptr The pointer passed to cubeb_stream_init. */ +typedef void (* cubeb_device_collection_changed_callback)(cubeb * context, + void * user_ptr); /** Initialize an application context. This will perform any library or application scoped initialization. - @param context - @param context_name - @retval CUBEB_OK - @retval CUBEB_ERROR */ + @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. + @retval CUBEB_OK in case of success. + @retval CUBEB_ERROR in case of error, for example because the host + has no audio hardware. */ int cubeb_init(cubeb ** context, char const * context_name); /** Get a read-only string identifying this context's current backend. - @param context + @param context A pointer to the cubeb context. @retval Read-only string identifying current backend. */ char const * cubeb_get_backend_id(cubeb * context); /** Get the maximum possible number of channels. - @param context + @param context A pointer to the cubeb context. @param max_channels The maximum number of channels. @retval CUBEB_OK @retval CUBEB_ERROR_INVALID_PARAMETER @@ -308,9 +364,9 @@ char const * cubeb_get_backend_id(cubeb * context); int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels); /** Get the minimal latency value, in milliseconds, that is guaranteed to work - when creating a stream for the specified sample rate. This is platform and - backend dependant. - @param context + when creating a stream for the specified sample rate. This is platform, + 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. @param latency_ms The latency value, in ms, to pass to cubeb_stream_init. @@ -323,26 +379,28 @@ int cubeb_get_min_latency(cubeb * context, /** Get the preferred sample rate for this backend: this is hardware and platform dependant, and can avoid resampling, and/or trigger fastpaths. - @param context + @param context A pointer to the cubeb context. @param rate The samplerate (in Hz) the current configuration prefers. @retval CUBEB_OK @retval CUBEB_ERROR_INVALID_PARAMETER @retval CUBEB_ERROR_NOT_SUPPORTED */ int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate); -/** Destroy an application context. - @param context */ +/** Destroy an application context. This must be called after all stream have + * been destroyed. + @param context A pointer to the cubeb context.*/ void cubeb_destroy(cubeb * context); /** Initialize a stream associated with the supplied application context. - @param context - @param stream - @param stream_name - @param input_device Device for the input side of the stream. If NULL + @param context A pointer to the cubeb context. + @param stream An out parameter to be filled with the an opaque pointer to a + cubeb stream. + @param stream_name A name for this stream. + @param input_device Device for the input side of the stream. If NULL the default input device is used. @param input_stream_params Parameters for the input side of the stream, or NULL if this stream is output only. - @param output_device Device for the output side of the stream. If NULL + @param output_device Device for the output side of the stream. If NULL the default output device is used. @param output_stream_params Parameters for the output side of the stream, or NULL if this stream is input only. @@ -350,8 +408,9 @@ void cubeb_destroy(cubeb * context); is [1, 2000]. @param data_callback Will be called to preroll data before playback is started by cubeb_stream_start. - @param state_callback - @param user_ptr + @param state_callback A pointer to a state callback. + @param user_ptr A pointer that will be passed to the callback. This pointer + must outlive the life time of the stream. @retval CUBEB_OK @retval CUBEB_ERROR @retval CUBEB_ERROR_INVALID_FORMAT @@ -369,7 +428,7 @@ int cubeb_stream_init(cubeb * context, void * user_ptr); /** Destroy a stream. - @param stream */ + @param stream The stream to destroy. */ void cubeb_stream_destroy(cubeb_stream * stream); /** Start playback. |