Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Functions | Variables
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"
#include "asterisk/format_cache.h"
#include "asterisk/translate.h"

Go to the source code of this file.

Data Structures

struct  engines
 

Functions

static void __reg_module (void)
 
static void __unreg_module (void)
 
struct ast_moduleAST_MODULE_SELF_SYM (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.
 
struct ast_speech_engineast_speech_find_engine (const char *engine_name)
 Find a speech recognition engine of specified name, if NULL then use the default one. 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 loaded (either local or global) grammar. More...
 
int ast_speech_grammar_deactivate (struct ast_speech *speech, const char *grammar_name)
 Deactivate a loaded grammar on a speech structure. More...
 
int ast_speech_grammar_load (struct ast_speech *speech, const char *grammar_name, const char *grammar)
 Load a local grammar on a speech structure. More...
 
int ast_speech_grammar_unload (struct ast_speech *speech, const char *grammar_name)
 Unload a local grammar from a speech structure. More...
 
struct ast_speechast_speech_new (const char *engine_name, const struct ast_format_cap *cap)
 Create a new speech structure using the engine specified. 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 list of results. More...
 
struct ast_speech_resultast_speech_results_get (struct ast_speech *speech)
 Return the results of a recognition from the speech structure. 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)
 Start speech recognition on a speech structure. 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 in signed linear audio to be recognized. More...
 
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 = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_APP_DEPEND - 1, }
 
static const struct ast_module_infoast_module_info = &__mod_info
 
static struct ast_speech_enginedefault_engine = NULL
 
static struct engines engines = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }
 

Detailed Description

Generic Speech Recognition API.

Author
Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file res_speech.c.

Function Documentation

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.

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 loaded (either local or global) grammar.

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 loaded 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 local grammar on a speech structure.

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 local grammar from a speech structure.

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 using the engine specified.

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 list 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)

Return the results of a recognition from the speech structure.

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)

Start speech recognition on a speech structure.

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 in signed linear audio to be recognized.

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