Document License

 This work is licensed under the Creative Commons Attribution-Share Alike 3.0
 United States License. To view a copy of this license, visit 
 http://creativecommons.org/licenses/by-sa/3.0/us/
 or send a letter to Creative Commons, 171 Second Street, Suite 300,
 San Francisco, California, 94105, USA.

 
Contributors to this document

 Copyright (C) 2010 Texas Instruments Incorporated - http://www.ti.com/


----------------

The TIesrFlex API is the top-level API that an application designer uses to
create a binary grammar network and acoustic model file set given an input
grammar specification. The output file set is used by the TIesrSI API to perform
speech recognition. The TIesrFlex API uses the TIesrDict and TIesrDT APIs.


Using the testtiesrflex Program
-------------------------------

The testtiesrflex program exercises the TIesrFlex API. The source of the
testtiesrflex program provides an illustration of how the TIesrFlex API can be
used to create a binary grammar and model file set. The detailed description of
the user API functions supplied by the TIesrFlex API is found in the TIesrFlex.h
header file. The command line for the program is: 

testtiesrflex grm_string out_dir data_dir language [max_pron inc_rule 
    auto_sil lit_end byte_mean byte_var
    
grm_string: String defining the grammar
out_dir:    Directory to place binary grammar network and acoustic model files
data_dir:   Top level directory holding pronunciation and model data
language:   Name of the language directory just under data_dir
max_pron:   Maximum pronunciations per word to include in output grammar network
inc_rule:   Flag indicating to include decision tree rule pronunciation
auto_sil:   Flag indicating to include optional silence between words
lit_end:    Flag output files in little endian format
byte_mean:  Output acoustic probability mean vectors as byte data
byte_var:   Output acoustic probability variance vectors as byte data
add_close:  (optional; default enabled) Add closure phones prior to stop
consonants

grm_string is a string argument that defines the grammar for which a network and
model set will be created.  The grammar string is in an easy to use text format.
Documentation of the format is provided in the TIesr documenation. out_dir is
the directory to hold the binary grammar network and model set output. data_dir
is the top level of a directory tree containing data that TIesrFlex needs to
create its output. Directly under this directory should be a sub-directory for a
language, which is specified by the language argument on the testtiesrflex
commmand line. The structure of data_dir/language is such that it holds the
TIesrDT decision trees, TIesrDict dictionary (in a sub-directory usually named
Dict), and the acoustic model information (in a sub-directory usually named
Models). There are several optional arguments to the test program. max_pron
specifies the maximum pronunciations allowed for a word. The number of
pronunciations actually available is dependent on the number of entries in the
dictionary. inc_rule is a 0/1 flag that specifies whether to include the
decision tree rule as a pronunciation.  If inc_rule is set to zero (false), then
the decision tree rule pronunciation generated by TIesrDT will not be used if
there is a pronunciation in the dictionary. If there is no entry for a word in
the dictionary, then the decision tree rule pronunciation must be used. auto-sil
is a 0/1 flag that specifies if a silence model is automatically inserted
between each word, and should normally be set to 1 (true). little_endian is a
0/1 flag that specifies if the output should be written in little or big-endian
format and depends on the platform architecture. byte_mean is a 0/1 flag
indicating if acoustic mean information should be compressed to single bytes,
and byte_var is a 0/1 flag indicating to compress acoustic variance data to
single bytes.  These last two flags reduce the size of the model information,
and have been designed such that there is minimal speech recognition performance
loss. add_close is a 0/1 flag indicating whether flexphone should automatically
add closure phones prior to the stop consonant phones (b,d,g,k,p,t). The closure
phones (bcl,dcl,gcl,kcl,pcl,tcl) must exist as valid phone models. This option
is turned on by default, but is somewhat specific to English.

An example of running the testtiesrflex program from the top-level distribution
directory on a Linux OS is shown below. This constructs the binary grammar
network and acoustic model file set for a simple grammar consisting of one of
the words "yes", "no", or "maybe".

Dist/LinuxReleaseGnu/bin/testtiesrflex \
      "start(_S). _S ---> yes | no | maybe." \
      Data/GramDir \
      Data/OffDT_GenDict_PhbVR_LE_MQ \
      English \
      2 0 1 1 1 1

Typical output from running this program is a sequence of messages
indicating correct operation and output:

Loading language, grammar, and model data
Parsing input grammar
Writing out binary grammar network and model files
Grammar network and model files output successfully

After running the program the directory Data/GramDir should contain the
following binary files with the sizes in bytes as:

    6  config.bin
    2  dim.bin
  336  gconst.bin
  278  hmm.bin
   22  hmm2phone.bin
 2056  mixture.bin
 5882  mu.bin
  152  net.bin
  296  o2amidx.bin
  184  pdf.bin
   80  scale.bin
  650  tran.bin
 3342  var.bin
 5124  vqcentr.bin
 
 
 The directory also contains the word.lis text file which should contain:
 
_SIL
yes
no
maybe





