1 /******************************************************************************\r
2 * FILE PURPOSE: Simple Voice Activity Detection (SVD) module\r
3 * \r
4 ******************************************************************************\r
5 * FILE NAME: svd.h \r
6 *\r
7 * DESCRIPTION: Implements a (very) simple Voice Activity Detector (VAD) based \r
8 * almost solely on the SNL module.\r
9 *\r
10 * Copyright (c) 2007 \96 2013 Texas Instruments Incorporated
11 *
12 * All rights reserved not granted herein.
13 *
14 * Limited License.
15 *
16 * Texas Instruments Incorporated grants a world-wide, royalty-free,
17 * non-exclusive license under copyrights and patents it now or hereafter owns
18 * or controls to make, have made, use, import, offer to sell and sell
19 * ("Utilize") this software subject to the terms herein. With respect to the
20 * foregoing patent license, such license is granted solely to the extent that
21 * any such patent is necessary to Utilize the software alone. The patent
22 * license shall not apply to any combinations which include this software,
23 * other than combinations with devices manufactured by or for TI (\93TI
24 * Devices\94). No hardware patent is licensed hereunder.
25 *
26 * Redistributions must preserve existing copyright notices and reproduce this
27 * license (including the above copyright notice and the disclaimer and (if
28 * applicable) source code license limitations below) in the documentation
29 * and/or other materials provided with the distribution
30 *
31 * Redistribution and use in binary form, without modification, are permitted
32 * provided that the following conditions are met:
33 *
34 * * No reverse engineering, decompilation, or disassembly of this software
35 * is permitted with respect to any software provided in binary form.
36 *
37 * * any redistribution and use are licensed by TI for use only with TI
38 * Devices.
39 *
40 * * Nothing shall obligate TI to provide you with source code for the
41 * software licensed and provided to you in object code.
42 *
43 * If software source code is provided to you, modification and redistribution
44 * of the source code are permitted provided that the following conditions are
45 * met:
46 *
47 * * any redistribution and use of the source code, including any resulting
48 * derivative works, are licensed by TI for use only with TI Devices.
49 *
50 * * any redistribution and use of any object code compiled from the source
51 * code and any resulting derivative works, are licensed by TI for use only
52 * with TI Devices.
53 *
54 * Neither the name of Texas Instruments Incorporated nor the names of its
55 * suppliers may be used to endorse or promote products derived from this
56 * software without specific prior written permission.
57 *
58 * DISCLAIMER.
59 *
60 * THIS SOFTWARE IS PROVIDED BY TI AND TI\92S LICENSORS "AS IS" AND ANY EXPRESS
61 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
62 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
63 * DISCLAIMED. IN NO EVENT SHALL TI AND TI\92S LICENSORS BE LIABLE FOR ANY
64 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
65 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
66 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
67 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
68 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
69 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
70 * DAMAGE. \r
71 *****************************************************************************/\r
72 #ifndef _SVD_H\r
73 #define _SVD_H\r
74 \r
75 /**\r
76 * @file svd.h\r
77 * @brief Contains external APIs for the SVD module.\r
78 *\r
79 */\r
80 \r
81 /** \r
82 * @defgroup SVD Simple Voice activity Detector (SVD)\r
83 *\r
84 * @brief The SVD module examines the signal and noise levels measured by SNL \r
85 * and makes a decision whether voice is active or not. \r
86 */\r
87 /** @ingroup SVD */\r
88 /* @{ */\r
89 \r
90 #include <ti/mas/types/types.h> /* DSP types */\r
91 \r
92 /** @defgroup svd_api_return_codes SVD API return codes\r
93 * These are the return codes for the SVD module API functions.\r
94 * \r
95 * @{\r
96 * @name SVD Function Return Value Definitions\r
97 *\r
98 */\r
99 /* @{ */\r
100 enum{\r
101 svd_NOERR = 0, /**< success, no error */\r
102 svd_ERR = 1, /**< failed */\r
103 svd_BADPARAM = 2 /**< Returned from function with wrong parameters */ \r
104 }; \r
105 /* @} */\r
106 /** @} */\r
107 \r
108 /**\r
109 * @name SVD decision codes\r
110 *\r
111 */\r
112 enum{\r
113 svd_VOICE_UNDEFINED = -1, /**< VAD decision undefined */\r
114 svd_VOICE_INACTIVE = 0, /**< VAD decision NO VOICE */\r
115 svd_VOICE_ACTIVE = 1 /**< VAD decision VOICE */\r
116 }; \r
117 \r
118 /**\r
119 * @name SVD sampling rate factor\r
120 * \remark These numbers are used as multipliers, so can't be changed to other values.\r
121 *\r
122 */\r
123 enum{\r
124 svd_SRATE_8K = 1, /**< sampling rate is 8kHz */\r
125 svd_SRATE_16K = 2 /**< sampling rate is 16kHz */\r
126 }; \r
127 \r
128 /**\r
129 * @def svd_ENV_Q\r
130 * The Fract Q format for the adaptive envelope threshold returned by\r
131 * svdGetLevels(). \r
132 */\r
133 #define svd_ENV_Q 3\r
134 \r
135 /**\r
136 * @def svd_PWR_Q\r
137 * The Fract Q format for the speech and noise power level returned by\r
138 * svdGetLevels(). \r
139 */\r
140 #define svd_PWR_Q 0\r
141 \r
142 /**\r
143 * @def svd_INVALID_POW_DB\r
144 * The initialization value for the signal and noise dB value. It's not a \r
145 * valid result for either signal or noise level estimation. \r
146 * @sa \r
147 */\r
148 #define svd_INVALID_POW_DB 0x7F\r
149 \r
150 /**\r
151 * @name External APIs for SVD\r
152 *\r
153 */\r
154 /* @{ */\r
155 /**\r
156 * @brief Obtain from SVD the instance memory requirements. \r
157 * \remark This must be the first function to be called before calling any other SVD APIs\r
158 * \r
159 * @param[out] instsize The size of the instance\r
160 *\r
161 * @return \link SVD::svd_NOERR svd_NOERR, \endlink \n\r
162 * \link SVD::svd_ERR svd_ERR \endlink: if instsize==NULL \r
163 */\r
164 tint svdGetSizes (tint *instsize);\r
165 \r
166 /**\r
167 * @brief Initialize simple voice activity detector\r
168 * \remark This function is called after svdGetSizes(), and initializes the instance. \r
169 *\r
170 * @param[in] *inst Pointer to the SVD instance memory, must NOT be NULL.\r
171 * @param[in] samp_rate \link SVD::svd_SRATE_8K svd_SRATE_8K \endlink \n\r
172 * \link SVD::svd_SRATE_16K svd_SRATE_16K \endlink \n \r
173 * @param[out] *inst Initialized SVD instance memory.\r
174 *\r
175 * @return \link SVD::svd_NOERR svd_NOERR, \endlink \n\r
176 * \link SVD::svd_ERR svd_ERR, \endlink :if inst==NULL \n \r
177 * \link SVD::svd_BADPARAM svd_BADPARAM \endlink :if samp_rate is not one of \r
178 * svd_SRATE_8K\r
179 * or svd_SRATE_16K\r
180 *\r
181 */\r
182 tint svdInit (void *inst, tint samp_rate);\r
183 \r
184 /**\r
185 * @brief Simple VAD detection process\r
186 * \remark This is the function that processes the signal and makes the Voice/Noise decision. The \r
187 * function should be called every frame. The frame size must be at least 1.5ms (12 for 8kHz, \r
188 * 24 for 16kHz).\r
189 *\r
190 * @param[in, out] *inst Pointer to the instance\r
191 * @param[in] *samples Pointer to samples\r
192 * @param[in] nSamps Number of samples, or frame size\r
193 *\r
194 * @return \link SVD::svd_NOERR svd_NOERR, \endlink \n\r
195 * \link SVD::svd_ERR svd_ERR, \endlink \n \r
196 */\r
197 tint svdProcess (void *inst, linSample *samples, tuint nSamps);\r
198 \r
199 /**\r
200 * @brief Get Voice decision\r
201 * \remark This is the function to call when a Voice/Noise decision is needed. It can be called \r
202 * as needed.\r
203 *\r
204 * @param[in] *inst Pointer to the instance\r
205 * @param[out] sig_pow Exponentially averaged signal power\r
206 * \r
207 * @return \link SVD::svd_VOICE_UNDEFINED svd_VOICE_UNDEFINED \endlink \n\r
208 * \link SVD::svd_VOICE_INACTIVE svd_VOICE_INACTIVE \endlink \n \r
209 * \link SVD::svd_VOICE_ACTIVE svd_VOICE_ACTIVE \endlink \n \r
210 */\r
211 tint svdGetDecision (void *inst, LFract *sig_pow);\r
212 \r
213 /**\r
214 * @brief Get speech and noise levels\r
215 * \remark This is the function to be called whenever the levels are needed. \r
216 * It can be called every frame or when requested.\r
217 *\r
218 * @param[in] *inst Pointer to the instance\r
219 * @param[out] *spchdB pointer to returned speech power level in Q0 dB\r
220 * @param[out] *noisedB pointer to returned noise power level in Q0 dB\r
221 * @param[out] *thresh pointer to returned adaptive threshold for envelope \r
222 * in Q\link SVD::svd_ENV_Q svd_ENV_Q \endlink linear amplitude.\r
223 * \r
224 * @return \link SVD::svd_NOERR svd_NOERR \endlink\r
225 */\r
226 tint svdGetLevels (void *inst, Fract *spchdB, Fract *noisedB, UFract *thresh);\r
227 \r
228 /* @} */\r
229 /* @} */ /* ingroup SVD */\r
230 #endif\r
231 \r
232 /* Nothing past this point */\r