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