Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


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 */
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 */
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 
48 };
49 
50 /* Speech structure */
51 struct ast_speech {
52  /*! Structure lock */
54  /*! Set flags */
55  unsigned int flags;
56  /*! Processing sound (used when engine is processing audio and getting results) */
58  /*! Current state of structure */
59  int state;
60  /*! Expected write format */
61  int format;
62  /*! Data for speech engine */
63  void *data;
64  /*! Cached results */
66  /*! Type of results we want */
68  /*! Pointer to the engine used by this speech structure */
70 };
71 
72 /* Speech recognition engine structure */
74  /*! Name of speech engine */
75  char *name;
76  /*! Set up the speech structure within the engine */
77  int (*create)(struct ast_speech *speech, int format);
78  /*! Destroy any data set on the speech structure by the engine */
79  int (*destroy)(struct ast_speech *speech);
80  /*! Load a local grammar on the speech structure */
81  int (*load)(struct ast_speech *speech, const char *grammar_name, const char *grammar);
82  /*! Unload a local grammar */
83  int (*unload)(struct ast_speech *speech, const char *grammar_name);
84  /*! Activate a loaded grammar */
85  int (*activate)(struct ast_speech *speech, const char *grammar_name);
86  /*! Deactivate a loaded grammar */
87  int (*deactivate)(struct ast_speech *speech, const char *grammar_name);
88  /*! Write audio to the speech engine */
89  int (*write)(struct ast_speech *speech, void *data, int len);
90  /*! Signal DTMF was received */
91  int (*dtmf)(struct ast_speech *speech, const char *dtmf);
92  /*! Prepare engine to accept audio */
93  int (*start)(struct ast_speech *speech);
94  /*! Change an engine specific setting */
95  int (*change)(struct ast_speech *speech, const char *name, const char *value);
96  /*! Change the type of results we want back */
98  /*! Try to get results */
99  struct ast_speech_result *(*get)(struct ast_speech *speech);
100  /*! Accepted formats by the engine */
101  int formats;
103 };
104 
105 /* Result structure */
107  /*! Recognized text */
108  char *text;
109  /*! Result score */
110  int score;
111  /*! NBest Alternative number if in NBest results type */
113  /*! Matched grammar */
114  char *grammar;
115  /*! List information */
116  AST_LIST_ENTRY(ast_speech_result) list;
117 };
118 
119 /*! \brief Activate a grammar on a speech structure */
120 int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name);
121 /*! \brief Deactivate a grammar on a speech structure */
122 int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name);
123 /*! \brief Load a grammar on a speech structure (not globally) */
124 int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar);
125 /*! \brief Unload a grammar */
126 int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name);
127 /*! \brief Get speech recognition results */
128 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech);
129 /*! \brief Free a set of results */
130 int ast_speech_results_free(struct ast_speech_result *result);
131 /*! \brief Indicate to the speech engine that audio is now going to start being written */
132 void ast_speech_start(struct ast_speech *speech);
133 /*! \brief Create a new speech structure */
134 struct ast_speech *ast_speech_new(const char *engine_name, int formats);
135 /*! \brief Destroy a speech structure */
136 int ast_speech_destroy(struct ast_speech *speech);
137 /*! \brief Write audio to the speech engine */
138 int ast_speech_write(struct ast_speech *speech, void *data, int len);
139 /*! \brief Signal to the engine that DTMF was received */
140 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf);
141 /*! \brief Change an engine specific attribute */
142 int ast_speech_change(struct ast_speech *speech, const char *name, const char *value);
143 /*! \brief Change the type of results we want */
145 /*! \brief Change state of a speech structure */
146 int ast_speech_change_state(struct ast_speech *speech, int state);
147 /*! \brief Register a speech recognition engine */
149 /*! \brief Unregister a speech recognition engine */
150 int ast_speech_unregister(const char *engine_name);
151 
152 #if defined(__cplusplus) || defined(c_plusplus)
153 }
154 #endif
155 
156 #endif /* _ASTERISK_SPEECH_H */
int state
Definition: speech.h:59
int(* change_results_type)(struct ast_speech *speech, enum ast_speech_results_type results_type)
Definition: speech.h:97
int ast_speech_destroy(struct ast_speech *speech)
Destroy a speech structure.
Definition: res_speech.c:224
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:123
int(* activate)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:85
enum ast_speech_results_type results_type
Definition: speech.h:67
int(* change)(struct ast_speech *speech, const char *name, const char *value)
Definition: speech.h:95
int ast_speech_register(struct ast_speech_engine *engine)
Register a speech recognition engine.
Definition: res_speech.c:272
struct ast_speech_result * ast_speech_results_get(struct ast_speech *speech)
Get speech recognition results.
Definition: res_speech.c:91
void * data
Definition: speech.h:63
char * name
Definition: speech.h:75
int value
Definition: syslog.c:39
int(* start)(struct ast_speech *speech)
Definition: speech.h:93
char * grammar
Definition: speech.h:114
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:264
ast_speech_results_type
Definition: speech.h:45
int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name)
Deactivate a grammar on a speech structure.
Definition: res_speech.c:73
int(* dtmf)(struct ast_speech *speech, const char *dtmf)
Definition: speech.h:91
int ast_speech_change_state(struct ast_speech *speech, int state)
Change state of a speech structure.
Definition: res_speech.c:249
int(* create)(struct ast_speech *speech, int format)
Definition: speech.h:77
struct ast_speech_engine * engine
Definition: speech.h:69
int(* unload)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:83
int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name)
Unload a grammar.
Definition: res_speech.c:85
struct ast_speech_result * results
Definition: speech.h:65
int(* write)(struct ast_speech *speech, void *data, int len)
Definition: speech.h:89
int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name)
Activate a grammar on a speech structure.
Definition: res_speech.c:67
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
Definition: file.c:65
int(* load)(struct ast_speech *speech, const char *grammar_name, const char *grammar)
Definition: speech.h:81
unsigned int flags
Definition: speech.h:55
int format
Definition: speech.h:61
int ast_speech_results_free(struct ast_speech_result *result)
Free a set of results.
Definition: res_speech.c:97
ast_mutex_t lock
Definition: speech.h:53
ast_speech_states
Definition: speech.h:38
int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
Signal to the engine that DTMF was received.
Definition: res_speech.c:155
AST_LIST_ENTRY(ast_speech_engine) list
int ast_speech_unregister(const char *engine_name)
Unregister a speech recognition engine.
Definition: res_speech.c:303
char * processing_sound
Definition: speech.h:57
int ast_speech_write(struct ast_speech *speech, void *data, int len)
Write audio to the speech engine.
Definition: res_speech.c:145
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:79
int(* deactivate)(struct ast_speech *speech, const char *grammar_name)
Definition: speech.h:87
ast_speech_flags
Definition: speech.h:31
static snd_pcm_format_t format
Definition: chan_alsa.c:93
int ast_speech_change(struct ast_speech *speech, const char *name, const char *value)
Change an engine specific attribute.
Definition: res_speech.c:170
int(* destroy)(struct ast_speech *speech)
Definition: speech.h:79
Structure for mutex and tracking information.
Definition: lock.h:121
struct ast_speech * ast_speech_new(const char *engine_name, int formats)
Create a new speech structure.
Definition: res_speech.c:176