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 "asterisk/channel.h"
  31 #include "asterisk/module.h"
  32 #include "asterisk/lock.h"
  33 #include "asterisk/linkedlists.h"
  34 #include "asterisk/cli.h"
  35 #include "asterisk/term.h"
  36 #include "asterisk/speech.h"
  37
  38
  39 static AST_RWLIST_HEAD_STATIC(engines, ast_speech_engine);
  40 static struct ast_speech_engine *default_engine = NULL;
  41
  42 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
  43 static struct ast_speech_engine *find_engine(char *engine_name)
  44 {
  45         struct ast_speech_engine *engine = NULL;
  46
  47         /* If no name is specified -- use the default engine */
  48         if (ast_strlen_zero(engine_name))
  49                 return default_engine;
  50
  51         AST_RWLIST_RDLOCK(&engines);
  52         AST_RWLIST_TRAVERSE(&engines, engine, list) {
  53                 if (!strcasecmp(engine->name, engine_name)) {
  54                         break;
  55                 }
  56         }
  57         AST_RWLIST_UNLOCK(&engines);
  58
  59         return engine;
  60 }
  61
  62 /*! \brief Activate a loaded (either local or global) grammar */
  63 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
  64 {
  65         return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
  66 }
  67
  68 /*! \brief Deactivate a loaded grammar on a speech structure */
  69 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
  70 {
  71         return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
  72 }
  73
  74 /*! \brief Load a local grammar on a speech structure */
  75 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
  76 {
  77         return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
  78 }
  79
  80 /*! \brief Unload a local grammar from a speech structure */
  81 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
  82 {
  83         return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
  84 }
  85
  86 /*! \brief Return the results of a recognition from the speech structure */
  87 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
  88 {
  89         return (speech->engine->get ? speech->engine->get(speech) : NULL);
  90 }
  91
  92 /*! \brief Free a list of results */
  93 int ast_speech_results_free(struct ast_speech_result *result)
  94 {
  95         struct ast_speech_result *current_result = result, *prev_result = NULL;
  96         int res = 0;
  97
  98         while (current_result != NULL) {
  99                 prev_result = current_result;
 100                 /* Deallocate what we can */
 101                 if (current_result->text != NULL) {
 102                         ast_free(current_result->text);
 103                         current_result->text = NULL;
 104                 }
 105                 if (current_result->grammar != NULL) {
 106                         ast_free(current_result->grammar);
 107                         current_result->grammar = NULL;
 108                 }
 109                 /* Move on and then free ourselves */
 110                 current_result = AST_LIST_NEXT(current_result, list);
 111                 ast_free(prev_result);
 112                 prev_result = NULL;
 113         }
 114
 115         return res;
 116 }
 117
 118 /*! \brief Start speech recognition on a speech structure */
 119 void ast_speech_start(struct ast_speech *speech)
 120 {
 121
 122         /* Clear any flags that may affect things */
 123         ast_clear_flag(speech, AST_SPEECH_SPOKE);
 124         ast_clear_flag(speech, AST_SPEECH_QUIET);
 125         ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
 126
 127         /* If results are on the structure, free them since we are starting again */
 128         if (speech->results) {
 129                 ast_speech_results_free(speech->results);
 130                 speech->results = NULL;
 131         }
 132
 133         /* If the engine needs to start stuff up, do it */
 134         if (speech->engine->start)
 135                 speech->engine->start(speech);
 136
 137         return;
 138 }
 139
 140 /*! \brief Write in signed linear audio to be recognized */
 141 int ast_speech_write(struct ast_speech *speech, void *data, int len)
 142 {
 143         /* Make sure the speech engine is ready to accept audio */
 144         if (speech->state != AST_SPEECH_STATE_READY)
 145                 return -1;
 146
 147         return speech->engine->write(speech, data, len);
 148 }
 149
 150 /*! \brief Signal to the engine that DTMF was received */
 151 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
 152 {
 153         int res = 0;
 154
 155         if (speech->state != AST_SPEECH_STATE_READY)
 156                 return -1;
 157
 158         if (speech->engine->dtmf != NULL) {
 159                 res = speech->engine->dtmf(speech, dtmf);
 160         }
 161
 162         return res;
 163 }
 164
 165 /*! \brief Change an engine specific attribute */
 166 int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
 167 {
 168         return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
 169 }
 170
 171 /*! \brief Create a new speech structure using the engine specified */
 172 struct ast_speech *ast_speech_new(char *engine_name, int formats)
 173 {
 174         struct ast_speech_engine *engine = NULL;
 175         struct ast_speech *new_speech = NULL;
 176         int format = AST_FORMAT_SLINEAR;
 177
 178         /* Try to find the speech recognition engine that was requested */
 179         if (!(engine = find_engine(engine_name)))
 180                 return NULL;
 181
 182         /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
 183         if ((format = (engine->formats & formats)))
 184                 format = ast_best_codec(format);
 185         else if ((engine->formats & AST_FORMAT_SLINEAR))
 186                 format = AST_FORMAT_SLINEAR;
 187         else
 188                 return NULL;
 189
 190         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
 191         if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
 192                 return NULL;
 193
 194         /* Initialize the lock */
 195         ast_mutex_init(&new_speech->lock);
 196
 197         /* Make sure no results are present */
 198         new_speech->results = NULL;
 199
 200         /* Copy over our engine pointer */
 201         new_speech->engine = engine;
 202
 203         /* Can't forget the format audio is going to be in */
 204         new_speech->format = format;
 205
 206         /* We are not ready to accept audio yet */
 207         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
 208
 209         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
 210         if (engine->create(new_speech, format)) {
 211                 ast_mutex_destroy(&new_speech->lock);
 212                 ast_free(new_speech);
 213                 new_speech = NULL;
 214         }
 215
 216         return new_speech;
 217 }
 218
 219 /*! \brief Destroy a speech structure */
 220 int ast_speech_destroy(struct ast_speech *speech)
 221 {
 222         int res = 0;
 223
 224         /* Call our engine so we are destroyed properly */
 225         speech->engine->destroy(speech);
 226
 227         /* Deinitialize the lock */
 228         ast_mutex_destroy(&speech->lock);
 229
 230         /* If results exist on the speech structure, destroy them */
 231         if (speech->results)
 232                 ast_speech_results_free(speech->results);
 233
 234         /* If a processing sound is set - free the memory used by it */
 235         if (speech->processing_sound)
 236                 ast_free(speech->processing_sound);
 237
 238         /* Aloha we are done */
 239         ast_free(speech);
 240
 241         return res;
 242 }
 243
 244 /*! \brief Change state of a speech structure */
 245 int ast_speech_change_state(struct ast_speech *speech, int state)
 246 {
 247         int res = 0;
 248
 249         switch (state) {
 250         case AST_SPEECH_STATE_WAIT:
 251                 /* The engine heard audio, so they spoke */
 252                 ast_set_flag(speech, AST_SPEECH_SPOKE);
 253         default:
 254                 speech->state = state;
 255                 break;
 256         }
 257
 258         return res;
 259 }
 260
 261 /*! \brief Change the type of results we want */
 262 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
 263 {
 264         speech->results_type = results_type;
 265
 266         return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
 267 }
 268
 269 /*! \brief Register a speech recognition engine */
 270 int ast_speech_register(struct ast_speech_engine *engine)
 271 {
 272         struct ast_speech_engine *existing_engine = NULL;
 273         int res = 0;
 274
 275         /* Confirm the engine meets the minimum API requirements */
 276         if (!engine->create || !engine->write || !engine->destroy) {
 277                 ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
 278                 return -1;
 279         }
 280
 281         /* If an engine is already loaded with this name, error out */
 282         if ((existing_engine = find_engine(engine->name))) {
 283                 ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
 284                 return -1;
 285         }
 286
 287         ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
 288
 289         /* Add to the engine linked list and make default if needed */
 290         AST_RWLIST_WRLOCK(&engines);
 291         AST_RWLIST_INSERT_HEAD(&engines, engine, list);
 292         if (!default_engine) {
 293                 default_engine = engine;
 294                 ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
 295         }
 296         AST_RWLIST_UNLOCK(&engines);
 297
 298         return res;
 299 }
 300
 301 /*! \brief Unregister a speech recognition engine */
 302 int ast_speech_unregister(char *engine_name)
 303 {
 304         struct ast_speech_engine *engine = NULL;
 305         int res = -1;
 306
 307         if (ast_strlen_zero(engine_name))
 308                 return -1;
 309
 310         AST_RWLIST_WRLOCK(&engines);
 311         AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
 312                 if (!strcasecmp(engine->name, engine_name)) {
 313                         /* We have our engine... removed it */
 314                         AST_RWLIST_REMOVE_CURRENT(list);
 315                         /* If this was the default engine, we need to pick a new one */
 316                         if (!default_engine)
 317                                 default_engine = AST_RWLIST_FIRST(&engines);
 318                         ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
 319                         /* All went well */
 320                         res = 0;
 321                         break;
 322                 }
 323         }
 324         AST_RWLIST_TRAVERSE_SAFE_END;
 325         AST_RWLIST_UNLOCK(&engines);
 326
 327         return res;
 328 }
 329
 330 static int unload_module(void)
 331 {
 332         /* We can not be unloaded */
 333         return -1;
 334 }
 335
 336 static int load_module(void)
 337 {
 338         return AST_MODULE_LOAD_SUCCESS;
 339 }
 340
 341 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
 342                 .load = load_module,
 343                 .unload = unload_module,
 344                 );