doc/speechrec.txt

   1 The Asterisk Speech Recognition API
   2 ===================================
   3
   4 The generic speech recognition engine is implemented in the res_speech.so module.
   5 This module connects through the API to speech recognition software, that is
   6 not included in the module.
   7
   8 To use the API, you must load the res_speech.so module before any connectors.
   9 For your convenience, there is a preload line commented out in the modules.conf
  10 sample file.
  11
  12 * Dialplan Applications:
  13 ------------------------
  14
  15 The dialplan API is based around a single speech utilities application file,
  16 which exports many applications to be used for speech recognition. These include an
  17 application to prepare for speech recognition, activate a grammar, and play back a
  18 sound file while waiting for the person to speak. Using a combination of these applications
  19 you can easily make a dialplan use speech recognition without worrying about what
  20 speech recognition engine is being used.
  21
  22 - SpeechCreate(Engine Name):
  23
  24 This application creates information to be used by all the other applications.
  25 It must be called before doing any speech recognition activities such as activating a
  26 grammar. It takes the engine name to use as the argument, if not specified the default
  27 engine will be used.
  28
  29 If an error occurs are you are not able to create an object, the variable ERROR will be
  30 set to 1. You can then exit your speech recognition specific context and play back an
  31 error message, or resort to a DTMF based IVR.
  32
  33 - SpeechLoadGrammar(Grammar Name|Path):
  34
  35 Loads grammar locally on a channel. Note that the grammar is only available as long as the
  36 channel exists, and you must call SpeechUnloadGrammar before all is done or you may cause a
  37 memory leak. First argument is the grammar name that it will be loaded as and second
  38 argument is the path to the grammar.
  39
  40 - SpeechUnloadGrammar(Grammar Name):
  41
  42 Unloads a locally loaded grammar and frees any memory used by it. The only argument is the
  43 name of the grammar to unload.
  44
  45 - SpeechActivateGrammar(Grammar Name):
  46
  47 This activates the specified grammar to be recognized by the engine. A grammar tells the
  48 speech recognition engine what to recognize, and how to portray it back to you in the
  49 dialplan. The grammar name is the only argument to this application.
  50
  51 - SpeechStart():
  52
  53 Tell the speech recognition engine that it should start trying to get results from audio
  54 being fed to it. This has no arguments.
  55
  56 - SpeechBackground(Sound File|Timeout):
  57
  58 This application plays a sound file and waits for the person to speak. Once they start
  59 speaking playback of the file stops, and silence is heard. Once they stop talking the
  60 processing sound is played to indicate the speech recognition engine is working. Note it is
  61 possible to have more then one result. The first argument is the sound file and the second is the
  62 timeout. Note the timeout will only start once the sound file has stopped playing.
  63
  64 - SpeechDeactivateGrammar(Grammar Name):
  65
  66 This deactivates the specified grammar so that it is no longer recognized. The
  67 only argument is the grammar name to deactivate.
  68
  69 - SpeechProcessingSound(Sound File):
  70
  71 This changes the processing sound that SpeechBackground plays back when the speech
  72 recognition engine is processing and working to get results. It takes the sound file as the
  73 only argument.
  74
  75 - SpeechDestroy():
  76
  77 This destroys the information used by all the other speech recognition applications.
  78 If you call this application but end up wanting to recognize more speech, you must call
  79 SpeechCreate again before calling any other application. It takes no arguments.
  80
  81 * Getting Result Information:
  82 -----------------------------
  83
  84 The speech recognition utilities module exports several dialplan functions that you can use to
  85 examine results.
  86
  87 - ${SPEECH(status)}:
  88
  89 Returns 1 if SpeechCreate has been called. This uses the same check that applications do to see if a
  90 speech object is setup. If it returns 0 then you know you can not use other speech applications.
  91
  92 - ${SPEECH(spoke)}:
  93
  94 Returns 1 if the speaker spoke something, or 0 if they were silent.
  95
  96 - ${SPEECH(results)}:
  97
  98 Returns the number of results that are available.
  99
 100 - ${SPEECH_SCORE(result number)}:
 101
 102 Returns the score of a result.
 103
 104 - ${SPEECH_TEXT(result number)}:
 105
 106 Returns the recognized text of a result.
 107
 108 - ${SPEECH_GRAMMAR(result number)}:
 109
 110 Returns the matched grammar of the result.
 111
 112 - SPEECH_ENGINE(name)=value
 113
 114 Sets a speech engine specific attribute.
 115
 116 * Dialplan Flow:
 117 -----------------
 118
 119 1. Create a speech recognition object using SpeechCreate()
 120 2. Activate your grammars using SpeechActivateGrammar(Grammar Name)
 121 3. Call SpeechStart() to indicate you are going to do speech recognition immediately
 122 4. Play back your audio and wait for recognition using SpeechBackground(Sound File|Timeout)
 123 5. Check the results and do things based on them
 124 6. Deactivate your grammars using SpeechDeactivateGrammar(Grammar Name)
 125 7. Destroy your speech recognition object using SpeechDestroy()
 126
 127 * Dialplan Examples:
 128
 129 This is pretty cheeky in that it does not confirmation of results. As well the way the
 130 grammar is written it returns the person's extension instead of their name so we can
 131 just do a Goto based on the result text.
 132
 133 - Grammar: company-directory.gram
 134
 135 #ABNF 1.0;
 136 language en-US;
 137 mode voice;
 138 tag-format <lumenvox/1.0>;
 139 root $company_directory;
 140
 141 $josh = ((Joshua | Josh) [Colp]):"6066";
 142 $mark = (Mark [Spencer] | Markster):"4569";
 143 $kevin = (Kevin [Fleming]):"2567";
 144
 145 $company_directory = ($josh | $mark | $kevin) { $ = $$ };
 146
 147 - Dialplan logic
 148
 149         [dial-by-name]
 150         exten => s,1,SpeechCreate()
 151         exten => s,2,SpeechActivateGrammar(company-directory)
 152         exten => s,3,SpeechStart()
 153         exten => s,4,SpeechBackground(who-would-you-like-to-dial)
 154         exten => s,5,SpeechDeactivateGrammar(company-directory)
 155         exten => s,6,Goto(internal-extensions-${SPEECH_TEXT(0)})
 156
 157 - Useful Dialplan Tidbits:
 158
 159 A simple macro that can be used for confirm of a result. Requires some sound files.
 160 ARG1 is equal to the file to play back after "I heard..." is played.
 161
 162         [macro-speech-confirm]
 163         exten => s,1,SpeechActivateGrammar(yes_no)
 164         exten => s,2,Set(OLDTEXT0=${SPEECH_TEXT(0)})
 165         exten => s,3,Playback(heard)
 166         exten => s,4,Playback(${ARG1})
 167         exten => s,5,SpeechStart()
 168         exten => s,6,SpeechBackground(correct)
 169         exten => s,7,Set(CONFIRM=${SPEECH_TEXT(0)})
 170         exten => s,8,GotoIf($["${SPEECH_TEXT(0)}" = "1"]?9:10)
 171         exten => s,9,Set(CONFIRM=yes)
 172         exten => s,10,Set(CONFIRMED=${OLDTEXT0})
 173         exten => s,11,SpeechDeactivateGrammar(yes_no)
 174
 175 * The Asterisk Speech Recognition C API
 176 ---------------------------------------
 177
 178 The module res_speech.so exports a C based API that any developer can use to speech
 179 recognize enable their application. The API gives greater control, but requires the
 180 developer to do more on their end in comparison to the dialplan speech utilities.
 181
 182 For all API calls that return an integer value, a non-zero value indicates an error has occurred.
 183
 184 - Creating a speech structure:
 185
 186         struct ast_speech *ast_speech_new(char *engine_name, int format)
 187
 188         struct ast_speech *speech = ast_speech_new(NULL, AST_FORMAT_SLINEAR);
 189
 190 This will create a new speech structure that will be returned to you. The speech recognition
 191 engine name is optional and if NULL the default one will be used. As well for now format should
 192 always be AST_FORMAT_SLINEAR.
 193
 194 - Activating a grammar:
 195
 196         int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
 197
 198         res = ast_speech_grammar_activate(speech, "yes_no");
 199
 200 This activates the specified grammar on the speech structure passed to it.
 201
 202 - Start recognizing audio:
 203
 204         void ast_speech_start(struct ast_speech *speech)
 205
 206         ast_speech_start(speech);
 207
 208 This essentially tells the speech recognition engine that you will be feeding audio to it from
 209 then on. It MUST be called every time before you start feeding audio to the speech structure.
 210
 211 - Send audio to be recognized:
 212
 213         int ast_speech_write(struct ast_speech *speech, void *data, int len)
 214
 215         res = ast_speech_write(speech, fr->data, fr->datalen);
 216
 217 This writes audio to the speech structure that will then be recognized. It must be written
 218 signed linear only at this time. In the future other formats may be supported.
 219
 220 - Checking for results:
 221
 222 The way the generic speech recognition API is written is that the speech structure will
 223 undergo state changes to indicate progress of recognition. The states are outlined below:
 224
 225         AST_SPEECH_STATE_NOT_READY - The speech structure is not ready to accept audio
 226         AST_SPEECH_STATE_READY - You may write audio to the speech structure
 227         AST_SPEECH_STATE_WAIT - No more audio should be written, and results will be available soon.
 228         AST_SPEECH_STATE_DONE - Results are available and the speech structure can only be used again by
 229                                 calling ast_speech_start
 230
 231 It is up to you to monitor these states. Current state is available via a variable on the speech
 232 structure. (state)
 233
 234 - Knowing when to stop playback:
 235
 236 If you are playing back a sound file to the user and you want to know when to stop play back because the
 237 individual started talking use the following.
 238
 239         ast_test_flag(speech, AST_SPEECH_QUIET) - This will return a positive value when the person has started talking.
 240
 241 - Getting results:
 242
 243         struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
 244
 245         struct ast_speech_result *results = ast_speech_results_get(speech);
 246
 247 This will return a linked list of result structures. A result structure looks like the following:
 248
 249         struct ast_speech_result {
 250                 char *text;                     /*!< Recognized text */
 251                 int score;                      /*!< Result score */
 252                 char *grammar;                  /*!< Matched grammar */
 253                 struct ast_speech_result *next; /*!< List information */
 254         };
 255
 256 - Freeing a set of results:
 257
 258         int ast_speech_results_free(struct ast_speech_result *result)
 259
 260         res = ast_speech_results_free(results);
 261
 262 This will free all results on a linked list. Results MAY NOT be used as the memory will have been freed.
 263
 264 - Deactivating a grammar:
 265
 266         int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
 267
 268         res = ast_speech_grammar_deactivate(speech, "yes_no");
 269
 270 This deactivates the specified grammar on the speech structure.
 271
 272 - Destroying a speech structure:
 273
 274         int ast_speech_destroy(struct ast_speech *speech)
 275
 276         res = ast_speech_destroy(speech);
 277
 278 This will free all associated memory with the speech structure and destroy it with the speech recognition engine.
 279
 280 - Loading a grammar on a speech structure:
 281
 282         int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
 283
 284         res = ast_speech_grammar_load(speech, "builtin:yes_no", "yes_no");
 285
 286 - Unloading a grammar on a speech structure:
 287
 288 If you load a grammar on a speech structure it is preferred that you unload it as well,
 289 or you may cause a memory leak. Don't say I didn't warn you.
 290
 291         int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
 292
 293         res = ast_speech_grammar_unload(speech, "yes_no");
 294
 295 This unloads the specified grammar from the speech structure.