libteletone_detect.h File Reference

Tone Detection Routines. More...

#include <libteletone.h>

Include dependency graph for libteletone_detect.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	teletone_goertzel_state_t
	A continer for the elements of a Goertzel Algorithm (The names are from his formula) More...
struct	teletone_dtmf_detect_state_t
	A container for a DTMF detection state. More...
struct	teletone_detection_descriptor_t
	An abstraction to store the coefficient of a tone frequency. More...
struct	teletone_multi_tone_t
	A container for a single multi-tone detection TELETONE_MAX_TONES dictates the maximum simultaneous tones that can be present in a multi-tone representation. More...

Macros
#define	FALSE   0
#define	TRUE   (!FALSE)
#define	DTMF_THRESHOLD   8.0e7
#define	DTMF_NORMAL_TWIST   6.3 /* 8dB */
#define	DTMF_REVERSE_TWIST   2.5 /* 4dB */
#define	DTMF_RELATIVE_PEAK_ROW   6.3 /* 8dB */
#define	DTMF_RELATIVE_PEAK_COL   6.3 /* 8dB */
#define	DTMF_2ND_HARMONIC_ROW   2.5 /* 4dB */
#define	DTMF_2ND_HARMONIC_COL   63.1 /* 18dB */
#define	GRID_FACTOR   4
#define	BLOCK_LEN   102
#define	M_TWO_PI   2.0*M_PI

Enumerations
enum	teletone_hit_type_t { TT_HIT_NONE = 0, TT_HIT_BEGIN = 1, TT_HIT_MIDDLE = 2, TT_HIT_END = 3 }

Functions
void	teletone_multi_tone_init (teletone_multi_tone_t *mt, teletone_tone_map_t *map)
	Initilize a multi-frequency tone detector. More...
int	teletone_multi_tone_detect (teletone_multi_tone_t *mt, int16_t sample_buffer[], int samples)
	Check a sample buffer for the presence of the mulit-frequency tone described by mt. More...
void	teletone_dtmf_detect_init (teletone_dtmf_detect_state_t *dtmf_detect_state, int sample_rate)
	Initilize a DTMF detection state object. More...
teletone_hit_type_t	teletone_dtmf_detect (teletone_dtmf_detect_state_t *dtmf_detect_state, int16_t sample_buffer[], int samples)
	Check a sample buffer for the presence of DTMF digits. More...
int	teletone_dtmf_get (teletone_dtmf_detect_state_t *dtmf_detect_state, char *buf, unsigned int *dur)
	retrieve any collected digits into a string buffer More...
void	teletone_goertzel_update (teletone_goertzel_state_t *goertzel_state, int16_t sample_buffer[], int samples)
	Step through the Goertzel Algorithm for each sample in a buffer. More...

Detailed Description

Tone Detection Routines.

This module is responsible for tone detection specifics

Definition in file libteletone_detect.h.

Macro Definition Documentation

#define BLOCK_LEN   102

Definition at line 134 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_2ND_HARMONIC_COL   63.1 /* 18dB */

Definition at line 132 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_2ND_HARMONIC_ROW   2.5 /* 4dB */

Definition at line 131 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_NORMAL_TWIST   6.3 /* 8dB */

Definition at line 127 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_RELATIVE_PEAK_COL   6.3 /* 8dB */

Definition at line 130 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_RELATIVE_PEAK_ROW   6.3 /* 8dB */

Definition at line 129 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_REVERSE_TWIST   2.5 /* 4dB */

Definition at line 128 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define DTMF_THRESHOLD   8.0e7

Definition at line 126 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect().

#define FALSE   0

Definition at line 108 of file libteletone_detect.h.

#define GRID_FACTOR   4

Definition at line 133 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect(), and teletone_dtmf_detect_init().

#define M_TWO_PI   2.0*M_PI

Definition at line 135 of file libteletone_detect.h.

Referenced by teletone_dtmf_detect_init(), and teletone_multi_tone_init().

#define TRUE   (!FALSE)

Definition at line 110 of file libteletone_detect.h.

Enumeration Type Documentation

enum teletone_hit_type_t

Enumerator
TT_HIT_NONE
TT_HIT_BEGIN
TT_HIT_MIDDLE
TT_HIT_END

Definition at line 137 of file libteletone_detect.h.

                     {
                TT_HIT_NONE = 0,
                TT_HIT_BEGIN = 1,
                TT_HIT_MIDDLE = 2,
                TT_HIT_END = 3
        } teletone_hit_type_t;

