Updates to speech recognition API and dialplan utilities. Moved to using dialplan...
[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 #include <stdio.h>
27 #include <stdlib.h>
28 #include <unistd.h>
29 #include <string.h>
30
31 #include "asterisk.h"
32
33 ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
34
35 #include "asterisk/channel.h"
36 #include "asterisk/module.h"
37 #include "asterisk/lock.h"
38 #include "asterisk/linkedlists.h"
39 #include "asterisk/cli.h"
40 #include "asterisk/term.h"
41 #include "asterisk/options.h"
42 #include "asterisk/speech.h"
43
44 static char *tdesc = "Generic Speech Recognition API";
45
46 static AST_LIST_HEAD_STATIC(engines, ast_speech_engine);
47 static struct ast_speech_engine *default_engine = NULL;
48
49 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
50 static struct ast_speech_engine *find_engine(char *engine_name)
51 {
52         struct ast_speech_engine *engine = NULL;
53
54         /* If no name is specified -- use the default engine */
55         if (engine_name == NULL || strlen(engine_name) == 0) {
56                 return default_engine;
57         }
58
59         AST_LIST_LOCK(&engines);
60         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
61                 if (!strcasecmp(engine->name, engine_name)) {
62                         break;
63                 }
64         }
65         AST_LIST_TRAVERSE_SAFE_END
66         AST_LIST_UNLOCK(&engines);
67
68         return engine;
69 }
70
71 /*! \brief Activate a loaded (either local or global) grammar */
72 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
73 {
74         int res = 0;
75
76         if (speech->engine->activate != NULL) {
77                 res = speech->engine->activate(speech, grammar_name);
78         }
79
80         return res;
81 }
82
83 /*! \brief Deactivate a loaded grammar on a speech structure */
84 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
85 {
86         int res = 0;
87
88         if (speech->engine->deactivate != NULL) {
89                 res = speech->engine->deactivate(speech, grammar_name);
90         }
91
92         return res;
93 }
94
95 /*! \brief Load a local grammar on a speech structure */
96 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
97 {
98         int res = 0;
99
100         if (speech->engine->load != NULL) {
101                 res = speech->engine->load(speech, grammar_name, grammar);
102         }
103
104         return res;
105 }
106
107 /*! \brief Unload a local grammar from a speech structure */
108 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
109 {
110         int res = 0;
111
112         if (speech->engine->unload != NULL) {
113                 res = speech->engine->unload(speech, grammar_name);
114         }
115
116         return res;
117 }
118
119 /*! \brief Return the results of a recognition from the speech structure */
120 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
121 {
122         struct ast_speech_result *result = NULL;
123
124         if (speech->engine->get != NULL) {
125                 result = speech->engine->get(speech);
126         }
127
128         return result;
129 }
130
131 /*! \brief Free a list of results */
132 int ast_speech_results_free(struct ast_speech_result *result)
133 {
134         struct ast_speech_result *current_result = result, *prev_result = NULL;
135         int res = 0;
136
137         while (current_result != NULL) {
138                 prev_result = current_result;
139                 /* Deallocate what we can */
140                 if (current_result->text != NULL) {
141                         free(current_result->text);
142                         current_result->text = NULL;
143                 }
144                 if (current_result->grammar != NULL) {
145                         free(current_result->grammar);
146                         current_result->grammar = NULL;
147                 }
148                 /* Move on and then free ourselves */
149                 current_result = current_result->next;
150                 free(prev_result);
151                 prev_result = NULL;
152         }
153
154         return res;
155 }
156
157 /*! \brief Start speech recognition on a speech structure */
158 void ast_speech_start(struct ast_speech *speech)
159 {
160
161         /* Clear any flags that may affect things */
162         ast_clear_flag(speech, AST_SPEECH_SPOKE);
163
164         /* If results are on the structure, free them since we are starting again */
165         if (speech->results != NULL) {
166                 ast_speech_results_free(speech->results);
167                 speech->results = NULL;
168         }
169
170         /* If the engine needs to start stuff up, do it */
171         if (speech->engine->start != NULL) {
172                 speech->engine->start(speech);
173         }
174
175         return;
176 }
177
178 /*! \brief Write in signed linear audio to be recognized */
179 int ast_speech_write(struct ast_speech *speech, void *data, int len)
180 {
181         int res = 0;
182
183         /* Make sure the speech engine is ready to accept audio */
184         if (speech->state != AST_SPEECH_STATE_READY) {
185                 return -1;
186         }
187
188         if (speech->engine->write != NULL) {
189                 speech->engine->write(speech, data, len);
190         }
191
192         return res;
193 }
194
195 /*! \brief Create a new speech structure using the engine specified */
196 struct ast_speech *ast_speech_new(char *engine_name, int format)
197 {
198         struct ast_speech_engine *engine = NULL;
199         struct ast_speech *new_speech = NULL;
200
201         /* Try to find the speech recognition engine that was requested */
202         engine = find_engine(engine_name);
203         if (engine == NULL) {
204                 /* Invalid engine or no engine available */
205                 return NULL;
206         }
207
208         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
209         new_speech = ast_calloc(1, sizeof(*new_speech));
210         if (new_speech == NULL) {
211                 /* Ran out of memory while trying to allocate some for a speech structure */
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         /* We are not ready to accept audio yet */
225         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
226
227         /* Pass ourselves to the engine so they can set us up some more */
228         engine->new(new_speech);
229
230         return new_speech;
231 }
232
233 /*! \brief Destroy a speech structure */
234 int ast_speech_destroy(struct ast_speech *speech)
235 {
236         int res = 0;
237
238         /* Call our engine so we are destroyed properly */
239         speech->engine->destroy(speech);
240
241         /* Deinitialize the lock */
242         ast_mutex_destroy(&speech->lock);
243
244         /* If results exist on the speech structure, destroy them */
245         if (speech->results != NULL) {
246                 ast_speech_results_free(speech->results);
247                 speech->results = NULL;
248         }
249
250         /* If a processing sound is set - free the memory used by it */
251         if (speech->processing_sound != NULL) {
252                 free(speech->processing_sound);
253                 speech->processing_sound = NULL;
254         }
255
256         /* Aloha we are done */
257         free(speech);
258         speech = NULL;
259
260         return res;
261 }
262
263 /*! \brief Change state of a speech structure */
264 int ast_speech_change_state(struct ast_speech *speech, int state)
265 {
266         int res = 0;
267
268         switch (state) {
269         case AST_SPEECH_STATE_WAIT:
270                 /* The engine heard audio, so they spoke */
271                 ast_set_flag(speech, AST_SPEECH_SPOKE);
272         default:
273                 speech->state = state;
274                 break;
275         }
276
277         return res;
278 }
279
280 /*! \brief Register a speech recognition engine */
281 int ast_speech_register(struct ast_speech_engine *engine)
282 {
283         struct ast_speech_engine *existing_engine = NULL;
284         int res = 0;
285
286         existing_engine = find_engine(engine->name);
287         if (existing_engine != NULL) {
288                 /* Engine already loaded */
289                 return -1;
290         }
291
292         if (option_verbose > 1)
293                 ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
294
295         /* Add to the engine linked list and make default if needed */
296         AST_LIST_LOCK(&engines);
297         AST_LIST_INSERT_HEAD(&engines, engine, list);
298         if (default_engine == NULL) {
299                 default_engine = engine;
300                 if (option_verbose > 1)
301                         ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
302         }
303         AST_LIST_UNLOCK(&engines);
304
305         return res;
306 }
307
308 /*! \brief Unregister a speech recognition engine */
309 int ast_speech_unregister(char *engine_name)
310 {
311         struct ast_speech_engine *engine = NULL;
312         int res = -1;
313
314         if (engine_name == NULL) {
315                 return res;
316         }
317
318         AST_LIST_LOCK(&engines);
319         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
320                 if (!strcasecmp(engine->name, engine_name)) {
321                         /* We have our engine... removed it */
322                         AST_LIST_REMOVE_CURRENT(&engines, list);
323                         /* If this was the default engine, we need to pick a new one */
324                         if (default_engine == engine) {
325                                 default_engine = AST_LIST_FIRST(&engines);
326                         }
327                         if (option_verbose > 1)
328                                 ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
329                         /* All went well */
330                         res = 0;
331                         break;
332                 }
333         }
334         AST_LIST_TRAVERSE_SAFE_END
335         AST_LIST_UNLOCK(&engines);
336
337         return res;
338 }
339
340 int unload_module(void)
341 {
342         /* We can not be unloaded */
343         return -1;
344 }
345
346 int load_module(void)
347 {
348         int res = 0;
349
350         /* Initialize our list of engines */
351         AST_LIST_HEAD_INIT_NOLOCK(&engines);
352
353         return res;
354 }
355
356 int reload(void)
357 {
358         return 0;
359 }
360
361 const char *description(void)
362 {
363         return tdesc;
364 }
365
366 int usecount(void)
367 {
368         int res = 0;
369
370         return res;
371 }
372
373 const char *key()
374 {
375         return ASTERISK_GPL_KEY;
376 }