After some study, thought, comparing, etc. I've backed out the previous universal...
[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 };
35
36 /* Speech structure states - in order of expected change */
37 enum ast_speech_states {
38         AST_SPEECH_STATE_NOT_READY = 0, /* Not ready to accept audio */
39         AST_SPEECH_STATE_READY, /* Accepting audio */
40         AST_SPEECH_STATE_WAIT, /* Wait for results to become available */
41         AST_SPEECH_STATE_DONE, /* Processing is all done */
42 };
43
44 enum ast_speech_results_type {
45         AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
46         AST_SPEECH_RESULTS_TYPE_NBEST,
47 };
48
49 /* Speech structure */
50 struct ast_speech {
51         /*! Structure lock */
52         ast_mutex_t lock;
53         /*! Set flags */
54         unsigned int flags;
55         /*! Processing sound (used when engine is processing audio and getting results) */
56         char *processing_sound;
57         /*! Current state of structure */
58         int state;
59         /*! Expected write format */
60         int format;
61         /*! Data for speech engine */
62         void *data;
63         /*! Cached results */
64         struct ast_speech_result *results;
65         /*! Type of results we want */
66         enum ast_speech_results_type results_type;
67         /*! Pointer to the engine used by this speech structure */
68         struct ast_speech_engine *engine;
69 };
70   
71 /* Speech recognition engine structure */
72 struct ast_speech_engine {
73         /*! Name of speech engine */
74         char *name;
75         /*! Set up the speech structure within the engine */
76         int (*create)(struct ast_speech *speech, int format);
77         /*! Destroy any data set on the speech structure by the engine */
78         int (*destroy)(struct ast_speech *speech);
79         /*! Load a local grammar on the speech structure */
80         int (*load)(struct ast_speech *speech, char *grammar_name, char *grammar);
81         /*! Unload a local grammar */
82         int (*unload)(struct ast_speech *speech, char *grammar_name);
83         /*! Activate a loaded grammar */
84         int (*activate)(struct ast_speech *speech, char *grammar_name);
85         /*! Deactivate a loaded grammar */
86         int (*deactivate)(struct ast_speech *speech, char *grammar_name);
87         /*! Write audio to the speech engine */
88         int (*write)(struct ast_speech *speech, void *data, int len);
89         /*! Prepare engine to accept audio */
90         int (*start)(struct ast_speech *speech);
91         /*! Change an engine specific setting */
92         int (*change)(struct ast_speech *speech, char *name, const char *value);
93         /*! Change the type of results we want back */
94         int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
95         /*! Try to get results */
96         struct ast_speech_result *(*get)(struct ast_speech *speech);
97         /*! Accepted formats by the engine */
98         int formats;
99         AST_LIST_ENTRY(ast_speech_engine) list;
100 };
101
102 /* Result structure */
103 struct ast_speech_result {
104         /*! Recognized text */
105         char *text;
106         /*! Result score */
107         int score;
108         /*! NBest Alternative number if in NBest results type */
109         int nbest_num;
110         /*! Matched grammar */
111         char *grammar;
112         /*! List information */
113         AST_LIST_ENTRY(ast_speech_result) list;
114 };
115
116 /*! \brief Activate a grammar on a speech structure */
117 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name);
118 /*! \brief Deactivate a grammar on a speech structure */
119 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name);
120 /*! \brief Load a grammar on a speech structure (not globally) */
121 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar);
122 /*! \brief Unload a grammar */
123 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name);
124 /*! \brief Get speech recognition results */
125 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
126 /*! \brief Free a set of results */
127 int ast_speech_results_free(struct ast_speech_result *result);
128 /*! \brief Indicate to the speech engine that audio is now going to start being written */
129 void ast_speech_start(struct ast_speech *speech);
130 /*! \brief Create a new speech structure */
131 struct ast_speech *ast_speech_new(char *engine_name, int formats);
132 /*! \brief Destroy a speech structure */
133 int ast_speech_destroy(struct ast_speech *speech);
134 /*! \brief Write audio to the speech engine */
135 int ast_speech_write(struct ast_speech *speech, void *data, int len);
136 /*! \brief Change an engine specific attribute */
137 int ast_speech_change(struct ast_speech *speech, char *name, const char *value);
138 /*! \brief Change the type of results we want */
139 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
140 /*! \brief Change state of a speech structure */
141 int ast_speech_change_state(struct ast_speech *speech, int state);
142 /*! \brief Register a speech recognition engine */
143 int ast_speech_register(struct ast_speech_engine *engine);
144 /*! \brief Unregister a speech recognition engine */
145 int ast_speech_unregister(char *engine_name);
146
147 #if defined(__cplusplus) || defined(c_plusplus)
148 }
149 #endif
150
151 #endif /* _ASTERISK_SPEECH_H */