Function Documentation

teletone_hit_type_t teletone_dtmf_detect	(	teletone_dtmf_detect_state_t *	dtmf_detect_state,
		int16_t	sample_buffer[],
		int	samples
	)

Check a sample buffer for the presence of DTMF digits.

Parameters

dtmf_detect_state	the detection state object to check
sample_buffer	an array aof 16 bit signed linear samples
samples	the number of samples present in sample_buffer

Returns

true when DTMF was detected or false when it is not

Definition at line 307 of file libteletone_detect.c.

References BLOCK_LEN, DTMF_2ND_HARMONIC_COL, DTMF_2ND_HARMONIC_ROW, DTMF_NORMAL_TWIST, dtmf_positions, DTMF_RELATIVE_PEAK_COL, DTMF_RELATIVE_PEAK_ROW, DTMF_REVERSE_TWIST, DTMF_THRESHOLD, goertzel_init(), GRID_FACTOR, LOW_ENG, teletone_goertzel_result, TELETONE_MAX_DTMF_DIGITS, TT_HIT_BEGIN, TT_HIT_END, TT_HIT_MIDDLE, and ZC.

Referenced by inband_dtmf_callback().

{
        float row_energy[GRID_FACTOR];
        float col_energy[GRID_FACTOR];
        float famp;
        float v1;
        int i;
        int j;
        int sample;
        int best_row;
        int best_col;
        char hit;
        int limit;
        teletone_hit_type_t r = 0;

        hit = 0;
        for (sample = 0;  sample < samples;      sample = limit) {
                /* BLOCK_LEN is optimised to meet the DTMF specs. */
                if ((samples - sample) >= (BLOCK_LEN - dtmf_detect_state->current_sample)) {
                        limit = sample + (BLOCK_LEN - dtmf_detect_state->current_sample);
                } else {
                        limit = samples;
                }

                for (j = sample;  j < limit;  j++) {
                        int x = 0;
                        famp = sample_buffer[j];
                        
                        dtmf_detect_state->energy += famp*famp;

                        for(x = 0; x < GRID_FACTOR; x++) {
                                v1 = dtmf_detect_state->row_out[x].v2;
                                dtmf_detect_state->row_out[x].v2 = dtmf_detect_state->row_out[x].v3;
                                dtmf_detect_state->row_out[x].v3 = (float)(dtmf_detect_state->row_out[x].fac*dtmf_detect_state->row_out[x].v2 - v1 + famp);
        
                                v1 = dtmf_detect_state->col_out[x].v2;
                                dtmf_detect_state->col_out[x].v2 = dtmf_detect_state->col_out[x].v3;
                                dtmf_detect_state->col_out[x].v3 = (float)(dtmf_detect_state->col_out[x].fac*dtmf_detect_state->col_out[x].v2 - v1 + famp);

                                v1 = dtmf_detect_state->col_out2nd[x].v2;
                                dtmf_detect_state->col_out2nd[x].v2 = dtmf_detect_state->col_out2nd[x].v3;
                                dtmf_detect_state->col_out2nd[x].v3 = (float)(dtmf_detect_state->col_out2nd[x].fac*dtmf_detect_state->col_out2nd[x].v2 - v1 + famp);
                
                                v1 = dtmf_detect_state->row_out2nd[x].v2;
                                dtmf_detect_state->row_out2nd[x].v2 = dtmf_detect_state->row_out2nd[x].v3;
                                dtmf_detect_state->row_out2nd[x].v3 = (float)(dtmf_detect_state->row_out2nd[x].fac*dtmf_detect_state->row_out2nd[x].v2 - v1 + famp);
                        }

                }

                if (dtmf_detect_state->zc > 0) {
                        if (dtmf_detect_state->energy < LOW_ENG && dtmf_detect_state->lenergy < LOW_ENG) {
                                if (!--dtmf_detect_state->zc) {
                                        /* Reinitialise the detector for the next block */
                                        dtmf_detect_state->hit1 = dtmf_detect_state->hit2 = 0;
                                        for (i = 0;      i < GRID_FACTOR;  i++) {
                                                goertzel_init (&dtmf_detect_state->row_out[i], &dtmf_detect_row[i]);
                                                goertzel_init (&dtmf_detect_state->col_out[i], &dtmf_detect_col[i]);
                                                goertzel_init (&dtmf_detect_state->row_out2nd[i], &dtmf_detect_row_2nd[i]);
                                                goertzel_init (&dtmf_detect_state->col_out2nd[i], &dtmf_detect_col_2nd[i]);
                                        }
                                        dtmf_detect_state->dur -= samples;
                                        return TT_HIT_END;
                                }
                        }
                        
                        dtmf_detect_state->dur += samples;
                        dtmf_detect_state->lenergy = dtmf_detect_state->energy;
                        dtmf_detect_state->energy = 0.0;
                        dtmf_detect_state->current_sample = 0;
                        return TT_HIT_MIDDLE;
                } else if (dtmf_detect_state->digit) {
                        return TT_HIT_END;
                }
                

                dtmf_detect_state->current_sample += (limit - sample);
                if (dtmf_detect_state->current_sample < BLOCK_LEN) {
                        continue;
                }
                /* We are at the end of a DTMF detection block */
                /* Find the peak row and the peak column */
                row_energy[0] = teletone_goertzel_result (&dtmf_detect_state->row_out[0]);
                col_energy[0] = teletone_goertzel_result (&dtmf_detect_state->col_out[0]);

                for (best_row = best_col = 0, i = 1;  i < GRID_FACTOR;  i++) {
                        row_energy[i] = teletone_goertzel_result (&dtmf_detect_state->row_out[i]);
                        if (row_energy[i] > row_energy[best_row]) {
                                best_row = i;
                        }
                        col_energy[i] = teletone_goertzel_result (&dtmf_detect_state->col_out[i]);
                        if (col_energy[i] > col_energy[best_col]) {
                                best_col = i;
                        }
                }
                hit = 0;
                /* Basic signal level test and the twist test */
                if (row_energy[best_row] >= DTMF_THRESHOLD &&
                        col_energy[best_col] >= DTMF_THRESHOLD &&
                        col_energy[best_col] < row_energy[best_row]*DTMF_REVERSE_TWIST &&
                        col_energy[best_col]*DTMF_NORMAL_TWIST > row_energy[best_row]) {
                        /* Relative peak test */
                        for (i = 0;      i < GRID_FACTOR;  i++) {
                                if ((i != best_col      &&      col_energy[i]*DTMF_RELATIVE_PEAK_COL > col_energy[best_col]) ||
                                        (i != best_row  &&      row_energy[i]*DTMF_RELATIVE_PEAK_ROW > row_energy[best_row])) {
                                        break;
                                }
                        }
                        /* ... and second harmonic test */
                        if (i >= GRID_FACTOR && (row_energy[best_row] + col_energy[best_col]) > 42.0*dtmf_detect_state->energy &&
                                teletone_goertzel_result (&dtmf_detect_state->col_out2nd[best_col])*DTMF_2ND_HARMONIC_COL < col_energy[best_col] &&
                                teletone_goertzel_result (&dtmf_detect_state->row_out2nd[best_row])*DTMF_2ND_HARMONIC_ROW < row_energy[best_row]) {
                                hit = dtmf_positions[(best_row << 2) + best_col];
                                /* Look for two successive similar results */
                                /* The logic in the next test is:
                                   We need two successive identical clean detects, with
                                   something different preceeding it. This can work with
                                   back to back differing digits. More importantly, it
                                   can work with nasty phones that give a very wobbly start
                                   to a digit. */
                                if (! r && hit == dtmf_detect_state->hit3 && dtmf_detect_state->hit3 != dtmf_detect_state->hit2) {
                                        dtmf_detect_state->digit_hits[(best_row << 2) + best_col]++;
                                        dtmf_detect_state->detected_digits++;
                                        if (dtmf_detect_state->current_digits < TELETONE_MAX_DTMF_DIGITS) {
                                                dtmf_detect_state->digit = hit;
                                        } else {
                                                dtmf_detect_state->lost_digits++;
                                        }
                                        
                                        if (!dtmf_detect_state->zc) {
                                                dtmf_detect_state->zc = ZC;
                                                dtmf_detect_state->dur = 0;
                                                r = TT_HIT_BEGIN;
                                                break;
                                        }                                       

                                }
                        }
                }

                dtmf_detect_state->hit1 = dtmf_detect_state->hit2;
                dtmf_detect_state->hit2 = dtmf_detect_state->hit3;
                dtmf_detect_state->hit3 = hit;

                dtmf_detect_state->energy = 0.0;
                dtmf_detect_state->current_sample = 0;
                
        }

        return r;
}

