libteletone_detect.h

Go to the documentation of this file.

/* 
 * libteletone
 * Copyright (C) 2005-2014, Anthony Minessale II <anthm@freeswitch.org>
 *
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is tone_detect.c - General telephony tone detection, and specific detection of DTMF.
 *
 *
 * The Initial Developer of the Original Code is
 * Stephen Underwood <steveu@coppice.org>
 * Portions created by the Initial Developer are Copyright (C)
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 * 
 * The the original interface designed by Steve Underwood was preserved to retain 
 *the optimizations when considering DTMF tones though the names were changed in the interest 
 * of namespace.
 *
 * Much less efficient expansion interface was added to allow for the detection of 
 * a single arbitrary tone combination which may also exceed 2 simultaneous tones.
 * (controlled by compile time constant TELETONE_MAX_TONES)
 *
 * Copyright (C) 2006 Anthony Minessale II <anthm@freeswitch.org>
 *
 *
 * libteletone_detect.c Tone Detection Code
 *
 *
 ********************************************************************************* 
 *
 * Derived from tone_detect.h - General telephony tone detection, and specific
 * detection of DTMF.
 *
 * Copyright (C) 2001  Steve Underwood <steveu@coppice.org>
 *
 * Despite my general liking of the GPL, I place this code in the
 * public domain for the benefit of all mankind - even the slimy
 * ones who might try to proprietize my work and use it to my
 * detriment.
 *
 *
 * Exception:
 * The author hereby grants the use of this source code under the 
 * following license if and only if the source code is distributed
 * as part of the OpenZAP or FreeTDM library.   Any use or distribution of this
 * source code outside the scope of the OpenZAP or FreeTDM library will nullify the
 * following license and reinact the MPL 1.1 as stated above.
 *
 * Copyright (c) 2007, Anthony Minessale II
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 * 
 * * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * 
 * * Neither the name of the original author; nor the names of any contributors
 * may be used to endorse or promote products derived from this software
 * without specific prior written permission.
 * 
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef LIBTELETONE_DETECT_H
#define LIBTELETONE_DETECT_H

#ifdef __cplusplus
extern "C" {
#endif
#include <libteletone.h>

        /*! \file libteletone_detect.h
          \brief Tone Detection Routines

          This module is responsible for tone detection specifics
        */

#ifndef FALSE
#define FALSE   0
#ifndef TRUE
#define TRUE    (!FALSE)
#endif
#endif

        /* Basic DTMF specs:
         *
         * Minimum tone on = 40ms
         * Minimum tone off = 50ms
         * Maximum digit rate = 10 per second
         * Normal twist <= 8dB accepted
         * Reverse twist <= 4dB accepted
         * S/N >= 15dB will detect OK
         * Attenuation <= 26dB will detect OK
         * Frequency tolerance +- 1.5% will detect, +-3.5% will reject
         */

#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

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


        /*! \brief A continer for the elements of a Goertzel Algorithm (The names are from his formula) */
        typedef struct {
                float v2;
                float v3;
                double fac;
        } teletone_goertzel_state_t;
        
        /*! \brief A container for a DTMF detection state.*/
        typedef struct {
                int hit1;
                int hit2;
                int hit3;
                int hit4;
                int dur;
                int zc;
                

                teletone_goertzel_state_t row_out[GRID_FACTOR];
                teletone_goertzel_state_t col_out[GRID_FACTOR];
                teletone_goertzel_state_t row_out2nd[GRID_FACTOR];
                teletone_goertzel_state_t col_out2nd[GRID_FACTOR];
                float energy;
                float lenergy;
        
                int current_sample;
                char digit;
                int current_digits;
                int detected_digits;
                int lost_digits;
                int digit_hits[16];
        } teletone_dtmf_detect_state_t;

        /*! \brief An abstraction to store the coefficient of a tone frequency */
        typedef struct {
                float fac;
        } teletone_detection_descriptor_t;

        /*! \brief 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.
        */
        typedef struct {
                int sample_rate;

                teletone_detection_descriptor_t tdd[TELETONE_MAX_TONES];
                teletone_goertzel_state_t gs[TELETONE_MAX_TONES];
                teletone_goertzel_state_t gs2[TELETONE_MAX_TONES];
                int tone_count;

                float energy;
                int current_sample;
        
                int min_samples;
                int total_samples;

                int positives;
                int negatives;
                int hits;

                int positive_factor;
                int negative_factor;
                int hit_factor;

        } teletone_multi_tone_t;


        /*! 
          \brief Initilize a multi-frequency tone detector
          \param mt the multi-frequency tone descriptor
          \param map a representation of the multi-frequency tone
        */
TELETONE_API(void) teletone_multi_tone_init(teletone_multi_tone_t *mt, teletone_tone_map_t *map);

        /*! 
          \brief Check a sample buffer for the presence of the mulit-frequency tone described by mt
          \param mt the multi-frequency tone descriptor
          \param sample_buffer an array aof 16 bit signed linear samples
          \param samples the number of samples present in sample_buffer
          \return true when the tone was detected or false when it is not
        */
TELETONE_API(int) teletone_multi_tone_detect (teletone_multi_tone_t *mt,
                                                                        int16_t sample_buffer[],
                                                                        int samples);

        /*! 
          \brief Initilize a DTMF detection state object
          \param dtmf_detect_state the DTMF detection state to initilize
          \param sample_rate the desired sample rate
        */
TELETONE_API(void) teletone_dtmf_detect_init (teletone_dtmf_detect_state_t *dtmf_detect_state, int sample_rate);

        /*! 
          \brief Check a sample buffer for the presence of DTMF digits
          \param dtmf_detect_state the detection state object to check
          \param sample_buffer an array aof 16 bit signed linear samples
          \param samples the number of samples present in sample_buffer
          \return true when DTMF was detected or false when it is not
        */
TELETONE_API(teletone_hit_type_t) teletone_dtmf_detect (teletone_dtmf_detect_state_t *dtmf_detect_state,
                                                          int16_t sample_buffer[],
                                                          int samples);
        /*! 
          \brief retrieve any collected digits into a string buffer
          \param dtmf_detect_state the detection state object to check
          \param buf the string buffer to write to
          \param max the maximum length of buf
          \return the number of characters written to buf
        */
TELETONE_API(int) teletone_dtmf_get (teletone_dtmf_detect_state_t *dtmf_detect_state, char *buf, unsigned int *dur);

        /*! 
          \brief Step through the Goertzel Algorithm for each sample in a buffer
          \param goertzel_state the goertzel state to step the samples through
          \param sample_buffer an array aof 16 bit signed linear samples
          \param samples the number of samples present in sample_buffer
        */
TELETONE_API(void) teletone_goertzel_update(teletone_goertzel_state_t *goertzel_state,
                                                                  int16_t sample_buffer[],
                                                                  int samples);



#ifdef __cplusplus
}
#endif

#endif

/* For Emacs:
 * Local Variables:
 * mode:c
 * indent-tabs-mode:t
 * tab-width:4
 * c-basic-offset:4
 * End:
 * For VIM:
 * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet:
 */