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 Lesser General Public License version 2.1, 00014 * as 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 Lesser General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU Lesser General Public 00022 * License 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.41 2008/06/13 14:46:52 steveu Exp $ 00026 */ 00027 00028 #if !defined(_SPANDSP_TONE_DETECT_H_) 00029 #define _SPANDSP_TONE_DETECT_H_ 00030 00031 /*! 00032 Goertzel filter descriptor. 00033 */ 00034 typedef struct 00035 { 00036 #if defined(SPANDSP_USE_FIXED_POINT) 00037 int16_t fac; 00038 #else 00039 float fac; 00040 #endif 00041 int samples; 00042 } goertzel_descriptor_t; 00043 00044 /*! 00045 Goertzel filter state descriptor. 00046 */ 00047 typedef struct 00048 { 00049 #if defined(SPANDSP_USE_FIXED_POINT) 00050 int16_t v2; 00051 int16_t v3; 00052 int16_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 void goertzel_reset(goertzel_state_t *s); 00082 00083 /*! \brief Update the state of a Goertzel transform. 00084 \param s The Goertzel context. 00085 \param amp The samples to be transformed. 00086 \param samples The number of samples. 00087 \return The number of samples unprocessed */ 00088 int goertzel_update(goertzel_state_t *s, 00089 const int16_t amp[], 00090 int samples); 00091 00092 /*! \brief Evaluate the final result of a Goertzel transform. 00093 \param s The Goertzel context. 00094 \return The result of the transform. The expected result for a pure sine wave 00095 signal of level x dBm0, at the very centre of the bin is: 00096 [Floating point] ((samples_per_goertzel_block*32768.0/1.4142)*10^((x - DBM0_MAX_SINE_POWER)/20.0))^2 00097 [Fixed point] ((samples_per_goertzel_block*256.0/1.4142)*10^((x - DBM0_MAX_SINE_POWER)/20.0))^2 */ 00098 #if defined(SPANDSP_USE_FIXED_POINT) 00099 int32_t goertzel_result(goertzel_state_t *s); 00100 #else 00101 float goertzel_result(goertzel_state_t *s); 00102 #endif 00103 00104 /*! \brief Update the state of a Goertzel transform. 00105 \param s The Goertzel context. 00106 \param amp The sample to be transformed. */ 00107 static __inline__ void goertzel_sample(goertzel_state_t *s, int16_t amp) 00108 { 00109 #if defined(SPANDSP_USE_FIXED_POINT) 00110 int16_t x; 00111 int16_t v1; 00112 #else 00113 float v1; 00114 #endif 00115 00116 v1 = s->v2; 00117 s->v2 = s->v3; 00118 #if defined(SPANDSP_USE_FIXED_POINT) 00119 x = (((int32_t) s->fac*s->v2) >> 14); 00120 /* Scale down the input signal to avoid overflows. 9 bits is enough to 00121 monitor the signals of interest with adequate dynamic range and 00122 resolution. In telephony we generally only start with 13 or 14 bits, 00123 anyway. */ 00124 s->v3 = x - v1 + (amp >> 7); 00125 #else 00126 s->v3 = s->fac*s->v2 - v1 + amp; 00127 #endif 00128 s->current_sample++; 00129 } 00130 /*- End of function --------------------------------------------------------*/ 00131 00132 /* Scale down the input signal to avoid overflows. 9 bits is enough to 00133 monitor the signals of interest with adequate dynamic range and 00134 resolution. In telephony we generally only start with 13 or 14 bits, 00135 anyway. This is sufficient for the longest Goertzel we currently use. */ 00136 #if defined(SPANDSP_USE_FIXED_POINT) 00137 #define goertzel_preadjust_amp(amp) (((int16_t) amp) >> 7) 00138 #else 00139 #define goertzel_preadjust_amp(amp) ((float) amp) 00140 #endif 00141 00142 /* Minimal update the state of a Goertzel transform. This is similar to 00143 goertzel_sample, but more suited to blocks of Goertzels. It assumes 00144 the amplitude is pre-shifted, and does not update the per-state sample 00145 count. 00146 \brief Update the state of a Goertzel transform. 00147 \param s The Goertzel context. 00148 \param amp The adjusted sample to be transformed. */ 00149 #if defined(SPANDSP_USE_FIXED_POINT) 00150 static __inline__ void goertzel_samplex(goertzel_state_t *s, int16_t amp) 00151 #else 00152 static __inline__ void goertzel_samplex(goertzel_state_t *s, float amp) 00153 #endif 00154 { 00155 #if defined(SPANDSP_USE_FIXED_POINT) 00156 int16_t x; 00157 int16_t v1; 00158 #else 00159 float v1; 00160 #endif 00161 00162 v1 = s->v2; 00163 s->v2 = s->v3; 00164 #if defined(SPANDSP_USE_FIXED_POINT) 00165 x = (((int32_t) s->fac*s->v2) >> 14); 00166 s->v3 = x - v1 + amp; 00167 #else 00168 s->v3 = s->fac*s->v2 - v1 + amp; 00169 #endif 00170 } 00171 /*- End of function --------------------------------------------------------*/ 00172 00173 /*! Generate a Hamming weighted coefficient set, to be used for a periodogram analysis. 00174 \param coeffs The generated coefficients. 00175 \param freq The frequency to be matched by the periodogram, in Hz. 00176 \param sample_rate The sample rate of the signal, in samples per second. 00177 \param window_len The length of the periodogram window. This must be an even number. 00178 \return The number of generated coefficients. 00179 */ 00180 int periodogram_generate_coeffs(complexf_t coeffs[], float freq, int sample_rate, int window_len); 00181 00182 /*! Generate the phase offset to be expected between successive periodograms evaluated at the 00183 specified interval. 00184 \param offset A point to the generated phase offset. 00185 \param freq The frequency being matched by the periodogram, in Hz. 00186 \param sample_rate The sample rate of the signal, in samples per second. 00187 \param interval The interval between periodograms, in samples. 00188 \return The scaling factor. 00189 */ 00190 float periodogram_generate_phase_offset(complexf_t *offset, float freq, int sample_rate, int interval); 00191 00192 /*! Evaluate a periodogram. 00193 \param coeffs A set of coefficients generated by periodogram_generate_coeffs(). 00194 \param amp The complex amplitude of the signal. 00195 \param len The length of the periodogram, in samples. This must be an even number. 00196 \return The periodogram result. 00197 */ 00198 complexf_t periodogram(const complexf_t coeffs[], const complexf_t amp[], int len); 00199 00200 /*! Prepare data for evaluating a set of periodograms. 00201 \param sum A vector of sums of pairs of signal samples. This will be half the length of len. 00202 \param diff A vector of differences between pairs of signal samples. This will be half the length of len. 00203 \param amp The complex amplitude of the signal. 00204 \param len The length of the periodogram, in samples. This must be an even number. 00205 \return The length of the vectors sum and diff. 00206 */ 00207 int periodogram_prepare(complexf_t sum[], complexf_t diff[], const complexf_t amp[], int len); 00208 00209 /*! Evaluate a periodogram, based on data prepared by periodogram_prepare(). This is more efficient 00210 than using periodogram() when several periodograms are to be applied to the same signal. 00211 \param coeffs A set of coefficients generated by periodogram_generate_coeffs(). 00212 \param sum A vector of sums produced by periodogram_prepare(). 00213 \param diff A vector of differences produced by periodogram_prepare(). 00214 \param len The length of the periodogram, in samples. This must be an even number. 00215 \return The periodogram result. 00216 */ 00217 complexf_t periodogram_apply(const complexf_t coeffs[], const complexf_t sum[], const complexf_t diff[], int len); 00218 00219 /*! Apply a phase offset, to find the frequency error between periodogram evaluations. 00220 specified interval. 00221 \param phase_offset A point to the expected phase offset. 00222 \param scale The scaling factor to be used. 00223 \param last_result A pointer to the previous periodogram result. 00224 \param result A pointer to the current periodogram result. 00225 \return The frequency error, in Hz. 00226 */ 00227 float periodogram_freq_error(const complexf_t *phase_offset, float scale, const complexf_t *last_result, const complexf_t *result); 00228 00229 #if defined(__cplusplus) 00230 } 00231 #endif 00232 00233 #endif 00234 /*- End of file ------------------------------------------------------------*/