Sat Aug 6 00:39:32 2011

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 #define AST_SPEECH_HAVE_RESULTS (1 << 2) /* Results are present */
00034 
00035 /* Speech structure states - in order of expected change */
00036 #define AST_SPEECH_STATE_NOT_READY 0 /* Not ready to accept audio */
00037 #define AST_SPEECH_STATE_READY 1 /* Accepting audio */
00038 #define AST_SPEECH_STATE_WAIT 2 /* Wait for results to become available */
00039 #define AST_SPEECH_STATE_DONE 3 /* Processing is done */
00040 
00041 enum ast_speech_results_type {
00042    AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
00043    AST_SPEECH_RESULTS_TYPE_NBEST,
00044 };
00045 
00046 /* Speech structure */
00047 struct ast_speech {
00048    /*! Structure lock */
00049    ast_mutex_t lock;
00050    /*! Set flags */
00051    unsigned int flags;
00052    /*! Processing sound (used when engine is processing audio and getting results) */
00053    char *processing_sound;
00054    /*! Current state of structure */
00055    int state;
00056    /*! Expected write format */
00057    int format;
00058    /*! Data for speech engine */
00059    void *data;
00060    /*! Cached results */
00061    struct ast_speech_result *results;
00062    /*! Type of results we want */
00063    enum ast_speech_results_type results_type;
00064    /*! Pointer to the engine used by this speech structure */
00065    struct ast_speech_engine *engine;
00066 };
00067   
00068 /* Speech recognition engine structure */
00069 struct ast_speech_engine {
00070    /*! Name of speech engine */
00071    char *name;
00072    /*! Set up the speech structure within the engine */
00073    int (*create)(struct ast_speech *speech);
00074    /*! Destroy any data set on the speech structure by the engine */
00075    int (*destroy)(struct ast_speech *speech);
00076    /*! Load a local grammar on the speech structure */
00077    int (*load)(struct ast_speech *speech, char *grammar_name, char *grammar);
00078    /*! Unload a local grammar */
00079    int (*unload)(struct ast_speech *speech, char *grammar_name);
00080    /*! Activate a loaded grammar */
00081    int (*activate)(struct ast_speech *speech, char *grammar_name);
00082    /*! Deactivate a loaded grammar */
00083    int (*deactivate)(struct ast_speech *speech, char *grammar_name);
00084    /*! Write audio to the speech engine */
00085    int (*write)(struct ast_speech *speech, void *data, int len);
00086    /*! Signal DTMF was received */
00087    int (*dtmf)(struct ast_speech *speech, const char *dtmf);
00088    /*! Prepare engine to accept audio */
00089    int (*start)(struct ast_speech *speech);
00090    /*! Change an engine specific setting */
00091    int (*change)(struct ast_speech *speech, char *name, const char *value);
00092    /*! Change the type of results we want back */
00093    int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
00094    /*! Try to get results */
00095    struct ast_speech_result *(*get)(struct ast_speech *speech);
00096    /*! Accepted formats by the engine */
00097    int formats;
00098    AST_LIST_ENTRY(ast_speech_engine) list;
00099 };
00100 
00101 /* Result structure */
00102 struct ast_speech_result {
00103    /*! Recognized text */
00104    char *text;
00105    /*! Result score */
00106    int score;
00107    /*! NBest Alternative number if in NBest results type */
00108    int nbest_num;
00109    /*! Matched grammar */
00110    char *grammar;
00111    /*! List information */
00112    struct ast_speech_result *next;
00113 };
00114 
00115 /*! \brief Activate a grammar on a speech structure */
00116 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name);
00117 /*! \brief Deactivate a grammar on a speech structure */
00118 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name);
00119 /*! \brief Load a grammar on a speech structure (not globally) */
00120 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar);
00121 /*! \brief Unload a grammar */
00122 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name);
00123 /*! \brief Get speech recognition results */
00124 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
00125 /*! \brief Free a set of results */
00126 int ast_speech_results_free(struct ast_speech_result *result);
00127 /*! \brief Indicate to the speech engine that audio is now going to start being written */
00128 void ast_speech_start(struct ast_speech *speech);
00129 /*! \brief Create a new speech structure */
00130 struct ast_speech *ast_speech_new(char *engine_name, int format);
00131 /*! \brief Destroy a speech structure */
00132 int ast_speech_destroy(struct ast_speech *speech);
00133 /*! \brief Write audio to the speech engine */
00134 int ast_speech_write(struct ast_speech *speech, void *data, int len);
00135 /*! \brief Signal to the engine that DTMF was received */
00136 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf);
00137 /*! \brief Change an engine specific attribute */
00138 int ast_speech_change(struct ast_speech *speech, char *name, const char *value);
00139 /*! \brief Change the type of results we want */
00140 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
00141 /*! \brief Change state of a speech structure */
00142 int ast_speech_change_state(struct ast_speech *speech, int state);
00143 /*! \brief Register a speech recognition engine */
00144 int ast_speech_register(struct ast_speech_engine *engine);
00145 /*! \brief Unregister a speech recognition engine */
00146 int ast_speech_unregister(char *engine_name);
00147 
00148 #if defined(__cplusplus) || defined(c_plusplus)
00149 }
00150 #endif
00151 
00152 #endif /* _ASTERISK_SPEECH_H */

Generated on Sat Aug 6 00:39:32 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7