Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Enumerations | Functions
speech.h File Reference

Generic Speech Recognition API. More...

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, 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.
 
struct ast_speech_engineast_speech_find_engine (const char *engine_name)
 Retrieve a speech recognition engine. More...
 
int ast_speech_get_setting (struct ast_speech *speech, const char *name, char *buf, size_t len)
 Get an engine specific attribute.
 
int ast_speech_grammar_activate (struct ast_speech *speech, const char *grammar_name)
 Activate a grammar on a speech structure. More...
 
int ast_speech_grammar_deactivate (struct ast_speech *speech, const char *grammar_name)
 Deactivate a grammar on a speech structure. More...
 
int ast_speech_grammar_load (struct ast_speech *speech, const char *grammar_name, const char *grammar)
 Load a grammar on a speech structure (not globally) More...
 
int ast_speech_grammar_unload (struct ast_speech *speech, const char *grammar_name)
 Unload a grammar. More...
 
struct ast_speechast_speech_new (const char *engine_name, const struct ast_format_cap *formats)
 Create a new speech structure. More...
 
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. More...
 
struct ast_speech_resultast_speech_results_get (struct ast_speech *speech)
 Get speech recognition results. More...
 
const char * ast_speech_results_type_to_string (enum ast_speech_results_type type)
 Convert a speech results type to a string.
 
void ast_speech_start (struct ast_speech *speech)
 Indicate to the speech engine that audio is now going to start being written. More...
 
int ast_speech_unregister (const char *engine_name)
 Unregister a speech recognition engine.
 
struct ast_speech_engineast_speech_unregister2 (const char *engine_name)
 Unregister a speech recognition engine.
 
void ast_speech_unregister_engines (int(*should_unregister)(const struct ast_speech_engine *engine, void *data), void *data, void(*on_unregistered)(void *obj))
 Unregister all speech recognition engines told to by callback.
 
int ast_speech_write (struct ast_speech *speech, void *data, int len)
 Write audio to the speech engine. More...
 

Detailed Description

Generic Speech Recognition API.

Definition in file speech.h.

Function Documentation

struct ast_speech_engine* ast_speech_find_engine ( const char *  engine_name)

Retrieve a speech recognition engine.

Retrieve a speech recognition engine.

Definition at line 46 of file res_speech.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and ast_speech_engine::name.

Referenced by ast_speech_new(), and ast_speech_register().

47 {
48  struct ast_speech_engine *engine = NULL;
49 
50  /* If no name is specified -- use the default engine */
51  if (ast_strlen_zero(engine_name))
52  return default_engine;
53 
55  AST_RWLIST_TRAVERSE(&engines, engine, list) {
56  if (!strcasecmp(engine->name, engine_name)) {
57  break;
58  }
59  }
61 
62  return engine;
63 }
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
char * name
Definition: speech.h:78
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
int ast_speech_grammar_activate ( struct ast_speech speech,
const char *  grammar_name 
)

Activate a grammar on a speech structure.

Activate a grammar on a speech structure.

Definition at line 66 of file res_speech.c.

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

Referenced by speech_activate().

67 {
68  return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
69 }
struct ast_speech_engine * engine
Definition: speech.h:72
int(* activate)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:88
int ast_speech_grammar_deactivate ( struct ast_speech speech,
const char *  grammar_name 
)

Deactivate a grammar on a speech structure.

Deactivate a grammar on a speech structure.

Definition at line 72 of file res_speech.c.

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

Referenced by speech_deactivate().

73 {
74  return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
75 }
struct ast_speech_engine * engine
Definition: speech.h:72
int(* deactivate)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:90
int ast_speech_grammar_load ( struct ast_speech speech,
const char *  grammar_name,
const char *  grammar 
)

Load a grammar on a speech structure (not globally)

Load a grammar on a speech structure (not globally)

Definition at line 78 of file res_speech.c.

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

Referenced by speech_load().

79 {
80  return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
81 }
struct ast_speech_engine * engine
Definition: speech.h:72
int(* load)(struct ast_speech *speech, const char *grammar_name, const char *grammar)
Definition: speech.h:84
int ast_speech_grammar_unload ( struct ast_speech speech,
const char *  grammar_name 
)

