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, const char *name, const char *value)
	Change an engine specific attribute. More...
int	ast_speech_change_results_type (struct ast_speech *speech, enum ast_speech_results_type results_type)
	Change the type of results we want. More...
int	ast_speech_change_state (struct ast_speech *speech, int state)
	Change state of a speech structure. More...
int	ast_speech_destroy (struct ast_speech *speech)
	Destroy a speech structure. More...
int	ast_speech_dtmf (struct ast_speech *speech, const char *dtmf)
	Signal to the engine that DTMF was received. More...
struct ast_speech_engine *	ast_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. More...
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_speech *	ast_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. More...
int	ast_speech_results_free (struct ast_speech_result *result)
	Free a set of results. More...
struct ast_speech_result *	ast_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. More...
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. More...
struct ast_speech_engine *	ast_speech_unregister2 (const char *engine_name)
	Unregister a speech recognition engine. More...
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. More...
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.

Enumeration Type Documentation

ast_speech_flags

enum ast_speech_flags

Enumerator
AST_SPEECH_QUIET
AST_SPEECH_SPOKE
AST_SPEECH_HAVE_RESULTS

Definition at line 31 of file speech.h.

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

ast_speech_results_type

enum ast_speech_results_type

Enumerator
AST_SPEECH_RESULTS_TYPE_NORMAL
AST_SPEECH_RESULTS_TYPE_NBEST

Definition at line 45 of file speech.h.

                             {
    AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
    AST_SPEECH_RESULTS_TYPE_NBEST,
};

ast_speech_states

enum ast_speech_states

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.

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

Function Documentation

ast_speech_change()

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

Change an engine specific attribute.

Definition at line 169 of file res_speech.c.

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

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

Referenced by AST_TEST_DEFINE(), handle_speechset(), and speech_engine_write().

ast_speech_change_results_type()

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

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

References ast_speech_engine::change_results_type, ast_speech::engine, and ast_speech::results_type.

Referenced by AST_TEST_DEFINE(), and speech_results_type_write().

ast_speech_change_state()

int ast_speech_change_state	(	struct ast_speech *	speech,
		int	state
	)

Change state of a speech structure.

Definition at line 278 of file res_speech.c.

{
    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;
}

References ast_set_flag, AST_SPEECH_SPOKE, AST_SPEECH_STATE_WAIT, ast_speech::state, and state.

Referenced by ast_aeap_speech_on_error(), ast_speech_new(), handle_request_set(), handle_speechrecognize(), speech_aeap_engine_start(), and speech_background().

ast_speech_destroy()

int ast_speech_destroy

(

struct ast_speech *

speech

)

Destroy a speech structure.

Definition at line 251 of file res_speech.c.

{
    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);
 
    ao2_ref(speech->format, -1);
 
    /* Aloha we are done */
    ast_free(speech);
 
    return res;
}

References ao2_ref, ast_free, ast_mutex_destroy, ast_speech_results_free(), ast_speech_engine::destroy, ast_speech::engine, ast_speech::format, ast_speech::lock, ast_speech::processing_sound, and ast_speech::results.

Referenced by AST_TEST_DEFINE(), destroy_callback(), handle_speechdestroy(), launch_asyncagi(), run_agi(), and speech_create().

ast_speech_dtmf()

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

Signal to the engine that DTMF was received.

Definition at line 154 of file res_speech.c.

{
    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;
}

References AST_SPEECH_STATE_READY, ast_speech_engine::dtmf, ast_speech::engine, NULL, and ast_speech::state.

Referenced by AST_TEST_DEFINE(), and speech_background().

ast_speech_find_engine()

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.

{
    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;
}

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

Referenced by ast_speech_new(), ast_speech_register(), and load_engine().

ast_speech_get_setting()

int ast_speech_get_setting	(	struct ast_speech *	speech,
		const char *	name,
		char *	buf,
		size_t	len
	)

Get an engine specific attribute.

Definition at line 175 of file res_speech.c.

{
    return (speech->engine->get_setting ? speech->engine->get_setting(speech, name, buf, len) : -1);
}

References buf, ast_speech::engine, ast_speech_engine::get_setting, len(), and name.

Referenced by AST_TEST_DEFINE(), and speech_engine_read().

ast_speech_grammar_activate()

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.

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

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

Referenced by handle_speechactivategrammar(), and speech_activate().

ast_speech_grammar_deactivate()

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.

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

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

Referenced by handle_speechdeactivategrammar(), and speech_deactivate().

ast_speech_grammar_load()

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.

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

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

Referenced by handle_speechloadgrammar(), and speech_load().

ast_speech_grammar_unload()

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.

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

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

Referenced by handle_speechunloadgrammar(), and speech_unload().

ast_speech_new()

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.

