Tue Aug 20 16:35:14 2013

Asterisk developer's documentation


res_speech.c File Reference

Generic Speech Recognition API. More...

#include "asterisk.h"
#include "asterisk/channel.h"
#include "asterisk/module.h"
#include "asterisk/lock.h"
#include "asterisk/linkedlists.h"
#include "asterisk/cli.h"
#include "asterisk/term.h"
#include "asterisk/speech.h"

Go to the source code of this file.

Data Structures

struct  engines

Functions

static void __reg_module (void)
static void __unreg_module (void)
int ast_speech_change (struct ast_speech *speech, const char *name, const char *value)
 Change an engine specific attribute.
int ast_speech_change_results_type (struct ast_speech *speech, enum ast_speech_results_type results_type)
 Change the type of results we want.
int ast_speech_change_state (struct ast_speech *speech, int state)
 Change state of a speech structure.
int ast_speech_destroy (struct ast_speech *speech)
 Destroy a speech structure.
int ast_speech_dtmf (struct ast_speech *speech, const char *dtmf)
 Signal to the engine that DTMF was received.
int ast_speech_grammar_activate (struct ast_speech *speech, const char *grammar_name)
 Activate a loaded (either local or global) grammar.
int ast_speech_grammar_deactivate (struct ast_speech *speech, const char *grammar_name)
 Deactivate a loaded grammar on a speech structure.
int ast_speech_grammar_load (struct ast_speech *speech, const char *grammar_name, const char *grammar)
 Load a local grammar on a speech structure.
int ast_speech_grammar_unload (struct ast_speech *speech, const char *grammar_name)
 Unload a local grammar from a speech structure.
struct ast_speechast_speech_new (const char *engine_name, int formats)
 Create a new speech structure using the engine specified.
int ast_speech_register (struct ast_speech_engine *engine)
 Register a speech recognition engine.
int ast_speech_results_free (struct ast_speech_result *result)
 Free a list of results.
struct ast_speech_resultast_speech_results_get (struct ast_speech *speech)
 Return the results of a recognition from the speech structure.
void ast_speech_start (struct ast_speech *speech)
 Start speech recognition on a speech structure.
int ast_speech_unregister (const char *engine_name)
 Unregister a speech recognition engine.
int ast_speech_write (struct ast_speech *speech, void *data, int len)
 Write in signed linear audio to be recognized.
 ASTERISK_FILE_VERSION (__FILE__,"$Revision: 368738 $")
static struct ast_speech_enginefind_engine (const char *engine_name)
 Find a speech recognition engine of specified name, if NULL then use the default one.
static int load_module (void)
static int unload_module (void)

Variables

static struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Generic Speech Recognition API" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "ac1f6a56484a8820659555499174e588" , .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_APP_DEPEND, }
static struct ast_module_infoast_module_info = &__mod_info
static struct ast_speech_enginedefault_engine = NULL

Detailed Description

Generic Speech Recognition API.

Author:
Joshua Colp <jcolp@digium.com>

Definition in file res_speech.c.


Function Documentation

static void __reg_module ( void   )  [static]

Definition at line 347 of file res_speech.c.

static void __unreg_module ( void   )  [static]

Definition at line 347 of file res_speech.c.

int ast_speech_change ( struct ast_speech speech,
const char *  name,
const char *  value 
)

Change an engine specific attribute.

Definition at line 170 of file res_speech.c.

References ast_speech_engine::change, and ast_speech::engine.

Referenced by handle_speechset(), and speech_engine_write().

00171 {
00172    return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
00173 }

int ast_speech_change_results_type ( struct ast_speech speech,
enum ast_speech_results_type  results_type 
)

Change the type of results we want.

Definition at line 264 of file res_speech.c.

References ast_speech_engine::change_results_type, ast_speech::engine, and ast_speech::results_type.

Referenced by speech_results_type_write().

00265 {
00266    speech->results_type = results_type;
00267 
00268    return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
00269 }

int ast_speech_change_state ( struct ast_speech speech,
int  state 
)

Change state of a speech structure.

Definition at line 249 of file res_speech.c.

References ast_set_flag, AST_SPEECH_SPOKE, AST_SPEECH_STATE_WAIT, and ast_speech::state.

Referenced by ast_speech_new(), handle_speechrecognize(), and speech_background().

