media formats: re-architect handling of media for performance improvements
[asterisk/asterisk.git] / res / res_speech.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief Generic Speech Recognition API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 /*** MODULEINFO
27         <support_level>core</support_level>
28  ***/
29
30 #include "asterisk.h"
31
32 ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
33
34 #include "asterisk/channel.h"
35 #include "asterisk/module.h"
36 #include "asterisk/lock.h"
37 #include "asterisk/linkedlists.h"
38 #include "asterisk/cli.h"
39 #include "asterisk/term.h"
40 #include "asterisk/speech.h"
41 #include "asterisk/format_cache.h"
42
43 static AST_RWLIST_HEAD_STATIC(engines, ast_speech_engine);
44 static struct ast_speech_engine *default_engine = NULL;
45
46 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
47 static struct ast_speech_engine *find_engine(const char *engine_name)
48 {
49         struct ast_speech_engine *engine = NULL;
50
51         /* If no name is specified -- use the default engine */
52         if (ast_strlen_zero(engine_name))
53                 return default_engine;
54
55         AST_RWLIST_RDLOCK(&engines);
56         AST_RWLIST_TRAVERSE(&engines, engine, list) {
57                 if (!strcasecmp(engine->name, engine_name)) {
58                         break;
59                 }
60         }
61         AST_RWLIST_UNLOCK(&engines);
62
63         return engine;
64 }
65
66 /*! \brief Activate a loaded (either local or global) grammar */
67 int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name)
68 {
69         return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
70 }
71
72 /*! \brief Deactivate a loaded grammar on a speech structure */
73 int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name)
74 {
75         return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
76 }
77
78 /*! \brief Load a local grammar on a speech structure */
79 int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar)
80 {
81         return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
82 }
83
84 /*! \brief Unload a local grammar from a speech structure */
85 int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name)
86 {
87         return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
88 }
89
90 /*! \brief Return the results of a recognition from the speech structure */
91 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
92 {
93         return (speech->engine->get ? speech->engine->get(speech) : NULL);
94 }
95
96 /*! \brief Free a list of results */
97 int ast_speech_results_free(struct ast_speech_result *result)
98 {
99         struct ast_speech_result *current_result = result, *prev_result = NULL;
100         int res = 0;
101
102         while (current_result != NULL) {
103                 prev_result = current_result;
104                 /* Deallocate what we can */
105                 if (current_result->text != NULL) {
106                         ast_free(current_result->text);
107                         current_result->text = NULL;
108                 }
109                 if (current_result->grammar != NULL) {
110                         ast_free(current_result->grammar);
111                         current_result->grammar = NULL;
112                 }
113                 /* Move on and then free ourselves */
114                 current_result = AST_LIST_NEXT(current_result, list);
115                 ast_free(prev_result);
116                 prev_result = NULL;
117         }
118
119         return res;
120 }
121
122 /*! \brief Start speech recognition on a speech structure */
123 void ast_speech_start(struct ast_speech *speech)
124 {
125
126         /* Clear any flags that may affect things */
127         ast_clear_flag(speech, AST_SPEECH_SPOKE);
128         ast_clear_flag(speech, AST_SPEECH_QUIET);
129         ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
130
131         /* If results are on the structure, free them since we are starting again */
132         if (speech->results) {
133                 ast_speech_results_free(speech->results);
134                 speech->results = NULL;
135         }
136
137         /* If the engine needs to start stuff up, do it */
138         if (speech->engine->start)
139                 speech->engine->start(speech);
140
141         return;
142 }
143
144 /*! \brief Write in signed linear audio to be recognized */
145 int ast_speech_write(struct ast_speech *speech, void *data, int len)
146 {
147         /* Make sure the speech engine is ready to accept audio */
148         if (speech->state != AST_SPEECH_STATE_READY)
149                 return -1;
150
151         return speech->engine->write(speech, data, len);
152 }
153
154 /*! \brief Signal to the engine that DTMF was received */
155 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
156 {
157         int res = 0;
158
159         if (speech->state != AST_SPEECH_STATE_READY)
160                 return -1;
161
162         if (speech->engine->dtmf != NULL) {
163                 res = speech->engine->dtmf(speech, dtmf);
164         }
165
166         return res;
167 }
168
169 /*! \brief Change an engine specific attribute */
170 int ast_speech_change(struct ast_speech *speech, const char *name, const char *value)
171 {
172         return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
173 }
174
175 /*! \brief Get an engine specific attribute */
176 int ast_speech_get_setting(struct ast_speech *speech, const char *name, char *buf, size_t len)
177 {
178         return (speech->engine->get_setting ? speech->engine->get_setting(speech, name, buf, len) : -1);
179 }
180
181 /*! \brief Create a new speech structure using the engine specified */
182 struct ast_speech *ast_speech_new(const char *engine_name, const struct ast_format_cap *cap)
183 {
184         struct ast_speech_engine *engine = NULL;
185         struct ast_speech *new_speech = NULL;
186         struct ast_format_cap *joint;
187         RAII_VAR(struct ast_format *, best, NULL, ao2_cleanup);
188
189         /* Try to find the speech recognition engine that was requested */
190         if (!(engine = find_engine(engine_name)))
191                 return NULL;
192
193         joint = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
194         if (!joint) {
195                 return NULL;
196         }
197
198         ast_format_cap_get_compatible(engine->formats, cap, joint);
199         best = ast_format_cap_get_format(joint, 0);
200         ao2_ref(joint, -1);
201
202         if (!best) {
203                 if (ast_format_cap_iscompatible_format(engine->formats, ast_format_slin) != AST_FORMAT_CMP_NOT_EQUAL) {
204                         best = ao2_bump(ast_format_slin);
205                 } else {
206                         return NULL;
207                 }
208         }
209
210         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
211         if (!(new_speech = ast_calloc(1, sizeof(*new_speech)))) {
212                 return NULL;
213         }
214
215         /* Initialize the lock */
216         ast_mutex_init(&new_speech->lock);
217
218         /* Make sure no results are present */
219         new_speech->results = NULL;
220
221         /* Copy over our engine pointer */
222         new_speech->engine = engine;
223
224         /* Can't forget the format audio is going to be in */
225         new_speech->format = best;
226
227         /* We are not ready to accept audio yet */
228         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
229
230         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
231         if (engine->create(new_speech, best)) {
232                 ast_mutex_destroy(&new_speech->lock);
233                 ast_free(new_speech);
234                 new_speech = NULL;
235         }
236
237         return new_speech;
238 }
239
240 /*! \brief Destroy a speech structure */
241 int ast_speech_destroy(struct ast_speech *speech)
242 {
243         int res = 0;
244
245         /* Call our engine so we are destroyed properly */
246         speech->engine->destroy(speech);
247
248         /* Deinitialize the lock */
249         ast_mutex_destroy(&speech->lock);
250
251         /* If results exist on the speech structure, destroy them */
252         if (speech->results)
253                 ast_speech_results_free(speech->results);
254
255         /* If a processing sound is set - free the memory used by it */
256         if (speech->processing_sound)
257                 ast_free(speech->processing_sound);
258
259         ao2_ref(speech->format, -1);
260
261         /* Aloha we are done */
262         ast_free(speech);
263
264         return res;
265 }
266
267 /*! \brief Change state of a speech structure */
268 int ast_speech_change_state(struct ast_speech *speech, int state)
269 {
270         int res = 0;
271
272         switch (state) {
273         case AST_SPEECH_STATE_WAIT:
274                 /* The engine heard audio, so they spoke */
275                 ast_set_flag(speech, AST_SPEECH_SPOKE);
276         default:
277                 speech->state = state;
278                 break;
279         }
280
281         return res;
282 }
283
284 /*! \brief Change the type of results we want */
285 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
286 {
287         speech->results_type = results_type;
288
289         return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
290 }
291
292 /*! \brief Register a speech recognition engine */
293 int ast_speech_register(struct ast_speech_engine *engine)
294 {
295         int res = 0;
296
297         /* Confirm the engine meets the minimum API requirements */
298         if (!engine->create || !engine->write || !engine->destroy) {
299                 ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
300                 return -1;
301         }
302
303         /* If an engine is already loaded with this name, error out */
304         if (find_engine(engine->name)) {
305                 ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
306                 return -1;
307         }
308
309         ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
310
311         /* Add to the engine linked list and make default if needed */
312         AST_RWLIST_WRLOCK(&engines);
313         AST_RWLIST_INSERT_HEAD(&engines, engine, list);
314         if (!default_engine) {
315                 default_engine = engine;
316                 ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
317         }
318         AST_RWLIST_UNLOCK(&engines);
319
320         return res;
321 }
322
323 /*! \brief Unregister a speech recognition engine */
324 int ast_speech_unregister(const char *engine_name)
325 {
326         struct ast_speech_engine *engine = NULL;
327         int res = -1;
328
329         if (ast_strlen_zero(engine_name))
330                 return -1;
331
332         AST_RWLIST_WRLOCK(&engines);
333         AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
334                 if (!strcasecmp(engine->name, engine_name)) {
335                         /* We have our engine... removed it */
336                         AST_RWLIST_REMOVE_CURRENT(list);
337                         /* If this was the default engine, we need to pick a new one */
338                         if (engine == default_engine) {
339                                 default_engine = AST_RWLIST_FIRST(&engines);
340                         }
341                         ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
342                         /* All went well */
343                         res = 0;
344                         break;
345                 }
346         }
347         AST_RWLIST_TRAVERSE_SAFE_END;
348         AST_RWLIST_UNLOCK(&engines);
349
350         return res;
351 }
352
353 static int unload_module(void)
354 {
355         /* We can not be unloaded */
356         return -1;
357 }
358
359 static int load_module(void)
360 {
361         return AST_MODULE_LOAD_SUCCESS;
362 }
363
364 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "Generic Speech Recognition API",
365                 .load = load_module,
366                 .unload = unload_module,
367                 .load_pri = AST_MODPRI_APP_DEPEND,
368                 );