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 dependency graph for res_speech.c:

Go to the source code of this file.

Data Structures
struct	engines
Functions
static void	__fini_engines (void)
static void	__init_engines (void)
static void	__reg_module (void)
static void	__unreg_module (void)
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 loaded (either local or global) grammar.
int	ast_speech_grammar_deactivate (struct ast_speech speech, char grammar_name)
	Deactivate a loaded grammar on a speech structure.
int	ast_speech_grammar_load (struct ast_speech speech, char grammar_name, char *grammar)
	Load a local grammar on a speech structure.
int	ast_speech_grammar_unload (struct ast_speech speech, char grammar_name)
	Unload a local grammar from a speech structure.
struct ast_speech *	ast_speech_new (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_result *	ast_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 (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: 247845 $")
static struct ast_speech_engine *	find_engine (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 __MODULE_INFO_SECTION	__mod_info = { __MODULE_INFO_GLOBALS .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS , .description = "Generic Speech Recognition API" , .key = ASTERISK_GPL_KEY , .buildopt_sum = AST_BUILDOPT_SUM, .load = load_module, .unload = unload_module, }
static struct ast_module_info *	ast_module_info = &__mod_info
static struct ast_speech_engine *	default_engine = NULL
static struct engines	engines

Detailed Description

Generic Speech Recognition API.

Author:: Joshua Colp <jcolp@digium.com>

Definition in file res_speech.c.

Function Documentation

static void __fini_engines ( void ) [static]

Definition at line 39 of file res_speech.c.

static void __init_engines ( void ) [static]

Definition at line 39 of file res_speech.c.

static void __reg_module ( void ) [static]

Definition at line 345 of file res_speech.c.

static void __unreg_module ( void ) [static]

Definition at line 345 of file res_speech.c.

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

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

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

{
   speech->results_type = results_type;

   return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
}

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

{
   int res = 0;

   switch (state) {
   case AST_SPEECH_STATE_WAIT:
      /* The engine heard audio, so they spoke */
      ast_set_flag(speech, AST_SPEECH_SPOKE);
   default:
      speech->state = state;
      break;
   }

   return res;
}

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

{
   int res = 0;

   /* Call our engine so we are destroyed properly */
   speech->engine->destroy(speech);

   /* Deinitialize the lock */
   ast_mutex_destroy(&speech->lock);

   /* If results exist on the speech structure, destroy them */
   if (speech->results)
      ast_speech_results_free(speech->results);

   /* If a processing sound is set - free the memory used by it */
   if (speech->processing_sound)
      ast_free(speech->processing_sound);

   /* Aloha we are done */
   ast_free(speech);

   return res;
}

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

{
   int res = 0;

   if (speech->state != AST_SPEECH_STATE_READY)
      return -1;

   if (speech->engine->dtmf != NULL) {
      res = speech->engine->dtmf(speech, dtmf);
   }

   return res;
}

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

Activate a loaded (either local or global) grammar.

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

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

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

Deactivate a loaded grammar on a speech structure.

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

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

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

Load a local grammar on a speech structure.

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

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

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

Unload a local grammar from a speech structure.

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

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

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

Create a new speech structure using the engine specified.

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

{
   struct ast_speech_engine *engine = NULL;
   struct ast_speech *new_speech = NULL;
   int format = AST_FORMAT_SLINEAR;

   /* Try to find the speech recognition engine that was requested */
   if (!(engine = find_engine(engine_name)))
      return NULL;

   /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
   if ((format = (engine->formats & formats)))
      format = ast_best_codec(format);
   else if ((engine->formats & AST_FORMAT_SLINEAR))
      format = AST_FORMAT_SLINEAR;
   else
      return NULL;

   /* Allocate our own speech structure, and try to allocate a structure from the engine too */
   if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
      return NULL;

   /* Initialize the lock */
   ast_mutex_init(&new_speech->lock);

   /* Make sure no results are present */
   new_speech->results = NULL;

   /* Copy over our engine pointer */
   new_speech->engine = engine;

   /* Can't forget the format audio is going to be in */
   new_speech->format = format;

   /* We are not ready to accept audio yet */
   ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);

   /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
   if (engine->create(new_speech, format)) {
      ast_mutex_destroy(&new_speech->lock);
      ast_free(new_speech);
      new_speech = NULL;
   }

   return new_speech;
}

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(), ast_speech_engine::list, LOG_WARNING, ast_speech_engine::name, and ast_speech_engine::write.

{
   struct ast_speech_engine *existing_engine = NULL;
   int res = 0;

   /* Confirm the engine meets the minimum API requirements */
   if (!engine->create || !engine->write || !engine->destroy) {
      ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
      return -1;
   }

   /* If an engine is already loaded with this name, error out */
   if ((existing_engine = find_engine(engine->name))) {
      ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
      return -1;
   }

   ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);

   /* Add to the engine linked list and make default if needed */
   AST_RWLIST_WRLOCK(&engines);
   AST_RWLIST_INSERT_HEAD(&engines, engine, list);
   if (!default_engine) {
      default_engine = engine;
      ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
   }
   AST_RWLIST_UNLOCK(&engines);

   return res;
}

int ast_speech_results_free ( struct ast_speech_result * result )

Free a list of results.

Free a set of results.

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

{
   struct ast_speech_result *current_result = result, *prev_result = NULL;
   int res = 0;

   while (current_result != NULL) {
      prev_result = current_result;
      /* Deallocate what we can */
      if (current_result->text != NULL) {
         ast_free(current_result->text);
         current_result->text = NULL;
      }
      if (current_result->grammar != NULL) {
         ast_free(current_result->grammar);
         current_result->grammar = NULL;
      }
      /* Move on and then free ourselves */
      current_result = AST_LIST_NEXT(current_result, list);
      ast_free(prev_result);
      prev_result = NULL;
   }

   return res;
}

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

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

Referenced by handle_speechrecognize(), and speech_background().

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

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

{

   /* Clear any flags that may affect things */
   ast_clear_flag(speech, AST_SPEECH_SPOKE);
   ast_clear_flag(speech, AST_SPEECH_QUIET);
   ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);

   /* If results are on the structure, free them since we are starting again */
   if (speech->results) {
      ast_speech_results_free(speech->results);
      speech->results = NULL;
   }

   /* If the engine needs to start stuff up, do it */
   if (speech->engine->start)
      speech->engine->start(speech);

   return;
}

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, ast_speech_engine::list, and ast_speech_engine::name.

