Re #1636: add initial support for bdIMAD

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@4432 74dad513-b988-da41-8d7b-12977e46ad98

1 files changed, 547 insertions, 0 deletions

diff --git a/third_party/bdsound/include/bdimad.h b/third_party/bdsound/include/bdimad.h
new file mode 100644
index 00000000..929fc213
--- /dev/null
+++ b/third_party/bdsound/include/bdimad.h
@@ -0,0 +1,547 @@
+ /**

+ * @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__