Wed Oct 28 11:46:20 2009

Asterisk developer's documentation


speech.h File Reference

Generic Speech Recognition API. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_speech
struct  ast_speech_engine
struct  ast_speech_result

Enumerations

enum  ast_speech_flags { AST_SPEECH_QUIET = (1 << 0), AST_SPEECH_SPOKE = (1 << 1), AST_SPEECH_HAVE_RESULTS = (1 << 2) }
enum  ast_speech_results_type { AST_SPEECH_RESULTS_TYPE_NORMAL = 0, AST_SPEECH_RESULTS_TYPE_NBEST }
enum  ast_speech_states { AST_SPEECH_STATE_NOT_READY = 0, AST_SPEECH_STATE_READY, AST_SPEECH_STATE_WAIT, AST_SPEECH_STATE_DONE }

Functions

int ast_speech_change (struct ast_speech *speech, 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, char *grammar_name)
 Activate a grammar on a speech structure.
int ast_speech_grammar_deactivate (struct ast_speech *speech, char *grammar_name)
 Deactivate a grammar on a speech structure.
int ast_speech_grammar_load (struct ast_speech *speech, char *grammar_name, char *grammar)
 Load a grammar on a speech structure (not globally).
int ast_speech_grammar_unload (struct ast_speech *speech, char *grammar_name)
 Unload a grammar.
struct ast_speechast_speech_new (char *engine_name, int formats)
 Create a new speech structure.
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 set of results.
struct ast_speech_resultast_speech_results_get (struct ast_speech *speech)
 Get speech recognition results.
void ast_speech_start (struct ast_speech *speech)
 Indicate to the speech engine that audio is now going to start being written.
int ast_speech_unregister (char *engine_name)
 Unregister a speech recognition engine.
int ast_speech_write (struct ast_speech *speech, void *data, int len)
 Write audio to the speech engine.


Detailed Description

Generic Speech Recognition API.

Definition in file speech.h.


Enumeration Type Documentation

Enumerator:
AST_SPEECH_QUIET 
AST_SPEECH_SPOKE 
AST_SPEECH_HAVE_RESULTS 

Definition at line 31 of file speech.h.

00031                       {
00032    AST_SPEECH_QUIET = (1 << 0),        /* Quiet down output... they are talking */
00033    AST_SPEECH_SPOKE = (1 << 1),        /* Speaker spoke! */
00034    AST_SPEECH_HAVE_RESULTS = (1 << 2), /* Results are present */
00035 };

Enumerator:
AST_SPEECH_RESULTS_TYPE_NORMAL 
AST_SPEECH_RESULTS_TYPE_NBEST 

Definition at line 45 of file speech.h.

Enumerator:
AST_SPEECH_STATE_NOT_READY 
AST_SPEECH_STATE_READY 
AST_SPEECH_STATE_WAIT 
AST_SPEECH_STATE_DONE 

Definition at line 38 of file speech.h.

00038                        {
00039    AST_SPEECH_STATE_NOT_READY = 0, /* Not ready to accept audio */
00040    AST_SPEECH_STATE_READY, /* Accepting audio */
00041    AST_SPEECH_STATE_WAIT, /* Wait for results to become available */
00042    AST_SPEECH_STATE_DONE, /* Processing is all done */
00043 };


Function Documentation

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

Change an engine specific attribute.

Definition at line 166 of file res_speech.c.

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

Referenced by handle_speechset(), and speech_engine_write().

00167 {
00168    return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
00169 }

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 262 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().

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

int ast_speech_change_state ( struct ast_speech speech,
int  state 
)

Change state of a speech structure.

Definition at line 245 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().

00246 {
00247    int res = 0;
00248 
00249    switch (state) {
00250    case AST_SPEECH_STATE_WAIT:
00251       /* The engine heard audio, so they spoke */
00252       ast_set_flag(speech, AST_SPEECH_SPOKE);
00253    default:
00254       speech->state = state;
00255       break;
00256    }
00257 
00258    return res;
00259 }

int ast_speech_destroy ( struct ast_speech speech  ) 

Destroy a speech structure.

Definition at line 220 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().

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

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

Signal to the engine that DTMF was received.

Definition at line 151 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().

00152 {
00153    int res = 0;
00154 
00155    if (speech->state != AST_SPEECH_STATE_READY)
00156       return -1;
00157 
00158    if (speech->engine->dtmf != NULL) {
00159       res = speech->engine->dtmf(speech, dtmf);
00160    }
00161 
00162    return res;
00163 }

int ast_speech_grammar_activate ( struct ast_speech speech,
char *  grammar_name 
)

Activate a grammar on a speech structure.

Definition at line 63 of file res_speech.c.

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

Referenced by handle_speechactivategrammar(), and speech_activate().

00064 {
00065    return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
00066 }

int ast_speech_grammar_deactivate ( struct ast_speech speech,
char *  grammar_name 
)

Deactivate a grammar on a speech structure.

Definition at line 69 of file res_speech.c.

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

Referenced by handle_speechdeactivategrammar(), and speech_deactivate().

00070 {
00071    return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
00072 }

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

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

Definition at line 75 of file res_speech.c.

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

Referenced by handle_speechloadgrammar(), and speech_load().

00076 {
00077    return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
00078 }

int ast_speech_grammar_unload ( struct ast_speech speech,
char *  grammar_name 
)

Unload a grammar.

Definition at line 81 of file res_speech.c.

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

Referenced by handle_speechunloadgrammar(), and speech_unload().

00082 {
00083    return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
00084 }

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

Create a new speech structure.

Definition at line 172 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().

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

int ast_speech_register ( struct ast_speech_engine engine  ) 

Register a speech recognition engine.

Definition at line 270 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.

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

int ast_speech_results_free ( struct ast_speech_result result  ) 

Free a set of results.

Definition at line 93 of file res_speech.c.

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

Referenced by ast_speech_destroy(), and ast_speech_start().

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

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

Get speech recognition results.

Definition at line 87 of file res_speech.c.

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

Referenced by handle_speechrecognize(), and speech_background().

00088 {
00089    return (speech->engine->get ? speech->engine->get(speech) : NULL);
00090 }

void ast_speech_start ( struct ast_speech speech  ) 

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

Definition at line 119 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().

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

int ast_speech_unregister ( char *  engine_name  ) 

Unregister a speech recognition engine.

Definition at line 302 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, and ast_speech_engine::name.

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

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

Write audio to the speech engine.

Definition at line 141 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().

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


Generated on Wed Oct 28 11:46:20 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6