{
   struct ast_speech_engine *engine = NULL;
   int res = -1;

   if (ast_strlen_zero(engine_name))
      return -1;

   AST_RWLIST_WRLOCK(&engines);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
      if (!strcasecmp(engine->name, engine_name)) {
         /* We have our engine... removed it */
         AST_RWLIST_REMOVE_CURRENT(list);
         /* If this was the default engine, we need to pick a new one */
         if (engine == default_engine) {
            default_engine = AST_RWLIST_FIRST(&engines);
         }
         ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
         /* All went well */
         res = 0;
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&engines);

   return res;
}

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

{
   /* Make sure the speech engine is ready to accept audio */
   if (speech->state != AST_SPEECH_STATE_READY)
      return -1;

   return speech->engine->write(speech, data, len);
}

ASTERISK_FILE_VERSION	(	__FILE__	,
		"$Revision: 247845 $"
	)

static struct ast_speech_engine* find_engine ( char * engine_name ) [static, read]

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

Definition at line 43 of file res_speech.c.

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

Referenced by ast_speech_new(), and ast_speech_register().

{
   struct ast_speech_engine *engine = NULL;

   /* If no name is specified -- use the default engine */
   if (ast_strlen_zero(engine_name))
      return default_engine;

   AST_RWLIST_RDLOCK(&engines);
   AST_RWLIST_TRAVERSE(&engines, engine, list) {
      if (!strcasecmp(engine->name, engine_name)) {
         break;
      }
   }
   AST_RWLIST_UNLOCK(&engines);

   return engine;
}

static int load_module ( void ) [static]

Definition at line 337 of file res_speech.c.

References AST_MODULE_LOAD_SUCCESS.

{
   return AST_MODULE_LOAD_SUCCESS;
}

static int unload_module ( void ) [static]

Definition at line 331 of file res_speech.c.

{
   /* We can not be unloaded */
   return -1;
}

Variable Documentation

struct ast_module_info __MODULE_INFO_SECTION __mod_info = { __MODULE_INFO_GLOBALS .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS , .description = "Generic Speech Recognition API" , .key = ASTERISK_GPL_KEY , .buildopt_sum = AST_BUILDOPT_SUM, .load = load_module, .unload = unload_module, } [static]

Definition at line 345 of file res_speech.c.

struct ast_module_info* ast_module_info = &__mod_info [static]

Definition at line 345 of file res_speech.c.

struct ast_speech_engine* default_engine = NULL [static]

Definition at line 40 of file res_speech.c.

Referenced by find_engine().

struct engines engines [static]

Asterisk developer's documentation

res_speech.c File Reference

Data Structures

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation