word_fsg.h
Go to the documentation of this file.
1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /* ====================================================================
3  * Copyright (c) 1999-2004 Carnegie Mellon University. All rights
4  * reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  *
13  * 2. Redistributions in binary form must reproduce the above copyright
14  * notice, this list of conditions and the following disclaimer in
15  * the documentation and/or other materials provided with the
16  * distribution.
17  *
18  *
19  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
20  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
23  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  *
31  * ====================================================================
32  *
33  */
34 /*
35  * word_fsg.h -- Word-level finite state graph
36  *
37  * **********************************************
38  * CMU ARPA Speech Project
39  *
40  * Copyright (c) 2003 Carnegie Mellon University.
41  * ALL RIGHTS RESERVED.
42  * **********************************************
43  *
44  * HISTORY
45  *
46  * $Log$
47  * Revision 1.1 2006/04/05 20:27:30 dhdfu
48  * A Great Reorganzation of header files and executables
49  *
50  * Revision 1.2 2006/02/23 05:10:18 arthchan2003
51  * Merged from branch SPHINX3_5_2_RCI_IRII_BRANCH: Adaptation of Sphinx 2's FSG search into Sphinx 3
52  *
53  * Revision 1.1.2.5 2005/07/20 21:15:56 arthchan2003
54  * A FSG in Sphinx 2 can be read by word_fsg.c but there is memory leaks using word_fsg_readfile. Sounds like related to str2word.
55  *
56  * Revision 1.1.2.4 2005/07/17 05:58:20 arthchan2003
57  * Added context-table argument in word_fsg.h
58  *
59  * Revision 1.1.2.3 2005/07/13 18:39:48 arthchan2003
60  * (For Fun) Remove the hmm_t hack. Consider each s2 global functions one-by-one and replace them by sphinx 3's macro. There are 8 minor HACKs where functions need to be removed temporarily. Also, there are three major hacks. 1, there are no concept of "phone" in sphinx3 dict_t, there is only ciphone. That is to say we need to build it ourselves. 2, sphinx2 dict_t will be a bunch of left and right context tables. This is currently bypass. 3, the fsg routine is using fsg_hmm_t which is just a duplication of CHAN_T in sphinx2, I will guess using hmm_evaluate should be a good replacement. But I haven't figure it out yet.
61  *
62  * Revision 1.1.2.2 2005/06/28 07:01:21 arthchan2003
63  * General fix of fsg routines to make a prototype of fsg_init and fsg_read. Not completed. The number of empty functions in fsg_search is now decreased from 35 to 30.
64  *
65  * Revision 1.1.2.1 2005/06/27 05:26:29 arthchan2003
66  * Sphinx 2 fsg mainpulation routines. Compiled with faked functions. Currently fended off from users.
67  *
68  * Revision 1.2 2004/07/23 23:36:34 egouvea
69  * Ravi's merge, with the latest fixes in the FSG code, and making the log files generated by FSG, LM, and allphone have the same 'look and feel', with the backtrace information presented consistently
70  *
71  * Revision 1.6 2004/07/20 20:48:41 rkm
72  * Added uttproc_load_fsg()
73  *
74  * Revision 1.5 2004/07/20 13:40:55 rkm
75  * Added FSG get/set start/final state functions
76  *
77  * Revision 1.1 2004/07/16 00:57:12 egouvea
78  * Added Ravi's implementation of FSG support.
79  *
80  * Revision 1.4 2004/07/15 20:51:07 rkm
81  * *** empty log message ***
82  *
83  * Revision 1.3 2004/06/21 18:14:20 rkm
84  * Omitted noise words from FSG if noise penalty = 0
85  *
86  * Revision 1.2 2004/05/27 14:22:57 rkm
87  * FSG cross-word triphones completed (but for single-phone words)
88  *
89  * Revision 1.1.1.1 2004/03/01 14:30:31 rkm
90  *
91  *
92  * Revision 1.6 2004/02/27 15:05:21 rkm
93  * *** empty log message ***
94  *
95  * Revision 1.5 2004/02/26 15:35:50 rkm
96  * *** empty log message ***
97  *
98  * Revision 1.4 2004/02/26 01:14:48 rkm
99  * *** empty log message ***
100  *
101  * Revision 1.3 2004/02/25 15:08:19 rkm
102  * *** empty log message ***
103  *
104  * Revision 1.2 2004/02/24 18:13:05 rkm
105  * Added NULL transition handling
106  *
107  * Revision 1.1 2004/02/23 15:53:46 rkm
108  * Renamed from fst to fsg
109  *
110  * Revision 1.6 2004/02/19 21:16:54 rkm
111  * Added fsg_search.{c,h}
112  *
113  * Revision 1.5 2004/02/16 21:10:10 rkm
114  * *** empty log message ***
115  *
116  * Revision 1.4 2004/02/12 16:06:03 rkm
117  * *** empty log message ***
118  *
119  * Revision 1.3 2004/02/09 21:19:22 rkm
120  * *** empty log message ***
121  *
122  * Revision 1.2 2004/02/09 17:30:49 rkm
123  * *** empty log message ***
124  *
125  * Revision 1.1 2004/02/03 21:08:05 rkm
126  * *** empty log message ***
127  *
128  *
129  * 13-Dec-2004 M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon
130  * Started.
131  */
132 
133 
134 #ifndef __S2_WORD_FSG_H__
135 #define __S2_WORD_FSG_H__
136 
137 
138 #include <stdio.h>
139 
140 #include <s3types.h>
141 #include <glist.h>
142 #include <fsg.h>
143 #include <kbcore.h>
144 #include <dict.h>
145 #include <mdef.h>
146 #include <tmat.h>
147 #include <ctxt_table.h>
148 
149 #if 0
150 #include <fbs.h>
151 #endif
152 
153 
154 #ifdef __cplusplus
155 extern "C" {
156 #endif
157 #if 0
158 /* Fool Emacs. */
159 }
160 #endif
161 
162 /*
163  * A single transition in the FSG.
164  */
165 typedef struct word_fsglink_s {
166  int32 from_state;
167  int32 to_state;
168  s3wid_t wid; /* Word-ID; <0 if epsilon or null transition */
169  int32 logs2prob; /* logs2(transition probability)*lw */
171 
172 
173 /* Access macros */
174 #define word_fsglink_from_state(l) ((l)->from_state)
175 #define word_fsglink_to_state(l) ((l)->to_state)
176 #define word_fsglink_wid(l) ((l)->wid)
177 #define word_fsglink_logs2prob(l) ((l)->logs2prob)
178 
179 
180 /*
181  * Word level FSG definition.
182  * States are simply integers 0..n_state-1.
183  * A transition emits a word and has a given probability of being taken.
184  * There can also be null or epsilon transitions, with no associated emitted
185  * word.
186  */
187 typedef struct word_fsg_s {
188  char *name; /* A unique string identifier for this FSG */
189  int32 n_state; /* #states in FSG */
190  int32 start_state; /* Must be in the range [0..n_state-1] */
191  int32 final_state; /* Must be in the range [0..n_state-1] */
192  uint8 use_altpron; /* Whether transitions for alternative pronunciations
193  have been added to the FSG */
194  uint8 use_filler; /* Whether silence and noise filler-word transitions
195  have been added at each state */
196  float32 lw; /* Language weight that's been applied to transition
197  logprobs */
198  glist_t **trans; /* trans[i][j] = glist of non-epsilon transitions or
199  links (word_fsglink_t *) from state i to state j,
200  if any; NULL if none. */
201  word_fsglink_t ***null_trans; /* null_trans[i][j] = epsilon or null link
202  from state i to j, if any; NULL if none.
203  (At most one null transition between two
204  given states.) */
205 
206  /*
207  * Left and right CIphone sets for each state.
208  * Left context CIphones for a state S: If word W transitions into S, W's
209  * final CIphone is in S's {lc}. Words transitioning out of S must consider
210  * these left context CIphones.
211  * Similarly, right contexts for state S: If word W transitions out of S,
212  * W's first CIphone is in S's {rc}. Words transitioning into S must consider
213  * these right contexts.
214  *
215  * NOTE: Words may transition into and out of S INDIRECTLY, with intermediate
216  * null transitions.
217  * NOTE: Single-phone words are difficult; only SILENCE right context is
218  * modelled for them.
219  * NOTE: Non-silence filler phones aren't included in these sets. Filler
220  * words don't use context, and present the SILENCE phone as context to
221  * adjacent words.
222  */
223  int8 **rc, **lc;
224 
226  int32 n_ciphone;
231 } word_fsg_t;
232 
233 /* Access macros */
234 #define word_fsg_name(f) ((f)->name)
235 #define word_fsg_n_state(f) ((f)->n_state)
236 #define word_fsg_start_state(f) ((f)->start_state)
237 #define word_fsg_final_state(f) ((f)->final_state)
238 #define word_fsg_lw(f) ((f)->lw)
239 #define word_fsg_use_altpron(f) ((f)->use_altpron)
240 #define word_fsg_use_filler(f) ((f)->use_filler)
241 #define word_fsg_trans(f,i,j) ((f)->trans[i][j])
242 #define word_fsg_null_trans(f,i,j) ((f)->null_trans[i][j])
243 #define word_fsg_lc(f,s) ((f)->lc[s])
244 #define word_fsg_rc(f,s) ((f)->rc[s])
245 
246 
247 /*
248  * Read a word FSG from the given file and return a pointer to the structure
249  * created. Return NULL if any error occurred.
250  *
251  * File format:
252  *
253  * Any number of comment lines; ignored
254  * FSG_BEGIN [<fsgname>]
255  * N <#states>
256  * S <start-state ID>
257  * F <final-state ID>
258  * T <from-state> <to-state> <prob> [<word-string>]
259  * T ...
260  * ... (any number of state transitions)
261  * FSG_END
262  * Any number of comment lines; ignored
263  *
264  * The FSG spec begins with the line containing the keyword FSG_BEGIN.
265  * It has an optional fsg name string. If not present, the FSG has the empty
266  * string as its name.
267  *
268  * Following the FSG_BEGIN declaration is the number of states, the start
269  * state, and the final state, each on a separate line. States are numbered
270  * in the range [0 .. <numberofstate>-1].
271  *
272  * These are followed by all the state transitions, each on a separate line,
273  * and terminated by the FSG_END line. A state transition has the given
274  * probability of being taken, and emits the given word. The word emission
275  * is optional; if word-string omitted, it is an epsilon or null transition.
276  *
277  * Comments can also be embedded within the FSG body proper (i.e. between
278  * FSG_BEGIN and FSG_END): any line with a # character in col 1 is treated
279  * as a comment line.
280  *
281  * Other arguments:
282  * - use_altpron: if TRUE, if a transition labelled W exists between two
283  * states, all the alternative pronunciations of W (in the dictionary) are
284  * also added as transitions with the same given probability.
285  * - use_filler: if TRUE, a separate transition for each silence and noise
286  * filler word in the lexicon is added at each state (loop transition).
287  * However, if noiseword penalty is 0.0, noise words are ignored.
288  * - silprob: transition prob for silence word transitions (if use_filler)
289  * - fillprob: transition prob for noise word transitions (if use_filler)
290  * - lw: language weight, applied as a multiplicative factor to the LOG of
291  * the transition probs.
292  *
293  * Return value: a new word_fsg_t structure if the file is successfully
294  * read, NULL otherwise.
295  */
296 word_fsg_t *word_fsg_readfile (const char *file,
297  int use_altpron, int use_filler,
298  kbcore_t *kbc);
299 
300 
301 /*
302  * Like word_fsg_readfile(), but from an already open stream.
303  */
304 word_fsg_t *word_fsg_read (FILE *fp,
305  int use_altpron, int use_filler,
306  kbcore_t *kbc);
307 
308 
309 /*
310  * Like word_fsg_read(), but from an in-memory structure.
311  */
313  int use_altpron, int use_filler,
314  kbcore_t *kbc);
315 
316 
317 /*
318  * Write the given fsg structure to the given file.
319  * (This needs options for writing in format readable by word_fsg_read().)
320  */
321 void word_fsg_writefile (word_fsg_t *fsg, char *file);
322 
323 
324 /*
325  * Like word_fsg_writefile(), but to an already open stream.
326  */
327 void word_fsg_write (word_fsg_t *fsg, FILE *fp);
328 
329 
330 /*
331  * Free the given word FSG
332  */
333 void word_fsg_free(word_fsg_t *);
334 
335 
336 /*
337  * Set the FSG start state (or the final state) to the given state.
338  * Return value: -1 if there was any error, otherwise the previous start
339  * state (or final state).
340  */
341 int32 word_fsg_set_start_state (word_fsg_t *fsg, int32 new_start_state);
342 int32 word_fsg_set_final_state (word_fsg_t *fsg, int32 new_final_state);
343 
344 #ifdef __cplusplus
345 }
346 #endif
347 
348 
349 #endif
strcture for storing the model definition.
Definition: mdef.h:184
struct word_fsglink_s word_fsglink_t
int32 word_fsg_set_start_state(word_fsg_t *fsg, int32 new_start_state)
char * name
Definition: word_fsg.h:188
int32 s3wid_t
Definition: s3types.h:136
void word_fsg_write(word_fsg_t *fsg, FILE *fp)
tmat_t * tmat
Definition: word_fsg.h:229
float32 lw
Definition: word_fsg.h:196
Definition: word_fsg.h:187
glist_t ** trans
Definition: word_fsg.h:198
kb core structures, the structure that stores parameters for s3.X search
Operations on dictionary.
word_fsg_t * word_fsg_readfile(const char *file, int use_altpron, int use_filler, kbcore_t *kbc)
ctxt_table_t * ctxt
Definition: word_fsg.h:230
uint8 use_filler
Definition: word_fsg.h:194
Definition: fsg.h:58
int32 final_state
Definition: word_fsg.h:191
word_fsg_t * word_fsg_read(FILE *fp, int use_altpron, int use_filler, kbcore_t *kbc)
dict_t * dict
Definition: word_fsg.h:227
void word_fsg_free(word_fsg_t *)
Size definition of semantically units. Common for both s3 and s3.X decoder.
a structure for a dictionary.
Definition: dict.h:146
Transition matrix data structure.
void word_fsg_writefile(word_fsg_t *fsg, char *file)
Transition matrix data structure. All phone HMMs are assumed to have the same topology.
Definition: tmat.h:113
struct word_fsg_s word_fsg_t
int32 n_ciphone
Definition: word_fsg.h:226
word_fsg_t * word_fsg_load(s2_fsg_t *s2_fsg, int use_altpron, int use_filler, kbcore_t *kbc)
uint8 use_altpron
Definition: word_fsg.h:192
Model definition.
int32 word_fsg_set_final_state(word_fsg_t *fsg, int32 new_final_state)
mdef_t * mdef
Definition: word_fsg.h:228
int8 ** rc
Definition: word_fsg.h:223
Definition: kbcore.h:134
int32 start_state
Definition: word_fsg.h:190
int32 n_state
Definition: word_fsg.h:189
Definition: ctxt_table.h:353
word_fsglink_t *** null_trans
Definition: word_fsg.h:201