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