/** * @file bdIMADpj.h * @brief bdSound IMproved Audio Device for PJSIP. */ /** * @defgroup bd_IMAD bdIMADpj bdSound IMproved Audio Device for PJSIP. * @ingroup audio_device_api * * bdSound IMproved Audio Device is a multiplatform audio interface * created to integrate in PJSIP library with no effort. * \n Porting bdIMADpj across the main operating systems is * straightforward, without the need of change a single line of code. * * - Features * - Echo cancellation (Full Duplex) * - Noise reduction * - Automatic Gain Control * - Audio Enhancement * * - Supported operating systems * - Windows * - Android * - MacOS X * - iOS * - Linux / Alsa * * - Supported platforms * - x86 * - x64 * - ARM Cortex-A8/A9/A15 with NEON * * Visit bdSound for updated * features, supported operating systems and platforms. * * Using PJSIP with bdIMAD audio device * * - Integration * \n Using bdIMAD within PJSIP is simple: * -# Request for bdIMADpj library to * bdSound: * bdSound will provide instruction to integrate the library depending on * the platform / O.S. / toolchain; * -# Add the bdimad_dev.c file to * pjmedia/src/pjmedia-audiodev folder; * -# Enable the bdIMAD audio device defining the periferal in the * pj/config_site.h and disabling all other devices: *
 *       #define PJMEDIA_AUDIO_DEV_HAS_BDIMAD 1
 *       
* * - Usage * \n There are only a couple of things the customer have to pay attention on * §when using bdIMAD library. * * - Initialization * \n Since the bdIMAD library provide itself the echo cancellation * and the latency management, is necessary to disable these features * in the PJSIP librariy applications. * \n For example in PJSUA sample application there is the need * to provide the following commands: *
 *       --ec-tail=0
 *       --no-vad
 *       --capture-lat=0
 *       --playback-lat=0
 *       
* * - Supported set capability * - PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING * \n Setting speaker volume. * - PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING * \n Setting michrophone volume. * - PJMEDIA_AUD_DEV_CAP_EC * \n Enable/disable echo cancellation. * * For additional information visit * www.bdsound.com * or write to info@bdsound.com * * @author bdSound * @version 1.0.1 * @copyright 2012 bdSound srl. All rights reserved. * */ /** * @defgroup groupFunction Functions * @ingroup bd_IMAD * * Functions defined in bdIMAD. */ /** * @defgroup groupCallback Callbacks * @ingroup bd_IMAD * * Callbacks defined in bdIMAD. */ /** * @defgroup groupStructEnum Structs and Enums * @ingroup bd_IMAD * * Struct and Enum defined in bdIMAD. */ #ifndef BD_IMAD_PJ_H__ #define BD_IMAD_PJ_H__ /** * @brief Macro for Windows DLL Support. */ #ifdef _BDIMADPJ_EXPORTDLL #ifdef WIN32 #define BDIMADPJ_API __declspec(dllexport) #else #define BDIMADPJ_API __attribute__((visibility("default"))) #endif #else #define BDIMADPJ_API #endif #define BD_IMAD_CAPTURE_DEVICES 1 #define BD_IMAD_PLAYBACK_DEVICES 0 #define BD_IMAD_DIAGNOSTIC_ENABLE 1 #define BD_IMAD_DIAGNOSTIC_DISABLE 0 #define BD_IMAD_BITS_X_SAMPLE 16 /**< Bits per sample */ typedef void* bdIMADpj; /** * @addtogroup groupCallback * @{ */ /** * @brief Callback used to fill the playback buffer of bdIMAD. * The function is called by bdIMAD each time are required sample to be played. * @param[in] *buffer pointer to the buffer with the audio * samples to be played(short type). * @param[in] nSamples number of samples required. * @param[in] user_data pointer to the user data structure * defined in the bdIMADpj_Setting_t * structure. * @return none. */ typedef int (* cb_fillPlayBackB_t) (void *buffer, int nSamples, void *user_data); /** * @brief Callback used to retrive the caputre buffer of bdIMAD. The function * is called by bdIMAD each time processed mic samples are available. * @param[out] *buffer pointer to the buffer with the audio * samples to download(short type). * @param[in] nSamples number of samples processed to download. * @param[in] user_data pointer to the user data structure * defined in the MainSet structure. * @return none. */ typedef void (* cb_emptyCaptureB_t) (void *buffer, int nSamples, void *user_data); /** * @} */ /** * @addtogroup groupStructEnum * @{ */ /** * @brief Error status returned by some functions in the library. */ typedef enum bdIMADpj_Status{ /**< No error. */ BD_PJ_OK = 0, /**< Watch bdIMADpj_Warnings_t structure to find the warnings. */ BD_PJ_WARN_BDIMAD_WARNING_ASSERTED = 1, /**< Error not identified. */ BD_PJ_ERROR_GENERIC = 2, /**< The pointer passed is NULL. */ BD_PJ_ERROR_NULL_POINTER = 3, /**< Allocation procedure failed. */ BD_PJ_ERROR_ALLOCATION = 4, /**< The parameter is not existent or the set/get function is not active. */ BD_PJ_ERROR_PARAMETER_NOT_FOUND = 5, /**< No capture device found. */ BD_PJ_ERROR_IMAD_NONE_CAPTURE_DEV = 10, /**< No play device found. */ BD_PJ_ERROR_IMAD_NONE_PLAY_DEV = 11, /**< Frame size not allowed. */ BD_PJ_ERROR_IMAD_FRAME_SIZE = 12, /**< Sample frequency not allowed. */ BD_PJ_ERROR_IMAD_SAMPLE_FREQ = 13, /**< Samples missing. */ BD_PJ_ERROR_IMAD_MISSING_SAMPLES = 14, /**< Device list is empty. */ BD_PJ_ERROR_IMAD_DEVICE_LIST_EMPTY = 15, /**< Library not authorized, entering demo mode. */ BD_PJ_ERROR_IMAD_LIB_NOT_AUTHORIZED = 16, /**< The input channel memory has not been allocated. */ BD_PJ_ERROR_IMAD_INPUT_CH_NOT_ALLOCATED = 17, /**< The library has expired, entering demo mode. */ BD_PJ_ERROR_IMAD_LICENSE_EXPIRED = 18, /**< Open of capture device failed. */ BD_PJ_ERROR_IMAD_OPEN_CAPTURE_DEV_FAILED = 19, /**< Open of play device failed. */ BD_PJ_ERROR_IMAD_OPEN_PLAY_DEV_FAILED = 20, /**< Start of play device failed. */ BD_PJ_ERROR_IMAD_START_PLAY_DEV_FAILED = 21, /**< Start of capture device failed. */ BD_PJ_ERROR_IMAD_START_CAPTURE_DEV_FAILED = 22, /**< Start of time process failed. */ BD_PJ_ERROR_IMAD_START_TIME_PROCESS_FAILED = 23, /**< Start of thread process failed. */ BD_PJ_ERROR_IMAD_THREAD_PROCESS_FAILED = 24, /**< No volume control available. */ BD_PJ_ERROR_IMAD_NO_VOL_CONTROL_AVAILABLE = 25, } bdIMADpj_Status; /** * @brief Parameter to pass to set and get parameter functions. * * For each enumeration are defined the data type and the supported operations * on that parameter (set and get). */ typedef enum bdIMADpj_Parameter{ /**< int* \n set/get \n 1 enable / 0 disable echo cancellation. */ BD_PARAM_IMAD_PJ_AEC_ENABLE = 1, /**< int* \n set/get \n 1 enable / 0 disable microphone control * (when possible). */ BD_PARAM_IMAD_PJ_MIC_CONTROL_ENABLE = 2, /**< int* \n set/get \n 1 ebable / 0 disable noise reduction. */ BD_PARAM_IMAD_PJ_NOISE_REDUCTION_ENABLE = 3, /**< int* \n set \n number of channel to reset. Used to reset * the input channel statistics. To be used when the same channel * is assigned to another partecipant. */ BD_PARAM_IMAD_PJ_RESET_STATISTIC_IN_CH = 4, /**< float* \n set/get \n 0.0f -> 1.0f volume of * the microphone(when possible). */ BD_PARAM_IMAD_PJ_MIC_VOLUME = 5, /**< int* \n set/get \n 0 mute / 1 not mute on microphone * (when possible). */ BD_PARAM_IMAD_PJ_MIC_MUTE = 6, /**< float* \n set/get \n 0.0f -> 1.0f volume of the speaker. */ BD_PARAM_IMAD_PJ_SPK_VOLUME = 7, /**< int* \n set/get \n 0 mute / 1 not mute on speaker. */ BD_PARAM_IMAD_PJ_SPK_MUTE = 8, } bdIMADpj_Parameter; /** * @brief Instance structure for the information regarding the aec engine. */ typedef struct bdIMADpj_Setting_t{ /**< Sample frequency (8kHz or 16kHz). */ int SamplingFrequency; /**< Audio buffer managed by the aec bdIMAD functions. * (from 16ms to 80ms, 16ms recommended). */ int FrameSize_ms; /**< Points to the validation functions in the validation library. */ void *validate; /**< Points to the the callback function used for filling * the playback buffer of bdIMAD. */ cb_fillPlayBackB_t cb_fillPlayBackBuffer; /**< Points to user data to pass to the callback. */ void *cb_fillPlayBackBuffer_user_data; /**< Points to the callback function used for retreive the processed * audio present in the capture buffer of bdIMAD. */ cb_emptyCaptureB_t cb_emptyCaptureBuffer; /**< Points to user data to pass to the callback. */ void *cb_emptyCaptureBuffer_user_data; /**< Is a wide char pointer to the capture device name. */ wchar_t *CaptureDevice; /**< Is a wide char pointer to the play device name. */ wchar_t *PlayDevice; /**< True to enable diagnostic, false to disable. */ int DiagnosticEnable; /**< Directory which will contains the files generated for diagnostic. */ wchar_t *DiagnosticFolderPath; /**< Is an auxiliary settings pointer used internally by bdIMAD. */ void *bdIMADwr_SettingsData; } bdIMADpj_Setting_t; /** * @brief Instance structure for the warnings generated by the initialization * functions. */ typedef struct bdIMADpj_Warnings_t{ /**< The capture device indicated can't be opened, has been selected * the default capture device. */ int DefaultCaptureDeviceAutomaticallySelected; /**< The capture device opened has not volume control. */ int CaptureDeviceWithoutVolumeControl; /**< The play device indicated can't be opened, has been selected * the default play device. */ int DefaultPlayDeviceAutomaticallySelected; /**< The number of channel requested is out of range. The number of * channel opened is equal to the maximum. */ int NumberOfChannelsOutOfRange; /**< The diagnostic files could not be saved. */ int DiagnosticSaveNotAllowed; /**< The nlp level requested is not allowed, it has been automatically * changed to the default value. */ int nlpLevelChangeSettting; /**< No capture device is present. Anyway the bdSES has been * istantiated only for playback. */ int NoCaptureDevicePresent; /**< The cpu is not adapt to run the aec engine, the aec has been disabled. * This appens for very old cpu like pentium III. */ int oldCPUdetected_AECdisable; /**< Windows Direct Sound error. */ long directSoundError; /**< Windows Direct Sound volume error. */ long directSoundLevel; /**< No play device is present. Anyway the bdSES has been istantiated * only for capture. */ int NoPlayDevicePresent; } bdIMADpj_Warnings_t; /** * @brief Instance structure for the library version */ typedef struct bdIMADpj_libVersion_t{ int major; /**< major version. */ int minor; /**< minor version. */ int build; /**< build number. */ char *name; /**< name "bdIMADpj ver.X". */ char *version; /**< beta, RC, release. */ char *buildDate; /**< build date. */ } bdIMADpj_libVersion_t; /** * @} */ /** * @addtogroup groupFunction * @{ */ #ifdef __cplusplus extern "C" { #endif /** * @brief Must be used to allocate and set to default parameter the memory * for the bdIMAD. * * The function generate a structure bdIMADpj_Setting_t filled with the * default settings. * \n The user can change this settings according to the need and then * launch the ::bdIMADpj_InitAEC. * \n The function generate also a warning structure (::bdIMADpj_Warnings_t) * that could be used in ::bdIMADpj_InitAEC to handle eventual warnings. * @param[out] **ppSettings Points to the pointer of the * allocated ::bdIMADpj_Setting_t. * @param[out] **ppWarningMessages Points to the pointer of the * allocated ::bdIMADpj_Warnings_t. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise return * an error (refer to ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_CreateStructures( bdIMADpj_Setting_t **ppSettings, bdIMADpj_Warnings_t **ppWarningMessages); /** * @brief Is used to free the memory for the ::bdIMADpj_Setting_t structure and * ::bdIMADpj_Warnings_t structure allocated with * the ::bdIMADpj_CreateStructures. * @param[in] **ppSettings Pointer to a memory location filled * with the address of the * ::bdIMADpj_Setting_t structure to free. * This address will be set to NULL. * @param[in] **ppWarningMessages Pointer to a memory location filled * with the address of the allocated * ::bdIMADpj_Warnings_t structure to free. * This address will be set to NULL. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise return * an error (refer to ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_FreeStructures( bdIMADpj_Setting_t **ppSettings, bdIMADpj_Warnings_t **ppWarningMessages); /** * @brief Is used to initialize the memory for bdIMAD with the settings * contained in the ppSettings. * @param[out] *pBdIMADInstance Is the pointer to the bdIMAD object. * @param[in] **ppSettings Pointer to pointer to a * ::bdIMADpj_Setting_t structure, filled * with initialization settings to be * applied to the bdIMAD. * \n Note, the pBdIMADInstance * is modified with the applied settings. * @param[out] **ppWarningMessages Pointer to pointer to a * ::bdIMADpj_Warnings_t sructure, * which reports the warnings after the * initialization. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise return * an error (refer to ::bdIMADpj_Status). * \n If the error is * ::BD_PJ_WARN_BDIMAD_WARNING_ASSERTED * the init has been performed with success, * but with a different settings * respect to the ones required. * This mainly happens if the audio * device opened is different to the * one requested. */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_InitAEC(bdIMADpj *pBdIMADInstance, bdIMADpj_Setting_t **ppSettings, bdIMADpj_Warnings_t **ppWarningMessages); /** * @brief Is used to free the bdIMAD object pointed by the * pBdIMADInstance. * @param[in] *pBdIMADInstance Pointer to the bdIMAD object to free. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise return * an error (refer to ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_FreeAEC(bdIMADpj *pBdIMADInstance); /** * @brief Is used to make a list of capure and play devices available * on the system. * @param[in] captureDevice Set to 1 to get the list of capture * devices. Set to 0 to get the list of * play devices. * @param[in] **deviceName Pointer to pointer to a wide char * containing the names of capture/play * devices. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise return * an error (refer to ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_getDeviceName(int captureDevice, wchar_t **deviceName); /** * @brief Is used to freeze the bdIMAD, stopping the audio playback * and recording. * @param[in] bdIMADInstance bdIMAD object. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise * return an error (refer to * ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_stop(bdIMADpj bdIMADInstance); /** * @brief Is used to put back in play the audio after it has been stopped by the * ::bdIMADpj_stop functions. * @param[in] bdIMADInstance bdIMAD object. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise * return an error (refer to * ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_run(bdIMADpj bdIMADInstance); /** * @brief Print on a standard output the warning messages. * @param[in] *pWarningMessages Pointer to the warning structure * to be printed. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise * return an error * (refer to ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_DisplayWarnings( bdIMADpj_Warnings_t *pWarningMessages); /** * @brief Clear the warning structure after being read. * @param[out] **ppWarningMessages Pointer to pointer to the warning * structure to be cleared. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise * return an error (refer to * ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_ClearAllWarnings( bdIMADpj_Warnings_t **ppWarningMessages); /** * @brief Is used to set a parameter of the bdIMAD object pointed by the * pBdIMADInstance. * @param[in] bdIMADInstance bdIMAD object. * @param[in] parameterName Indicate the parameter to set. * @param[in] *pValue Is a pointer to the value to set * cast to void. * \n In the ::bdIMADpj_Parameter * declaration is indicated the real type of * the value, depending on the * parameterName. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise * return an error (refer to * §::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_setParameter(bdIMADpj bdIMADInstance, bdIMADpj_Parameter parameterName, void *pValue); /** * @brief Is used to get a parameter of the bdIMAD object pointed by the * pBdIMADInstance. * @param[in] bdIMADInstance bdIMAD object. * @param[in] parameterName Indicate the parameter to get. * @param[out] *pValue Is a pointer to the value to get cast * to void. \n In the * ::bdIMADpj_Parameter declaration is * indicated the real type of the value, * depending on the * parameterName. * @return ::BD_PJ_OK if the function has been * performed successfully, otherwise return * an error (refer to ::bdIMADpj_Status). */ BDIMADPJ_API bdIMADpj_Status bdIMADpj_getParameter(bdIMADpj bdIMADInstance, bdIMADpj_Parameter parameterName, void *pValue); #ifdef __cplusplus } #endif /** * @} */ #endif //BD_IMAD_PJ_H__