include/hal_bt_capture.h

/*
 * Copyright (C) 2017 Amlogic Corporation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


/**
 * @defgroup MEDIA_UTILS Media Utils
 * - Audio capture manager presents the audio data to registered applications.
 *
 * @defgroup MEDIA_UTILS_TYPES Media Utils Data types
 * @ingroup  MEDIA_UTILS
 *
 * @defgroup MEDIA_UTILS_HAL_APIS  Media Utils hal APIs
 * @ingroup  MEDIA_UTILS
 *
 **/

#ifndef __AUDIO_CAPTURE_H__
#define __AUDIO_CAPTURE_H__

#include <stddef.h>  /* size_t */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup MEDIA_UTILS_TYPES
 * @{
 */

typedef struct AML_AudioCapture_Struct *AML_AudioCaptureHandle;

typedef char *AML_AudioCaptureType;

#define success 1
#define fail 0

#define AML_AC_TYPE_PRIMARY     "primary"
#define AML_AC_TYPE_AUXILIARY   "auxiliary"

typedef enum AML_AudioCapture_Freq {
    Freq_e16000,         /**< 16KHz    */
    Freq_e22050,         /**< 22.05KHz    */
    Freq_e24000,         /**< 24KHz    */
    Freq_e32000,         /**< 32KHz    */
    Freq_e44100,         /**< 44.1KHz  */
    Freq_e48000,         /**< 48KHz    */
    Freq_eMax
} Freq;

typedef enum AML_AudioCapture_Format {
    Format_e16BitStereo,    /**< Stereo, 16 bits per sample interleaved into a 32-bit word. */
    Format_e24BitStereo,    /**< Stereo, 24 bits per sample.  The data is aligned to 32-bits,
                                             left-justified.  Left and right channels will interleave
                                             one sample per 32-bit word.  */
    Format_e16BitMonoLeft,  /**< Mono, 16 bits per sample interleaved into a 32-bit word. Left channel samples only. */
    Format_e16BitMonoRight, /**< Mono, 16 bits per sample interleaved into a 32-bit word. Right channel samples only. */
    Format_e16BitMono,      /**< Mono, 16 bits per sample interleaved into a 32-bit word. Left and Right channels mixed. */
    Format_e24Bit5_1,       /**< 5.1 Multichannel, 24 bits per sample.  The data is aligned to 32-bits,
                                             left-justified.  Channels will interleave
                                             one sample per 32-bit word, ordered L,R,Ls,Rs,C,LFE.  */
    Format_eMax
} Format;


typedef struct AML_AudioCapture_Settings {
    size_t fifoSize;                                /**< FIFO size in bytes.  This value is a total FIFO size to hold all channels of data
                                                         If not set, a default size will be used.  Needs to be big enough to avoid overflow (expected service time * byte rate)*/
    size_t threshold;                               /**< FIFO data callback threshold in bytes.  When the amount of data in the FIFO reaches this level, the dataCallback will be invoked */
    Format format;                               /**< Captured data format.  Default is 16bit stereo.
                                                        This value is ignored for compressed data, and
                                                         can not be changed while connected to any inputs. */
    Freq  samplingFreq;                          /**< Captured data sampling freq  tbd, not currently supported..*/
} AML_AudioCapture_Settings;


typedef struct AML_AudioCapture_Status {
    int             started;                /**< is the capture started */ //TODO: C interface, bool not define, typedef later
    Format       format;                 /**< Current capture format (Bit depth & Channel) */
    Freq         samplingFreq;           /**< Current capture sample rate */
    size_t          fifoDepth;              /**< number of bytes in local fifo */
    /* tbd ... need to determine what is useful or even what is possible.*/
} AML_AudioCapture_Status;

/** @} */  //END OF GROUP MEDIA_UTILS_TYPES


/**
 * @addtogroup MEDIA_UTILS_HAL_APIS
 * @{
 */

/*
 * Interfaces
 */

/**
 * @brief This API creates audio capture session, create all required resources to provide audio capture handle.
 *
 * @param[in] handle AML audio capture instance handle.
 *
 * @return  Returns a opaque AudioCaptureHandle, which has to be passed as an argument for all subsequent AudioCapture calls
 * @return  Returns fail or success.
 */
struct AML_AudioCapture_Struct * AML_AudioCapture_Open ();



/**
 * @brief This API Will return default AML audio capture settings.
 *
 * Once audio capture gets started this API will continue to return the default capture settings.
 *
 * @param[in] settings Structure which holds the audio properties.
 *
 * @return  Returns fail or success.
 */
int AML_AudioCapture_GetDefaultSettings (AML_AudioCapture_Settings* settings);


/**
 * @brief This API will start the Audio capture.
 *
 * If audio capture settings are retained then this API will reconfigure with the provided capture settings to start audio capture.
 * If audio capture settings are not retained then audio capture will start with the default capture settings.
 *
 * @param[in] handle audio capture handle.
 * @param[in] settings Structure which holds the audio settings.
 *
 * @return Returns fail or success.
*/
int AML_AudioCapture_Start (AML_AudioCaptureHandle handle,AML_AudioCapture_Settings* settings);


/**
 * @brief This API will stop the audio capture.
 *
 * Start can be called again after a Stop, as long as Close has not been called.
 *
 * @param[in] handle audio capture handle.
 *
 * @return Returns fail or success.
 */
int AML_AudioCapture_Stop (AML_AudioCaptureHandle handle);

/**
 * @brief This API will free all resources associated with this audio capture handle. It will close audio capture session.
 *
 * @param[in] handle audio capture handle.
 *
 * @return  Returns fail or success.
 */
int AML_AudioCapture_Close (AML_AudioCaptureHandle handle);

/**
 * @brie This API will write audio data to file
 *
 * @param[in] path:file path
 * @param[in] buf:audio data buf
 * @param[in] bytes:audio data bytes length
 * @return  Returns fail or success.
**/
int audio_dump_audio_bitstreams(const char *path, const void *buf, size_t bytes);





/** @} */  //END OF GROUP MEDIA_UTILS_HAL_APIS


#ifdef __cplusplus
}
#endif
#endif /* __AUDIO_CAPTURE_H__ */