2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2006, Digium, Inc.
6 * Joshua Colp <jcolp@digium.com>
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.
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.
21 * \brief Generic Speech Recognition API
23 * \author Joshua Colp <jcolp@digium.com>
28 ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
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"
45 static AST_LIST_HEAD_STATIC(engines, ast_speech_engine);
46 static struct ast_speech_engine *default_engine = NULL;
48 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
49 static struct ast_speech_engine *find_engine(char *engine_name)
51 struct ast_speech_engine *engine = NULL;
53 /* If no name is specified -- use the default engine */
54 if (engine_name == NULL || strlen(engine_name) == 0) {
55 return default_engine;
58 AST_LIST_LOCK(&engines);
59 AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
60 if (!strcasecmp(engine->name, engine_name)) {
64 AST_LIST_TRAVERSE_SAFE_END
65 AST_LIST_UNLOCK(&engines);
70 /*! \brief Activate a loaded (either local or global) grammar */
71 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
75 if (speech->engine->activate != NULL) {
76 res = speech->engine->activate(speech, grammar_name);
82 /*! \brief Deactivate a loaded grammar on a speech structure */
83 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
87 if (speech->engine->deactivate != NULL) {
88 res = speech->engine->deactivate(speech, grammar_name);
94 /*! \brief Load a local grammar on a speech structure */
95 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
99 if (speech->engine->load != NULL) {
100 res = speech->engine->load(speech, grammar_name, grammar);
106 /*! \brief Unload a local grammar from a speech structure */
107 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
111 if (speech->engine->unload != NULL) {
112 res = speech->engine->unload(speech, grammar_name);
118 /*! \brief Return the results of a recognition from the speech structure */
119 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
121 struct ast_speech_result *result = NULL;
123 if (speech->engine->get != NULL) {
124 result = speech->engine->get(speech);
130 /*! \brief Free a list of results */
131 int ast_speech_results_free(struct ast_speech_result *result)
133 struct ast_speech_result *current_result = result, *prev_result = NULL;
136 while (current_result != NULL) {
137 prev_result = current_result;
138 /* Deallocate what we can */
139 if (current_result->text != NULL) {
140 free(current_result->text);
141 current_result->text = NULL;
143 if (current_result->grammar != NULL) {
144 free(current_result->grammar);
145 current_result->grammar = NULL;
147 /* Move on and then free ourselves */
148 current_result = current_result->next;
156 /*! \brief Start speech recognition on a speech structure */
157 void ast_speech_start(struct ast_speech *speech)
160 /* Clear any flags that may affect things */
161 ast_clear_flag(speech, AST_SPEECH_SPOKE);
162 ast_clear_flag(speech, AST_SPEECH_QUIET);
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;
170 /* If the engine needs to start stuff up, do it */
171 if (speech->engine->start != NULL) {
172 speech->engine->start(speech);
178 /*! \brief Write in signed linear audio to be recognized */
179 int ast_speech_write(struct ast_speech *speech, void *data, int len)
183 /* Make sure the speech engine is ready to accept audio */
184 if (speech->state != AST_SPEECH_STATE_READY) {
188 if (speech->engine->write != NULL) {
189 speech->engine->write(speech, data, len);
195 /*! \brief Change an engine specific attribute */
196 int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
200 if (speech->engine->change != NULL) {
201 res = speech->engine->change(speech, name, value);
207 /*! \brief Create a new speech structure using the engine specified */
208 struct ast_speech *ast_speech_new(char *engine_name, int format)
210 struct ast_speech_engine *engine = NULL;
211 struct ast_speech *new_speech = NULL;
213 /* Try to find the speech recognition engine that was requested */
214 engine = find_engine(engine_name);
215 if (engine == NULL) {
216 /* Invalid engine or no engine available */
220 /* Allocate our own speech structure, and try to allocate a structure from the engine too */
221 new_speech = ast_calloc(1, sizeof(*new_speech));
222 if (new_speech == NULL) {
223 /* Ran out of memory while trying to allocate some for a speech structure */
227 /* Initialize the lock */
228 ast_mutex_init(&new_speech->lock);
230 /* Make sure no results are present */
231 new_speech->results = NULL;
233 /* Copy over our engine pointer */
234 new_speech->engine = engine;
236 /* We are not ready to accept audio yet */
237 ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
239 /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
240 if (engine->new(new_speech)) {
241 ast_mutex_destroy(&new_speech->lock);
249 /*! \brief Destroy a speech structure */
250 int ast_speech_destroy(struct ast_speech *speech)
254 /* Call our engine so we are destroyed properly */
255 speech->engine->destroy(speech);
257 /* Deinitialize the lock */
258 ast_mutex_destroy(&speech->lock);
260 /* If results exist on the speech structure, destroy them */
261 if (speech->results != NULL) {
262 ast_speech_results_free(speech->results);
263 speech->results = NULL;
266 /* If a processing sound is set - free the memory used by it */
267 if (speech->processing_sound != NULL) {
268 free(speech->processing_sound);
269 speech->processing_sound = NULL;
272 /* Aloha we are done */
279 /*! \brief Change state of a speech structure */
280 int ast_speech_change_state(struct ast_speech *speech, int state)
285 case AST_SPEECH_STATE_WAIT:
286 /* The engine heard audio, so they spoke */
287 ast_set_flag(speech, AST_SPEECH_SPOKE);
289 speech->state = state;
296 /*! \brief Register a speech recognition engine */
297 int ast_speech_register(struct ast_speech_engine *engine)
299 struct ast_speech_engine *existing_engine = NULL;
302 existing_engine = find_engine(engine->name);
303 if (existing_engine != NULL) {
304 /* Engine already loaded */
308 if (option_verbose > 1)
309 ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
311 /* Add to the engine linked list and make default if needed */
312 AST_LIST_LOCK(&engines);
313 AST_LIST_INSERT_HEAD(&engines, engine, list);
314 if (default_engine == NULL) {
315 default_engine = engine;
316 if (option_verbose > 1)
317 ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
319 AST_LIST_UNLOCK(&engines);
324 /*! \brief Unregister a speech recognition engine */
325 int ast_speech_unregister(char *engine_name)
327 struct ast_speech_engine *engine = NULL;
330 if (engine_name == NULL) {
334 AST_LIST_LOCK(&engines);
335 AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
336 if (!strcasecmp(engine->name, engine_name)) {
337 /* We have our engine... removed it */
338 AST_LIST_REMOVE_CURRENT(&engines, list);
339 /* If this was the default engine, we need to pick a new one */
340 if (default_engine == engine) {
341 default_engine = AST_LIST_FIRST(&engines);
343 if (option_verbose > 1)
344 ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
350 AST_LIST_TRAVERSE_SAFE_END
351 AST_LIST_UNLOCK(&engines);
356 static int unload_module(void)
358 /* We can not be unloaded */
362 static int load_module(void)
366 /* Initialize our list of engines */
367 AST_LIST_HEAD_INIT_NOLOCK(&engines);
372 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
374 .unload = unload_module,