res/res_speech.c

   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  *
  21  * \brief Generic Speech Recognition API
  22  *
  23  * \author Joshua Colp <jcolp@digium.com>
  24  */
  25
  26 #include "asterisk.h"
  27
  28 ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
  29
  30 #include <stdio.h>
  31 #include <stdlib.h>
  32 #include <unistd.h>
  33 #include <string.h>
  34
  35 #include "asterisk/channel.h"
  36 #include "asterisk/module.h"
  37 #include "asterisk/lock.h"
  38 #include "asterisk/linkedlists.h"
  39 #include "asterisk/cli.h"
  40 #include "asterisk/term.h"
  41 #include "asterisk/options.h"
  42 #include "asterisk/speech.h"
  43
  44
  45 static AST_LIST_HEAD_STATIC(engines, ast_speech_engine);
  46 static struct ast_speech_engine *default_engine = NULL;
  47
  48 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
  49 static struct ast_speech_engine *find_engine(char *engine_name)
  50 {
  51         struct ast_speech_engine *engine = NULL;
  52
  53         /* If no name is specified -- use the default engine */
  54         if (engine_name == NULL || strlen(engine_name) == 0) {
  55                 return default_engine;
  56         }
  57
  58         AST_LIST_LOCK(&engines);
  59         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
  60                 if (!strcasecmp(engine->name, engine_name)) {
  61                         break;
  62                 }
  63         }
  64         AST_LIST_TRAVERSE_SAFE_END
  65         AST_LIST_UNLOCK(&engines);
  66
  67         return engine;
  68 }
  69
  70 /*! \brief Activate a loaded (either local or global) grammar */
  71 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
  72 {
  73         int res = 0;
  74
  75         if (speech->engine->activate != NULL) {
  76                 res = speech->engine->activate(speech, grammar_name);
  77         }
  78
  79         return res;
  80 }
  81
  82 /*! \brief Deactivate a loaded grammar on a speech structure */
  83 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
  84 {
  85         int res = 0;
  86
  87         if (speech->engine->deactivate != NULL) {
  88                 res = speech->engine->deactivate(speech, grammar_name);
  89         }
  90
  91         return res;
  92 }
  93
  94 /*! \brief Load a local grammar on a speech structure */
  95 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
  96 {
  97         int res = 0;
  98
  99         if (speech->engine->load != NULL) {
 100                 res = speech->engine->load(speech, grammar_name, grammar);
 101         }
 102
 103         return res;
 104 }
 105
 106 /*! \brief Unload a local grammar from a speech structure */
 107 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
 108 {
 109         int res = 0;
 110
 111         if (speech->engine->unload != NULL) {
 112                 res = speech->engine->unload(speech, grammar_name);
 113         }
 114
 115         return res;
 116 }
 117
 118 /*! \brief Return the results of a recognition from the speech structure */
 119 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
 120 {
 121         struct ast_speech_result *result = NULL;
 122
 123         if (speech->engine->get != NULL) {
 124                 result = speech->engine->get(speech);
 125         }
 126
 127         return result;
 128 }
 129
 130 /*! \brief Free a list of results */
 131 int ast_speech_results_free(struct ast_speech_result *result)
 132 {
 133         struct ast_speech_result *current_result = result, *prev_result = NULL;
 134         int res = 0;
 135
 136         while (current_result != NULL) {
 137                 prev_result = current_result;
 138                 /* Deallocate what we can */
 139                 if (current_result->text != NULL) {
 140                         free(current_result->text);
 141                         current_result->text = NULL;
 142                 }
 143                 if (current_result->grammar != NULL) {
 144                         free(current_result->grammar);
 145                         current_result->grammar = NULL;
 146                 }
 147                 /* Move on and then free ourselves */
 148                 current_result = current_result->next;
 149                 free(prev_result);
 150                 prev_result = NULL;
 151         }
 152
 153         return res;
 154 }
 155
 156 /*! \brief Start speech recognition on a speech structure */
 157 void ast_speech_start(struct ast_speech *speech)
 158 {
 159
 160         /* Clear any flags that may affect things */
 161         ast_clear_flag(speech, AST_SPEECH_SPOKE);
 162         ast_clear_flag(speech, AST_SPEECH_QUIET);
 163         ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
 164
 165         /* If results are on the structure, free them since we are starting again */
 166         if (speech->results != NULL) {
 167                 ast_speech_results_free(speech->results);
 168                 speech->results = NULL;
 169         }
 170
 171         /* If the engine needs to start stuff up, do it */
 172         if (speech->engine->start != NULL) {
 173                 speech->engine->start(speech);
 174         }
 175
 176         return;
 177 }
 178
 179 /*! \brief Write in signed linear audio to be recognized */
 180 int ast_speech_write(struct ast_speech *speech, void *data, int len)
 181 {
 182         int res = 0;
 183
 184         /* Make sure the speech engine is ready to accept audio */
 185         if (speech->state != AST_SPEECH_STATE_READY) {
 186                 return -1;
 187         }
 188
 189         if (speech->engine->write != NULL) {
 190                 speech->engine->write(speech, data, len);
 191         }
 192
 193         return res;
 194 }
 195
 196 /*! \brief Signal to the engine that DTMF was received */
 197 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
 198 {
 199         int res = 0;
 200
 201         if (speech->state != AST_SPEECH_STATE_READY)
 202                 return -1;
 203
 204         if (speech->engine->dtmf != NULL) {
 205                 res = speech->engine->dtmf(speech, dtmf);
 206         }
 207
 208         return res;
 209 }
 210
 211 /*! \brief Change an engine specific attribute */
 212 int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
 213 {
 214         int res = 0;
 215
 216         if (speech->engine->change != NULL) {
 217                 res = speech->engine->change(speech, name, value);
 218         }
 219
 220         return res;
 221 }
 222
 223 /*! \brief Create a new speech structure using the engine specified */
 224 struct ast_speech *ast_speech_new(char *engine_name, int format)
 225 {
 226         struct ast_speech_engine *engine = NULL;
 227         struct ast_speech *new_speech = NULL;
 228
 229         /* Try to find the speech recognition engine that was requested */
 230         engine = find_engine(engine_name);
 231         if (engine == NULL) {
 232                 /* Invalid engine or no engine available */
 233                 return NULL;
 234         }
 235
 236         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
 237         new_speech = ast_calloc(1, sizeof(*new_speech));
 238         if (new_speech == NULL) {
 239                 /* Ran out of memory while trying to allocate some for a speech structure */
 240                 return NULL;
 241         }
 242
 243         /* Initialize the lock */
 244         ast_mutex_init(&new_speech->lock);
 245
 246         /* Make sure no results are present */
 247         new_speech->results = NULL;
 248
 249         /* Copy over our engine pointer */
 250         new_speech->engine = engine;
 251
 252         /* We are not ready to accept audio yet */
 253         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
 254
 255         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
 256         if (engine->create(new_speech)) {
 257                 ast_mutex_destroy(&new_speech->lock);
 258                 free(new_speech);
 259                 new_speech = NULL;
 260         }
 261
 262         return new_speech;
 263 }
 264
 265 /*! \brief Destroy a speech structure */
 266 int ast_speech_destroy(struct ast_speech *speech)
 267 {
 268         int res = 0;
 269
 270         /* Call our engine so we are destroyed properly */
 271         speech->engine->destroy(speech);
 272
 273         /* Deinitialize the lock */
 274         ast_mutex_destroy(&speech->lock);
 275
 276         /* If results exist on the speech structure, destroy them */
 277         if (speech->results != NULL) {
 278                 ast_speech_results_free(speech->results);
 279                 speech->results = NULL;
 280         }
 281
 282         /* If a processing sound is set - free the memory used by it */
 283         if (speech->processing_sound != NULL) {
 284                 free(speech->processing_sound);
 285                 speech->processing_sound = NULL;
 286         }
 287
 288         /* Aloha we are done */
 289         free(speech);
 290         speech = NULL;
 291
 292         return res;
 293 }
 294
 295 /*! \brief Change state of a speech structure */
 296 int ast_speech_change_state(struct ast_speech *speech, int state)
 297 {
 298         int res = 0;
 299
 300         switch (state) {
 301         case AST_SPEECH_STATE_WAIT:
 302                 /* The engine heard audio, so they spoke */
 303                 ast_set_flag(speech, AST_SPEECH_SPOKE);
 304         default:
 305                 speech->state = state;
 306                 break;
 307         }
 308
 309         return res;
 310 }
 311
 312 /*! \brief Change the type of results we want */
 313 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
 314 {
 315         int res = 0;
 316
 317         speech->results_type = results_type;
 318
 319         if (speech->engine->change_results_type)
 320                 res = speech->engine->change_results_type(speech, results_type);
 321
 322         return res;
 323 }
 324
 325 /*! \brief Register a speech recognition engine */
 326 int ast_speech_register(struct ast_speech_engine *engine)
 327 {
 328         struct ast_speech_engine *existing_engine = NULL;
 329         int res = 0;
 330
 331         existing_engine = find_engine(engine->name);
 332         if (existing_engine != NULL) {
 333                 /* Engine already loaded */
 334                 return -1;
 335         }
 336
 337         if (option_verbose > 1)
 338                 ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
 339
 340         /* Add to the engine linked list and make default if needed */
 341         AST_LIST_LOCK(&engines);
 342         AST_LIST_INSERT_HEAD(&engines, engine, list);
 343         if (default_engine == NULL) {
 344                 default_engine = engine;
 345                 if (option_verbose > 1)
 346                         ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
 347         }
 348         AST_LIST_UNLOCK(&engines);
 349
 350         return res;
 351 }
 352
 353 /*! \brief Unregister a speech recognition engine */
 354 int ast_speech_unregister(char *engine_name)
 355 {
 356         struct ast_speech_engine *engine = NULL;
 357         int res = -1;
 358
 359         if (engine_name == NULL) {
 360                 return res;
 361         }
 362
 363         AST_LIST_LOCK(&engines);
 364         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
 365                 if (!strcasecmp(engine->name, engine_name)) {
 366                         /* We have our engine... removed it */
 367                         AST_LIST_REMOVE_CURRENT(&engines, list);
 368                         /* If this was the default engine, we need to pick a new one */
 369                         if (default_engine == engine) {
 370                                 default_engine = AST_LIST_FIRST(&engines);
 371                         }
 372                         if (option_verbose > 1)
 373                                 ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
 374                         /* All went well */
 375                         res = 0;
 376                         break;
 377                 }
 378         }
 379         AST_LIST_TRAVERSE_SAFE_END
 380         AST_LIST_UNLOCK(&engines);
 381
 382         return res;
 383 }
 384
 385 static int unload_module(void)
 386 {
 387         /* We can not be unloaded */
 388         return -1;
 389 }
 390
 391 static int load_module(void)
 392 {
 393         int res = 0;
 394
 395         /* Initialize our list of engines */
 396         AST_LIST_HEAD_INIT_NOLOCK(&engines);
 397
 398         return res;
 399 }
 400
 401 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
 402                 .load = load_module,
 403                 .unload = unload_module,
 404                 );