Thu Sep 7 01:03:05 2017

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

Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1