name: trace_projector
synopsis: trace_projector [options] 

description:  
this is the isip trace projection decoder, the core of the asr system. 
the decoder can be run in several modes:

   viterbi alignment,
   lattice rescoring (n-gram rescoring or acoustic model rescoring)
   ngram decoding,
   lattice generation (from a lattice or from an n-gram LM),
   lattice error rate calculation

all input to the utility is provided via a parameter file.

Note that the lexicon must follow a specific order of words.
This order is --- !SENT_END, then!SENT_START, followed by !NET_START,
and these followed by all words sorted in alphabetical order. In case
dynamic LMs are not used in your application, !NET_START need not
appear in the lexicon

Also, note that for the HTK feature file, this utility strips the HTK header
and read features as floats. The ISIP prototype system has features as
doubles. This is a very limited HTK format support that we provide for
our system.

arguments:

  -p params_file	: parameters file
  -demo                 : run the decoder in demo mode, outputs a partial 
                          hypothesis after processing a user specified number
                          of frames
  -help                 : this file

examples:

trace_projector -p params.text

an example parameter file:

   # parameters file for the isip decoder
   #
   
   # define function mode
   # - forced_alignment: time align a set of known transcriptions using a 
   #   Viterbi DP
   # - lattice_rescoring: perform an acoustic rescoring of lattice files
   #   the language model scores are taken from the lattice file
   # - ngram_decoding: decode using an n-gram language model. note that for
   #   most applications this is very memory intensive
   # - lattice_generation: generate a lattice representing a narrowed
   #   search space. typically we use an n-gram language model to generate
   #   the lattice and then run with a stronger n-gram language model and 
   #   stronger acoustic models in "lattice_verification" mode
   # - lattice_verification: performs language model and acoustic model 
   #   rescoring of lattice files. this is typically the followup stage to
   #   running in lattice_generation mode
   # - lattice_to_lattice: generate a lattice from a lattice. similar to 
   #   lattice_generation mode but uses an existing lattice as the initial
   #   search space rather than the n-gram search space
   # - lattice_error_rate: calculates the error rate in the lattice by doing
   #   a DP alignment of a reference transcription to the lattice
   #
   # function = forced_alignment
   # function = lattice_rescoring
   # function = ngram_decoding
   # function = lattice_generation
   # function = lattice_verification
   # function = lattice_to_lattice
   function = lattice_error_rate

   # define segment mode
   # - none (default): the segmental information (alignments) is not
   #   used while decoding
   # - model: the model-level segmental information (alignments) is
   #   used to constraint the search space while decoding
   segment_mode = none
      
   # define model level segment list that contains the model
   # alignments. this list should match one-to-one with the input	
   # lists. this parameter is required only when the segment_mode is set
   # to model. the format of the alignments file is the same as the
   # output of the model-level force alignments
   #
   model_segment_list = model_segment.list
   
   # define input acoustic feature file list. this parameter is required
   # in all modes but lattice_error_rate
   #
   mfcc_list = test_input.list

   # define the output hypothesis file list. this list should match one-to-one
   # with the mfcc_list. this parameter is required in all modes which 
   # generate hypotheses: forced_alignment, lattice_rescoring, ngram_decoding,
   # lattice_generation, lattice_verification, lattice_to_lattice
   #
   output_list = test_output.list

   # define input lattice list. this list should match one-to-one with the
   # mfcc_list. this parameter is required in all modes which accept lattices
   # as input: lattice_rescoring, lattice_verification, lattice_to_lattice,
   # lattice_error_rate
   #
   input_lattice_list = test_lattice.list
   
   # define transcription file. this list should match one-to-one with the 
   # input lists. this parameter is required only in lattice_error_rate mode
   # and forced_alignment mode
   #
   transcription_file = test_ref.text
   
   # define lattice_error_rate output file. this parameter is required
   # only in lattice_error_rate mode
   #
   lattice_wer_file = test_wer.text
   
   # define output lattice list. this list should match one-to-one with the
   # mfcc_list. this parameter is required in any mode which generates a 
   # lattice: lattice_generation, lattice_to_lattice
   #
   output_lattice_list = test_outlat.list

   # define output nbest list. this list should match one-to-one with the
   # mfcc_list. this parameter is required if nbestlist is required in
   # any of the three modes : lattice_rescoring, ngram_decoding,
   # lattice_verification
   #	
   output_nbest_list = test_nbest.list
   
   # define grammar list file. this is a list of defined grammars in the 
   # dynamic language models. 
   #
   grammar_list_file = test_grammars.list
   
   # define the file containing the list of context-independent models.
   # required for all modes but lattice_error_rate
   #
   monophones_file = monophones.text

   # define the model definition file
   # required for all modes but lattice_error_rate
   #
   models_file = models.text
   
   # define phone mapping file created by create_triphone_map
   # required for all modes but lattice_error_rate
   #
   phones_file = phones.text
  
   # define lexicon file
   # required for all modes but lattice_error_rate
   #
   lexicon_file = lexicon.text
   
   # define the input states file
   # required for all modes but lattice_error_rate
   #
   states_file = states.bin

   # define the input transitions file
   # required for all modes but lattice_error_rate
   #
   transitions_file = transitions.text

   # define the output alignment mode (word, model, state). this parameter
   # determines how detailed the hypothesis alignments are. in state mode
   # the alignments are a state-frame mapping. beware that in state mode,
   # more information is stored by the decoder so the memory consumption
   # may be greater. also note that align_mode must be set to word when 
   # doing n-best generation. this parameter is required for all modes
   # which produce hypothesis output: forced_alignment, lattice_rescoring,
   # ngram_decoding, lattice_generation, lattice_verification,
   # lattice_to_lattice
   #
   align_mode = word
   
   # define an n-gram backoff language model and relevant n-gram parameters:
   # - lm_file: the language model file is in ARPA n-gram backoff format
   # - ngram_order: N >= 1. 1=unigram, 2=bigram, 3=trigram
   # - lm_scale: is a prescaling factor used to scale the n-gram score before
   #   incorporating it into the likelihood function during the search
   # - word_penalty: is a factor to add to any hypothesis which arrives at a 
   #   word end. this has the effect of discouraging the hypothesis of a long
   #   string of short duration words (common in LVCSR systems)
   # these parameters should be defined for any mode which uses an n-gram
   # language model: ngram_decoding, lattice_generation, lattice_verification
   #
   lm_file = bigram_lm.text
   ngram_order = 2
   lm_scale = 12.0
   word_penalty = -10
   
   # define number of history paths and n-best paths to preserve (N > 0)
   # - history_paths defines the number of n-best paths to keep at each 
   #   point in the search space. note that the history_paths should be set
   #   to 1 in n-gram decoding mode. this is required for modes where lattices
   #   are generated: lattice_generation, lattice_to_lattice and for 
   #   ngram_decoding mode
   # - nbest_paths defines the number of final sentence hypotheses to output.
   #   this parameter is required for any mode which produces a hypothesis:
   #   lattice_rescoring, ngram_decoding, lattice_generation,
   #   lattice_verification, lattice_to_lattice
   #
   history_paths = 100
   nbest_paths = 1
   
   # define the pruning parameters for the nbest list
   # - max_paths defines the maximum number of paths allowed at any
   #   time instance that will be used to determine the nbest paths
   # - nbest_beam defines the beam pruning threshold
   nbest_max_paths = 50
   nbest_beam = 100

   # define input acoustic feature file format (ascii or binary). note
   # that the states file should always be in binary mode. this parameter
   # is required for all modes which use acoustic feature file input: 
   # forced_alignment, lattice_rescoring, ngram_decoding, lattice_generation,
   # lattice_verification, lattice_to_lattice
   #
   input_format = ascii

   # define input feature file format (isip_proto (default) or htk)
   #	
   input_feature_format = isip_proto
   
   # define context mode (monophone, word_internal, or cross_word). this 
   # parameter is required for all modes
   #
   context_mode = cross_word
   
   # define pruning thresholds
   # - beam_pruning specifies the beam pruning thresholds (state, model, word)
   # - mapmi_limit specifies the maximum number of active phone instances
   # - num_allowed_words specifies the maximum number of hypothesized word ends
   #   which are allowed to be extended at any time frame
   # these parameters are required for all modes which perform acoustic
   # decoding: forced_alignment, lattice_rescoring, ngram_decoding, 
   # lattice_generation, lattice_verification, lattice_to_lattice
   # 
   beam_pruning = 300 150 150
   mapmi_limit = 10000
   num_allowed_words = 50

   # define parameters for the computation of delta and acceleration features
   # options for compute_delta and compute_acc are yes/no 
   #
   delta_win = 2
   compute_delta = no
   compute_acc = no

man page: http://www.isip.msstate.edu/projects/speech/education/toolkits/asr/decoder/decoder.html
