166f309eee330f6e97c91c3910875be84c1db41d
[asterisk/asterisk.git] / doc / speechrec.txt
1 Generic Speech Recognition API
2
3 *** NOTE:  To use the API, you must laod the res_speech.so module before any connectors.  For your convenience, there is a preload line commented out in the modules.conf sample file. ***
4
5 Dialplan Applications:
6
7 The dialplan API is based around a single speech utilities application file, which exports many applications to be used for speech recognition. These include an application to prepare for speech recognition, activate a grammar, and play back a sound file while waiting for the person to speak. Using a combination of these applications you can easily make a dialplan use speech recognition without worrying about what speech recognition engine is being used.
8
9 SpeechCreate(Engine Name):
10
11 This application creates information to be used by all the other applications. It must be called before doing any speech recognition activities such as activating a grammar. It takes the engine name to use as the argument, if not specified the default engine will be used.
12
13 If an error occurs are you are not able to create an object, the variable ERROR will be set to 1. You can then exit your speech recognition specific context and play back an error message, or resort to a DTMF based IVR.
14
15 SpeechActivateGrammar(Grammar Name):
16
17 This activates the specified grammar to be recognized by the engine. A grammar tells the speech recognition engine what to recognize, and how to portray it back to you in the dialplan. The grammar name is the only argument to this application.
18
19 SpeechStart():
20
21 Tell the speech recognition engine that it should start trying to get results from audio being fed to it. This has no arguments.
22
23 SpeechBackground(Sound File|Timeout):
24
25 This application plays a sound file and waits for the person to speak. Once they start speaking playback of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate the speech recognition engine is working. Once results are available the application returns and results (score and text) are available as dialplan variables. The first text and score are ${TEXT0} AND ${SCORE0} while the second are ${TEXT1} and ${SCORE1}. This may change in the future, however, to use a dialplan function instead of dialplan variables. Note it is possible to have more then one result. The first argument is the sound file and the second is the timeout. Note the timeout will only start once the sound file has stopped playing. If the timeout is reached, then the variable SILENCE is set to 1 so that you will know that the person did not speak anything.
26
27 SpeechDeactivateGrammar(Grammar Name):
28
29 This deactivates the specified grammar so that it is no longer recognized. The only argument is the grammar name to deactivate.
30
31 SpeechProcessingSound(Sound File):
32
33 This changes the processing sound that SpeechBackground plays back when the speech recognition engine is processing and working to get results. It takes the sound file as the only argument.
34
35 SpeechDestroy():
36
37 This destroys the information used by all the other speech recognition applications. If you call this application but end up wanting to recognize more speech, you must call SpeechCreate again before calling any other application. It takes no arguments.
38
39 Dialplan Flow:
40
41 1. Create a speech recognition object using SpeechCreate()
42 2. Activate your grammars using SpeechActivateGrammar(Grammar Name)
43 3. Call SpeechStart() to indicate you are going to do speech recognition immediately
44 4. Play back your audio and wait for recognition using SpeechBackground(Sound File|Timeout)
45 5. Check the results and do things based on them
46 6. Deactivate your grammars using SpeechDeactivateGrammar(Grammar Name)
47 7. Destroy your speech recognition object using SpeechDestroy()
48
49 Dialplan Examples:
50
51 This is pretty cheeky in that it does not confirmation of results. As well the way the grammar is written it returns the person's extension instead of their name so we can just do a Goto based on the result text.
52
53 company-directory.gram
54
55 #ABNF 1.0;
56 language en-US;
57 mode voice;
58 tag-format <lumenvox/1.0>;
59
60 root $company_directory;
61
62 $josh = (Joshua | Josh) [Colp]:"6066";
63 $mark = Mark [Spencer] | Markster:"4569";
64 $kevin = Kevin [Fleming]:"2567";
65
66 $company_directory = ($josh | $mark | $kevin) { $ = parseInt($$) };
67
68 dialplan logic
69
70 [dial-by-name]
71 exten => s,1,SpeechCreate()
72 exten => s,2,SpeechActivateGrammar(company-directory)
73 exten => s,3,SpeechStart()
74 exten => s,4,SpeechBackground(who-would-you-like-to-dial)
75 exten => s,5,SpeechDeactivateGrammar(company-directory)
76 exten => s,6,SpeechDestroy()
77 exten => s,7,Goto(internal-extensions-${TEXT0})
78
79 Useful Dialplan Tidbits:
80
81 A simple macro that can be used for confirm of a result. Requires some sound files. ARG1 is equal to the file to play back after "I heard..." is played.
82
83 [macro-speech-confirm]
84 exten => s,1,SpeechActivateGrammar(yes_no)
85 exten => s,2,Set(OLDTEXT0=${TEXT0})
86 exten => s,3,Playback(heard)
87 exten => s,4,Playback(${ARG1})
88 exten => s,5,SpeechStart()
89 exten => s,6,SpeechBackground(correct)
90 exten => s,7,Set(CONFIRM=${TEXT0})
91 exten => s,8,GotoIf($["${TEXT0}" = "1"]?9:10)
92 exten => s,9,Set(CONFIRM=yes)
93 exten => s,10,Set(${TEXT0}=${OLDTEXT0})
94 exten => s,11,SpeechDeactivateGrammar(yes_no)
95
96 C API
97
98 The module res_speech.so exports a C based API that any developer can use to speech recognize enable their application. The API gives greater control, but requires the developer to do more on their end in comparison to the dialplan speech utilities.
99
100 For all API calls that return an integer value a non-zero value indicates an error has occured.
101
102 Creating a speech structure:
103
104 struct ast_speech *ast_speech_new(char *engine_name, int format)
105
106 struct ast_speech *speech = ast_speech_new(NULL, AST_FORMAT_SLINEAR);
107
108 This will create a new speech structure that will be returned to you. The speech recognition engine name is optional and if NULL the default one will be used. As well for now format should always be AST_FORMAT_SLINEAR.
109
110 Activating a grammar:
111
112 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
113
114 res = ast_speech_grammar_activate(speech, "yes_no");
115
116 This activates the specified grammar on the speech structure passed to it.
117
118 Start recognizing audio:
119
120 void ast_speech_start(struct ast_speech *speech)
121
122 ast_speech_start(speech);
123
124 This essentially tells the speech recognition engine that you will be feeding audio to it from then on. It MUST be called every time before you start feeding audio to the speech structure.
125
126 Send audio to be recognized:
127
128 int ast_speech_write(struct ast_speech *speech, void *data, int len)
129
130 res = ast_speech_write(speech, fr->data, fr->datalen);
131
132 This writes audio to the speech structure that will then be recognized. It must be written signed linear only at this time. In the future other formats may be supported.
133
134 Checking for results:
135
136 The way the generic speech recognition API is written is that the speech structure will undergo state changes to indicate progress of recognition. The states are outlined below:
137
138 AST_SPEECH_STATE_NOT_READY - The speech structure is not ready to accept audio
139 AST_SPEECH_STATE_READY - You may write audio to the speech structure
140 AST_SPEECH_STATE_WAIT - No more audio should be written, and results will be available soon.
141 AST_SPEECH_STATE_DONE - Results are available and the speech structure can only be used again by calling ast_speech_start
142
143 It is up to you to monitor these states. Current state is available via a variable on the speech structure. (state)
144
145 Knowing when to stop playback:
146
147 If you are playing back a sound file to the user and you want to know when to stop play back because the individual started talking use the following.
148
149 ast_test_flag(speech, AST_SPEECH_QUIET) - This will return a positive value when the person has started talking.
150
151 Getting results:
152
153 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
154
155 struct ast_speech_result *results = ast_speech_results_get(speech);
156
157 This will return a linked list of result structures. A result structure looks like the following:
158
159 struct ast_speech_result {
160         /*! Recognized text */
161         char *text;
162         /*! Result score */
163         int score;
164         /*! Next result (may not always be present) */
165         struct ast_speech_result *next;
166 };
167
168 Freeing a set of results:
169
170 int ast_speech_results_free(struct ast_speech_result *result)
171
172 res = ast_speech_results_free(results);
173
174 This will free all results on a linked list. Results MAY NOT be used as the memory will have been freed.
175
176 Deactivating a grammar:
177
178 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
179
180 res = ast_speech_grammar_deactivate(speech, "yes_no");
181
182 This deactivates the specified grammar on the speech structure.
183
184 Destroying a speech structure:
185
186 int ast_speech_destroy(struct ast_speech *speech)
187
188 res = ast_speech_destroy(speech);
189
190 This will free all associated memory with the speech structure and destroy it with the speech recognition engine.
191
192 Loading a grammar on a speech structure:
193
194 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
195
196 res = ast_speech_grammar_load(speech, "builtin:yes_no", "yes_no");
197
198 Unloading a grammar on a speech structure:
199
200 If you load a grammar on a speech structure it is preferred that you unload it as well, or you may cause a memory leak. Don't say I didn't warn you.
201
202 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
203
204 res = ast_speech_grammar_unload(speech, "yes_no");
205
206 This unloads the specified grammar from the speech structure.