void teletone_dtmf_detect_init	(	teletone_dtmf_detect_state_t *	dtmf_detect_state,
		int	sample_rate
	)

Initilize a DTMF detection state object.

Parameters

dtmf_detect_state	the DTMF detection state to initilize
sample_rate	the desired sample rate

Definition at line 139 of file libteletone_detect.c.

References dtmf_col, dtmf_row, teletone_detection_descriptor_t::fac, goertzel_init(), GRID_FACTOR, and M_TWO_PI.

Referenced by switch_ivr_inband_dtmf_session().

{
        int i;
        float theta;

        if (!sample_rate) {
                sample_rate = 8000;
        }

        dtmf_detect_state->hit1 = dtmf_detect_state->hit2 = 0;

        for (i = 0;      i < GRID_FACTOR;  i++) {
                theta = (float)(M_TWO_PI*(dtmf_row[i]/(float)sample_rate));
                dtmf_detect_row[i].fac = (float)(2.0*cos(theta));

                theta = (float)(M_TWO_PI*(dtmf_col[i]/(float)sample_rate));
                dtmf_detect_col[i].fac = (float)(2.0*cos(theta));
        
                theta = (float)(M_TWO_PI*(dtmf_row[i]*2.0/(float)sample_rate));
                dtmf_detect_row_2nd[i].fac = (float)(2.0*cos(theta));

                theta = (float)(M_TWO_PI*(dtmf_col[i]*2.0/(float)sample_rate));
                dtmf_detect_col_2nd[i].fac = (float)(2.0*cos(theta));
        
                goertzel_init (&dtmf_detect_state->row_out[i], &dtmf_detect_row[i]);
                goertzel_init (&dtmf_detect_state->col_out[i], &dtmf_detect_col[i]);
                goertzel_init (&dtmf_detect_state->row_out2nd[i], &dtmf_detect_row_2nd[i]);
                goertzel_init (&dtmf_detect_state->col_out2nd[i], &dtmf_detect_col_2nd[i]);
        
                dtmf_detect_state->energy = 0.0;
        }
        dtmf_detect_state->current_sample = 0;
        dtmf_detect_state->detected_digits = 0;
        dtmf_detect_state->lost_digits = 0;
        dtmf_detect_state->digit = 0;
        dtmf_detect_state->dur = 0;
}

