guide.doc

speech signal process tools

       type  float  such  that 1.0 + x != 1.0.  FLT_MIN is intended to be the
       minimum positive value of type float---a small positive number, not  a
       big  negative number.  DBL_EPSILON and DBL_MIN are the analogous quan-
       tities for type double.)  These names, and the ones already defined in
       esps/limits.h,  are taken from a draft of the forthcoming ANSI C stan-
       dard.  Under an ANSI implementation all these constants and  a  number
       of  others  could be made available by making esps/limits.h a two-line
       file containing

           #include <limits.h>
           #include <float.h>.


       13 .  ESPS File Types

       The file ftypes.h, as described above, defines a  symbol  for  various
       ESPS file types.  These symbols all begin with FT_ ; for example, ESPS
       feature files have the type FT_FEA stored in the  header  type  field.
       FEA  file  (type  FT_FEA) also have subtype codes, such as FEA_ANA and
       FEA_VQ. The various specialized  file  types  other  than  FT_FEA  are
       obsolescent and have been replaced with subtypes of FT_FEA.  For exam-
       ple, former special file types for sampled data (FT_SD)  and  spectrum
       data  (FT_SPEC)  have  been  superseded  by  FEA  subtypes  FEA_SD and
       FEA_SPEC.  In the case of sampled-data  files,  provisions  have  been


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 18


       made  to allow programs that read FEA_SD files to automatically accept
       the old FT_SD files as well---see [6].

       14 .  Type Specific I/O

       For each of the defined data file types and FEA subtypes, there  is  a
       set  of data access functions (see the manual entries for each type or
       subtype in reference [4]).  For example  for  FEA_SPEC(5-ESPS)  files,
       one  can  use  allo_feaspec_rec(3-ESPSu)  to  allocate  memory  for  a
       FEA_SPEC record (the size of the record depends on values in the  data
       file  header), get_feaspec_rec(3-ESPSu) to read a FEA_SPEC record from
       a    file    into    the    FEA_SPEC     record     structure,     and
       put_feaspec_rec(3-ESPSu)  to  write  a  FEA_SPEC data structure onto a
       file.

       Some older programs use a function get_gen_recd(3-ESPSu) that supports
       non-type-specific  data-file  input by reading the next record from an
       ESPS data file into a vector;  access  to  a  field  element  requires
       knowledge  of  the  starting  location of the field within the vector.
       This style of file access is  obsolete  now  that  FEA  subtypes  have
       replaced file types other than FT_FEA.

       New programs should use the general FEA file facilities, which use the
       self-documenting  property of FEA files and, among other things, allow
       access to fields within a record by name.  See [3] for information  on
       how to program with FEA files, how to create new FEA subtypes for gen-
       eral or private use, and how to create extensions of existing FEA sub-
       types.

       15 .  NULL POINTERS

       Whenever NULL is passed as a function argument, it  must  be  cast  to
       something.  No exceptions.  (Otherwise it is liable to be passed as an
       integer 0, and on some machines a null pointer may  have  a  different
       size or representation.)

       NULL pointers can be de-referenced on MASSCOMPs, but not on  Suns  and
       many  other  machines.   Accordingly,  there  should  be  no  such de-
       references in ESPS code.

       16 .  Example

       Here is a sketch of an ESPS program (this does not correspond  exactly
       to the current ESPS program fft(1-ESPS)):

           /*
            * system include files
            */
           #include <stdio.h>
           /*
            * include files
            */
           #include <esps/esps.h>


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 19


           #include <esps/feasd.h>
           #include <esps/feaspec.h>
           /*
            *defines
            */
           #define Fprintf (void)fprintf
           #define SYNTAX USAGE(     "fft [-o order] [-{pr} range][-x debug_level] [-P param] file.sd file.spec")
           /*
            * external functions
            */
            . . .
           /*
            * main program
            */
           main(argc, argv)
               int   argc;
               char  **argv;
           {
               char  *ProgName = "fft";
               char  *Version = "1.19";
               char  *Date = "2/20/90";
               char  *param_file = NULL;       /* parameter file name */
               FILE  *ifile = stdin,
                     *ofile = stdout;          /* input and output file streams */
               struct header   *ih, *oh;       /* input and output file headers */
               char  *iname, *oname;           /* input and output file names */
               struct feaspec  *spec_rec;      /* record for spectral data */
               struct feasd    *sd_rec;        /* record for input data */
               char  *prange = NULL;           /* string to specify range (-p, -r) */
               int   p_flag = 0;               /* flag for range option */
               long  nframes = 1;              /* number of frames to process */
               float *x, *y;                   /* arrays for data and fft of data */
               int   more = 1;                 /* flag to indicate more sampled data */
               int   err;                      /* return code from init_feaspec_hd */
               float sf;                       /* sampling frequency */
               . . .
               /*
                * process command line options
                */
               while ((ch = getopt(argc, argv, "o:p:r:x:P:")) != EOF)
                   switch (ch) {
                       case 'o':
                           order = atoi(optarg);
                           break;
                       case 'p':
                       case 'r':
                           prange = optarg;
                           p_flag++;
                           break;
                       case 'x':
                           debug_level = atoi(optarg);
                           break;
                       case 'P':


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 20


                           param_file = optarg;
                           break;
                       default:
                           SYNTAX;
                           break;
                   }
               /*
                * open input FEA_SD file
                */
               if (optind < argc)
                   iname = eopen(ProgName, argv[optind++],
                                       "r", FT_FEA, FEA_SD, &ih, &ifile);
               else {
                   Fprintf(stderr,
                       "%s: no input sampled-data file specified.0, ProgName);
                   SYNTAX;
               }
               /*
                * open output FEA_SPEC file
                */
               if optind < argc)
                   oname = eopen(ProgName, argv[optind++],
                                       "w", NONE, NONE, &oh, &ofile);
               else {
                   Fprintf(stderr, "%s: no output file specified.0, ProgName);
                   SYNTAX;
               }
               /*
                * read range from ESPS common, if range option not used;
                * the filename in common must match that of the input sampled-data file
                */
               if (!p_flag) read_params(param_file, SC_CHECK_FILE, iname);
               get_range(&first, &last, prange, p_flag);
               symerr_exit();  /* exit if any of the parameters were missing */
               . . .
               nan = last - first + 1;
               length = ROUND(pow(2.0, (double) order));
               /*
                * allocate input record and set up pointer to data
                */
               sd_rec = allo_feasd_recs(ih, FLOAT, length, (char *) NULL, NO);
               spsassert(sd_rec, "Can't allocate record for input data");
               x = (float *) sd_rec->data;
               y = (float *) malloc((unsigned) length * sizeof(float));
               spsassert(y, "Can't allocate space for imaginary part");

               /*
                * create output FEA file header and fill in universal portion
                */
               oh = new_header(FT_FEA);
               oh->common.tag = YES;
               (void) strcpy(oh->common.prog, ProgName);
               (void) strcpy(oh->common.vers, Version);


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 21


               (void) strcpy(oh->common.progdate, Date);
               oh->variable.refer = iname;
               add_source_file(oh, iname, ih);
               add_comment(oh, get_cmd_line(argc, argv));
               /*
                * Set up FEA_SPEC header
                */
               sf = *get_genhd_d("record_freq", ih);
               err = init_feaspec_hd(oh, YES, SYM_EDGE, ST_DB, YES,
                       (length/2+1), SPFRM_FIXED, (float *) NULL,
                       sf, length, FLOAT),
               spsassert(!err, "Error filling FEA_SPEC header");

               /*
                * add generic header items
                */
               *add_genhd_l("fft_length", (long *) NULL, 1, oh) = length;
               /*
                * write FEA_SPEC file header and allocate FEA_SPEC record
                */
               write_header(oh, ofile);
               spec_rec = allo_feaspec_rec(oh, FLOAT);
               /*
                * move to starting position in FEA_SD file
                */
               if (first > 1) skiprec(ifile, first - 1, size_rec(ih));
               /*
                * main loop
                */
               position = first;
               nframes = 1 + (nan - 1)/length;

               for (i = 0; i < nframes && more; i++) {
                   /*
                    * initialize data arrays
                    */
                   for (j = 0; j < length; j++) x[j] =  y[j] = 0.0;
                   /*
                    * get sampled data and perform fft
                    */
                   if (get_feasd_recs(sd_rec, 0L, length, ih, ifile) == 0) {
                       more = 0;
                       Fprintf(stderr, "%s: WARNING, EOF reached in input file0, ProgName);
                   }
                   get_fft(x, y, order);
                   /*
                    * fill in and write out spectral record
                    */
                   spec_rec->tag = first;
                   for (j = 0; j < (length/2+1); j++)
                       spec_rec->re_spec_val[j] = 10 * log10(x[j]*x[j] + y[j]*y[j]);
                   spec_rec->tag = position;
                   position += length;


       Version 3.6                      ERL                           1/22/93







       ETM-S-86-14                                                    page 22


                   put_feaspec_rec(spec_rec, oh, ofile);
               }

           /*
            * put FEA_SD file info into ESPS common
            */
               if (strcmp(iname, "<stdout>") != 0) {
                   (void) putsym_s("filename", iname);
                   (void) putsym_s("prog", ProgName);
                   (void) putsym_i("start", (int) first);
                   (void) putsym_i("nan", (int) nan);
               }
               exit(0);
           }

           void
           get_range(srec, erec, rng, rflag)
           long *srec;                 /* starting record */
           long *erec;                 /* end record */
           char *rng;                  /* range string from range option */
           int rflag;                  /* flag for whether range option used */
           {
               *srec = 1;
               *erec = LONG_MAX;
               if (rflag)
               lrange_switch (rng, srec, erec, 1);
               else {
               if(symtype("start") != ST_UNDEF) *srec = getsym_i("start");
               if(symtype("nan") != ST_UNDEF) *erec = *srec + getsym_i("nan") - 1;
               }
           }
























       Version 3.6                      ERL                           1/22/93