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 && ast_test_flag(speech, AST_SPEECH_HAVE_RESULTS)) ? 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                         ast_free(current_result->text);
 109                         current_result->text = NULL;
 110                 }
 111                 if (current_result->grammar != NULL) {
 112                         ast_free(current_result->grammar);
 113                         current_result->grammar = NULL;
 114                 }
 115                 /* Move on and then free ourselves */
 116                 current_result = AST_LIST_NEXT(current_result, list);
 117                 ast_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         ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
 132
 133         /* If results are on the structure, free them since we are starting again */
 134         if (speech->results) {
 135                 ast_speech_results_free(speech->results);
 136                 speech->results = NULL;
 137         }
 138
 139         /* If the engine needs to start stuff up, do it */
 140         if (speech->engine->start)
 141                 speech->engine->start(speech);
 142
 143         return;
 144 }
 145
 146 /*! \brief Write in signed linear audio to be recognized */
 147 int ast_speech_write(struct ast_speech *speech, void *data, int len)
 148 {
 149         /* Make sure the speech engine is ready to accept audio */
 150         if (speech->state != AST_SPEECH_STATE_READY)
 151                 return -1;
 152
 153         return speech->engine->write(speech, data, len);
 154 }
 155
 156 /*! \brief Change an engine specific attribute */
 157 int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
 158 {
 159         return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
 160 }
 161
 162 /*! \brief Create a new speech structure using the engine specified */
 163 struct ast_speech *ast_speech_new(char *engine_name, int formats)
 164 {
 165         struct ast_speech_engine *engine = NULL;
 166         struct ast_speech *new_speech = NULL;
 167         int format = AST_FORMAT_SLINEAR;
 168
 169         /* Try to find the speech recognition engine that was requested */
 170         if (!(engine = find_engine(engine_name)))
 171                 return NULL;
 172
 173         /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
 174         if ((format = (engine->formats & formats)))
 175                 format = ast_best_codec(format);
 176         else if ((engine->formats & AST_FORMAT_SLINEAR))
 177                 format = AST_FORMAT_SLINEAR;
 178         else
 179                 return NULL;
 180
 181         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
 182         if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
 183                 return NULL;
 184
 185         /* Initialize the lock */
 186         ast_mutex_init(&new_speech->lock);
 187
 188         /* Make sure no results are present */
 189         new_speech->results = NULL;
 190
 191         /* Copy over our engine pointer */
 192         new_speech->engine = engine;
 193
 194         /* Can't forget the format audio is going to be in */
 195         new_speech->format = format;
 196
 197         /* We are not ready to accept audio yet */
 198         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
 199
 200         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
 201         if (engine->create(new_speech, format)) {
 202                 ast_mutex_destroy(&new_speech->lock);
 203                 ast_free(new_speech);
 204                 new_speech = NULL;
 205         }
 206
 207         return new_speech;
 208 }
 209
 210 /*! \brief Destroy a speech structure */
 211 int ast_speech_destroy(struct ast_speech *speech)
 212 {
 213         int res = 0;
 214
 215         /* Call our engine so we are destroyed properly */
 216         speech->engine->destroy(speech);
 217
 218         /* Deinitialize the lock */
 219         ast_mutex_destroy(&speech->lock);
 220
 221         /* If results exist on the speech structure, destroy them */
 222         if (speech->results)
 223                 ast_speech_results_free(speech->results);
 224
 225         /* If a processing sound is set - free the memory used by it */
 226         if (speech->processing_sound)
 227                 ast_free(speech->processing_sound);
 228
 229         /* Aloha we are done */
 230         ast_free(speech);
 231
 232         return res;
 233 }
 234
 235 /*! \brief Change state of a speech structure */
 236 int ast_speech_change_state(struct ast_speech *speech, int state)
 237 {
 238         int res = 0;
 239
 240         switch (state) {
 241         case AST_SPEECH_STATE_WAIT:
 242                 /* The engine heard audio, so they spoke */
 243                 ast_set_flag(speech, AST_SPEECH_SPOKE);
 244         default:
 245                 speech->state = state;
 246                 break;
 247         }
 248
 249         return res;
 250 }
 251
 252 /*! \brief Change the type of results we want */
 253 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
 254 {
 255         speech->results_type = results_type;
 256
 257         return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
 258 }
 259
 260 /*! \brief Register a speech recognition engine */
 261 int ast_speech_register(struct ast_speech_engine *engine)
 262 {
 263         struct ast_speech_engine *existing_engine = NULL;
 264         int res = 0;
 265
 266         /* Confirm the engine meets the minimum API requirements */
 267         if (!engine->create || !engine->write || !engine->destroy) {
 268                 ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
 269                 return -1;
 270         }
 271
 272         /* If an engine is already loaded with this name, error out */
 273         if ((existing_engine = find_engine(engine->name))) {
 274                 ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
 275                 return -1;
 276         }
 277
 278         ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
 279
 280         /* Add to the engine linked list and make default if needed */
 281         AST_RWLIST_WRLOCK(&engines);
 282         AST_RWLIST_INSERT_HEAD(&engines, engine, list);
 283         if (!default_engine) {
 284                 default_engine = engine;
 285                 ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
 286         }
 287         AST_RWLIST_UNLOCK(&engines);
 288
 289         return res;
 290 }
 291
 292 /*! \brief Unregister a speech recognition engine */
 293 int ast_speech_unregister(char *engine_name)
 294 {
 295         struct ast_speech_engine *engine = NULL;
 296         int res = -1;
 297
 298         if (ast_strlen_zero(engine_name))
 299                 return -1;
 300
 301         AST_RWLIST_WRLOCK(&engines);
 302         AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
 303                 if (!strcasecmp(engine->name, engine_name)) {
 304                         /* We have our engine... removed it */
 305                         AST_RWLIST_REMOVE_CURRENT(&engines, list);
 306                         /* If this was the default engine, we need to pick a new one */
 307                         if (!default_engine)
 308                                 default_engine = AST_RWLIST_FIRST(&engines);
 309                         ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
 310                         /* All went well */
 311                         res = 0;
 312                         break;
 313                 }
 314         }
 315         AST_RWLIST_TRAVERSE_SAFE_END
 316         AST_RWLIST_UNLOCK(&engines);
 317
 318         return res;
 319 }
 320
 321 static int unload_module(void)
 322 {
 323         /* We can not be unloaded */
 324         return -1;
 325 }
 326
 327 static int load_module(void)
 328 {
 329         return 0;
 330 }
 331
 332 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
 333                 .load = load_module,
 334                 .unload = unload_module,
 335                 );