00250 {
00251    int res = 0;
00252 
00253    if (state == AST_SPEECH_STATE_WAIT) {
00254       /* The engine heard audio, so they spoke */
00255       ast_set_flag(speech, AST_SPEECH_SPOKE);
00256    }
00257 
00258    speech->state = state;
00259 
00260    return res;
00261 }

int ast_speech_destroy ( struct ast_speech speech  ) 

Destroy a speech structure.

Definition at line 224 of file res_speech.c.

References ast_free, ast_mutex_destroy, ast_speech_results_free(), ast_speech_engine::destroy, ast_speech::engine, ast_speech::lock, ast_speech::processing_sound, and ast_speech::results.

Referenced by destroy_callback(), handle_speechdestroy(), launch_asyncagi(), run_agi(), speech_background(), speech_create(), and speech_destroy().

00225 {
00226    int res = 0;
00227 
00228    /* Call our engine so we are destroyed properly */
00229    speech->engine->destroy(speech);
00230 
00231    /* Deinitialize the lock */
00232    ast_mutex_destroy(&speech->lock);
00233 
00234    /* If results exist on the speech structure, destroy them */
00235    if (speech->results)
00236       ast_speech_results_free(speech->results);
00237 
00238    /* If a processing sound is set - free the memory used by it */
00239    if (speech->processing_sound)
00240       ast_free(speech->processing_sound);
00241 
00242    /* Aloha we are done */
00243    ast_free(speech);
00244 
00245    return res;
00246 }

int ast_speech_dtmf ( struct ast_speech speech,
const char *  dtmf 
)

Signal to the engine that DTMF was received.

Definition at line 155 of file res_speech.c.

References AST_SPEECH_STATE_READY, ast_speech_engine::dtmf, ast_speech::engine, and ast_speech::state.

Referenced by speech_background().

00156 {
00157    int res = 0;
00158 
00159    if (speech->state != AST_SPEECH_STATE_READY)
00160       return -1;
00161 
00162    if (speech->engine->dtmf != NULL) {
00163       res = speech->engine->dtmf(speech, dtmf);
00164    }
00165 
00166    return res;
00167 }

int ast_speech_grammar_activate ( struct ast_speech speech,
const char *  grammar_name 
)

Activate a loaded (either local or global) grammar.

Activate a grammar on a speech structure.

Definition at line 67 of file res_speech.c.

References ast_speech_engine::activate, and ast_speech::engine.

Referenced by handle_speechactivategrammar(), and speech_activate().

00068 {
00069    return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
00070 }

int ast_speech_grammar_deactivate ( struct ast_speech speech,
const char *  grammar_name 
)

Deactivate a loaded grammar on a speech structure.

Deactivate a grammar on a speech structure.

Definition at line 73 of file res_speech.c.

References ast_speech_engine::deactivate, and ast_speech::engine.

Referenced by handle_speechdeactivategrammar(), and speech_deactivate().

00074 {
00075    return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
00076 }

int ast_speech_grammar_load ( struct ast_speech speech,
const char *  grammar_name,
const char *  grammar 
)

Load a local grammar on a speech structure.

Load a grammar on a speech structure (not globally).

Definition at line 79 of file res_speech.c.

References ast_speech::engine, and ast_speech_engine::load.

Referenced by handle_speechloadgrammar(), and speech_load().

00080 {
00081    return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
00082 }

int ast_speech_grammar_unload ( struct ast_speech speech,
const char *  grammar_name 
)

Unload a local grammar from a speech structure.

Unload a grammar.

Definition at line 85 of file res_speech.c.

References ast_speech::engine, and ast_speech_engine::unload.

Referenced by handle_speechunloadgrammar(), and speech_unload().

00086 {
00087    return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
00088 }

struct ast_speech* ast_speech_new ( const char *  engine_name,
int  formats 
) [read]

Create a new speech structure using the engine specified.

Create a new speech structure.

Definition at line 176 of file res_speech.c.

References ast_best_codec(), ast_calloc, AST_FORMAT_SLINEAR, ast_free, ast_mutex_destroy, ast_mutex_init, ast_speech_change_state(), AST_SPEECH_STATE_NOT_READY, ast_speech_engine::create, ast_speech::engine, find_engine(), ast_speech::format, format, ast_speech_engine::formats, ast_speech::lock, and ast_speech::results.

Referenced by handle_speechcreate(), and speech_create().

