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