fix caffiene-induced typo.
[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 #define AST_SPEECH_QUIET (1 << 0) /* Quiet down output... they are talking */
32
33 /* Speech structure states - in order of expected change */
34 #define AST_SPEECH_STATE_NOT_READY 0 /* Not ready to accept audio */
35 #define AST_SPEECH_STATE_READY 1 /* Accepting audio */
36 #define AST_SPEECH_STATE_WAIT 2 /* Wait for results to become available */
37 #define AST_SPEECH_STATE_DONE 3 /* Processing is done */
38
39 /* Speech structure */
40 struct ast_speech {
41         /*! Structure lock */
42         ast_mutex_t lock;
43         /*! Set flags */
44         unsigned int flags;
45         /*! Processing sound (used when engine is processing audio and getting results) */
46         char *processing_sound;
47         /*! Current state of structure */
48         int state;
49         /*! Expected write format */
50         int format;
51         /*! Data for speech engine */
52         void *data;
53         /*! Pointer to the engine used by this speech structure */
54         struct ast_speech_engine *engine;
55 };
56   
57 /* Speech recognition engine structure */
58 struct ast_speech_engine {
59         /*! Name of speech engine */
60         char *name;
61         /*! Set up the speech structure within the engine */
62         int (*new)(struct ast_speech *speech);
63         /*! Destroy any data set on the speech structure by the engine */
64         int (*destroy)(struct ast_speech *speech);
65         /*! Load a local grammar on the speech structure */
66         int (*load)(struct ast_speech *speech, char *grammar_name, char *grammar);
67         /*! Unload a local grammar */
68         int (*unload)(struct ast_speech *speech, char *grammar_name);
69         /*! Activate a loaded grammar */
70         int (*activate)(struct ast_speech *speech, char *grammar_name);
71         /*! Deactivate a loaded grammar */
72         int (*deactivate)(struct ast_speech *speech, char *grammar_name);
73         /*! Write audio to the speech engine */
74         int (*write)(struct ast_speech *speech, void *data, int len);
75         /*! Prepare engine to accept audio */
76         int (*start)(struct ast_speech *speech);
77         /*! Try to get results */
78         struct ast_speech_result *(*get)(struct ast_speech *speech);
79         /*! Accepted formats by the engine */
80         int formats;
81         AST_LIST_ENTRY(ast_speech_engine) list;
82 };
83
84 /* Result structure */
85 struct ast_speech_result {
86         /*! Recognized text */
87         char *text;
88         /*! Result score */
89         int score;
90         /*! Next result (may not always be present) */
91         struct ast_speech_result *next;
92 };
93
94 /*! \brief Activate a grammar on a speech structure */
95 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name);
96 /*! \brief Deactivate a grammar on a speech structure */
97 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name);
98 /*! \brief Load a grammar on a speech structure (not globally) */
99 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar);
100 /*! \brief Unload a grammar */
101 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name);
102 /*! \brief Get speech recognition results */
103 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
104 /*! \brief Free a set of results */
105 int ast_speech_results_free(struct ast_speech_result *result);
106 /*! \brief Indicate to the speech engine that audio is now going to start being written */
107 void ast_speech_start(struct ast_speech *speech);
108 /*! \brief Create a new speech structure */
109 struct ast_speech *ast_speech_new(char *engine_name, int format);
110 /*! \brief Destroy a speech structure */
111 int ast_speech_destroy(struct ast_speech *speech);
112 /*! \brief Write audio to the speech engine */
113 int ast_speech_write(struct ast_speech *speech, void *data, int len);
114 /*! \brief Change state of a speech structure */
115 int ast_speech_change_state(struct ast_speech *speech, int state);
116 /*! \brief Register a speech recognition engine */
117 int ast_speech_register(struct ast_speech_engine *engine);
118 /*! \brief Unregister a speech recognition engine */
119 int ast_speech_unregister(char *engine_name);
120
121 #if defined(__cplusplus) || defined(c_plusplus)
122 }
123 #endif
124
125 #endif /* _ASTERISK_SPEECH_H */