00177 {
00178    struct ast_speech_engine *engine = NULL;
00179    struct ast_speech *new_speech = NULL;
00180    int format = AST_FORMAT_SLINEAR;
00181 
00182    /* Try to find the speech recognition engine that was requested */
00183    if (!(engine = find_engine(engine_name)))
00184       return NULL;
00185 
00186    /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
00187    if ((format = (engine->formats & formats)))
00188       format = ast_best_codec(format);
00189    else if ((engine->formats & AST_FORMAT_SLINEAR))
00190       format = AST_FORMAT_SLINEAR;
00191    else
00192       return NULL;
00193 
00194    /* Allocate our own speech structure, and try to allocate a structure from the engine too */
00195    if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
00196       return NULL;
00197 
00198    /* Initialize the lock */
00199    ast_mutex_init(&new_speech->lock);
00200 
00201    /* Make sure no results are present */
00202    new_speech->results = NULL;
00203 
00204    /* Copy over our engine pointer */
00205    new_speech->engine = engine;
00206 
00207    /* Can't forget the format audio is going to be in */
00208    new_speech->format = format;
00209 
00210    /* We are not ready to accept audio yet */
00211    ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
00212 
00213    /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
00214    if (engine->create(new_speech, format)) {
00215       ast_mutex_destroy(&new_speech->lock);
00216       ast_free(new_speech);
00217       new_speech = NULL;
00218    }
00219 
00220    return new_speech;
00221 }

int ast_speech_register ( struct ast_speech_engine engine  ) 

Register a speech recognition engine.

Definition at line 272 of file res_speech.c.

References ast_log(), AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, ast_speech_engine::create, ast_speech_engine::destroy, find_engine(), LOG_WARNING, ast_speech_engine::name, and ast_speech_engine::write.

00273 {
00274    int res = 0;
00275 
00276    /* Confirm the engine meets the minimum API requirements */
00277    if (!engine->create || !engine->write || !engine->destroy) {
00278       ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
00279       return -1;
00280    }
00281 
00282    /* If an engine is already loaded with this name, error out */
00283    if (find_engine(engine->name)) {
00284       ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
00285       return -1;
00286    }
00287 
00288    ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
00289 
00290    /* Add to the engine linked list and make default if needed */
00291    AST_RWLIST_WRLOCK(&engines);
00292    AST_RWLIST_INSERT_HEAD(&engines, engine, list);
00293    if (!default_engine) {
00294       default_engine = engine;
00295       ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
00296    }
00297    AST_RWLIST_UNLOCK(&engines);
00298 
00299    return res;
00300 }

int ast_speech_results_free ( struct ast_speech_result result  ) 

Free a list of results.

Free a set of results.

Definition at line 97 of file res_speech.c.

References ast_free, AST_LIST_NEXT, ast_speech_result::grammar, ast_speech_result::list, and ast_speech_result::text.

Referenced by ast_speech_destroy(), and ast_speech_start().

00098 {
00099    struct ast_speech_result *current_result = result, *prev_result = NULL;
00100    int res = 0;
00101 
00102    while (current_result != NULL) {
00103       prev_result = current_result;
00104       /* Deallocate what we can */
00105       if (current_result->text != NULL) {
00106          ast_free(current_result->text);
00107          current_result->text = NULL;
00108       }
00109       if (current_result->grammar != NULL) {
00110          ast_free(current_result->grammar);
00111          current_result->grammar = NULL;
00112       }
00113       /* Move on and then free ourselves */
00114       current_result = AST_LIST_NEXT(current_result, list);
00115       ast_free(prev_result);
00116       prev_result = NULL;
00117    }
00118 
00119    return res;
00120 }

struct ast_speech_result* ast_speech_results_get ( struct ast_speech speech  )  [read]

Return the results of a recognition from the speech structure.

Get speech recognition results.

Definition at line 91 of file res_speech.c.

References ast_speech::engine, and ast_speech_engine::get.

Referenced by handle_speechrecognize(), and speech_background().

00092 {
00093    return (speech->engine->get ? speech->engine->get(speech) : NULL);
00094 }

void ast_speech_start ( struct ast_speech speech  ) 

Start speech recognition on a speech structure.

Indicate to the speech engine that audio is now going to start being written.

Definition at line 123 of file res_speech.c.

