history.doc

speech signal process tools

       5 .  DETAILED RECORD KEEPING IN ESPS FILE HEADERS

            ESPS file headers comprise three parts:  the  universal  section,
       the type-specific section, and generic header items.  When headers are
       viewed with psps, all header items are identified by name.  The header
       items  are  also referred to by these same names within ESPS programs,
       which makes it easier to write, read, and maintain programs.

       5 .1 .1 .  The Universal Section of the Header

            As the name implies, the universal section of the ESPS header has
       the  same  definition for all ESPS file types.  The comment field dis-
       cussed above is part of the universal  section,  which  also  contains


       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                          page 8


       information  about  the  type  of  data  in the file, the program that
       created the file, the user who created  the  file,  the  input  source
       files, etc.

            When psps is called without any options, it outputs the universal
       section  of  the  header  followed  by  all  of the data records.  The
       universal header alone, can be viewed with the -D  (no  data)  option,
       and  the  universal header plus a restricted range of data records can
       be viewed with the -r (range)  option.   Here,  for  example,  is  the
       universal header and first 15 data records of a sampled data file from
       specdemo:

           %psps -r1:15 sines.sd
           File: sines.sd

           ---Universal Part of Header---
           File type: FEA (Feature File)
           File header date: Tue Mar 20 14:37:01 1990 , header version: 1.73
           Produced by: addsd, version: 3.12, of: 2/19/90, user: burton
           Hostname:path: epiwrl:/u2/burton/esps/doc
           Machine type: Masscomp; file is in NATIVE format.
           Number of data records: 8000
           Data is not tagged.
           comment text:
            addsd sine1.sd sine2.sd sines.sd
              Added samples from sine2.sd to samples 1 - 8000 of sine1.sd.
           Source files: sine1.sd
                         sine2.sd
           There is no reference header.

                1:      0.0000   263.0596   502.7742   698.2844   833.4172
                6:    898.3527   890.5669   814.9475   683.0757   511.7628
               11:    321.0198   131.6999   -36.9073  -169.2464  -255.1805

       The meaning of most of the header items is obvious; for the others see
       ESPS (5-ESPS) in Section 5 of the User's Manual.

       5 .2 .  Type-Specific Section of the Header

            As the name implies, this section of the header is used to record
       information relevant to the specific file type.  The items defined for
       a particular built-in file type are described in the manual  page  for
       that  file  type in Section 5 of the ESPS Manual.  For example, see SD
       (5-ESPS) for the  type-specific  header  definition  for  sampled-data
       files.  For FEA files and FEA subtypes, the type-specific section con-
       tains the self-description information - the names, types,  and  sizes
       of the record fields defined in the file.

            The output from psps will include the  type-specific  header  (in
       addition  to  the  universal  header) if the -l (for "long") option is
       used.  For example, here is the header for the  file  signal.sd  (pro-
       duced as part of specdemo:
            %psps -l signal.sd


       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                          page 9


            File: signal.sd

            ---Universal Part of Header---
            File type: FEA (Feature File)
            File header date: Tue Mar 20 14:37:06 1990 , header version: 1.73
            Produced by: addsd, version: 3.12, of: 2/19/90, user: burton
            Hostname:path: epiwrl:/u2/burton/esps/doc
            Machine type: Masscomp; file is in NATIVE format.
            Number of data records: 8000
            Data is not tagged.
            comment text:
             addsd gauss.sd sines.sd signal.sd
               Added samples from sines.sd to samples 1 - 8000 of gauss.sd.
            Source files: gauss.sd
                          sines.sd
            There is no reference header.

            ---Type Specific Part of Header (FEA)---
            fea_type: FEA_SD, segment_labeled: NO, field_count: 1

            ---Generic Part of Header---
            record_freq:  20000
            start_time:  0

       The generic part of the header  is  explained  in  the  next  section.
       Notice  that non-numeric quantities are printed symbolically (e.g., NO
       instead of something like "type 0").

            For FEA files, the -l option on psps shows the  FEA  subtype  (if
       any),  whether  or not the file is segment labelled, and the number of
       fields.  Here is an example using the FEA_SPEC file  signal.spec  from
       specdemo:

           %psps -l signal.spec
           File: signal.spec

           ---Universal Part of Header---
           File type: FEA (Feature File)
           File header date: Fri Jan  6 11:11:22 1989 , header version: 1.66
           Produced by: me_spec, version: 1.4, of: 12/13/88, user: shore
           Hostname:path: epiwrl:/u2/shore/epi/esps/doc/demo
           Number of data records: 1
           Data is  tagged.
           refer file: signal.sd
           comment text:
           me_spec signal.rc signal.spec
           Source files: signal.rc
           There is no reference header.

           ---Type Specific Part of Header (FEA)---
           fea_type: FEA_SPEC, segment_labeled: NO, field_count: 3

           ---Generic Part of Header---


       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                         page 10


           contin:  YES
           frame_meth:  FIXED
           freq_format:  SYM_EDGE
           frmlen:  2500
           num_freqs:  513
           order_unvcd:  100
           order_vcd:  0
           record_freq:  8
           sf:  20000
           spec_type:  DB
           src_sf:  20000
           start:  1
           start_time:

       The generic part of the header  is  explained  in  the  next  section.
       Notice,  however, that non-numeric quantities are printed symbolically
       (e.g., SYM_EDGE instead of something like "type 3").  Again, the mean-
       ings  of these items are described in the relevant Section 5 man page,
       in this case FEA_SPEC (5-ESPS).

            If detailed information is needed about the field definitions for
       FEA  files,  the  -v  should  be used on psps.  This expands the type-
       specific portion of the FEA header to show the names, types, and sizes
       of the defined fields.  For CODED fields, the possible symbolic values
       are shown.  The -v also gives the same details for the generic  header
       items.

           %psps -v signal.spec
           File: signal.spec

           ---Universal Part of Header---
           File type: FEA (Feature File)
           File header date: Fri Jan  6 11:11:22 1989 , header version: 1.66
           Produced by: me_spec, version: 1.4, of: 12/13/88, user: shore
           Hostname:path: epiwrl:/u2/shore/epi/esps/doc/demo
           Number of data records: 1
           Data is  tagged.
           Data format is 0 doubles, 514 floats, 0 longs,
           1 shorts, and 0 chars (bytes).
           refer file: signal.sd
           comment text:
           me_spec signal.rc signal.spec
           Source files: signal.rc
           There is no reference header.

           ---Type Specific Part of Header (FEA)---
           fea_type: FEA_SPEC, segment_labeled: NO, field_count: 3
           Item name: tot_power, type: FLOAT, size: 1
           Item name: re_spec_val, type: FLOAT, size: 513, rank: 1
           Item name: voiced, type: CODED, size: 1
           Possible coded values:
           NO
           YES


       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                         page 11


           ---Generic Part of Header---
           contin: (CODED) YES
           Possible coded values:
           NO
           YES
           frame_meth: (CODED) FIXED
           Possible coded values:
           NONE
           FIXED
           VARIABLE
           freq_format: (CODED) SYM_EDGE
           Possible coded values:
           NONE
           SYM_CTR
           SYM_EDGE
           ASYM_CTR
           ASYM_EDGE
           ARB_VAR
           ARB_FIXED
           frmlen: (LONG) 2500
           num_freqs: (LONG) 513
           order_unvcd: (LONG) 100
           order_vcd: (LONG) 0
           record_freq: (DOUBLE) 8
           sf: (FLOAT) 20000
           spec_type: (CODED) DB
           Possible coded values:
           NONE
           PWR
           DB
           REAL
           CPLX
           src_sf: (DOUBLE) 20000
           start: (LONG) 1
           start_time: (DOUBLE) 0.0625


       5 .3 .  Generic Header Items

            The pre-defined items in the universal and  type-specific  header
       sections  are intended to be useful in a broad range of typical appli-
       cations.  However, they cannot anticipate every application,  so  ESPS
       provides  a  mechanism  by  which programs can store additional, arbi-
       trarily named items in any  ESPS  header;  these  are  called  generic
       header  items.   Like other header items, the values in generic header
       items are available (by name) to programs that process the files.

            For example, testsd can produce several types  of  test  sampled-
       data (sine waves, noise, or pulses), and it is useful to record in the
       output header which of these was chosen.  Since  the  standard  FEA_SD
       type-specific  header has no provision for this (which would be silly,
       as the list of possibly useful items  would  be  endless),  a  generic
       header-item is used.


       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                         page 12


            Generic header items are output by psps when  the  -l  option  is
       used.   (Thus,  this  option  yields  the  universal header, the type-
       specific header, and the generics.)  Here, for example,  is  the  com-
       plete header of sine1.sd (from specdemo):

           %psps -Dl sine1.sd
           File: sine1.sd

           ---Universal Part of Header---
           File type: FEA (Feature File)
           File header date: Tue Mar 20 14:36:48 1990 , header version: 1.71
           Produced by: testsd, version: 3.12, of: 10/17/89, user: burton
           Hostname:path: epiwrl:/u2/burton/esps/doc
           Machine type: Masscomp; file is in NATIVE format.
           Number of data records: 8000
           Data is not tagged.
           comment text:
            testsd -Tsine -f600 -r20000 sine1.sd
           There is no reference header.

           ---Type Specific Part of Header (FEA)---
           fea_type: FEA_SD, segment_labeled: NO, field_count: 1

           ---Generic Part of Header---
           frequency:  600
           level:  500
           max_value:  500
           phase:  0
           record_freq:  20000
           start_time:  0
           test_type:  SINE

       Although in this case the type of test signal can be deduced from  the
       command  line  in  the comment field, it is not always so obvious (the
       default might be used).  Besides, a program  that  processes  sine1.sd
       can  obtain  the  test  type by means of a simple library call, rather
       than having to do elaborate string processing on the comment field.

       5 .3 .1 .  Adding Generic Header Items at the User Level

            The program addgen (1-ESPS) allows users to add  to  add  generic
       header  items  to existing ESPS files (analogous to the use of comment
       in adding to the comment field).  This can be useful as an alternative
       form  of  informal  record record keeping, and as a means of inserting
       values that may not be present but are needed by other  programs  that
       are  to  be  run  subsequently  on the file.  For example, suppose one
       wants to insert a header item in the file signal.sd to record the sig-
       nal  to  noise  ratio  (which is 1.0).  Here's the appropriate call to
       addgen:

           %addgen -g sn_ratio -v float -v 1.0 signal.sd




       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                         page 13


       An alternative is to use the eparam (1-ESPS) to provide an interactive
       interface:

           %eparam addgen signal.sd
           Name of new generic header item [item1]: sn_ratio
           Type of new generic header item [long]: float
           Value of new generic header item [1000.000000]: 1.0


       Here, each of the three lines following the eparam call has  a  prompt
       (with  default)  output  by eparam with the the user's input following
       the colon.  After adding a generic header item in this way, it will be
       reflected in subsequent psps listings:

           %psps -Dl signal.sd
           File: signal.sd

           ---Universal Part of Header---
           File type: FEA (Feature File)
           File header date: Tue Mar 20 14:37:06 1990 , header version: 1.73
           Produced by: addsd, version: 3.12, of: 2/19/90, user: burton
           Hostname:path: epiwrl:/u2/burton/esps/doc
           Machine type: Masscomp; file is in NATIVE format.
           Number of data records: 8000
           Data is not tagged.
           comment text:
            addsd gauss.sd sines.sd signal.sd
              Added samples from sines.sd to samples 1 - 8000 of gauss.sd.
            added generic "sn_ratio" on Tue Mar 20 14:58:46 1990
           Source files: gauss.sd
                         sines.sd
           There is no reference header.

           ---Type Specific Part of Header (FEA)---
           fea_type: FEA_SD, segment_labeled: NO, field_count: 1

           ---Generic Part of Header---
           record_freq:  20000
           sn_ratio:  1
           start_time:  0


       Besides floats, addgen supports double precision, long integer,  short
       integer,  and  string header items.  It also supports two special data
       types that link the header to ESPS  headers  and  ASCII  files  stored
       separates.  We discuss these next.

       5 .3 .2 .  External Headers and Files

            It is sometimes convenient to associate a parameter set  with  an
       ESPS file without storing the parameters within the header.  For exam-
       ple, a large database of speech files  could  have  a  common  set  of
       parameters  that  document  aspects  of the data collection.  While it


       3.9                              ERL                           1/22/93







       RECORD KEEPING IN ESPS                                         page 14


       would be wasteful to store this information in every file, it's impor-
       tant  that it be readily available not only for visual inspection, but
       also for access by programs.  ESPS meets this need with generic header