michael@0: /*
michael@0:  * Copyright © 2011 Mozilla Foundation
michael@0:  *
michael@0:  * This program is made available under an ISC-style license.  See the
michael@0:  * accompanying file LICENSE for details.
michael@0:  */
michael@0: #if !defined(CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382)
michael@0: #define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382
michael@0: 
michael@0: #include <cubeb/cubeb-stdint.h>
michael@0: 
michael@0: #if defined(__cplusplus)
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: /** @mainpage
michael@0: 
michael@0:     @section intro Introduction
michael@0: 
michael@0:     This is the documentation for the <tt>libcubeb</tt> C API.
michael@0:     <tt>libcubeb</tt> is a callback-based audio API library allowing the
michael@0:     authoring of portable multiplatform audio playback.
michael@0: 
michael@0:     @section example Example code
michael@0: 
michael@0:     @code
michael@0:     cubeb * app_ctx;
michael@0:     cubeb_init(&app_ctx, "Example Application");
michael@0: 
michael@0:     cubeb_stream_params params;
michael@0:     params.format = CUBEB_SAMPLE_S16NE;
michael@0:     params.rate = 48000;
michael@0:     params.channels = 2;
michael@0: 
michael@0:     unsigned int latency_ms = 250;
michael@0: 
michael@0:     cubeb_stream * stm;
michael@0:     cubeb_stream_init(app_ctx, &stm, "Example Stream 1", params,
michael@0:                       latency_ms, data_cb, state_cb, NULL);
michael@0: 
michael@0:     cubeb_stream_start(stm);
michael@0:     for (;;) {
michael@0:       cubeb_stream_get_position(stm, &ts);
michael@0:       printf("time=%llu\n", ts);
michael@0:       sleep(1);
michael@0:     }
michael@0:     cubeb_stream_stop(stm);
michael@0: 
michael@0:     cubeb_stream_destroy(stm);
michael@0:     cubeb_destroy(app_ctx);
michael@0:     @endcode
michael@0: 
michael@0:     @code
michael@0:     long data_cb(cubeb_stream * stm, void * user, void * buffer, long nframes)
michael@0:     {
michael@0:       short * buf = buffer;
michael@0:       for (i = 0; i < nframes; ++i) {
michael@0:         for (c = 0; c < params.channels; ++c) {
michael@0:           buf[i][c] = 0;
michael@0:         }
michael@0:       }
michael@0:       return nframes;
michael@0:     }
michael@0:     @endcode
michael@0: 
michael@0:     @code
michael@0:     void state_cb(cubeb_stream * stm, void * user, cubeb_state state)
michael@0:     {
michael@0:       printf("state=%d\n", state);
michael@0:     }
michael@0:     @endcode
michael@0: */
michael@0: 
michael@0: /** @file
michael@0:     The <tt>libcubeb</tt> C API. */
michael@0: 
michael@0: typedef struct cubeb cubeb;               /**< Opaque handle referencing the application state. */
michael@0: typedef struct cubeb_stream cubeb_stream; /**< Opaque handle referencing the stream state. */
michael@0: 
michael@0: /** Sample format enumeration. */
michael@0: typedef enum {
michael@0:   /**< Little endian 16-bit signed PCM. */
michael@0:   CUBEB_SAMPLE_S16LE,
michael@0:   /**< Big endian 16-bit signed PCM. */
michael@0:   CUBEB_SAMPLE_S16BE,
michael@0:   /**< Little endian 32-bit IEEE floating point PCM. */
michael@0:   CUBEB_SAMPLE_FLOAT32LE,
michael@0:   /**< Big endian 32-bit IEEE floating point PCM. */
michael@0:   CUBEB_SAMPLE_FLOAT32BE,
michael@0: #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__)
michael@0:   /**< Native endian 16-bit signed PCM. */
michael@0:   CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16BE,
michael@0:   /**< Native endian 32-bit IEEE floating point PCM. */
michael@0:   CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE
michael@0: #else
michael@0:   /**< Native endian 16-bit signed PCM. */
michael@0:   CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE,
michael@0:   /**< Native endian 32-bit IEEE floating point PCM. */
michael@0:   CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE
michael@0: #endif
michael@0: } cubeb_sample_format;
michael@0: 
michael@0: #if defined(__ANDROID__)
michael@0: typedef enum {
michael@0:     CUBEB_STREAM_TYPE_VOICE_CALL = 0,
michael@0:     CUBEB_STREAM_TYPE_SYSTEM = 1,
michael@0:     CUBEB_STREAM_TYPE_RING = 2,
michael@0:     CUBEB_STREAM_TYPE_MUSIC = 3,
michael@0:     CUBEB_STREAM_TYPE_ALARM = 4,
michael@0:     CUBEB_STREAM_TYPE_NOTIFICATION = 5,
michael@0:     CUBEB_STREAM_TYPE_BLUETOOTH_SCO = 6,
michael@0:     CUBEB_STREAM_TYPE_ENFORCED_AUDIBLE = 7,
michael@0:     CUBEB_STREAM_TYPE_DTMF = 8,
michael@0:     CUBEB_STREAM_TYPE_TTS = 9,
michael@0:     CUBEB_STREAM_TYPE_FM = 10,
michael@0: 
michael@0:     CUBEB_STREAM_TYPE_MAX
michael@0: } cubeb_stream_type;
michael@0: #endif
michael@0: 
michael@0: /** Stream format initialization parameters. */
michael@0: typedef struct {
michael@0:   cubeb_sample_format format; /**< Requested sample format.  One of
michael@0:                                    #cubeb_sample_format. */
michael@0:   unsigned int rate;          /**< Requested sample rate.  Valid range is [1, 192000]. */
michael@0:   unsigned int channels;      /**< Requested channel count.  Valid range is [1, 32]. */
michael@0: #if defined(__ANDROID__)
michael@0:   cubeb_stream_type stream_type; /**< Used to map Android audio stream types */
michael@0: #endif
michael@0: } cubeb_stream_params;
michael@0: 
michael@0: /** Stream states signaled via state_callback. */
michael@0: typedef enum {
michael@0:   CUBEB_STATE_STARTED, /**< Stream started. */
michael@0:   CUBEB_STATE_STOPPED, /**< Stream stopped. */
michael@0:   CUBEB_STATE_DRAINED, /**< Stream drained. */
michael@0:   CUBEB_STATE_ERROR    /**< Stream disabled due to error. */
michael@0: } cubeb_state;
michael@0: 
michael@0: /** Result code enumeration. */
michael@0: enum {
michael@0:   CUBEB_OK = 0,                       /**< Success. */
michael@0:   CUBEB_ERROR = -1,                   /**< Unclassified error. */
michael@0:   CUBEB_ERROR_INVALID_FORMAT = -2,    /**< Unsupported #cubeb_stream_params requested. */
michael@0:   CUBEB_ERROR_INVALID_PARAMETER = -3  /**< Invalid parameter specified. */
michael@0: };
michael@0: 
michael@0: /** User supplied data callback.
michael@0:     @param stream
michael@0:     @param user_ptr
michael@0:     @param buffer
michael@0:     @param nframes
michael@0:     @retval Number of frames written to buffer, which must equal nframes except at end of stream.
michael@0:     @retval CUBEB_ERROR on error, in which case the data callback will stop
michael@0:             and the stream will enter a shutdown state. */
michael@0: typedef long (* cubeb_data_callback)(cubeb_stream * stream,
michael@0:                                      void * user_ptr,
michael@0:                                      void * buffer,
michael@0:                                      long nframes);
michael@0: 
michael@0: /** User supplied state callback.
michael@0:     @param stream
michael@0:     @param user_ptr
michael@0:     @param state */
michael@0: typedef void (* cubeb_state_callback)(cubeb_stream * stream,
michael@0:                                       void * user_ptr,
michael@0:                                       cubeb_state state);
michael@0: 
michael@0: /** Initialize an application context.  This will perform any library or
michael@0:     application scoped initialization.
michael@0:     @param context
michael@0:     @param context_name
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR */
michael@0: int cubeb_init(cubeb ** context, char const * context_name);
michael@0: 
michael@0: /** Get a read-only string identifying this context's current backend.
michael@0:     @param context
michael@0:     @retval Read-only string identifying current backend. */
michael@0: char const * cubeb_get_backend_id(cubeb * context);
michael@0: 
michael@0: /** Get the maximum possible number of channels.
michael@0:     @param context
michael@0:     @param max_channels The maximum number of channels.
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR_INVALID_PARAMETER
michael@0:     @retval CUBEB_ERROR */
michael@0: int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels);
michael@0: 
michael@0: /** Get the minimal latency value, in milliseconds, that is guaranteed to work
michael@0:     when creating a stream for the specified sample rate. This is platform and
michael@0:     backend dependant.
michael@0:     @param context
michael@0:     @param params On some backends, the minimum achievable latency depends on
michael@0:                   the characteristics of the stream.
michael@0:     @param latency The latency value, in ms, to pass to cubeb_stream_init.
michael@0:     @retval CUBEB_ERROR_INVALID_PARAMETER
michael@0:     @retval CUBEB_OK */
michael@0: int cubeb_get_min_latency(cubeb * context, cubeb_stream_params params, uint32_t * latency_ms);
michael@0: 
michael@0: /** Get the preferred sample rate for this backend: this is hardware and platform
michael@0:    dependant, and can avoid resampling, and/or trigger fastpaths.
michael@0:    @param context
michael@0:    @param samplerate The samplerate (in Hz) the current configuration prefers.
michael@0:    @return CUBEB_ERROR_INVALID_PARAMETER
michael@0:    @return CUBEB_OK */
michael@0: int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate);
michael@0: 
michael@0: /** Destroy an application context.
michael@0:     @param context */
michael@0: void cubeb_destroy(cubeb * context);
michael@0: 
michael@0: /** Initialize a stream associated with the supplied application context.
michael@0:     @param context
michael@0:     @param stream
michael@0:     @param stream_name
michael@0:     @param stream_params
michael@0:     @param latency Approximate stream latency in milliseconds.  Valid range is [1, 2000].
michael@0:     @param data_callback Will be called to preroll data before playback is
michael@0:                           started by cubeb_stream_start.
michael@0:     @param state_callback
michael@0:     @param user_ptr
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR
michael@0:     @retval CUBEB_ERROR_INVALID_FORMAT */
michael@0: int cubeb_stream_init(cubeb * context, cubeb_stream ** stream, char const * stream_name,
michael@0:                       cubeb_stream_params stream_params, unsigned int latency,
michael@0:                       cubeb_data_callback data_callback,
michael@0:                       cubeb_state_callback state_callback,
michael@0:                       void * user_ptr);
michael@0: 
michael@0: /** Destroy a stream.
michael@0:     @param stream */
michael@0: void cubeb_stream_destroy(cubeb_stream * stream);
michael@0: 
michael@0: /** Start playback.
michael@0:     @param stream
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR */
michael@0: int cubeb_stream_start(cubeb_stream * stream);
michael@0: 
michael@0: /** Stop playback.
michael@0:     @param stream
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR */
michael@0: int cubeb_stream_stop(cubeb_stream * stream);
michael@0: 
michael@0: /** Get the current stream playback position.
michael@0:     @param stream
michael@0:     @param position Playback position in frames.
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR */
michael@0: int cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position);
michael@0: 
michael@0: /** Get the latency for this stream, in frames. This is the number of frames
michael@0:     between the time cubeb acquires the data in the callback and the listener
michael@0:     can hear the sound.
michael@0:     @param stream
michael@0:     @param latency Current approximate stream latency in ms
michael@0:     @retval CUBEB_OK
michael@0:     @retval CUBEB_ERROR */
michael@0: int cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * latency);
michael@0: 
michael@0: #if defined(__cplusplus)
michael@0: }
michael@0: #endif
michael@0: 
michael@0: #endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */