Wed Aug 15 01:25:33 2007

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

Defines

#define AST_SPEECH_HAVE_RESULTS   (1 << 2)
#define AST_SPEECH_QUIET   (1 << 0)
#define AST_SPEECH_SPOKE   (1 << 1)
#define AST_SPEECH_STATE_DONE   3
#define AST_SPEECH_STATE_NOT_READY   0
#define AST_SPEECH_STATE_READY   1
#define AST_SPEECH_STATE_WAIT   2

Enumerations

enum  ast_speech_results_type { AST_SPEECH_RESULTS_TYPE_NORMAL = 0, AST_SPEECH_RESULTS_TYPE_NBEST }

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_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 format)
 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_result
ast_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.


Define Documentation

#define AST_SPEECH_HAVE_RESULTS   (1 << 2)

Definition at line 33 of file speech.h.

Referenced by ast_speech_results_get(), and ast_speech_start().

#define AST_SPEECH_QUIET   (1 << 0)

Definition at line 31 of file speech.h.

Referenced by ast_speech_start(), and speech_background().

#define AST_SPEECH_SPOKE   (1 << 1)

Definition at line 32 of file speech.h.

Referenced by ast_speech_change_state(), ast_speech_start(), and speech_read().

#define AST_SPEECH_STATE_DONE   3

Definition at line 39 of file speech.h.

Referenced by speech_background().

#define AST_SPEECH_STATE_NOT_READY   0

Definition at line 36 of file speech.h.

Referenced by ast_speech_new(), and speech_background().

#define AST_SPEECH_STATE_READY   1

Definition at line 37 of file speech.h.

Referenced by ast_speech_write(), and speech_background().

#define AST_SPEECH_STATE_WAIT   2

Definition at line 38 of file speech.h.

Referenced by ast_speech_change_state(), and speech_background().


Enumeration Type Documentation

enum ast_speech_results_type

Enumerator:
AST_SPEECH_RESULTS_TYPE_NORMAL 
AST_SPEECH_RESULTS_TYPE_NBEST 

Definition at line 41 of file speech.h.


Function Documentation

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

Change an engine specific attribute.

Definition at line 197 of file res_speech.c.

Referenced by speech_engine_write().

00198 {
00199    int res = 0;
00200 
00201    if (speech->engine->change != NULL) {
00202       res = speech->engine->change(speech, name, value);
00203    }
00204 
00205    return res;
00206 }

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 298 of file res_speech.c.

Referenced by speech_results_type_write().

00299 {
00300    int res = 0;
00301 
00302    speech->results_type = results_type;
00303 
00304    if (speech->engine->change_results_type)
00305       res = speech->engine->change_results_type(speech, results_type);
00306 
00307    return res;
00308 }

int ast_speech_change_state ( struct ast_speech speech,
int  state 
)

Change state of a speech structure.

Definition at line 281 of file res_speech.c.

Referenced by ast_speech_new(), and speech_background().

00282 {
00283    int res = 0;
00284 
00285    switch (state) {
00286    case AST_SPEECH_STATE_WAIT:
00287       /* The engine heard audio, so they spoke */
00288       ast_set_flag(speech, AST_SPEECH_SPOKE);
00289    default:
00290       speech->state = state;
00291       break;
00292    }
00293 
00294    return res;
00295 }

int ast_speech_destroy ( struct ast_speech speech  ) 

Destroy a speech structure.

Definition at line 251 of file res_speech.c.

Referenced by destroy_callback(), speech_background(), speech_create(), and speech_destroy().

