d556cf183c94fef1c306f971b8d571bd0695c8fa
1 /******************************************************************************\r
2 * FILE PURPOSE: Speech and Noise level estimation\r
3 * \r
4 ******************************************************************************\r
5 * FILE NAME: snl.h \r
6 *\r
7 * DESCRIPTION: Implements active speech and noise level estimation for the purposes\r
8 * of voice doctor \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 _SNL_H\r
73 #define _SNL_H\r
74 \r
75 #include <ti/mas/types/types.h> /* DSP types */\r
76 \r
77 /**\r
78 * @file snl.h\r
79 * @brief Contains external APIs for the SNL module.\r
80 *\r
81 */\r
82 \r
83 /** \r
84 * @defgroup SNL Siganl and Noise Level estimator (SNL)\r
85 *\r
86 * @brief SNL estimates the speech and background noise level of the incoming \r
87 * voice signal.\r
88 *\r
89 */\r
90 /** @ingroup SNL */\r
91 /* @{ */\r
92 \r
93 /** @defgroup snl_api_return_codes SNL API return codes\r
94 * These are the return codes for the SNL module API functions.\r
95 * \r
96 * @{\r
97 * @name SNL Function Return Value Definitions\r
98 *\r
99 */\r
100 /* @{ */\r
101 enum {\r
102 snl_NOERR = 0, /**< success, no error */\r
103 snl_ERR = 1, /**< failed */\r
104 snl_BADPARAM = 2 /**< Returned from function with wrong parameters */ \r
105 }; \r
106 /* @} */\r
107 /** @} */\r
108 \r
109 /**\r
110 * @name SNL sampling rate factor\r
111 * \remark These numbers are used as multipliers, so can't be changed to other values.\r
112 *\r
113 */\r
114 enum {\r
115 snl_SRATE_FACTOR_8K = 1, /**< sampling rate is 8kHz */\r
116 snl_SRATE_FACTOR_16K = 2 /**< sampling rate is 16kHz */\r
117 }; \r
118 \r
119 /**\r
120 * @def snl_ENV_Q\r
121 * The Fract Q format for the adaptive envelope threshold returned by\r
122 * snlGetLevels(). \r
123 */\r
124 #define snl_ENV_Q 3\r
125 \r
126 /**\r
127 * @def snl_INVALID_POW_DB\r
128 * The initialization value for the signal and noise dB value. It's not a \r
129 * valid result for either signal or noise level estimation. \r
130 * @sa \r
131 */\r
132 #define snl_INVALID_POW_DB 0x7F\r
133 \r
134 /**\r
135 * @name External APIs for SNL\r
136 *\r
137 */\r
138 /* @{ */\r
139 /**\r
140 * @brief Obtain from SNL the memory requirements of an instance. \r
141 * \remark This must be the first function to be called before calling any other SNL APIs\r
142 * \r
143 *\r
144 * @param[out] instsize The size of the instance\r
145 *\r
146 * @return \link SNL::snl_NOERR snl_NOERR, \endlink \n\r
147 * \link SNL::snl_ERR snl_ERR \endlink: if instsize==NULL \r
148 */\r
149 tint snlGetSizes (tint *instsize);\r
150 \r
151 /**\r
152 * @brief Initialize signal level estimator\r
153 * \remark This is the function to call after calling snlGetSizes(), only samp_rate is user configurable.\r
154 * After this function call, both signal and noise level are initialized to \r
155 * \link SNL::snl_INVALID_POW_DB snl_INVALID_POW_DB,\endlink which is not considered\r
156 * a valid result from SNL\r
157 *\r
158 * @param[out] *inst Pointer to the SNL instance\r
159 * @param[in] samp_rate \link SNL::snl_SRATE_FACTOR_8K snl_SRATE_FACTOR_8K \endlink \n\r
160 * \link SNL::snl_SRATE_FACTOR_16K snl_SRATE_FACTOR_16K \endlink \n \r
161 *\r
162 * @return \link SNL::snl_NOERR snl_NOERR, \endlink \n\r
163 * \link SNL::snl_ERR snl_ERR, \endlink :if inst==NULL \n \r
164 * \link SNL::snl_BADPARAM snl_BADPARAM \endlink :if samp_rate is not one of snl_SRATE_FACTOR_8K\r
165 * and snl_SRATE_FACTOR_16K\r
166 *\r
167 */\r
168 tint snlInit (void *inst, tint samp_rate);\r
169 \r
170 /**\r
171 * @brief Signal and noise level estimator\r
172 * \remark This is the function that processes the signal and calculates various parameters needed for level\r
173 * estimation. This function needs to be called every frame. There is a limitation of 1.5ms for the \r
174 * frame size, which will equivalent to 12 for the nSamps parameter for 8kHz sampling rate and 24\r
175 * for the nSamps parameter for 16kHz sampling rate.\r
176 *\r
177 * @param[in, out] *inst Pointer to the instance\r
178 * @param[in] *samples Pointer to samples\r
179 * @param[in] nSamps Number of samples\r
180 *\r
181 * @return \link SNL::snl_NOERR snl_NOERR \endlink\r
182 */\r
183 tint snlProcess (void *inst, linSample *samples, tuint nSamps);\r
184 \r
185 /**\r
186 * @brief Get speech and noise levels\r
187 * \remark This is the function to be called whenever the levels are needed. It can be called every frame\r
188 * or when requested.\r
189 *\r
190 * @param[in] *inst Pointer to the instance\r
191 * @param[out] *spchdB pointer to returned speech power level in Q0 dB\r
192 * @param[out] *noisedB pointer to returned noise power level in Q0 dB\r
193 * @param[out] *thresh pointer to returned adaptive threshold for envelope \r
194 * in Q\link SNL::snl_ENV_Q snl_ENV_Q \endlink linear amplitude.\r
195 * \r
196 * @return \link SNL::snl_NOERR snl_NOERR \endlink\r
197 */\r
198 tint snlGetLevels (void *inst, Fract *spchdB, Fract *noisedB, UFract *thresh);\r
199 \r
200 /* @} */\r
201 /* @} */ /* ingroup SNL */\r
202 #endif\r
203 \r
204 /* Nothing past this point */\r