int teletone_dtmf_get	(	teletone_dtmf_detect_state_t *	dtmf_detect_state,
		char *	buf,
		unsigned int *	dur
	)

retrieve any collected digits into a string buffer

Parameters

dtmf_detect_state	the detection state object to check
buf	the string buffer to write to
max	the maximum length of buf

Returns

the number of characters written to buf

Definition at line 462 of file libteletone_detect.c.

Referenced by inband_dtmf_callback().

{
        if (!dtmf_detect_state->digit) {
                return 0;
        }

        *buf = dtmf_detect_state->digit;

        *dur = dtmf_detect_state->dur;

        if (!dtmf_detect_state->zc) {
                dtmf_detect_state->dur = 0;
                dtmf_detect_state->digit = 0;
        }
        
        return 1;
}

void teletone_goertzel_update	(	teletone_goertzel_state_t *	goertzel_state,
		int16_t	sample_buffer[],
		int	samples
	)

Step through the Goertzel Algorithm for each sample in a buffer.

Parameters

goertzel_state	the goertzel state to step the samples through
sample_buffer	an array aof 16 bit signed linear samples
samples	the number of samples present in sample_buffer

Definition at line 120 of file libteletone_detect.c.

{
        int i;
        float v1;
        
        for (i = 0;      i < samples;  i++) {
                v1 = goertzel_state->v2;
                goertzel_state->v2 = goertzel_state->v3;
                goertzel_state->v3 = (float)(goertzel_state->fac*goertzel_state->v2 - v1 + sample_buffer[i]);
        }
}

int teletone_multi_tone_detect	(	teletone_multi_tone_t *	mt,
		int16_t	sample_buffer[],
		int	samples
	)

Check a sample buffer for the presence of the mulit-frequency tone described by mt.

Parameters

mt	the multi-frequency tone descriptor
sample_buffer	an array aof 16 bit signed linear samples
samples	the number of samples present in sample_buffer

Returns

true when the tone was detected or false when it is not

Definition at line 217 of file libteletone_detect.c.

References goertzel_init(), teletone_goertzel_result, and TELETONE_MAX_TONES.

Referenced by tone_detect_callback().

