/** | |
* @file bdIMADpj.h | |
* @brief bdSound IMproved Audio Device for PJSIP. | |
*/ | |
/** | |
* @defgroup bd_IMAD bdIMADpj bdSound IMproved Audio Device for PJSIP. | |
* @ingroup audio_device_api | |
* | |
* <b>bdSound IMproved Audio Device</b> is a multiplatform audio interface | |
* created to integrate in <b>PJSIP</b> library with no effort. | |
* \n Porting <b>bdIMADpj</b> across the main operating systems is | |
* straightforward, without the need of change a single line of code. | |
* | |
* - <b>Features</b> | |
* - Echo cancellation (Full Duplex) | |
* - Noise reduction | |
* - Automatic Gain Control | |
* - Audio Enhancement | |
* | |
* - <b>Supported operating systems</b> | |
* - Windows | |
* - Android | |
* - MacOS X | |
* - iOS | |
* - Linux / Alsa | |
* | |
* - <b>Supported platforms</b> | |
* - x86 | |
* - x64 | |
* - ARM Cortex-A8/A9/A15 with NEON | |
* | |
* Visit <a href="http:/www.bdsound.com" target="new">bdSound</a> for updated | |
* features, supported operating systems and platforms. | |
* | |
* <b>Using PJSIP with bdIMAD audio device</b> | |
* | |
* - <b>Integration</b> | |
* \n Using <b>bdIMAD</b> within <b>PJSIP</b> is simple: | |
* -# Request for bdIMADpj library to | |
* <a href="http:/www.bdsound.com" target="new">bdSound</a>: | |
* bdSound will provide instruction to integrate the library depending on | |
* the platform / O.S. / toolchain; | |
* -# Add the <code>bdimad_dev.c</code> file to | |
* <code>pjmedia/src/pjmedia-audiodev</code> folder; | |
* -# Enable the bdIMAD audio device defining the periferal in the | |
* <code>pj/config_site.h</code> and disabling all other devices: | |
* <pre> | |
* #define PJMEDIA_AUDIO_DEV_HAS_BDIMAD 1 | |
* </pre> | |
* | |
* - <b>Usage</b> | |
* \n There are only a couple of things the customer have to pay attention on | |
* §when using bdIMAD library. | |
* | |
* - <b>Initialization</b> | |
* \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: | |
* <pre> | |
* --ec-tail=0 | |
* --no-vad | |
* --capture-lat=0 | |
* --playback-lat=0 | |
* </pre> | |
* | |
* - <b>Supported set capability</b> | |
* - <code>PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING</code> | |
* \n Setting speaker volume. | |
* - <code>PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING</code> | |
* \n Setting michrophone volume. | |
* - <code>PJMEDIA_AUD_DEV_CAP_EC</code> | |
* \n Enable/disable echo cancellation. | |
* | |
* For additional information visit | |
* <a href="http:/www.bdsound.com" target="new">www.bdsound.com</a> | |
* 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 <code>ppSettings</code>. | |
* @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 <code>pBdIMADInstance</code> | |
* 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 | |
* <code>pBdIMADInstance</code>. | |
* @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 | |
* <code>pBdIMADInstance</code>. | |
* @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 | |
* <code>parameterName</code>. | |
* @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 | |
* <code>pBdIMADInstance</code>. | |
* @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 | |
* <code>parameterName</code>. | |
* @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__ |