Unload a grammar.

Unload a grammar.

Definition at line 84 of file res_speech.c.

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

Referenced by speech_unload().

85 {
86  return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
87 }
int(* unload)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:86
struct ast_speech_engine * engine
Definition: speech.h:72
struct ast_speech* ast_speech_new ( const char *  engine_name,
const struct ast_format_cap cap 
)

Create a new speech structure.

Create a new speech structure.

Definition at line 181 of file res_speech.c.

References ao2_bump, ao2_ref, ast_calloc, ast_format_cap_alloc, AST_FORMAT_CAP_FLAG_DEFAULT, ast_format_cap_get_compatible(), ast_format_cap_get_format(), ast_format_cap_iscompatible_format(), AST_FORMAT_CMP_NOT_EQUAL, ast_format_slin, ast_speech_change_state(), ast_speech_find_engine(), ast_translator_best_choice(), ast_speech_engine::create, ast_speech::engine, ast_speech::format, ast_speech_engine::formats, ast_speech::lock, RAII_VAR, and ast_speech::results.

Referenced by speech_create().

182 {
183  struct ast_speech_engine *engine = NULL;
184  struct ast_speech *new_speech = NULL;
185  struct ast_format_cap *joint;
186  RAII_VAR(struct ast_format *, best, NULL, ao2_cleanup);
187  RAII_VAR(struct ast_format *, best_translated, NULL, ao2_cleanup);
188 
189  /* Try to find the speech recognition engine that was requested */
190  if (!(engine = ast_speech_find_engine(engine_name)))
191  return NULL;
192 
194  if (!joint) {
195  return NULL;
196  }
197 
198  ast_format_cap_get_compatible(engine->formats, cap, joint);
199  best = ast_format_cap_get_format(joint, 0);
200  ao2_ref(joint, -1);
201 
202  if (!best) {
204  best = ao2_bump(ast_format_slin);
205  } else {
206  /*
207  * If there is no overlap and the engine does not support slin, find the best
208  * format to translate to and set that as the 'best' input format for the engine.
209  * API consumer is responsible for translating to this format.
210  * Safe to cast cap as ast_translator_best_choice does not modify the caps
211  */
212  if (ast_translator_best_choice(engine->formats, (struct ast_format_cap *)cap, &best, &best_translated)) {
213  /* No overlapping formats and no translatable formats */
214  return NULL;
215  }
216  }
217  }
218 
219  /* Allocate our own speech structure, and try to allocate a structure from the engine too */
220  if (!(new_speech = ast_calloc(1, sizeof(*new_speech)))) {
221  return NULL;
222  }
223 
224  /* Initialize the lock */
225  ast_mutex_init(&new_speech->lock);
226 
227  /* Make sure no results are present */
228  new_speech->results = NULL;
229 
230  /* Copy over our engine pointer */
231  new_speech->engine = engine;
232 
233  /* Can't forget the format audio is going to be in */
234  new_speech->format = ao2_bump(best);
235 
236  /* We are not ready to accept audio yet */
237  ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
238 
239  /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
240  if (engine->create(new_speech, new_speech->format)) {
241  ast_mutex_destroy(&new_speech->lock);
242  ao2_ref(new_speech->format, -1);
243  ast_free(new_speech);
244  return NULL;
245  }
246 
247  return new_speech;
248 }
int ast_speech_change_state(struct ast_speech *speech, int state)
Change state of a speech structure.
Definition: res_speech.c:278
int(* create)(struct ast_speech *speech, struct ast_format *format)
Definition: speech.h:80
struct ast_speech_engine * ast_speech_find_engine(const char *engine_name)
Find a speech recognition engine of specified name, if NULL then use the default one.
Definition: res_speech.c:46
Definition of a media format.
Definition: format.c:43
int ast_translator_best_choice(struct ast_format_cap *dst_cap, struct ast_format_cap *src_cap, struct ast_format **dst_fmt_out, struct ast_format **src_fmt_out)
Chooses the best translation path.
Definition: translate.c:1402
enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format)
Find if ast_format is within the capabilities of the ast_format_cap object.
Definition: format_cap.c:581
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct ast_format_cap * formats
Definition: speech.h:106
struct ast_speech_engine * engine
Definition: speech.h:72
struct ast_speech_result * results
Definition: speech.h:68
#define ast_format_cap_alloc(flags)
Allocate a new ast_format_cap structure.
Definition: format_cap.h:49
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
struct ast_format * format
Definition: speech.h:64
ast_mutex_t lock
Definition: speech.h:56
struct ast_format * ast_format_cap_get_format(const struct ast_format_cap *cap, int position)
Get the format at a specific index.
Definition: format_cap.c:400
struct ast_format * ast_format_slin
Built-in cached signed linear 8kHz format.
Definition: format_cache.c:41
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
int ast_format_cap_get_compatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result)
Find the compatible formats between two capabilities structures.
Definition: format_cap.c:628
int ast_speech_results_free ( struct ast_speech_result result)

