speech.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2006, Digium, Inc.
 *
 * Joshua Colp <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 * \brief Generic Speech Recognition API
 */

#ifndef _ASTERISK_SPEECH_H
#define _ASTERISK_SPEECH_H

#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif

/* Speech structure flags */
enum ast_speech_flags {
 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 */
};

/* Speech structure states - in order of expected change */
enum ast_speech_states {
 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 */
};

enum ast_speech_results_type {
 AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
 AST_SPEECH_RESULTS_TYPE_NBEST,
};

/* Speech structure */
struct ast_speech {
 /*! Structure lock */
 ast_mutex_t lock;
 /*! Set flags */
 unsigned int flags;
 /*! Processing sound (used when engine is processing audio and getting results) */
 char *processing_sound;
 /*! Current state of structure */
 int state;
 /*! Expected write format */
 struct ast_format *format;
 /*! Data for speech engine */
 void *data;
 /*! Cached results */
 struct ast_speech_result *results;
 /*! Type of results we want */
 enum ast_speech_results_type results_type;
 /*! Pointer to the engine used by this speech structure */
 struct ast_speech_engine *engine;
};

/* Speech recognition engine structure */
struct ast_speech_engine {
 /*! Name of speech engine */
 char *name;
 /*! Set up the speech structure within the engine */
 int (*create)(struct ast_speech *speech, struct ast_format *format);
 /*! Destroy any data set on the speech structure by the engine */
 int (*destroy)(struct ast_speech *speech);
 /*! Load a local grammar on the speech structure */
 int (*load)(struct ast_speech *speech, const char *grammar_name, const char *grammar);
 /*! Unload a local grammar */
 int (*unload)(struct ast_speech *speech, const char *grammar_name);
 /*! Activate a loaded grammar */
 int (*activate)(struct ast_speech *speech, const char *grammar_name);
 /*! Deactivate a loaded grammar */
 int (*deactivate)(struct ast_speech *speech, const char *grammar_name);
 /*! Write audio to the speech engine */
 int (*write)(struct ast_speech *speech, void *data, int len);
 /*! Signal DTMF was received */
 int (*dtmf)(struct ast_speech *speech, const char *dtmf);
 /*! Prepare engine to accept audio */
 int (*start)(struct ast_speech *speech);
 /*! Change an engine specific setting */
 int (*change)(struct ast_speech *speech, const char *name, const char *value);
 /*! Get an engine specific setting */
 int (*get_setting)(struct ast_speech *speech, const char *name, char *buf, size_t len);
 /*! Change the type of results we want back */
 int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
 /*! Try to get results */
 struct ast_speech_result *(*get)(struct ast_speech *speech);
 /*! Accepted formats by the engine */
 struct ast_format_cap *formats;
 AST_LIST_ENTRY(ast_speech_engine) list;
};

/* Result structure */
struct ast_speech_result {
 /*! Recognized text */
 char *text;
 /*! Result score */
 int score;
 /*! NBest Alternative number if in NBest results type */
 int nbest_num;
 /*! Matched grammar */
 char *grammar;
 /*! List information */
 AST_LIST_ENTRY(ast_speech_result) list;
};

/*! \brief Activate a grammar on a speech structure */
int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name);
/*! \brief Deactivate a grammar on a speech structure */
int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name);
/*! \brief Load a grammar on a speech structure (not globally) */
int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar);
/*! \brief Unload a grammar */
int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name);
/*! \brief Get speech recognition results */
struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
/*! \brief Free a set of results */
int ast_speech_results_free(struct ast_speech_result *result);
/*! \brief Indicate to the speech engine that audio is now going to start being written */
void ast_speech_start(struct ast_speech *speech);
/*! \brief Create a new speech structure */
struct ast_speech *ast_speech_new(const char *engine_name, const struct ast_format_cap *formats);
/*! \brief Destroy a speech structure */
int ast_speech_destroy(struct ast_speech *speech);
/*! \brief Write audio to the speech engine */
int ast_speech_write(struct ast_speech *speech, void *data, int len);
/*! \brief Signal to the engine that DTMF was received */
int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf);
/*! \brief Change an engine specific attribute */
int ast_speech_change(struct ast_speech *speech, const char *name, const char *value);
/*! \brief Get an engine specific attribute */
int ast_speech_get_setting(struct ast_speech *speech, const char *name, char *buf, size_t len);
/*! \brief Change the type of results we want */
int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
/*! \brief Change state of a speech structure */
int ast_speech_change_state(struct ast_speech *speech, int state);
/*! \brief Register a speech recognition engine */
int ast_speech_register(struct ast_speech_engine *engine);
/*! \brief Unregister a speech recognition engine */
int ast_speech_unregister(const char *engine_name);

#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

#endif /* _ASTERISK_SPEECH_H */