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