asterisk/include/asterisk/speech.h

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2006, Digium, Inc.
 *
 * Joshua Colp <jcolp@digium.com>
 *
 * 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 */