{
        int sample, limit = 0, j, x = 0;
        float v1, famp;
        float eng_sum = 0, eng_all[TELETONE_MAX_TONES] = {0.0};
        int gtest = 0, see_hit = 0;

        for (sample = 0;  sample >= 0 && sample < samples; sample = limit) {
                mt->total_samples++;

                if ((samples - sample) >= (mt->min_samples - mt->current_sample)) {
                        limit = sample + (mt->min_samples - mt->current_sample);
                } else {
                        limit = samples;
                }
                if (limit < 0 || limit > samples) {
                        limit = samples;
                }

                for (j = sample;  j < limit;  j++) {
                        famp = sample_buffer[j];
                        
                        mt->energy += famp*famp;

                        for(x = 0; x < TELETONE_MAX_TONES && x < mt->tone_count; x++) {
                                v1 = mt->gs[x].v2;
                                mt->gs[x].v2 = mt->gs[x].v3;
                                mt->gs[x].v3 = (float)(mt->gs[x].fac * mt->gs[x].v2 - v1 + famp);
        
                                v1 = mt->gs2[x].v2;
                                mt->gs2[x].v2 = mt->gs2[x].v3;
                                mt->gs2[x].v3 = (float)(mt->gs2[x].fac*mt->gs2[x].v2 - v1 + famp);
                        }
                }

                mt->current_sample += (limit - sample);
                if (mt->current_sample < mt->min_samples) {
                        continue;
                }

                eng_sum = 0;
                for(x = 0; x < TELETONE_MAX_TONES && x < mt->tone_count; x++) {
                        eng_all[x] = (float)(teletone_goertzel_result (&mt->gs[x]));
                        eng_sum += eng_all[x];
                }

                gtest = 0;
                for(x = 0; x < TELETONE_MAX_TONES && x < mt->tone_count; x++) {
                        gtest += teletone_goertzel_result (&mt->gs2[x]) < eng_all[x] ? 1 : 0;
                }

                if ((gtest >= 2 || gtest == mt->tone_count) && eng_sum > 42.0 * mt->energy) {
                        if(mt->negatives) {
                                mt->negatives--;
                        }
                        mt->positives++;

                        if(mt->positives >= mt->positive_factor) {
                                mt->hits++;
                        }
                        if (mt->hits >= mt->hit_factor) {
                                see_hit++;
                                mt->positives = mt->negatives = mt->hits = 0;
                        }
                } else {
                        mt->negatives++;
                        if(mt->positives) {
                                mt->positives--;
                        }
                        if(mt->negatives > mt->negative_factor) {
                                mt->positives = mt->hits = 0;
                        }
                }

                /* Reinitialise the detector for the next block */
                for(x = 0; x < TELETONE_MAX_TONES && x < mt->tone_count; x++) {
                        goertzel_init (&mt->gs[x], &mt->tdd[x]);
                        goertzel_init (&mt->gs2[x], &mt->tdd[x]);
                }

                mt->energy = 0.0;
                mt->current_sample = 0;
        }

        return see_hit;
}

void teletone_multi_tone_init	(	teletone_multi_tone_t *	mt,
		teletone_tone_map_t *	map
	)

Initilize a multi-frequency tone detector.

Parameters

mt	the multi-frequency tone descriptor
map	a representation of the multi-frequency tone

Definition at line 177 of file libteletone_detect.c.

References goertzel_init(), M_TWO_PI, and TELETONE_MAX_TONES.

Referenced by switch_ivr_tone_detect_session().

{
        float theta = 0;
        int x = 0;

        if (!mt->sample_rate) {
                mt->sample_rate = 8000;
        }

        if (!mt->min_samples) {
                mt->min_samples = 102;
        }

        mt->min_samples *= (mt->sample_rate / 8000);

        if (!mt->positive_factor) {
                mt->positive_factor = 2;
        }

        if(!mt->negative_factor) {
                mt->negative_factor = 10;
        }

        if (!mt->hit_factor) {
                mt->hit_factor = 2;
        }

        for(x = 0; x < TELETONE_MAX_TONES; x++) {
                if ((int) map->freqs[x] == 0) {
                        break;
                }
                mt->tone_count++;
                theta = (float)(M_TWO_PI*(map->freqs[x]/(float)mt->sample_rate));
                mt->tdd[x].fac = (float)(2.0 * cos(theta));
                goertzel_init (&mt->gs[x], &mt->tdd[x]);
                goertzel_init (&mt->gs2[x], &mt->tdd[x]);
        }

}