guide.doc

speech signal process tools

       ETM-S-86-14                                                    page 12


       default  behavior  should  be  to  plot  on  the user's screen.  Also,
       device-specific output should be specifiable with the -T switch on the
       command  line.   Where  possible,  values for the -T option will agree
       with those of the UNIX plot(1) command  where  possible.  Common  ESPS
       supported options here are gps, mcd, tek,  and imagen.

       7 .  Standard Option Letters

       When appropriate, ESPS programs should use the the following  standard
       options:

            -c = comment
            -f = fieldname
            -g = gain
            -h = history file
            -k = clock, keyword
            -m = mode, method
            -n = number, value
            -r = records
            -s = seconds
            -t = text, title, data type
            -u = unvoiced speech
            -v = voiced speech/records
            -w = width, window
            -x = debug level
            -y = y-axis
            -z = suppress
            -P = parameter file name
            -T = device type
            -X = x-axis
            -Y = y-axis
            -Z = suppress


       The -x and -P options in particular are nearly universal.

       The -r option is commonly used to specify a range  of  input  records,
       counting  from  1  for the first record of a file.  Programs that read
       sampled data used to use -p ("points")  in  a  similar  way;  however,
       current practice is to favor -r, and programs that accept -p and -r as
       synonyms do so for the sake of backward compatibility.  The -s  option
       is commonly used to specify an input range in seconds.  For interpret-
       ing the arguments of -r and -s, special library support is  available:
       range_switch(3-ESPSu), lrange_switch(3-ESPSu), frange_switch(3-ESPSu),
       trange_switch(3-ESPSu).

       The -f option often accepts an extended "field name" that  includes  a
       bracketed  specification  of  a  subset  of  the  field  elements; see
       fld_range_switch(3-ESPSu), grange_switch(3-ESPSu).






       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 13


       8 .  Command Line Options and Parameter File Values

       In general analysis conditions are specified in a  file  read  by  the
       ESPS  program  (see  reference (2) for details of the parameter file).
       However, if the programmer decides that certain parameter values  will
       change  often  from  run to run, then these values can be specified on
       the command line as options.  When  used,  command  line  values  will
       override  values  in  the  parameter  file  given  for  the  variable.
       Analysis parameter values should be stored in the output file  header,
       using  either  built-in  header fields or generics; this holds whether
       the parameters were specified on the command line or in the  parameter
       file.  For compatibility with current ESPS, programs should be written
       so that all parameters are obtained from the parameter file (with pos-
       sible command-line overrides).

       For programs that process parameter and common files, the manual  page
       must  include  the  sections  "ESPS PARAMETERS" and "ESPS COMMON". The
       first of these should document all of the  parameters  that  are  read
       from the parameter file.  The second should explain how ESPS common is
       handled by the  program  (ignored,  processed,  or  processed  with  a
       filename  restriction---see  [3]),  and  it should document any values
       that are written to ESPS common.

       In order to allow new analysis condition options to be added for test-
       ing  or  experiments,  without modifying the data file headers immedi-
       ately, but still record all analysis conditions  in  the  output  file
       header,  all  ESPS  programs  will store the command line that invoked
       them in the comment field of the of the output file header.  A library
       function,  get_cmd_line  (3-ESPS) returns the command line as a string
       for inclusion in the header.

       9 .  Internal Structure of ESPS Programs

       Programs should conform to the following general structure:

                 include files
                 defines
                 system functions and variables
                 external ESPS functions and variables
                 global variables (not too many please)
                 main program
                 functions

       All ESPS programs go through similar steps at the beginning and at the
       end.   First, the options, if any, are parsed using the getopt(3) sub-
       routine (note:  getopt is standard in System V.   We  have  a  public-
       domain  version  in  the  ESPS  library).   A  USAGE message should be
       printed if the command line is incorrect.   Source  file  headers  are
       read  using  the  read_header(3-ESPS)  routine and the various generic
       header access routines:  genhd_list (3-ESPS), genhd_type (3-ESPS), and
       get_genhd  (3-ESPS).  The routine eopen(3-ESPS) can be used to facili-
       tate file opening, header  reading,  and  file  type  checking.   Then
       read_params(3-ESPS)  is  called to read the parameter and common files


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 14


       and create a symbol table; needed parameters are checked and retrieved
       from   the  symbol  table  using  the  symbol  table  access  routines
       (getsym_X(3-ESPS)).  The routine symerr_exit(3-ESPS) is  called  after
       all  parameter  values are retrieved; it cleans up and exits after any
       symbol table errors.  Parameter values and header values  are  checked
       for  consistency  (documentation for individual programs will describe
       the checks performed), and the program exits if the any  source  files
       are  the wrong type or if they are inconsistent with one another.  For
       details about programming procedures for parameter and  common  files,
       see [2].

       Record keeping is performed using add_source_file,  get_cmd_line,  and
       add_comment (3-ESPS).

       Output headers  are  created  with  new_header  (3-ESPS),  copy_header
       (3-ESPS),  and  the  generic  header routines add_genhd_X(3-ESPS).  In
       most cases, all fields of the output file header will be known  before
       any  processing  is  performed.   If  so, the output header(s) is(are)
       written by calling write_header(3-ESPS) and any data to be written  by
       the  program is appended.  If this is not possible, output is directed
       to a temporary file, then the header is written,  and  then  the  tem-
       porary  file is dumped to the output and deleted.  This method is pre-
       ferred to patching up header locations by doing disk  seeks  since  it
       allows  the output to be a pipe.  Definition of FEA file records using
       add_fea_fld (3-ESPS) must also take place before the header  is  writ-
       ten.

       All programs return zero exit status if the  program's  operation  was
       successful,  and  nonzero  exit  status if an error occurred, so shell
       scripts are notified of the error condition.

       10 .  Compile-time vs. Run-time Symbols

       Many analysis conditions are given as character strings for  names  of
       methods,  such  as AUTO_SAM, HAMMING, LPC10, etc.    These strings are
       associated with  C  compile-time  #define  values.   For  example,  in
       <header.h> there is the statement

           #define HAMMING 1

       The value that actually gets stored to identify  the  method  in  this
       case  is  1,  but  the  programs  all reference that value as HAMMING.
       There is no built-in connection between the run-time  reading  of  the
       parameter  file  and  the  compile-time symbol HAMMING.  Of course, we
       don't want to read the integer 1 from the parameter file  (or  command
       line)  in  this  case,  and  we  don't want to see it in listings from
       psps(1-ESPS).  To make the connection between the compile-time symbols
       and  the run-time reading of the parameter file, there are arrays that
       contain these symbols.   A  function,  lin_search  (3-ESPS),  searches
       these  arrays  and returns the index if the symbol is found.  By using
       these arrays and this function, the programmer can easily read charac-
       ter  strings  from  the parameter file or the command line and get the
       value associated with that string for comparison against the  compile-


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 15


       time  symbols.   See  lin_search (3-ESPS) and lin_search2 (3-ESPS) for
       details.

       These arrays can also be used to return the string associated  with  a
       particular compile-time symbol.  For example:

           printf("Method is %s",method_array[method_code]);

       will  print  the  symbol  associated  with  the   current   value   of
       method_code.   The  values  for  many  of  these  arrays are stored in
       <header.h> or ...general/src/lib/methods.c.  Others can  be  found  by
       reading the relevant program documentation.

       11 .  ESPS Include Files and Library Functions

       Include  files  for  ESPS  programs  are   stored   in   a   directory
       $ESPS_BASE/include/esps.   Programs  include  such files by means of a
       line of the form

            #include <esps/include_file.h>

       The install script makes sure that ESPS compilations are done with the
       appropriate -I flag to cause the ESPS include directory to be searched
       before the standard locations.  Here are some of  the  most  important
       ESPS include files:

       anafea.h  Includes declarations needed for FEA_ANA files;

       constants.h
                 Includes some useful constant declarations,  in  particular,
                 PI.

       epaths.h  Convenient macros for using find_esps_file(3-ESPS) to locate
                 files at standard locations in the ESPS directory tree or at
                 alternative  locations  specified  by  standard  environment
                 variables.  This file is included automatically by <esps.h>.

       esps.h    Includes  some  useful  macro   definitions   and   includes
                 epaths.h,   ftypes.h,   header.h,   limits.h,  param.h,  and
                 spsassert.h.  All ESPS programs should  include  this  file,
                 and not make specific reference to those files.

       exview.h  Main  include  file   for   libxv.    Includes   exv_keys.h,
                 exv_icon.h,  exv_colors.h, exv_bbox.h, and exv_func.h, which
                 should not be included directly  by  programs  that  include
                 this file.

       fea.h     Includes declarations for FEA files.

       feafilt.h Includes declarations for FEA_FILT files.

       feasd.h   Includes declarations for FEA_SD files.



       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 16


       feaspec.h Includes declarations for FEA_SPEC files.

       feastat.h Includes declarations for FEA_STAT files.

       ftypes.h  Includes declarations for file type constants.  This file is
                 included automatically by <esps.h>.

       header.h  Includes declarations for header  structure,  header  access
                 routines  and  character arrays containing methods and codes
                 values for use  with  lin_search.   This  file  is  included
                 automatically by <esps.h>.

       limits.h  Limits on values representable in  various  C  numeric  data
                 types.   See "Defined Constants for Numerical Limits" below.
                 This file is included automatically by <esps.h>.

       param.h   Includes declarations for parameter  file  access  routines.
                 This file is included automatically by <esps.h>.

       spsassert.h
                 Definition of the  macro  spsassert(3-ESPSu)  This  file  is
                 included automatically by <esps.h>.

       scbk.h    Includes declarations for SCBK files.

       unix.h    Declarations for the standard Unix  library  functions  with
                 ifdefs  for machine type.  Programs should include this file
                 and not define the Unix functions directly, since the return
                 types  vary  from  implementation  to  implementation, and a
                 declaration that is correct for one may fail on another.

       vq.h      Includes declarations for FEA_VQ files.

       In most cases, an ESPS program will include <esps/esps.h> and  one  or
       more  type specific include files, depending on the type of data files
       the program handles.  See the Section 5 manual pages [4].

       12 .  Defined Constants for Numerical Limits

       ESPS programs sometimes need to be written in terms of the  limits  on
       the  values  representable  in various C numeric data types.  A set of
       defined constants giving the maximum and minimum  values  for  various
       data types is available and should be used when appropriate.  Here are
       the names of the defined constants and typical values  for  a  machine
       with IEEE floating point:

            CHAR_MAX       127
            CHAR_MIN       -128
            SHRT_MAX       32767
            SHRT_MIN       -32768
            LONG_MAX       2147483647
            LONG_MIN       -2147483648
            FLT_MAX        (float)3.40282346638528860e+38


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 17


            DBL_MAX        1.79769313486231470e+308


       These are available in programs that contain the line

           #include <esps/limits.h>

       and since that line is in the ESPS include file esps.h, the  constants
       are also automatically available in programs that contain

           #include <esps/esps.h>

       Instead of containing private definitions like

           #define MAX_FLOAT 1.0e37

       or

           #define REALLY_BIG_NUMBER 1.0e30

       ESPS programs should simply refer to an appropriate constant, such  as
       FLT_MAX,  from  the  list  above.  They should also avoid referring to
       similar definitions in the system include file  /usr/include/values.h;
       on  Masscomp systems, for example, some of the values in values.h can-
       not be processed correctly by some versions of the C compiler.

       The  following  names   are   reserved   for   future   expansion   of
       esps/limits.h:   INT_MIN,  INT_MAX, FLT_EPSILON, DBL_EPSILON, FLT_MIN,
       DBL_MIN.  (FLT_EPSILON is intended to be the smallest  positive  x  of