{
    struct ast_speech_engine *engine = NULL;
    struct ast_speech *new_speech = NULL;
    struct ast_format_cap *joint;
    RAII_VAR(struct ast_format *, best, NULL, ao2_cleanup);
    RAII_VAR(struct ast_format *, best_translated, NULL, ao2_cleanup);
 
    /* Try to find the speech recognition engine that was requested */
    if (!(engine = ast_speech_find_engine(engine_name)))
        return NULL;
 
    joint = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
    if (!joint) {
        return NULL;
    }
 
    ast_format_cap_get_compatible(engine->formats, cap, joint);
    best = ast_format_cap_get_format(joint, 0);
    ao2_ref(joint, -1);
 
    if (!best) {
        if (ast_format_cap_iscompatible_format(engine->formats, ast_format_slin) != AST_FORMAT_CMP_NOT_EQUAL) {
            best = ao2_bump(ast_format_slin);
        } else {
            /*
             * If there is no overlap and the engine does not support slin, find the best
             * format to translate to and set that as the 'best' input format for the engine.
             * API consumer is responsible for translating to this format.
             * Safe to cast cap as ast_translator_best_choice does not modify the caps
             */
            if (ast_translator_best_choice(engine->formats, (struct ast_format_cap *)cap, &best, &best_translated)) {
                /* No overlapping formats and no translatable formats */
                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 = ao2_bump(best);
 
    /* 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, new_speech->format)) {
        ast_mutex_destroy(&new_speech->lock);
        ao2_ref(new_speech->format, -1);
        ast_free(new_speech);
        return NULL;
    }
 
    return new_speech;
}

References ao2_bump, ao2_cleanup, 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_free, ast_mutex_destroy, ast_mutex_init, ast_speech_change_state(), ast_speech_find_engine(), AST_SPEECH_STATE_NOT_READY, ast_translator_best_choice(), ast_speech_engine::create, ast_speech::engine, ast_speech::format, ast_speech_engine::formats, ast_speech::lock, NULL, RAII_VAR, and ast_speech::results.

Referenced by AST_TEST_DEFINE(), handle_speechcreate(), and speech_create().

ast_speech_register()

int ast_speech_register

(

struct ast_speech_engine *

engine

)

Register a speech recognition engine.

Definition at line 316 of file res_speech.c.

{
    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 (ast_speech_find_engine(engine->name)) {
        ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
        return -1;
    }
 
    ast_verb(5, "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(5, "Made '%s' the default speech recognition engine\n", engine->name);
    }
    AST_RWLIST_UNLOCK(&engines);
 
    return res;
}

References ast_log, AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_speech_find_engine(), ast_verb, ast_speech_engine::create, default_engine, ast_speech_engine::destroy, LOG_WARNING, ast_speech_engine::name, and ast_speech_engine::write.

Referenced by speech_engine_alloc_and_register().

ast_speech_results_free()

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.

{
    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;
}

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

Referenced by ast_speech_destroy(), ast_speech_start(), and AST_TEST_DEFINE().

ast_speech_results_get()

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.

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

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

Referenced by AST_TEST_DEFINE(), handle_speechrecognize(), and speech_background().

ast_speech_results_type_to_string()

const char * ast_speech_results_type_to_string

(

enum ast_speech_results_type

type

)

Convert a speech results type to a string.

Definition at line 294 of file res_speech.c.

{
    switch (type) {
    case AST_SPEECH_RESULTS_TYPE_NORMAL:
        return "normal";
    case AST_SPEECH_RESULTS_TYPE_NBEST:
        return "nbest";
    default:
        ast_assert(0);
        return "unknown";
    }
}

References ast_assert, AST_SPEECH_RESULTS_TYPE_NBEST, AST_SPEECH_RESULTS_TYPE_NORMAL, and type.

Referenced by speech_aeap_engine_change_results_type().

ast_speech_start()

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.

{
 
    /* 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;
}

References ast_clear_flag, AST_SPEECH_HAVE_RESULTS, AST_SPEECH_QUIET, ast_speech_results_free(), AST_SPEECH_SPOKE, ast_speech::engine, NULL, ast_speech::results, and ast_speech_engine::start.

Referenced by AST_TEST_DEFINE(), handle_speechrecognize(), speech_background(), and speech_start().

ast_speech_unregister()

int ast_speech_unregister

(

const char *

engine_name

)

Unregister a speech recognition engine.

Definition at line 347 of file res_speech.c.

{
    return ast_speech_unregister2(engine_name) == NULL ? -1 : 0;
}

References ast_speech_unregister2(), and NULL.

ast_speech_unregister2()

struct ast_speech_engine * ast_speech_unregister2

(

const char *

engine_name

)

Unregister a speech recognition engine.

Definition at line 352 of file res_speech.c.

{
    struct ast_speech_engine *engine = NULL;
 
    if (ast_strlen_zero(engine_name)) {
        return NULL;
    }
 
    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(5, "Unregistered speech recognition engine '%s'\n", engine_name);
            /* All went well */
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
    AST_RWLIST_UNLOCK(&engines);
 
    return engine;
}

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

Referenced by ast_speech_unregister(), load_engine(), unload_engine(), and unload_module().

ast_speech_unregister_engines()

void ast_speech_unregister_engines	(	int(*)(const struct ast_speech_engine *engine, void *data)	should_unregister,
		void *	data,
		void(*)(void *obj)	on_unregistered
	)

Unregister all speech recognition engines told to by callback.

Definition at line 380 of file res_speech.c.

{
    struct ast_speech_engine *engine = NULL;
 
    if (!should_unregister) {
        return;
    }
 
    AST_RWLIST_WRLOCK(&engines);
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
        if (should_unregister(engine, data)) {
            /* 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(5, "Unregistered speech recognition engine '%s'\n", engine->name);
            /* All went well */
            if (on_unregistered) {
                on_unregistered(engine);
            }
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
    AST_RWLIST_UNLOCK(&engines);
}

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_verb, default_engine, ast_speech_engine::name, NULL, and should_unregister().

Referenced by speech_observer_loaded().

ast_speech_write()

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.

{
    /* 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);
}

References AST_SPEECH_STATE_READY, ast_speech::engine, len(), ast_speech::state, and ast_speech_engine::write.

Referenced by handle_speechrecognize(), and speech_background().