[Freeswitch-svn] [commit] r10733 - freeswitch/trunk/src/mod/applications/mod_vmd
FreeSWITCH SVN
ericdc at freeswitch.org
Fri Dec 12 08:07:53 PST 2008
Author: ericdc
Date: Fri Dec 12 11:07:53 2008
New Revision: 10733
Log:
Added even more documentation. This should look good with doxygen.
Modified:
freeswitch/trunk/src/mod/applications/mod_vmd/mod_vmd.c
Modified: freeswitch/trunk/src/mod/applications/mod_vmd/mod_vmd.c
==============================================================================
--- freeswitch/trunk/src/mod/applications/mod_vmd/mod_vmd.c (original)
+++ freeswitch/trunk/src/mod/applications/mod_vmd/mod_vmd.c Fri Dec 12 11:07:53 2008
@@ -50,34 +50,38 @@
#define ISNAN(x) ((x)== NAN)
#endif
-/*! Number of points for beep detection */
+/*! Number of points for beep detection. */
#define POINTS 32
-/*! Number of valid points required for beep detection */
+/*! Number of valid points required for beep detection. */
#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
-/*! Minimum time for a beep */
+/*! Minimum time for a beep. */
#define MIN_TIME 8000
-/*! Minimum amplitude of the signal */
+/*! Minimum amplitude of the signal. */
#define MIN_AMPL 0.10
-/*! Minimum beep frequency */
+/*! Minimum beep frequency. */
#define MIN_FREQ (600)
-/*! Maximum beep frequency */
+/*! Maximum beep frequency. */
#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])
-/*! Sample rate NOTE: this should be dynamic in the future */
+/*! Sample rate NOTE: this should be dynamic in the future. */
#define F (8000)
/*! \brief Conversion of frequency to Hz
@@ -86,7 +90,7 @@
*/
#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)
/* Maximum signed value of int16_t
@@ -96,22 +100,22 @@
* DEPRECATED */
#define ADJUST_MAX (65536)
-/*! Discreet energy separation tolerance to error */
+/*! Discreet energy separation tolerance to error. */
#define TOLERANCE (0.20)
-/*! Maximum value within tolerance */
+/*! Maximum value within tolerance. */
#define TOLERANCE_T(m) (m + (m * TOLERANCE))
-/*! Minimum value within tolerance */
+/*! Minimum value within tolerance. */
#define TOLERANCE_B(m) (m - (m * TOLERANCE))
-/*! Syntax of the API call */
+/*! Syntax of the API call. */
#define VMD_SYNTAX "<uuid> <command>"
-/*! Number of expected parameters in api call */
+/*! Number of expected parameters in api call. */
#define VMD_PARAMS 2
-/*! FreeSWITCH CUSTOM event type */
+/*! FreeSWITCH CUSTOM event type. */
#define VMD_EVENT_BEEP "vmd::beep"
/* Prototypes */
@@ -122,7 +126,7 @@
SWITCH_MODULE_DEFINITION(mod_vmd, mod_vmd_load, NULL, NULL);
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 {
BEEP_DETECTED, BEEP_NOT_DETECTED
} vmd_state_t;
@@ -133,28 +137,30 @@
double ampl;
} vmd_point_t;
-/*! Type that holds codec information */
+/*! Type that holds codec information. */
typedef struct vmd_codec_info {
+ /*! The sampling rate of the audio stream. */
int rate;
+ /*! The number of channels. */
int channels;
} 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 {
- /*! State of the session */
+ /*! State of the session. */
vmd_state_t state;
- /*! Snapshot of DESA samples */
+ /*! Snapshot of DESA samples. */
vmd_point_t points[POINTS];
- /*! Internal FreeSWITCH session */
+ /*! Internal FreeSWITCH session. */
switch_core_session_t *session;
- /*! Codec information for the session */
+ /*! Codec information for the session. */
vmd_codec_info_t vmd_codec;
- /*! Current position in the snapshot */
+ /*! Current position in the snapshot. */
unsigned int pos;
- /*! Frequency aproximation of a detected beep */
+ /*! Frequency aproximation of a detected beep. */
double beep_freq;
- /*! A count of how long a distinct beep was detected by
- * by the discreet energy separation algorithm */
+ /*! A count of how long a distinct beep was detected
+ * by the discreet energy separation algorithm. */
switch_size_t timestamp;
} vmd_session_info_t;
@@ -171,6 +177,14 @@
#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)
{
vmd_session_info_t *vmd_info;
@@ -207,7 +221,13 @@
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)
{
uint32_t i;
@@ -259,7 +279,13 @@
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)
{
int i;
@@ -354,7 +380,12 @@
}
}
-/*! 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)
{
int i;
@@ -418,7 +449,14 @@
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)
{
int i;
@@ -430,7 +468,11 @@
/*! \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)
{
@@ -444,14 +486,15 @@
/*! \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_2}} - {{x^2_3} -
* {x_2}{x_4}}}
* {{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$
- * @return a frequency estimate
+ * @author Eric des Courtis
+ * @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)
{
@@ -463,9 +506,10 @@
);
}
-/*! 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)
{
@@ -484,9 +528,11 @@
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)
{
@@ -544,7 +590,11 @@
}
-/*! 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_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_NOTICE, "Voicemail detection disabled\n");
@@ -552,7 +602,13 @@
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_core_session_t *vmd_session;
More information about the Freeswitch-svn
mailing list