Asterisk - The Open Source Telephony Project  21.4.1
speech.h
Go to the documentation of this file.
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  * \brief Generic Speech Recognition API
21  */
22 
23 #ifndef _ASTERISK_SPEECH_H
24 #define _ASTERISK_SPEECH_H
25 
26 #if defined(__cplusplus) || defined(c_plusplus)
27 extern "C" {
28 #endif
29 
30 /* Speech structure flags */
31 enum ast_speech_flags {
32  AST_SPEECH_QUIET = (1 << 0), /* Quiet down output... they are talking */
33  AST_SPEECH_SPOKE = (1 << 1), /* Speaker spoke! */
34  AST_SPEECH_HAVE_RESULTS = (1 << 2), /* Results are present */
35 };
36 
37 /* Speech structure states - in order of expected change */
38 enum ast_speech_states {
39  AST_SPEECH_STATE_NOT_READY = 0, /* Not ready to accept audio */
40  AST_SPEECH_STATE_READY, /* Accepting audio */
41  AST_SPEECH_STATE_WAIT, /* Wait for results to become available */
42  AST_SPEECH_STATE_DONE, /* Processing is all done */
43 };
44 
45 enum ast_speech_results_type {
46  AST_SPEECH_RESULTS_TYPE_NORMAL = 0,
47  AST_SPEECH_RESULTS_TYPE_NBEST,
48 };
49 
50 /*! \brief Convert a speech results type to a string */
51 const char *ast_speech_results_type_to_string(enum ast_speech_results_type type);
52 
53 /* Speech structure */
54 struct ast_speech {
55  /*! Structure lock */
57  /*! Set flags */
58  unsigned int flags;
59  /*! Processing sound (used when engine is processing audio and getting results) */
61  /*! Current state of structure */
62  int state;
63  /*! Expected write format */
64  struct ast_format *format;
65  /*! Data for speech engine */
66  void *data;
67  /*! Cached results */
69  /*! Type of results we want */
70  enum ast_speech_results_type results_type;
71  /*! Pointer to the engine used by this speech structure */
73 };
74 
75 /* Speech recognition engine structure */
77  /*! Name of speech engine */
78  char *name;
79  /*! Set up the speech structure within the engine */
80  int (*create)(struct ast_speech *speech, struct ast_format *format);
81  /*! Destroy any data set on the speech structure by the engine */
82  int (*destroy)(struct ast_speech *speech);
83  /*! Load a local grammar on the speech structure */
84  int (*load)(struct ast_speech *speech, const char *grammar_name, const char *grammar);
85  /*! Unload a local grammar */
86  int (*unload)(struct ast_speech *speech, const char *grammar_name);
87  /*! Activate a loaded grammar */
88  int (*activate)(struct ast_speech *speech, const char *grammar_name);
89  /*! Deactivate a loaded grammar */
90  int (*deactivate)(struct ast_speech *speech, const char *grammar_name);
91  /*! Write audio to the speech engine */
92  int (*write)(struct ast_speech *speech, void *data, int len);
93  /*! Signal DTMF was received */
94  int (*dtmf)(struct ast_speech *speech, const char *dtmf);
95  /*! Prepare engine to accept audio */
96  int (*start)(struct ast_speech *speech);
97  /*! Change an engine specific setting */
98  int (*change)(struct ast_speech *speech, const char *name, const char *value);
99  /*! Get an engine specific setting */
100  int (*get_setting)(struct ast_speech *speech, const char *name, char *buf, size_t len);
101  /*! Change the type of results we want back */
102  int (*change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type);
103  /*! Try to get results */
104  struct ast_speech_result *(*get)(struct ast_speech *speech);
105  /*! Accepted formats by the engine */
108 };
109 
110 /* Result structure */
112  /*! Recognized text */
113  char *text;
114  /*! Result score */
115  int score;
116  /*! NBest Alternative number if in NBest results type */
118  /*! Matched grammar */
119  char *grammar;
120  /*! List information */
121  AST_LIST_ENTRY(ast_speech_result) list;
122 };
123 
124 /*! \brief Activate a grammar on a speech structure */
125 int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name);
126 /*! \brief Deactivate a grammar on a speech structure */
127 int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name);
128 /*! \brief Load a grammar on a speech structure (not globally) */
129 int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar);
130 /*! \brief Unload a grammar */
131 int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name);
132 /*! \brief Get speech recognition results */
133 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
134 /*! \brief Free a set of results */
135 int ast_speech_results_free(struct ast_speech_result *result);
136 /*! \brief Indicate to the speech engine that audio is now going to start being written */
137 void ast_speech_start(struct ast_speech *speech);
138 /*! \brief Create a new speech structure */
139 struct ast_speech *ast_speech_new(const char *engine_name, const struct ast_format_cap *formats);
140 /*! \brief Destroy a speech structure */
141 int ast_speech_destroy(struct ast_speech *speech);
142 /*! \brief Write audio to the speech engine */
143 int ast_speech_write(struct ast_speech *speech, void *data, int len);
144 /*! \brief Signal to the engine that DTMF was received */
145 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf);
146 /*! \brief Change an engine specific attribute */
147 int ast_speech_change(struct ast_speech *speech, const char *name, const char *value);
148 /*! \brief Get an engine specific attribute */
149 int ast_speech_get_setting(struct ast_speech *speech, const char *name, char *buf, size_t len);
150 /*! \brief Change the type of results we want */
151 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type);
152 /*! \brief Change state of a speech structure */
153 int ast_speech_change_state(struct ast_speech *speech, int state);
154 /*! \brief Register a speech recognition engine */
155 int ast_speech_register(struct ast_speech_engine *engine);
156 /*! \brief Unregister a speech recognition engine */
157 int ast_speech_unregister(const char *engine_name);
158 /*! \brief Unregister a speech recognition engine */
159 struct ast_speech_engine *ast_speech_unregister2(const char *engine_name);
160 
161 /*! \brief Retrieve a speech recognition engine */
162 struct ast_speech_engine *ast_speech_find_engine(const char *engine_name);
163 /*! \brief Unregister all speech recognition engines told to by callback */
165  int (*should_unregister)(const struct ast_speech_engine *engine, void *data), void *data,
166  void (*on_unregistered)(void *obj));
167 
168 #if defined(__cplusplus) || defined(c_plusplus)
169 }
170 #endif
171 
172 #endif /* _ASTERISK_SPEECH_H */
int state
Definition: speech.h:62
int(* destroy)(struct ast_speech *speech)
Definition: speech.h:82
int ast_speech_destroy(struct ast_speech *speech)
Destroy a speech structure.
Definition: res_speech.c:251
int(* create)(struct ast_speech *speech, struct ast_format *format)
Definition: speech.h:80
void ast_speech_start(struct ast_speech *speech)
Indicate to the speech engine that audio is now going to start being written.
Definition: res_speech.c:122
int(* change)(struct ast_speech *speech, const char *name, const char *value)
Definition: speech.h:98
void ast_speech_unregister_engines(int(*should_unregister)(const struct ast_speech_engine *engine, void *data), void *data, void(*on_unregistered)(void *obj))
Unregister all speech recognition engines told to by callback.
Definition: res_speech.c:380
struct ast_speech_engine * ast_speech_unregister2(const char *engine_name)
Unregister a speech recognition engine.
Definition: res_speech.c:352
enum ast_speech_results_type results_type
Definition: speech.h:70
int ast_speech_register(struct ast_speech_engine *engine)
Register a speech recognition engine.
Definition: res_speech.c:316
struct ast_speech_result * ast_speech_results_get(struct ast_speech *speech)
Get speech recognition results.
Definition: res_speech.c:90
Definition of a media format.
Definition: format.c:43
void * data
Definition: speech.h:66
char * name
Definition: speech.h:78
int(* start)(struct ast_speech *speech)
Definition: speech.h:96
char * grammar
Definition: speech.h:119
int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
Change the type of results we want.
Definition: res_speech.c:308
int(* unload)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:86
int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name)
Deactivate a grammar on a speech structure.
Definition: res_speech.c:72
int ast_speech_change_state(struct ast_speech *speech, int state)
Change state of a speech structure.
Definition: res_speech.c:278
struct ast_format_cap * formats
Definition: speech.h:106
int(* change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type)
Definition: speech.h:102
struct ast_speech_engine * engine
Definition: speech.h:72
int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name)
Unload a grammar.
Definition: res_speech.c:84
struct ast_speech_result * results
Definition: speech.h:68
struct ast_speech_engine * ast_speech_find_engine(const char *engine_name)
Retrieve a speech recognition engine.
Definition: res_speech.c:46
int(* activate)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:88
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
int(* write)(struct ast_speech *speech, void *data, int len)
Definition: speech.h:92
int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name)
Activate a grammar on a speech structure.
Definition: res_speech.c:66
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
unsigned int flags
Definition: speech.h:58
struct ast_format * format
Definition: speech.h:64
const char * ast_speech_results_type_to_string(enum ast_speech_results_type type)
Convert a speech results type to a string.
Definition: res_speech.c:294
int ast_speech_results_free(struct ast_speech_result *result)
Free a set of results.
Definition: res_speech.c:96
ast_mutex_t lock
Definition: speech.h:56
int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
Signal to the engine that DTMF was received.
Definition: res_speech.c:154
int ast_speech_unregister(const char *engine_name)
Unregister a speech recognition engine.
Definition: res_speech.c:347
int(* deactivate)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:90
struct ast_speech * ast_speech_new(const char *engine_name, const struct ast_format_cap *formats)
Create a new speech structure.
Definition: res_speech.c:181
int(* load)(struct ast_speech *speech, const char *grammar_name, const char *grammar)
Definition: speech.h:84
int(* dtmf)(struct ast_speech *speech, const char *dtmf)
Definition: speech.h:94
char * processing_sound
Definition: speech.h:60
int ast_speech_write(struct ast_speech *speech, void *data, int len)
Write audio to the speech engine.
Definition: res_speech.c:144
int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar)
Load a grammar on a speech structure (not globally)
Definition: res_speech.c:78
int ast_speech_get_setting(struct ast_speech *speech, const char *name, char *buf, size_t len)
Get an engine specific attribute.
Definition: res_speech.c:175
int ast_speech_change(struct ast_speech *speech, const char *name, const char *value)
Change an engine specific attribute.
Definition: res_speech.c:169
Structure for mutex and tracking information.
Definition: lock.h:135
int(* get_setting)(struct ast_speech *speech, const char *name, char *buf, size_t len)
Definition: speech.h:100