References ast_clear_flag, AST_SPEECH_HAVE_RESULTS, AST_SPEECH_QUIET, ast_speech_results_free(), AST_SPEECH_SPOKE, ast_speech::engine, ast_speech::results, and ast_speech_engine::start.

Referenced by handle_speechrecognize(), speech_background(), and speech_start().

00124 {
00125 
00126    /* Clear any flags that may affect things */
00127    ast_clear_flag(speech, AST_SPEECH_SPOKE);
00128    ast_clear_flag(speech, AST_SPEECH_QUIET);
00129    ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
00130 
00131    /* If results are on the structure, free them since we are starting again */
00132    if (speech->results) {
00133       ast_speech_results_free(speech->results);
00134       speech->results = NULL;
00135    }
00136 
00137    /* If the engine needs to start stuff up, do it */
00138    if (speech->engine->start)
00139       speech->engine->start(speech);
00140 
00141    return;
00142 }

int ast_speech_unregister ( const char *  engine_name  ) 

Unregister a speech recognition engine.

Definition at line 303 of file res_speech.c.

References AST_RWLIST_FIRST, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero(), ast_verb, ast_speech_engine::list, and ast_speech_engine::name.

00304 {
00305    struct ast_speech_engine *engine = NULL;
00306    int res = -1;
00307 
00308    if (ast_strlen_zero(engine_name))
00309       return -1;
00310 
00311    AST_RWLIST_WRLOCK(&engines);
00312    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00313       if (!strcasecmp(engine->name, engine_name)) {
00314          /* We have our engine... removed it */
00315          AST_RWLIST_REMOVE_CURRENT(list);
00316          /* If this was the default engine, we need to pick a new one */
00317          if (engine == default_engine) {
00318             default_engine = AST_RWLIST_FIRST(&engines);
00319          }
00320          ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
00321          /* All went well */
00322          res = 0;
00323          break;
00324       }
00325    }
00326    AST_RWLIST_TRAVERSE_SAFE_END;
00327    AST_RWLIST_UNLOCK(&engines);
00328 
00329    return res;
00330 }

int ast_speech_write ( struct ast_speech speech,
void *  data,
int  len 
)

Write in signed linear audio to be recognized.

Write audio to the speech engine.

Definition at line 145 of file res_speech.c.

References AST_SPEECH_STATE_READY, ast_speech::engine, ast_speech::state, and ast_speech_engine::write.

Referenced by handle_speechrecognize(), and speech_background().

00146 {
00147    /* Make sure the speech engine is ready to accept audio */
00148    if (speech->state != AST_SPEECH_STATE_READY)
00149       return -1;
00150 
00151    return speech->engine->write(speech, data, len);
00152 }

ASTERISK_FILE_VERSION ( __FILE__  ,
"$Revision: 368738 $"   
)
static struct ast_speech_engine* find_engine ( const char *  engine_name  )  [static, read]

Find a speech recognition engine of specified name, if NULL then use the default one.

Definition at line 47 of file res_speech.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strlen_zero(), ast_speech_engine::list, and ast_speech_engine::name.

Referenced by ast_speech_new(), and ast_speech_register().

00048 {
00049    struct ast_speech_engine *engine = NULL;
00050 
00051    /* If no name is specified -- use the default engine */
00052    if (ast_strlen_zero(engine_name))
00053       return default_engine;
00054 
00055    AST_RWLIST_RDLOCK(&engines);
00056    AST_RWLIST_TRAVERSE(&engines, engine, list) {
00057       if (!strcasecmp(engine->name, engine_name)) {
00058          break;
00059       }
00060    }
00061    AST_RWLIST_UNLOCK(&engines);
00062 
00063    return engine;
00064 }

static int load_module ( void   )  [static]

Definition at line 338 of file res_speech.c.

References AST_MODULE_LOAD_SUCCESS.

00339 {
00340    return AST_MODULE_LOAD_SUCCESS;
00341 }

static int unload_module ( void   )  [static]

Definition at line 332 of file res_speech.c.

00333 {
00334    /* We can not be unloaded */
00335    return -1;
00336 }


Variable Documentation

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Generic Speech Recognition API" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "ac1f6a56484a8820659555499174e588" , .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_APP_DEPEND, } [static]

Definition at line 347 of file res_speech.c.

Definition at line 347 of file res_speech.c.

struct ast_speech_engine* default_engine = NULL [static]

Definition at line 44 of file res_speech.c.


Generated on 20 Aug 2013 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1