Free a set of results.

Free a set of results.

Definition at line 96 of file res_speech.c.

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

Referenced by ast_speech_destroy(), and ast_speech_start().

97 {
98  struct ast_speech_result *current_result = result, *prev_result = NULL;
99  int res = 0;
100 
101  while (current_result != NULL) {
102  prev_result = current_result;
103  /* Deallocate what we can */
104  if (current_result->text != NULL) {
105  ast_free(current_result->text);
106  current_result->text = NULL;
107  }
108  if (current_result->grammar != NULL) {
109  ast_free(current_result->grammar);
110  current_result->grammar = NULL;
111  }
112  /* Move on and then free ourselves */
113  current_result = AST_LIST_NEXT(current_result, list);
114  ast_free(prev_result);
115  prev_result = NULL;
116  }
117 
118  return res;
119 }
#define AST_LIST_NEXT(elm, field)
Returns the next entry in the list after the given entry.
Definition: linkedlists.h:439
char * grammar
Definition: speech.h:119
struct ast_speech_result* ast_speech_results_get ( struct ast_speech speech)

Get speech recognition results.

Get speech recognition results.

Definition at line 90 of file res_speech.c.

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

Referenced by speech_background().

91 {
92  return (speech->engine->get ? speech->engine->get(speech) : NULL);
93 }
struct ast_speech_engine * engine
Definition: speech.h:72
struct ast_speech_result *(* get)(struct ast_speech *speech)
Definition: speech.h:104
void ast_speech_start ( struct ast_speech speech)

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

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

Definition at line 122 of file res_speech.c.

References ast_speech_results_free(), ast_speech::engine, ast_speech::results, and ast_speech_engine::start.

Referenced by speech_background(), and speech_start().

123 {
124 
125  /* Clear any flags that may affect things */
126  ast_clear_flag(speech, AST_SPEECH_SPOKE);
127  ast_clear_flag(speech, AST_SPEECH_QUIET);
128  ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
129 
130  /* If results are on the structure, free them since we are starting again */
131  if (speech->results) {
133  speech->results = NULL;
134  }
135 
136  /* If the engine needs to start stuff up, do it */
137  if (speech->engine->start)
138  speech->engine->start(speech);
139 
140  return;
141 }
int(* start)(struct ast_speech *speech)
Definition: speech.h:96
struct ast_speech_engine * engine
Definition: speech.h:72
struct ast_speech_result * results
Definition: speech.h:68
int ast_speech_results_free(struct ast_speech_result *result)
Free a list of results.
Definition: res_speech.c:96
int ast_speech_write ( struct ast_speech speech,
void *  data,
int  len 
)

Write audio to the speech engine.

Write audio to the speech engine.

Definition at line 144 of file res_speech.c.

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

Referenced by speech_background().

145 {
146  /* Make sure the speech engine is ready to accept audio */
147  if (speech->state != AST_SPEECH_STATE_READY)
148  return -1;
149 
150  return speech->engine->write(speech, data, len);
151 }
int state
Definition: speech.h:62
struct ast_speech_engine * engine
Definition: speech.h:72
int(* write)(struct ast_speech *speech, void *data, int len)
Definition: speech.h:92