word_fsg.h

Go to the documentation of this file.
00001 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
00002 /* ====================================================================
00003  * Copyright (c) 1999-2004 Carnegie Mellon University.  All rights
00004  * reserved.
00005  *
00006  * Redistribution and use in source and binary forms, with or without
00007  * modification, are permitted provided that the following conditions
00008  * are met:
00009  *
00010  * 1. Redistributions of source code must retain the above copyright
00011  *    notice, this list of conditions and the following disclaimer. 
00012  *
00013  * 2. Redistributions in binary form must reproduce the above copyright
00014  *    notice, this list of conditions and the following disclaimer in
00015  *    the documentation and/or other materials provided with the
00016  *    distribution.
00017  *
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND 
00020  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
00021  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00022  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
00023  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00024  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00025  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
00026  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
00027  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00029  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  * ====================================================================
00032  *
00033  */
00034 /*
00035  * word_fsg.h -- Word-level finite state graph
00036  * 
00037  * **********************************************
00038  * CMU ARPA Speech Project
00039  *
00040  * Copyright (c) 2003 Carnegie Mellon University.
00041  * ALL RIGHTS RESERVED.
00042  * **********************************************
00043  * 
00044  * HISTORY
00045  * 
00046  * $Log$
00047  * Revision 1.1  2006/04/05  20:27:30  dhdfu
00048  * A Great Reorganzation of header files and executables
00049  * 
00050  * Revision 1.2  2006/02/23 05:10:18  arthchan2003
00051  * Merged from branch SPHINX3_5_2_RCI_IRII_BRANCH: Adaptation of Sphinx 2's FSG search into Sphinx 3
00052  *
00053  * Revision 1.1.2.5  2005/07/20 21:15:56  arthchan2003
00054  * 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.
00055  *
00056  * Revision 1.1.2.4  2005/07/17 05:58:20  arthchan2003
00057  * Added context-table argument in word_fsg.h
00058  *
00059  * Revision 1.1.2.3  2005/07/13 18:39:48  arthchan2003
00060  * (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.
00061  *
00062  * Revision 1.1.2.2  2005/06/28 07:01:21  arthchan2003
00063  * 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.
00064  *
00065  * Revision 1.1.2.1  2005/06/27 05:26:29  arthchan2003
00066  * Sphinx 2 fsg mainpulation routines.  Compiled with faked functions.  Currently fended off from users.
00067  *
00068  * Revision 1.2  2004/07/23 23:36:34  egouvea
00069  * 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
00070  *
00071  * Revision 1.6  2004/07/20 20:48:41  rkm
00072  * Added uttproc_load_fsg()
00073  *
00074  * Revision 1.5  2004/07/20 13:40:55  rkm
00075  * Added FSG get/set start/final state functions
00076  *
00077  * Revision 1.1  2004/07/16 00:57:12  egouvea
00078  * Added Ravi's implementation of FSG support.
00079  *
00080  * Revision 1.4  2004/07/15 20:51:07  rkm
00081  * *** empty log message ***
00082  *
00083  * Revision 1.3  2004/06/21 18:14:20  rkm
00084  * Omitted noise words from FSG if noise penalty = 0
00085  *
00086  * Revision 1.2  2004/05/27 14:22:57  rkm
00087  * FSG cross-word triphones completed (but for single-phone words)
00088  *
00089  * Revision 1.1.1.1  2004/03/01 14:30:31  rkm
00090  *
00091  *
00092  * Revision 1.6  2004/02/27 15:05:21  rkm
00093  * *** empty log message ***
00094  *
00095  * Revision 1.5  2004/02/26 15:35:50  rkm
00096  * *** empty log message ***
00097  *
00098  * Revision 1.4  2004/02/26 01:14:48  rkm
00099  * *** empty log message ***
00100  *
00101  * Revision 1.3  2004/02/25 15:08:19  rkm
00102  * *** empty log message ***
00103  *
00104  * Revision 1.2  2004/02/24 18:13:05  rkm
00105  * Added NULL transition handling
00106  *
00107  * Revision 1.1  2004/02/23 15:53:46  rkm
00108  * Renamed from fst to fsg
00109  *
00110  * Revision 1.6  2004/02/19 21:16:54  rkm
00111  * Added fsg_search.{c,h}
00112  *
00113  * Revision 1.5  2004/02/16 21:10:10  rkm
00114  * *** empty log message ***
00115  *
00116  * Revision 1.4  2004/02/12 16:06:03  rkm
00117  * *** empty log message ***
00118  *
00119  * Revision 1.3  2004/02/09 21:19:22  rkm
00120  * *** empty log message ***
00121  *
00122  * Revision 1.2  2004/02/09 17:30:49  rkm
00123  * *** empty log message ***
00124  *
00125  * Revision 1.1  2004/02/03 21:08:05  rkm
00126  * *** empty log message ***
00127  *
00128  * 
00129  * 13-Dec-2004  M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon
00130  *              Started.
00131  */
00132 
00133 
00134 #ifndef __S2_WORD_FSG_H__
00135 #define __S2_WORD_FSG_H__
00136 
00137 
00138 #include <stdio.h>
00139 
00140 #include <s3types.h>
00141 #include <glist.h>
00142 #include <fsg.h>
00143 #include <kbcore.h>
00144 #include <dict.h>
00145 #include <mdef.h>
00146 #include <tmat.h>
00147 #include <ctxt_table.h>
00148 
00149 #if 0 
00150 #include <fbs.h>
00151 #endif
00152 
00153 
00154 #ifdef __cplusplus
00155 extern "C" {
00156 #endif
00157 #if 0
00158 /* Fool Emacs. */
00159 }
00160 #endif
00161 
00162 /*
00163  * A single transition in the FSG.
00164  */
00165 typedef struct word_fsglink_s {
00166     int32 from_state;
00167     int32 to_state;
00168     s3wid_t wid;                /* Word-ID; <0 if epsilon or null transition */
00169     int32 logs2prob;    /* logs2(transition probability)*lw */
00170 } word_fsglink_t;
00171 
00172 
00173 /* Access macros */
00174 #define word_fsglink_from_state(l)      ((l)->from_state)
00175 #define word_fsglink_to_state(l)        ((l)->to_state)
00176 #define word_fsglink_wid(l)             ((l)->wid)
00177 #define word_fsglink_logs2prob(l)       ((l)->logs2prob)
00178 
00179 
00180 /*
00181  * Word level FSG definition.
00182  * States are simply integers 0..n_state-1.
00183  * A transition emits a word and has a given probability of being taken.
00184  * There can also be null or epsilon transitions, with no associated emitted
00185  * word.
00186  */
00187 typedef struct word_fsg_s {
00188     char *name;         /* A unique string identifier for this FSG */
00189     int32 n_state;      /* #states in FSG */
00190     int32 start_state;  /* Must be in the range [0..n_state-1] */
00191     int32 final_state;  /* Must be in the range [0..n_state-1] */
00192     uint8 use_altpron;  /* Whether transitions for alternative pronunciations
00193                                    have been added to the FSG */
00194     uint8 use_filler;   /* Whether silence and noise filler-word transitions
00195                            have been added at each state */
00196     float32 lw;         /* Language weight that's been applied to transition
00197                            logprobs */
00198     glist_t **trans;    /* trans[i][j] = glist of non-epsilon transitions or
00199                            links (word_fsglink_t *) from state i to state j,
00200                            if any; NULL if none. */
00201     word_fsglink_t ***null_trans;       /* null_trans[i][j] = epsilon or null link
00202                                            from state i to j, if any; NULL if none.
00203                                            (At most one null transition between two
00204                                            given states.) */
00205 
00206     /*
00207      * Left and right CIphone sets for each state.
00208      * Left context CIphones for a state S: If word W transitions into S, W's
00209      * final CIphone is in S's {lc}.  Words transitioning out of S must consider
00210      * these left context CIphones.
00211      * Similarly, right contexts for state S: If word W transitions out of S,
00212      * W's first CIphone is in S's {rc}.  Words transitioning into S must consider
00213      * these right contexts.
00214      * 
00215      * NOTE: Words may transition into and out of S INDIRECTLY, with intermediate
00216      *   null transitions.
00217      * NOTE: Single-phone words are difficult; only SILENCE right context is
00218      *   modelled for them.
00219      * NOTE: Non-silence filler phones aren't included in these sets.  Filler
00220      *   words don't use context, and present the SILENCE phone as context to
00221      *   adjacent words.
00222      */
00223     int8 **rc, **lc;
00224 
00226     int32 n_ciphone;
00227     dict_t* dict;
00228     mdef_t* mdef;
00229     tmat_t* tmat;
00230     ctxt_table_t *ctxt;
00231 } word_fsg_t;
00232 
00233 /* Access macros */
00234 #define word_fsg_name(f)                ((f)->name)
00235 #define word_fsg_n_state(f)             ((f)->n_state)
00236 #define word_fsg_start_state(f)         ((f)->start_state)
00237 #define word_fsg_final_state(f)         ((f)->final_state)
00238 #define word_fsg_lw(f)                  ((f)->lw)
00239 #define word_fsg_use_altpron(f)         ((f)->use_altpron)
00240 #define word_fsg_use_filler(f)          ((f)->use_filler)
00241 #define word_fsg_trans(f,i,j)           ((f)->trans[i][j])
00242 #define word_fsg_null_trans(f,i,j)      ((f)->null_trans[i][j])
00243 #define word_fsg_lc(f,s)                ((f)->lc[s])
00244 #define word_fsg_rc(f,s)                ((f)->rc[s])
00245 
00246 
00247 /*
00248  * Read a word FSG from the given file and return a pointer to the structure
00249  * created.  Return NULL if any error occurred.
00250  * 
00251  * File format:
00252  * 
00253  *   Any number of comment lines; ignored
00254  *   FSG_BEGIN [<fsgname>]
00255  *   N <#states>
00256  *   S <start-state ID>
00257  *   F <final-state ID>
00258  *   T <from-state> <to-state> <prob> [<word-string>]
00259  *   T ...
00260  *   ... (any number of state transitions)
00261  *   FSG_END
00262  *   Any number of comment lines; ignored
00263  * 
00264  * The FSG spec begins with the line containing the keyword FSG_BEGIN.
00265  * It has an optional fsg name string.  If not present, the FSG has the empty
00266  * string as its name.
00267  * 
00268  * Following the FSG_BEGIN declaration is the number of states, the start
00269  * state, and the final state, each on a separate line.  States are numbered
00270  * in the range [0 .. <numberofstate>-1].
00271  * 
00272  * These are followed by all the state transitions, each on a separate line,
00273  * and terminated by the FSG_END line.  A state transition has the given
00274  * probability of being taken, and emits the given word.  The word emission
00275  * is optional; if word-string omitted, it is an epsilon or null transition.
00276  * 
00277  * Comments can also be embedded within the FSG body proper (i.e. between
00278  * FSG_BEGIN and FSG_END): any line with a # character in col 1 is treated
00279  * as a comment line.
00280  * 
00281  * Other arguments:
00282  * - use_altpron: if TRUE, if a transition labelled W exists between two
00283  *   states, all the alternative pronunciations of W (in the dictionary) are
00284  *   also added as transitions with the same given probability.
00285  * - use_filler: if TRUE, a separate transition for each silence and noise
00286  *   filler word in the lexicon is added at each state (loop transition).
00287  *   However, if noiseword penalty is 0.0, noise words are ignored.
00288  * - silprob: transition prob for silence word transitions (if use_filler)
00289  * - fillprob: transition prob for noise word transitions (if use_filler)
00290  * - lw: language weight, applied as a multiplicative factor to the LOG of
00291  *   the transition probs.
00292  * 
00293  * Return value: a new word_fsg_t structure if the file is successfully
00294  * read, NULL otherwise.
00295  */
00296 word_fsg_t *word_fsg_readfile (const char *file,
00297                                int use_altpron, int use_filler,
00298                                kbcore_t *kbc);
00299 
00300 
00301 /*
00302  * Like word_fsg_readfile(), but from an already open stream.
00303  */
00304 word_fsg_t *word_fsg_read (FILE *fp,
00305                            int use_altpron, int use_filler,
00306                            kbcore_t *kbc);
00307 
00308 
00309 /*
00310  * Like word_fsg_read(), but from an in-memory structure.
00311  */
00312 word_fsg_t *word_fsg_load (s2_fsg_t *s2_fsg,
00313                            int use_altpron, int use_filler,
00314                            kbcore_t *kbc);
00315 
00316 
00317 /*
00318  * Write the given fsg structure to the given file.
00319  * (This needs options for writing in format readable by word_fsg_read().)
00320  */
00321 void word_fsg_writefile (word_fsg_t *fsg, char *file);
00322 
00323 
00324 /*
00325  * Like word_fsg_writefile(), but to an already open stream.
00326  */
00327 void word_fsg_write (word_fsg_t *fsg, FILE *fp);
00328 
00329 
00330 /*
00331  * Free the given word FSG
00332  */
00333 void word_fsg_free(word_fsg_t *);
00334 
00335 
00336 /*
00337  * Set the FSG start state (or the final state) to the given state.
00338  * Return value: -1 if there was any error, otherwise the previous start
00339  * state (or final state).
00340  */
00341 int32 word_fsg_set_start_state (word_fsg_t *fsg, int32 new_start_state);
00342 int32 word_fsg_set_final_state (word_fsg_t *fsg, int32 new_final_state);
00343 
00344 #ifdef __cplusplus
00345 }
00346 #endif
00347 
00348 
00349 #endif

Generated on 7 Mar 2010 by  doxygen 1.6.1