kenmirrors/freeswitch
1
0
Fork 0
mirror of https://github.com/signalwire/freeswitch.git synced 2025-04-22 11:19:52 +00:00
Code Issues Projects Releases Wiki Activity

Added even more documentation. This should look good with doxygen.

Browse Source 
git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@10733 d0543943-73ff-0310-b7d9-9358b9ac24b2
This commit is contained in:
Eric des Courtis 2008-12-12 16:07:53 +00:00
parent 1220bbcff2
commit c94e6a9368
1 changed files with 98 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
src/mod/applications/mod_vmd/mod_vmd.c
View File

@ -50,34 +50,38 @@
#define ISNAN(x) ((x)== NAN) #define ISNAN(x) ((x)== NAN)
#endif #endif
/*! Number of points for beep detection */ /*! Number of points for beep detection. */
#define POINTS 32 #define POINTS 32
/*! Number of valid points required for beep detection */ /*! Number of valid points required for beep detection. */
#define VALID 22 #define VALID 22
/*! Maximum number of invalid points to declare beep has stopped */ /*! Maximum number of invalid points to declare beep has stopped. */
#define MAX_CHIRP 22 #define MAX_CHIRP 22
/*! Minimum time for a beep */ /*! Minimum time for a beep. */
#define MIN_TIME 8000 #define MIN_TIME 8000
/*! Minimum amplitude of the signal */ /*! Minimum amplitude of the signal. */
#define MIN_AMPL 0.10 #define MIN_AMPL 0.10
/*! Minimum beep frequency */ /*! Minimum beep frequency. */
#define MIN_FREQ (600) #define MIN_FREQ (600)
/*! Maximum beep frequency */ /*! Maximum beep frequency. */
#define MAX_FREQ (1100) #define MAX_FREQ (1100)
/*! \brief \f$\psi{(x)}\f$ function for amplitude calculation /*! \brief Helper for amplitude calculation
* *
* \f$\psi{(x)} = {x^2_1} - {x_2} {x_0}\f$ * The function is defined as \f$\psi{(x)} = {x^2_1} - {x_2} {x_0}\f$
*
* @author Eric des Courtis
* @param x An array of 3 or more samples.
* @return The value of \f$\psi{(x)}\f$.
*/ */
#define PSI(x) (x[1]*x[1]-x[2]*x[0]) #define PSI(x) (x[1]*x[1]-x[2]*x[0])
/*! Sample rate NOTE: this should be dynamic in the future */ /*! Sample rate NOTE: this should be dynamic in the future. */
#define F (8000) #define F (8000)
/*! \brief Conversion of frequency to Hz /*! \brief Conversion of frequency to Hz
@ -86,7 +90,7 @@
*/ */
#define TO_HZ(f) ((F * f) / (2.0 * M_PI)) #define TO_HZ(f) ((F * f) / (2.0 * M_PI))
/* Number of points in discreet energy separation */ /* Number of points in discreet energy separation. */
#define P (5) #define P (5)
/* Maximum signed value of int16_t /* Maximum signed value of int16_t
@ -96,22 +100,22 @@
* DEPRECATED */ * DEPRECATED */
#define ADJUST_MAX (65536) #define ADJUST_MAX (65536)
/*! Discreet energy separation tolerance to error */ /*! Discreet energy separation tolerance to error. */
#define TOLERANCE (0.20) #define TOLERANCE (0.20)
/*! Maximum value within tolerance */ /*! Maximum value within tolerance. */
#define TOLERANCE_T(m) (m + (m * TOLERANCE)) #define TOLERANCE_T(m) (m + (m * TOLERANCE))
/*! Minimum value within tolerance */ /*! Minimum value within tolerance. */
#define TOLERANCE_B(m) (m - (m * TOLERANCE)) #define TOLERANCE_B(m) (m - (m * TOLERANCE))
/*! Syntax of the API call */ /*! Syntax of the API call. */
#define VMD_SYNTAX "<uuid> <command>" #define VMD_SYNTAX "<uuid> <command>"
/*! Number of expected parameters in api call */ /*! Number of expected parameters in api call. */
#define VMD_PARAMS 2 #define VMD_PARAMS 2
/*! FreeSWITCH CUSTOM event type */ /*! FreeSWITCH CUSTOM event type. */
#define VMD_EVENT_BEEP "vmd::beep" #define VMD_EVENT_BEEP "vmd::beep"
/* Prototypes */ /* Prototypes */
@ -122,7 +126,7 @@ SWITCH_MODULE_LOAD_FUNCTION(mod_vmd_load);
SWITCH_MODULE_DEFINITION(mod_vmd, mod_vmd_load, NULL, NULL); SWITCH_MODULE_DEFINITION(mod_vmd, mod_vmd_load, NULL, NULL);
SWITCH_STANDARD_APP(vmd_start_function); SWITCH_STANDARD_APP(vmd_start_function);
/*! Type that holds state information about the beep */ /*! Type that holds state information about the beep. */
typedef enum vmd_state { typedef enum vmd_state {
BEEP_DETECTED, BEEP_NOT_DETECTED BEEP_DETECTED, BEEP_NOT_DETECTED
} vmd_state_t; } vmd_state_t;
@ -133,28 +137,30 @@ typedef struct vmd_point {
double ampl; double ampl;
} vmd_point_t; } vmd_point_t;
/*! Type that holds codec information */ /*! Type that holds codec information. */
typedef struct vmd_codec_info { typedef struct vmd_codec_info {
/*! The sampling rate of the audio stream. */
int rate; int rate;
/*! The number of channels. */
int channels; int channels;
} vmd_codec_info_t; } vmd_codec_info_t;
/*! Type that holds session information pertinent to the vmd module */ /*! Type that holds session information pertinent to the vmd module. */
typedef struct vmd_session_info { typedef struct vmd_session_info {
/*! State of the session */ /*! State of the session. */
vmd_state_t state; vmd_state_t state;
/*! Snapshot of DESA samples */ /*! Snapshot of DESA samples. */
vmd_point_t points[POINTS]; vmd_point_t points[POINTS];
/*! Internal FreeSWITCH session */ /*! Internal FreeSWITCH session. */
switch_core_session_t *session; switch_core_session_t *session;
/*! Codec information for the session */ /*! Codec information for the session. */
vmd_codec_info_t vmd_codec; vmd_codec_info_t vmd_codec;
/*! Current position in the snapshot */ /*! Current position in the snapshot. */
unsigned int pos; unsigned int pos;
/*! Frequency aproximation of a detected beep */ /*! Frequency aproximation of a detected beep. */
double beep_freq; double beep_freq;
/*! A count of how long a distinct beep was detected by /*! A count of how long a distinct beep was detected
* by the discreet energy separation algorithm */ * by the discreet energy separation algorithm. */
switch_size_t timestamp; switch_size_t timestamp;
} vmd_session_info_t; } vmd_session_info_t;
@ -171,6 +177,14 @@ static double median(double *m, int n);
#define PRINT2(a, b) do{ switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_WARNING, a, b); }while(0) #define PRINT2(a, b) do{ switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_WARNING, a, b); }while(0)
*/ */
/*! \brief The callback function that is called when new audio data becomes available
*
* @author Eric des Courtis
* @param bug A reference to the media bug.
* @param user_data The session information for this call.
* @param type The switch callback type.
* @return The success or failure of the function.
*/
static switch_bool_t vmd_callback(switch_media_bug_t * bug, void *user_data, switch_abc_type_t type) static switch_bool_t vmd_callback(switch_media_bug_t * bug, void *user_data, switch_abc_type_t type)
{ {
vmd_session_info_t *vmd_info; vmd_session_info_t *vmd_info;
@ -207,7 +221,13 @@ static switch_bool_t vmd_callback(switch_media_bug_t * bug, void *user_data, swi
return SWITCH_TRUE; return SWITCH_TRUE;
} }
/*! Process and convert data to be used by the find_beep() function */ /*! \brief Process and convert data to be used by the find_beep() function
*
* @author Eric des Courtis
* @param vmd_info The session information associated with the call.
* @param frame The audio data.
* @return The success or failure of the function.
*/
static switch_bool_t process_data(vmd_session_info_t * vmd_info, switch_frame_t * frame) static switch_bool_t process_data(vmd_session_info_t * vmd_info, switch_frame_t * frame)
{ {
uint32_t i; uint32_t i;
@ -259,7 +279,13 @@ static switch_bool_t process_data(vmd_session_info_t * vmd_info, switch_frame_t
return SWITCH_TRUE; return SWITCH_TRUE;
} }
/*! Find voicemail beep in the audio stream */ /*! \brief Find voicemail beep in the audio stream
*
* @author Eric des Courtis
* @param vmd_info The session information associated with the call.
* @param frame The audio data.
* @return The success or failure of the function.
*/
static void find_beep(vmd_session_info_t * vmd_info, switch_frame_t * frame) static void find_beep(vmd_session_info_t * vmd_info, switch_frame_t * frame)
{ {
int i; int i;
@ -354,7 +380,12 @@ static void find_beep(vmd_session_info_t * vmd_info, switch_frame_t * frame)
} }
} }
/*! Find the median of an array of doubles */ /*! \brief Find the median of an array of doubles
*
* @param m Array of frequency samples.
* @param n Number of samples in the array.
* @return The median.
*/
static double median(double *m, int n) static double median(double *m, int n)
{ {
int i; int i;
@ -418,7 +449,14 @@ static double median(double *m, int n)
return mingtguess; return mingtguess;
} }
/*! Convert many points for Signed L16 to relative floating point */ /*! \brief Convert many points for Signed L16 to relative floating point
*
* @author Eric des Courtis
* @param i_pts Array of P 16 bit integer audio samples.
* @param d_pts Array of P double floating point audio samples.
* @param max The maximum value in the entire audio frame.
* @return Nothing.
*/
static void convert_pts(int16_t * i_pts, double *d_pts, int16_t max) static void convert_pts(int16_t * i_pts, double *d_pts, int16_t max)
{ {
int i; int i;
@ -430,7 +468,11 @@ static void convert_pts(int16_t * i_pts, double *d_pts, int16_t max)
/*! \brief Amplitude estimator for DESA-2 /*! \brief Amplitude estimator for DESA-2
* *
* \f$A = \sqrt{\frac{\psi{(x)}}{\sin{\Omega^2}}}\f$ * The function is defined as \f$A = \sqrt{\frac{\psi{(x)}}{\sin{\Omega^2}}}\f$
*
* @author Eric des Courtis
* @param x An array of 5 evenly spaced audio samples \f$x_0, x_1, x_2, x_3, x_4\f$.
* @return The estimated amplitude.
*/ */
double ampl_estimator(double *x) double ampl_estimator(double *x)
{ {
@ -444,14 +486,15 @@ double ampl_estimator(double *x)
/*! \brief The DESA-2 algorithm /*! \brief The DESA-2 algorithm
* *
* \f$\frac{1}{2}\arccos{\frac{{{x^2_2} - * The function is defined as \f$f = \frac{1}{2}\arccos{\frac{{{x^2_2} -
* {x_0}{x_4}} - {{x^2_1} - * {x_0}{x_4}} - {{x^2_1} -
* {x_0}{x_2}} - {{x^2_3} - * {x_0}{x_2}} - {{x^2_3} -
* {x_2}{x_4}}} * {x_2}{x_4}}}
* {{2}({x^2_2} - {x_1}{x_3})}}\f$ * {{2}({x^2_2} - {x_1}{x_3})}}\f$
* *
* @param x an array for 5 evenly spaced audio samples \f$x_0, x_1, x_2, x_3, x_4\f$ * @author Eric des Courtis
* @return a frequency estimate * @param x An array for 5 evenly spaced audio samples \f$x_0, x_1, x_2, x_3, x_4\f$.
* @return A frequency estimate.
*/ */
double freq_estimator(double *x) double freq_estimator(double *x)
{ {
@ -463,9 +506,10 @@ double freq_estimator(double *x)
); );
} }
/*! FreeSWITCH module loading function /*! \brief FreeSWITCH module loading function
* *
* @return load success or failure * @author Eric des Courtis
* @return Load success or failure.
*/ */
SWITCH_MODULE_LOAD_FUNCTION(mod_vmd_load) SWITCH_MODULE_LOAD_FUNCTION(mod_vmd_load)
{ {
@ -484,9 +528,11 @@ SWITCH_MODULE_LOAD_FUNCTION(mod_vmd_load)
return SWITCH_STATUS_SUCCESS; return SWITCH_STATUS_SUCCESS;
} }
/*! FreeSWITCH application handler function /*! \brief FreeSWITCH application handler function.
* This handles calls made from applications such as LUA and the dialplan
* *
* @return success or failure * @author Eric des Courtis
* @return Success or failure of the function.
*/ */
SWITCH_STANDARD_APP(vmd_start_function) SWITCH_STANDARD_APP(vmd_start_function)
{ {
@ -544,7 +590,11 @@ SWITCH_STANDARD_APP(vmd_start_function)
} }
/*! Called when the system shuts down */ /*! \brief Called when the module shuts down
*
* @author Eric des Courtis
* @return The success or failure of the function.
*/
SWITCH_MODULE_SHUTDOWN_FUNCTION(mod_vmd_shutdown) SWITCH_MODULE_SHUTDOWN_FUNCTION(mod_vmd_shutdown)
{ {
switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_NOTICE, "Voicemail detection disabled\n"); switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_NOTICE, "Voicemail detection disabled\n");
@ -552,7 +602,13 @@ SWITCH_MODULE_SHUTDOWN_FUNCTION(mod_vmd_shutdown)
return SWITCH_STATUS_SUCCESS; return SWITCH_STATUS_SUCCESS;
} }
/*! FreeSWITCH API handler function */ /*! \brief FreeSWITCH API handler function.
* This function handles API calls such as the ones from mod_event_socket and in some cases
* scripts such as LUA scripts.
*
* @author Eric des Courtis
* @return The success or failure of the function.
*/
SWITCH_STANDARD_API(vmd_api_main) SWITCH_STANDARD_API(vmd_api_main)
{ {
switch_core_session_t *vmd_session; switch_core_session_t *vmd_session;