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>
33 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"
44 static char *tdesc = "Generic Speech Recognition API";
46 static AST_LIST_HEAD_STATIC(engines, ast_speech_engine);
47 static struct ast_speech_engine *default_engine = NULL;
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)
52 struct ast_speech_engine *engine = NULL;
54 /* If no name is specified -- use the default engine */
55 if (engine_name == NULL || strlen(engine_name) == 0) {
56 return default_engine;
59 AST_LIST_LOCK(&engines);
60 AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
61 if (!strcasecmp(engine->name, engine_name)) {
65 AST_LIST_TRAVERSE_SAFE_END
66 AST_LIST_UNLOCK(&engines);
71 /*! \brief Activate a loaded (either local or global) grammar */
72 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
76 if (speech->engine->activate != NULL) {
77 res = speech->engine->activate(speech, grammar_name);
83 /*! \brief Deactivate a loaded grammar on a speech structure */
84 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
88 if (speech->engine->deactivate != NULL) {
89 res = speech->engine->deactivate(speech, grammar_name);
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)
100 if (speech->engine->load != NULL) {
101 res = speech->engine->load(speech, grammar_name, grammar);
107 /*! \brief Unload a local grammar from a speech structure */
108 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
112 if (speech->engine->unload != NULL) {
113 res = speech->engine->unload(speech, grammar_name);
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)
122 struct ast_speech_result *result = NULL;
124 if (speech->engine->get != NULL) {
125 result = speech->engine->get(speech);
131 /*! \brief Free a list of results */
132 int ast_speech_results_free(struct ast_speech_result *result)
134 struct ast_speech_result *current_result = result, *prev_result = NULL;
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;
144 if (current_result->grammar != NULL) {
145 free(current_result->grammar);
146 current_result->grammar = NULL;
148 /* Move on and then free ourselves */
149 current_result = current_result->next;
157 /*! \brief Start speech recognition on a speech structure */
158 void ast_speech_start(struct ast_speech *speech)
161 /* Clear any flags that may affect things */
162 ast_clear_flag(speech, AST_SPEECH_SPOKE);
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 Create a new speech structure using the engine specified */
196 struct ast_speech *ast_speech_new(char *engine_name, int format)
198 struct ast_speech_engine *engine = NULL;
199 struct ast_speech *new_speech = NULL;
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 */
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 */
215 /* Initialize the lock */
216 ast_mutex_init(&new_speech->lock);
218 /* Make sure no results are present */
219 new_speech->results = NULL;
221 /* Copy over our engine pointer */
222 new_speech->engine = engine;
224 /* We are not ready to accept audio yet */
225 ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
227 /* Pass ourselves to the engine so they can set us up some more */
228 engine->new(new_speech);
233 /*! \brief Destroy a speech structure */
234 int ast_speech_destroy(struct ast_speech *speech)
238 /* Call our engine so we are destroyed properly */
239 speech->engine->destroy(speech);
241 /* Deinitialize the lock */
242 ast_mutex_destroy(&speech->lock);
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;
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;
256 /* Aloha we are done */
263 /*! \brief Change state of a speech structure */
264 int ast_speech_change_state(struct ast_speech *speech, int state)
269 case AST_SPEECH_STATE_WAIT:
270 /* The engine heard audio, so they spoke */
271 ast_set_flag(speech, AST_SPEECH_SPOKE);
273 speech->state = state;
280 /*! \brief Register a speech recognition engine */
281 int ast_speech_register(struct ast_speech_engine *engine)
283 struct ast_speech_engine *existing_engine = NULL;
286 existing_engine = find_engine(engine->name);
287 if (existing_engine != NULL) {
288 /* Engine already loaded */
292 if (option_verbose > 1)
293 ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
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);
303 AST_LIST_UNLOCK(&engines);
308 /*! \brief Unregister a speech recognition engine */
309 int ast_speech_unregister(char *engine_name)
311 struct ast_speech_engine *engine = NULL;
314 if (engine_name == NULL) {
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);
327 if (option_verbose > 1)
328 ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
334 AST_LIST_TRAVERSE_SAFE_END
335 AST_LIST_UNLOCK(&engines);
340 int unload_module(void)
342 /* We can not be unloaded */
346 int load_module(void)
350 /* Initialize our list of engines */
351 AST_LIST_HEAD_INIT_NOLOCK(&engines);
361 const char *description(void)
375 return ASTERISK_GPL_KEY;