Mon May 14 04:43:01 2007

Asterisk developer's documentation


speech.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2006, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Generic Speech Recognition API
00021  */
00022 
00023 #ifndef _ASTERISK_SPEECH_H
00024 #define _ASTERISK_SPEECH_H
00025 
00026 #if defined(__cplusplus) || defined(c_plusplus)
00027 extern "C" {
00028 #endif
00029 
00030 /* Speech structure flags */
00031 #define AST_SPEECH_QUIET (1 << 0) /* Quiet down output... they are talking */
00032 #define AST_SPEECH_SPOKE (1 << 1) /* Speaker did not speak */
00033 
00034 /* Speech structure states - in order of expected change */
00035 #define AST_SPEECH_STATE_NOT_READY 0 /* Not ready to accept audio */
00036 #define AST_SPEECH_STATE_READY 1 /* Accepting audio */
00037 #define AST_SPEECH_STATE_WAIT 2 /* Wait for results to become available */
00038 #define AST_SPEECH_STATE_DONE 3 /* Processing is done */
00039 
00040 enum ast_speech_results_type {
00041    AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
00042    AST_SPEECH_RESULTS_TYPE_NBEST,
00043 };
00044 
00045 /* Speech structure */
00046 struct ast_speech {
00047    /*! Structure lock */
00048    ast_mutex_t lock;
00049    /*! Set flags */
00050    unsigned int flags;
00051    /*! Processing sound (used when engine is processing audio and getting results) */
00052    char *processing_sound;
00053    /*! Current state of structure */
00054    int state;
00055    /*! Expected write format */
00056    int format;
00057    /*! Data for speech engine */
00058    void *data;
00059    /*! Cached results */
00060    struct ast_speech_result *results;
00061    /*! Type of results we want */
00062    enum ast_speech_results_type results_type;
00063    /*! Pointer to the engine used by this speech structure */
00064    struct ast_speech_engine *engine;
00065 };
00066   
00067 /* Speech recognition engine structure */
00068 struct ast_speech_engine {
00069    /*! Name of speech engine */
00070    char *name;
00071    /*! Set up the speech structure within the engine */
00072    int (*new)(struct ast_speech *speech);
00073    /*! Destroy any data set on the speech structure by the engine */
00074    int (*destroy)(struct ast_speech *speech);
00075    /*! Load a local grammar on the speech structure */
00076    int (*load)(struct ast_speech *speech, char *grammar_name, char *grammar);
00077    /*! Unload a local grammar */
00078    int (*unload)(struct ast_speech *speech, char *grammar_name);
00079    /*! Activate a loaded grammar */
00080    int (*activate)(struct ast_speech *speech, char *grammar_name);
00081    /*! Deactivate a loaded grammar */
00082    int (*deactivate)(struct ast_speech *speech, char *grammar_name);
00083    /*! Write audio to the speech engine */
00084    int (*write)(struct ast_speech *speech, void *data, int len);
00085    /*! Prepare engine to accept audio */
00086    int (*start)(struct ast_speech *speech);
00087    /*! Change an engine specific setting */
00088    int (*change)(struct ast_speech *speech, char *name, const char *value);
00089    /*! Change the type of results we want back */
00090    int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
00091    /*! Try to get results */
00092    struct ast_speech_result *(*get)(struct ast_speech *speech);
00093    /*! Accepted formats by the engine */
00094    int formats;
00095    AST_LIST_ENTRY(ast_speech_engine) list;
00096 };
00097 
00098 /* Result structure */
00099 struct ast_speech_result {
00100    /*! Recognized text */
00101    char *text;
00102    /*! Result score */
00103    int score;
00104    /*! NBest Alternative number if in NBest results type */
00105    int nbest_num;
00106    /*! Matched grammar */
00107    char *grammar;
00108    /*! List information */
00109    struct ast_speech_result *next;
00110 };
00111 
00112 /*! \brief Activate a grammar on a speech structure */
00113 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name);
00114 /*! \brief Deactivate a grammar on a speech structure */
00115 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name);
00116 /*! \brief Load a grammar on a speech structure (not globally) */
00117 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar);
00118 /*! \brief Unload a grammar */
00119 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name);
00120 /*! \brief Get speech recognition results */
00121 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
00122 /*! \brief Free a set of results */
00123 int ast_speech_results_free(struct ast_speech_result *result);
00124 /*! \brief Indicate to the speech engine that audio is now going to start being written */
00125 void ast_speech_start(struct ast_speech *speech);
00126 /*! \brief Create a new speech structure */
00127 struct ast_speech *ast_speech_new(char *engine_name, int format);
00128 /*! \brief Destroy a speech structure */
00129 int ast_speech_destroy(struct ast_speech *speech);
00130 /*! \brief Write audio to the speech engine */
00131 int ast_speech_write(struct ast_speech *speech, void *data, int len);
00132 /*! \brief Change an engine specific attribute */
00133 int ast_speech_change(struct ast_speech *speech, char *name, const char *value);
00134 /*! \brief Change the type of results we want */
00135 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
00136 /*! \brief Change state of a speech structure */
00137 int ast_speech_change_state(struct ast_speech *speech, int state);
00138 /*! \brief Register a speech recognition engine */
00139 int ast_speech_register(struct ast_speech_engine *engine);
00140 /*! \brief Unregister a speech recognition engine */
00141 int ast_speech_unregister(char *engine_name);
00142 
00143 #if defined(__cplusplus) || defined(c_plusplus)
00144 }
00145 #endif
00146 
00147 #endif /* _ASTERISK_SPEECH_H */

Generated on Mon May 14 04:43:01 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1