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
 163         /* If results are on the structure, free them since we are starting again */
 164         if (speech->results != NULL) {
 165                 ast_speech_results_free(speech->results);
 166                 speech->results = NULL;
 167         }
 168
 169         /* If the engine needs to start stuff up, do it */
 170         if (speech->engine->start != NULL) {
 171                 speech->engine->start(speech);
 172         }
 173
 174         return;
 175 }
 176
 177 /*! \brief Write in signed linear audio to be recognized */
 178 int ast_speech_write(struct ast_speech *speech, void *data, int len)
 179 {
 180         int res = 0;
 181
 182         /* Make sure the speech engine is ready to accept audio */
 183         if (speech->state != AST_SPEECH_STATE_READY) {
 184                 return -1;
 185         }
 186
 187         if (speech->engine->write != NULL) {
 188                 speech->engine->write(speech, data, len);
 189         }
 190
 191         return res;
 192 }
 193
 194 /*! \brief Change an engine specific attribute */
 195 int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
 196 {
 197         int res = 0;
 198
 199         if (speech->engine->change != NULL) {
 200                 res = speech->engine->change(speech, name, value);
 201         }
 202
 203         return res;
 204 }
 205
 206 /*! \brief Create a new speech structure using the engine specified */
 207 struct ast_speech *ast_speech_new(char *engine_name, int format)
 208 {
 209         struct ast_speech_engine *engine = NULL;
 210         struct ast_speech *new_speech = NULL;
 211
 212         /* Try to find the speech recognition engine that was requested */
 213         engine = find_engine(engine_name);
 214         if (engine == NULL) {
 215                 /* Invalid engine or no engine available */
 216                 return NULL;
 217         }
 218
 219         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
 220         new_speech = ast_calloc(1, sizeof(*new_speech));
 221         if (new_speech == NULL) {
 222                 /* Ran out of memory while trying to allocate some for a speech structure */
 223                 return NULL;
 224         }
 225
 226         /* Initialize the lock */
 227         ast_mutex_init(&new_speech->lock);
 228
 229         /* Make sure no results are present */
 230         new_speech->results = NULL;
 231
 232         /* Copy over our engine pointer */
 233         new_speech->engine = engine;
 234
 235         /* We are not ready to accept audio yet */
 236         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
 237
 238         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
 239         if (engine->new(new_speech)) {
 240                 ast_mutex_destroy(&new_speech->lock);
 241                 free(new_speech);
 242                 new_speech = NULL;
 243         }
 244
 245         return new_speech;
 246 }
 247
 248 /*! \brief Destroy a speech structure */
 249 int ast_speech_destroy(struct ast_speech *speech)
 250 {
 251         int res = 0;
 252
 253         /* Call our engine so we are destroyed properly */
 254         speech->engine->destroy(speech);
 255
 256         /* Deinitialize the lock */
 257         ast_mutex_destroy(&speech->lock);
 258
 259         /* If results exist on the speech structure, destroy them */
 260         if (speech->results != NULL) {
 261                 ast_speech_results_free(speech->results);
 262                 speech->results = NULL;
 263         }
 264
 265         /* If a processing sound is set - free the memory used by it */
 266         if (speech->processing_sound != NULL) {
 267                 free(speech->processing_sound);
 268                 speech->processing_sound = NULL;
 269         }
 270
 271         /* Aloha we are done */
 272         free(speech);
 273         speech = NULL;
 274
 275         return res;
 276 }
 277
 278 /*! \brief Change state of a speech structure */
 279 int ast_speech_change_state(struct ast_speech *speech, int state)
 280 {
 281         int res = 0;
 282
 283         switch (state) {
 284         case AST_SPEECH_STATE_WAIT:
 285                 /* The engine heard audio, so they spoke */
 286                 ast_set_flag(speech, AST_SPEECH_SPOKE);
 287         default:
 288                 speech->state = state;
 289                 break;
 290         }
 291
 292         return res;
 293 }
 294
 295 /*! \brief Register a speech recognition engine */
 296 int ast_speech_register(struct ast_speech_engine *engine)
 297 {
 298         struct ast_speech_engine *existing_engine = NULL;
 299         int res = 0;
 300
 301         existing_engine = find_engine(engine->name);
 302         if (existing_engine != NULL) {
 303                 /* Engine already loaded */
 304                 return -1;
 305         }
 306
 307         if (option_verbose > 1)
 308                 ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
 309
 310         /* Add to the engine linked list and make default if needed */
 311         AST_LIST_LOCK(&engines);
 312         AST_LIST_INSERT_HEAD(&engines, engine, list);
 313         if (default_engine == NULL) {
 314                 default_engine = engine;
 315                 if (option_verbose > 1)
 316                         ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
 317         }
 318         AST_LIST_UNLOCK(&engines);
 319
 320         return res;
 321 }
 322
 323 /*! \brief Unregister a speech recognition engine */
 324 int ast_speech_unregister(char *engine_name)
 325 {
 326         struct ast_speech_engine *engine = NULL;
 327         int res = -1;
 328
 329         if (engine_name == NULL) {
 330                 return res;
 331         }
 332
 333         AST_LIST_LOCK(&engines);
 334         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
 335                 if (!strcasecmp(engine->name, engine_name)) {
 336                         /* We have our engine... removed it */
 337                         AST_LIST_REMOVE_CURRENT(&engines, list);
 338                         /* If this was the default engine, we need to pick a new one */
 339                         if (default_engine == engine) {
 340                                 default_engine = AST_LIST_FIRST(&engines);
 341                         }
 342                         if (option_verbose > 1)
 343                                 ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
 344                         /* All went well */
 345                         res = 0;
 346                         break;
 347                 }
 348         }
 349         AST_LIST_TRAVERSE_SAFE_END
 350         AST_LIST_UNLOCK(&engines);
 351
 352         return res;
 353 }
 354
 355 static int unload_module(void)
 356 {
 357         /* We can not be unloaded */
 358         return -1;
 359 }
 360
 361 static int load_module(void)
 362 {
 363         int res = 0;
 364
 365         /* Initialize our list of engines */
 366         AST_LIST_HEAD_INIT_NOLOCK(&engines);
 367
 368         return res;
 369 }
 370
 371 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
 372                 .load = load_module,
 373                 .unload = unload_module,
 374                 );