00252 {
00253    int res = 0;
00254 
00255    /* Call our engine so we are destroyed properly */
00256    speech->engine->destroy(speech);
00257 
00258    /* Deinitialize the lock */
00259    ast_mutex_destroy(&speech->lock);
00260 
00261    /* If results exist on the speech structure, destroy them */
00262    if (speech->results != NULL) {
00263       ast_speech_results_free(speech->results);
00264       speech->results = NULL;
00265    }
00266 
00267    /* If a processing sound is set - free the memory used by it */
00268    if (speech->processing_sound != NULL) {
00269       free(speech->processing_sound);
00270       speech->processing_sound = NULL;
00271    }
00272 
00273    /* Aloha we are done */
00274    free(speech);
00275    speech = NULL;
00276 
00277    return res;
00278 }

int ast_speech_grammar_activate ( struct ast_speech speech,
char *  grammar_name 
)

Activate a grammar on a speech structure.

Definition at line 71 of file res_speech.c.

Referenced by speech_activate().

00072 {
00073    int res = 0;
00074 
00075    if (speech->engine->activate != NULL) {
00076       res = speech->engine->activate(speech, grammar_name);
00077    }
00078 
00079    return res;
00080 }

int ast_speech_grammar_deactivate ( struct ast_speech speech,
char *  grammar_name 
)

Deactivate a grammar on a speech structure.

Definition at line 83 of file res_speech.c.

Referenced by speech_deactivate().

00084 {
00085    int res = 0;
00086 
00087         if (speech->engine->deactivate != NULL) {
00088                 res = speech->engine->deactivate(speech, grammar_name);
00089         }
00090 
00091    return res;
00092 }

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 95 of file res_speech.c.

Referenced by speech_load().

00096 {
00097    int res = 0;
00098 
00099    if (speech->engine->load != NULL) {
00100       res = speech->engine->load(speech, grammar_name, grammar);
00101    }
00102 
00103    return res;
00104 }

int ast_speech_grammar_unload ( struct ast_speech speech,
char *  grammar_name 
)

Unload a grammar.

Definition at line 107 of file res_speech.c.

Referenced by speech_unload().

00108 {
00109         int res = 0;
00110 
00111         if (speech->engine->unload != NULL) {
00112                 res = speech->engine->unload(speech, grammar_name);
00113         }
00114 
00115         return res;
00116 }

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

Create a new speech structure.

Definition at line 209 of file res_speech.c.

Referenced by speech_create().

00210 {
00211    struct ast_speech_engine *engine = NULL;
00212    struct ast_speech *new_speech = NULL;
00213 
00214    /* Try to find the speech recognition engine that was requested */
00215    engine = find_engine(engine_name);
00216    if (engine == NULL) {
00217       /* Invalid engine or no engine available */
00218       return NULL;
00219    }
00220 
00221    /* Allocate our own speech structure, and try to allocate a structure from the engine too */
00222    new_speech = ast_calloc(1, sizeof(*new_speech));
00223    if (new_speech == NULL) {
00224       /* Ran out of memory while trying to allocate some for a speech structure */
00225       return NULL;
00226    }
00227 
00228    /* Initialize the lock */
00229    ast_mutex_init(&new_speech->lock);
00230 
00231    /* Make sure no results are present */
00232    new_speech->results = NULL;
00233 
00234    /* Copy over our engine pointer */
00235    new_speech->engine = engine;
00236 
00237    /* We are not ready to accept audio yet */
00238    ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
00239 
00240    /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
00241    if (engine->create(new_speech)) {
00242       ast_mutex_destroy(&new_speech->lock);
00243       free(new_speech);
00244       new_speech = NULL;
00245    }
00246 
00247    return new_speech;
00248 }

int ast_speech_register ( struct ast_speech_engine engine  ) 

Register a speech recognition engine.

Definition at line 311 of file res_speech.c.

00312 {
00313    struct ast_speech_engine *existing_engine = NULL;
00314    int res = 0;
00315 
00316    existing_engine = find_engine(engine->name);
00317    if (existing_engine != NULL) {
00318       /* Engine already loaded */
00319       return -1;
00320    }
00321 
00322    if (option_verbose > 1)
00323       ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
00324 
00325    /* Add to the engine linked list and make default if needed */
00326    AST_LIST_LOCK(&engines);
00327    AST_LIST_INSERT_HEAD(&engines, engine, list);
00328    if (default_engine == NULL) {
00329       default_engine = engine;
00330       if (option_verbose > 1)
00331          ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
00332    }
00333    AST_LIST_UNLOCK(&engines);
00334 
00335    return res;
00336 }

