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
);
163 ast_clear_flag(speech
, AST_SPEECH_HAVE_RESULTS
);
165 /* If results are on the structure, free them since we are starting again */
166 if (speech
->results
!= NULL
) {
167 ast_speech_results_free(speech
->results
);
168 speech
->results
= NULL
;
171 /* If the engine needs to start stuff up, do it */
172 if (speech
->engine
->start
!= NULL
) {
173 speech
->engine
->start(speech
);
179 /*! \brief Write in signed linear audio to be recognized */
180 int ast_speech_write(struct ast_speech
*speech
, void *data
, int len
)
184 /* Make sure the speech engine is ready to accept audio */
185 if (speech
->state
!= AST_SPEECH_STATE_READY
) {
189 if (speech
->engine
->write
!= NULL
) {
190 speech
->engine
->write(speech
, data
, len
);
196 /*! \brief Signal to the engine that DTMF was received */
197 int ast_speech_dtmf(struct ast_speech
*speech
, const char *dtmf
)
201 if (speech
->state
!= AST_SPEECH_STATE_READY
)
204 if (speech
->engine
->dtmf
!= NULL
) {
205 res
= speech
->engine
->dtmf(speech
, dtmf
);
211 /*! \brief Change an engine specific attribute */
212 int ast_speech_change(struct ast_speech
*speech
, char *name
, const char *value
)
216 if (speech
->engine
->change
!= NULL
) {
217 res
= speech
->engine
->change(speech
, name
, value
);
223 /*! \brief Create a new speech structure using the engine specified */
224 struct ast_speech
*ast_speech_new(char *engine_name
, int format
)
226 struct ast_speech_engine
*engine
= NULL
;
227 struct ast_speech
*new_speech
= NULL
;
229 /* Try to find the speech recognition engine that was requested */
230 engine
= find_engine(engine_name
);
231 if (engine
== NULL
) {
232 /* Invalid engine or no engine available */
236 /* Allocate our own speech structure, and try to allocate a structure from the engine too */
237 new_speech
= ast_calloc(1, sizeof(*new_speech
));
238 if (new_speech
== NULL
) {
239 /* Ran out of memory while trying to allocate some for a speech structure */
243 /* Initialize the lock */
244 ast_mutex_init(&new_speech
->lock
);
246 /* Make sure no results are present */
247 new_speech
->results
= NULL
;
249 /* Copy over our engine pointer */
250 new_speech
->engine
= engine
;
252 /* We are not ready to accept audio yet */
253 ast_speech_change_state(new_speech
, AST_SPEECH_STATE_NOT_READY
);
255 /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
256 if (engine
->create(new_speech
)) {
257 ast_mutex_destroy(&new_speech
->lock
);
265 /*! \brief Destroy a speech structure */
266 int ast_speech_destroy(struct ast_speech
*speech
)
270 /* Call our engine so we are destroyed properly */
271 speech
->engine
->destroy(speech
);
273 /* Deinitialize the lock */
274 ast_mutex_destroy(&speech
->lock
);
276 /* If results exist on the speech structure, destroy them */
277 if (speech
->results
!= NULL
) {
278 ast_speech_results_free(speech
->results
);
279 speech
->results
= NULL
;
282 /* If a processing sound is set - free the memory used by it */
283 if (speech
->processing_sound
!= NULL
) {
284 free(speech
->processing_sound
);
285 speech
->processing_sound
= NULL
;
288 /* Aloha we are done */
295 /*! \brief Change state of a speech structure */
296 int ast_speech_change_state(struct ast_speech
*speech
, int state
)
301 case AST_SPEECH_STATE_WAIT
:
302 /* The engine heard audio, so they spoke */
303 ast_set_flag(speech
, AST_SPEECH_SPOKE
);
305 speech
->state
= state
;
312 /*! \brief Change the type of results we want */
313 int ast_speech_change_results_type(struct ast_speech
*speech
, enum ast_speech_results_type results_type
)
317 speech
->results_type
= results_type
;
319 if (speech
->engine
->change_results_type
)
320 res
= speech
->engine
->change_results_type(speech
, results_type
);
325 /*! \brief Register a speech recognition engine */
326 int ast_speech_register(struct ast_speech_engine
*engine
)
328 struct ast_speech_engine
*existing_engine
= NULL
;
331 existing_engine
= find_engine(engine
->name
);
332 if (existing_engine
!= NULL
) {
333 /* Engine already loaded */
337 if (option_verbose
> 1)
338 ast_verbose(VERBOSE_PREFIX_2
"Registered speech recognition engine '%s'\n", engine
->name
);
340 /* Add to the engine linked list and make default if needed */
341 AST_LIST_LOCK(&engines
);
342 AST_LIST_INSERT_HEAD(&engines
, engine
, list
);
343 if (default_engine
== NULL
) {
344 default_engine
= engine
;
345 if (option_verbose
> 1)
346 ast_verbose(VERBOSE_PREFIX_2
"Made '%s' the default speech recognition engine\n", engine
->name
);
348 AST_LIST_UNLOCK(&engines
);
353 /*! \brief Unregister a speech recognition engine */
354 int ast_speech_unregister(char *engine_name
)
356 struct ast_speech_engine
*engine
= NULL
;
359 if (engine_name
== NULL
) {
363 AST_LIST_LOCK(&engines
);
364 AST_LIST_TRAVERSE_SAFE_BEGIN(&engines
, engine
, list
) {
365 if (!strcasecmp(engine
->name
, engine_name
)) {
366 /* We have our engine... removed it */
367 AST_LIST_REMOVE_CURRENT(&engines
, list
);
368 /* If this was the default engine, we need to pick a new one */
369 if (default_engine
== engine
) {
370 default_engine
= AST_LIST_FIRST(&engines
);
372 if (option_verbose
> 1)
373 ast_verbose(VERBOSE_PREFIX_2
"Unregistered speech recognition engine '%s'\n", engine_name
);
379 AST_LIST_TRAVERSE_SAFE_END
380 AST_LIST_UNLOCK(&engines
);
385 static int unload_module(void)
387 /* We can not be unloaded */
391 static int load_module(void)
395 /* Initialize our list of engines */
396 AST_LIST_HEAD_INIT_NOLOCK(&engines
);
401 AST_MODULE_INFO(ASTERISK_GPL_KEY
, AST_MODFLAG_GLOBAL_SYMBOLS
, "Generic Speech Recognition API",
403 .unload
= unload_module
,