Merged revisions 79207 via svnmerge from
[asterisk/asterisk.git] / include / asterisk / speech.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Generic Speech Recognition API
21  */
22
23 #ifndef _ASTERISK_SPEECH_H
24 #define _ASTERISK_SPEECH_H
25
26 #if defined(__cplusplus) || defined(c_plusplus)
27 extern "C" {
28 #endif
29
30 /* Speech structure flags */
31 enum ast_speech_flags {
32         AST_SPEECH_QUIET = (1 << 0),        /* Quiet down output... they are talking */
33         AST_SPEECH_SPOKE = (1 << 1),        /* Speaker spoke! */
34         AST_SPEECH_HAVE_RESULTS = (1 << 2), /* Results are present */
35 };
36
37 /* Speech structure states - in order of expected change */
38 enum ast_speech_states {
39         AST_SPEECH_STATE_NOT_READY = 0, /* Not ready to accept audio */
40         AST_SPEECH_STATE_READY, /* Accepting audio */
41         AST_SPEECH_STATE_WAIT, /* Wait for results to become available */
42         AST_SPEECH_STATE_DONE, /* Processing is all done */
43 };
44
45 enum ast_speech_results_type {
46         AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
47         AST_SPEECH_RESULTS_TYPE_NBEST,
48 };
49
50 /* Speech structure */
51 struct ast_speech {
52         /*! Structure lock */
53         ast_mutex_t lock;
54         /*! Set flags */
55         unsigned int flags;
56         /*! Processing sound (used when engine is processing audio and getting results) */
57         char *processing_sound;
58         /*! Current state of structure */
59         int state;
60         /*! Expected write format */
61         int format;
62         /*! Data for speech engine */
63         void *data;
64         /*! Cached results */
65         struct ast_speech_result *results;
66         /*! Type of results we want */
67         enum ast_speech_results_type results_type;
68         /*! Pointer to the engine used by this speech structure */
69         struct ast_speech_engine *engine;
70 };
71   
72 /* Speech recognition engine structure */
73 struct ast_speech_engine {
74         /*! Name of speech engine */
75         char *name;
76         /*! Set up the speech structure within the engine */
77         int (*create)(struct ast_speech *speech, int format);
78         /*! Destroy any data set on the speech structure by the engine */
79         int (*destroy)(struct ast_speech *speech);
80         /*! Load a local grammar on the speech structure */
81         int (*load)(struct ast_speech *speech, char *grammar_name, char *grammar);
82         /*! Unload a local grammar */
83         int (*unload)(struct ast_speech *speech, char *grammar_name);
84         /*! Activate a loaded grammar */
85         int (*activate)(struct ast_speech *speech, char *grammar_name);
86         /*! Deactivate a loaded grammar */
87         int (*deactivate)(struct ast_speech *speech, char *grammar_name);
88         /*! Write audio to the speech engine */
89         int (*write)(struct ast_speech *speech, void *data, int len);
90         /*! Signal DTMF was received */
91         int (*dtmf)(struct ast_speech *speech, char dtmf);
92         /*! Prepare engine to accept audio */
93         int (*start)(struct ast_speech *speech);
94         /*! Change an engine specific setting */
95         int (*change)(struct ast_speech *speech, char *name, const char *value);
96         /*! Change the type of results we want back */
97         int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
98         /*! Try to get results */
99         struct ast_speech_result *(*get)(struct ast_speech *speech);
100         /*! Accepted formats by the engine */
101         int formats;
102         AST_LIST_ENTRY(ast_speech_engine) list;
103 };
104
105 /* Result structure */
106 struct ast_speech_result {
107         /*! Recognized text */
108         char *text;
109         /*! Result score */
110         int score;
111         /*! NBest Alternative number if in NBest results type */
112         int nbest_num;
113         /*! Matched grammar */
114         char *grammar;
115         /*! List information */
116         AST_LIST_ENTRY(ast_speech_result) list;
117 };
118
119 /*! \brief Activate a grammar on a speech structure */
120 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name);
121 /*! \brief Deactivate a grammar on a speech structure */
122 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name);
123 /*! \brief Load a grammar on a speech structure (not globally) */
124 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar);
125 /*! \brief Unload a grammar */
126 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name);
127 /*! \brief Get speech recognition results */
128 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
129 /*! \brief Free a set of results */
130 int ast_speech_results_free(struct ast_speech_result *result);
131 /*! \brief Indicate to the speech engine that audio is now going to start being written */
132 void ast_speech_start(struct ast_speech *speech);
133 /*! \brief Create a new speech structure */
134 struct ast_speech *ast_speech_new(char *engine_name, int formats);
135 /*! \brief Destroy a speech structure */
136 int ast_speech_destroy(struct ast_speech *speech);
137 /*! \brief Write audio to the speech engine */
138 int ast_speech_write(struct ast_speech *speech, void *data, int len);
139 /*! \brief Signal to the engine that DTMF was received */
140 int ast_speech_dtmf(struct ast_speech *speech, char dtmf);
141 /*! \brief Change an engine specific attribute */
142 int ast_speech_change(struct ast_speech *speech, char *name, const char *value);
143 /*! \brief Change the type of results we want */
144 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
145 /*! \brief Change state of a speech structure */
146 int ast_speech_change_state(struct ast_speech *speech, int state);
147 /*! \brief Register a speech recognition engine */
148 int ast_speech_register(struct ast_speech_engine *engine);
149 /*! \brief Unregister a speech recognition engine */
150 int ast_speech_unregister(char *engine_name);
151
152 #if defined(__cplusplus) || defined(c_plusplus)
153 }
154 #endif
155
156 #endif /* _ASTERISK_SPEECH_H */