tone_detect.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * tone_detect.h - General telephony tone detection.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2001, 2005 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License version 2, as
00014  * published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: tone_detect.h,v 1.36 2007/09/07 13:22:25 steveu Exp $
00026  */
00027 
00028 #if !defined(_SPANDSP_TONE_DETECT_H_)
00029 #define _SPANDSP_TONE_DETECT_H_
00030 
00031 /*!
00032     Floating point Goertzel filter descriptor.
00033 */
00034 typedef struct
00035 {
00036 #if defined(SPANDSP_USE_FIXED_POINT_EXPERIMENTAL)
00037     int32_t fac;
00038 #else
00039     float fac;
00040 #endif
00041     int samples;
00042 } goertzel_descriptor_t;
00043 
00044 /*!
00045     Floating point Goertzel filter state descriptor.
00046 */
00047 typedef struct
00048 {
00049 #if defined(SPANDSP_USE_FIXED_POINT_EXPERIMENTAL)
00050     int32_t v2;
00051     int32_t v3;
00052     int32_t fac;
00053 #else
00054     float v2;
00055     float v3;
00056     float fac;
00057 #endif
00058     int samples;
00059     int current_sample;
00060 } goertzel_state_t;
00061 
00062 #if defined(__cplusplus)
00063 extern "C"
00064 {
00065 #endif
00066 
00067 /*! \brief Create a descriptor for use with either a Goertzel transform */
00068 void make_goertzel_descriptor(goertzel_descriptor_t *t,
00069                               float freq,
00070                               int samples);
00071 
00072 /*! \brief Initialise the state of a Goertzel transform.
00073     \param s The Goertzel context. If NULL, a context is allocated with malloc.
00074     \param t The Goertzel descriptor.
00075     \return A pointer to the Goertzel state. */
00076 goertzel_state_t *goertzel_init(goertzel_state_t *s,
00077                                 goertzel_descriptor_t *t);
00078 
00079 /*! \brief Reset the state of a Goertzel transform.
00080     \param s The Goertzel context.
00081     \param t The Goertzel descriptor.
00082     \return A pointer to the Goertzel state. */
00083 void goertzel_reset(goertzel_state_t *s);
00084 
00085 /*! \brief Update the state of a Goertzel transform.
00086     \param s The Goertzel context.
00087     \param amp The samples to be transformed.
00088     \param samples The number of samples.
00089     \return The number of samples unprocessed */
00090 int goertzel_update(goertzel_state_t *s,
00091                     const int16_t amp[],
00092                     int samples);
00093 
00094 /*! \brief Evaluate the final result of a Goertzel transform.
00095     \param s The Goertzel context.
00096     \return The result of the transform. */
00097 float goertzel_result(goertzel_state_t *s);
00098 
00099 /*! \brief Update the state of a Goertzel transform.
00100     \param s The Goertzel context.
00101     \param amp The sample to be transformed. */
00102 static __inline__ void goertzel_sample(goertzel_state_t *s, int16_t amp)
00103 {
00104 #if defined(SPANDSP_USE_FIXED_POINT_EXPERIMENTAL)
00105     int32_t v1;
00106 #else
00107     float v1;
00108 #endif
00109 
00110     v1 = s->v2;
00111     s->v2 = s->v3;
00112     s->v3 = s->fac*s->v2 - v1 + amp;
00113     s->current_sample++;
00114 }
00115 /*- End of function --------------------------------------------------------*/
00116 
00117 /*! Generate a Hamming weighted coefficient set, to be used for a periodogram analysis.
00118     \param coeffs The generated coefficients.
00119     \param freq The frequency to be matched by the periodogram, in Hz.
00120     \param sample_rate The sample rate of the signal, in samples per second.
00121     \param window_len The length of the periodogram window. This must be an even number.
00122     \return The number of generated coefficients.
00123 */
00124 int periodogram_generate_coeffs(complexf_t coeffs[], float freq, int sample_rate, int window_len);
00125 
00126 /*! Generate the phase offset to be expected between successive periodograms evaluated at the 
00127     specified interval.
00128     \param offset A point to the generated phase offset.
00129     \param freq The frequency being matched by the periodogram, in Hz.
00130     \param sample_rate The sample rate of the signal, in samples per second.
00131     \param interval The interval between periodograms, in samples.
00132     \return The scaling factor.
00133 */
00134 float periodogram_generate_phase_offset(complexf_t *offset, float freq, int sample_rate, int interval);
00135 
00136 /*! Evaluate a periodogram.
00137     \param coeffs A set of coefficients generated by periodogram_generate_coeffs().
00138     \param amp The complex amplitude of the signal.
00139     \param len The length of the periodogram, in samples. This must be an even number.
00140     \return The periodogram result.
00141 */
00142 complexf_t periodogram(const complexf_t coeffs[], const complexf_t amp[], int len);
00143 
00144 /*! Prepare data for evaluating a set of periodograms.
00145     \param sum A vector of sums of pairs of signal samples. This will be half the length of len.
00146     \param diff A vector of differences between pairs of signal samples. This will be half the length of len.
00147     \param amp The complex amplitude of the signal.
00148     \param len The length of the periodogram, in samples. This must be an even number.
00149     \return The length of the vectors sum and diff.
00150 */
00151 int periodogram_prepare(complexf_t sum[], complexf_t diff[], const complexf_t amp[], int len);
00152 
00153 /*! Evaluate a periodogram, based on data prepared by periodogram_prepare(). This is more efficient
00154     than using periodogram() when several periodograms are to be applied to the same signal.
00155     \param coeffs A set of coefficients generated by periodogram_generate_coeffs().
00156     \param sum A vector of sums produced by periodogram_prepare().
00157     \param diff A vector of differences produced by periodogram_prepare().
00158     \param len The length of the periodogram, in samples. This must be an even number.
00159     \return The periodogram result.
00160 */
00161 complexf_t periodogram_apply(const complexf_t coeffs[], const complexf_t sum[], const complexf_t diff[], int len);
00162 
00163 /*! Apply a phase offset, to find the frequency error between periodogram evaluations.
00164     specified interval.
00165     \param offset A point to the expected phase offset.
00166     \param scale The scaling factor to be used.
00167     \param last_result A pointer to the previous periodogram result.
00168     \param result A pointer to the current periodogram result.
00169     \return The frequency error, in Hz.
00170 */
00171 float periodogram_freq_error(const complexf_t *phase_offset, float scale, const complexf_t *last_result, const complexf_t *result);
00172 
00173 #if defined(__cplusplus)
00174 }
00175 #endif
00176 
00177 #endif
00178 /*- End of file ------------------------------------------------------------*/

Generated on Sat Nov 3 00:38:56 2007 for libspandsp by  doxygen 1.5.2