int ast_speech_results_free ( struct ast_speech_result result  ) 

Free a set of results.

Definition at line 131 of file res_speech.c.

Referenced by ast_speech_destroy(), and ast_speech_start().

00132 {
00133    struct ast_speech_result *current_result = result, *prev_result = NULL;
00134    int res = 0;
00135 
00136    while (current_result != NULL) {
00137       prev_result = current_result;
00138       /* Deallocate what we can */
00139       if (current_result->text != NULL) {
00140          free(current_result->text);
00141          current_result->text = NULL;
00142       }
00143       if (current_result->grammar != NULL) {
00144          free(current_result->grammar);
00145          current_result->grammar = NULL;
00146       }
00147       /* Move on and then free ourselves */
00148       current_result = current_result->next;
00149       free(prev_result);
00150       prev_result = NULL;
00151    }
00152 
00153    return res;
00154 }

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

Get speech recognition results.

Definition at line 119 of file res_speech.c.

Referenced by speech_background().

00120 {
00121    struct ast_speech_result *result = NULL;
00122 
00123    if (speech->engine->get != NULL && ast_test_flag(speech, AST_SPEECH_HAVE_RESULTS)) {
00124       result = speech->engine->get(speech);
00125    }
00126 
00127    return result;
00128 }

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 157 of file res_speech.c.

Referenced by speech_background(), and speech_start().

00158 {
00159 
00160    /* Clear any flags that may affect things */
00161    ast_clear_flag(speech, AST_SPEECH_SPOKE);
00162    ast_clear_flag(speech, AST_SPEECH_QUIET);
00163    ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
00164 
00165    /* If results are on the structure, free them since we are starting again */
00166    if (speech->results != NULL) {
00167       ast_speech_results_free(speech->results);
00168       speech->results = NULL;
00169    }
00170 
00171    /* If the engine needs to start stuff up, do it */
00172    if (speech->engine->start != NULL) {
00173       speech->engine->start(speech);
00174    }
00175 
00176    return;
00177 }

int ast_speech_unregister ( char *  engine_name  ) 

Unregister a speech recognition engine.

Definition at line 339 of file res_speech.c.

00340 {
00341    struct ast_speech_engine *engine = NULL;
00342    int res = -1;
00343 
00344    if (engine_name == NULL) {
00345       return res;
00346    }
00347 
00348    AST_LIST_LOCK(&engines);
00349    AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00350       if (!strcasecmp(engine->name, engine_name)) {
00351          /* We have our engine... removed it */
00352          AST_LIST_REMOVE_CURRENT(&engines, list);
00353          /* If this was the default engine, we need to pick a new one */
00354          if (default_engine == engine) {
00355             default_engine = AST_LIST_FIRST(&engines);
00356          }
00357          if (option_verbose > 1)
00358             ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
00359          /* All went well */
00360          res = 0;
00361          break;
00362       }
00363    }
00364    AST_LIST_TRAVERSE_SAFE_END
00365    AST_LIST_UNLOCK(&engines);
00366 
00367    return res;
00368 }

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

Write audio to the speech engine.

Definition at line 180 of file res_speech.c.

Referenced by speech_background().

00181 {
00182    int res = 0;
00183 
00184    /* Make sure the speech engine is ready to accept audio */
00185    if (speech->state != AST_SPEECH_STATE_READY) {
00186       return -1;
00187    }
00188 
00189    if (speech->engine->write != NULL) {
00190       speech->engine->write(speech, data, len);
00191    }
00192 
00193    return res;
00194 }


Generated on Wed Aug 15 01:25:33 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.3