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