spspaper.vme

speech signal process tools

consider the following sequence of ESPS commands:  
.nf

	%refco data.sd data.fana
	%anaspec data.fana data.spec
	%plotspecm data.spec 

.fi
.lp
The first command causes the reflection coefficients computed from
data frames in the SD file data.sd to be placed in the FEA_ANA file
data.fana.  The second command computes spectra for each set of
reflection coefficients and puts the results in the SPEC file
data.spec.  The third command plots all the spectra on the screen
using a single set of axes.  If there is no need to retain the
intermediate FEA_ANA and SPEC files, one could do the following
instead:
.nf

	%refco data.sd \- | anaspec \- \- | plotspecm \-
 
.fi
.lp
Similarly, if only the SPEC file is wanted, the first two commands 
could be replaced by:
.nf

	%refco data.sd \- | anaspec \- data.spec

.fi
.lp
An important consideration in using pipes with ESPS programs is that
record keeping is not compromised.  Thus, the file header for
data.spec in the command above will include the header of the 
file produced by \fIrefco\fP (i.e., the header of data.fana in 
the first version of this sequence of operations, above).  
.sh 1 "PARAMETERS FOR ESPS PROGRAMS"
.lp
Signal processing programs often are affected by a large set of input
parameters.  Rather than requiring that all parameters be specified
on the command line, which is not only error-prone but leads to
ridiculously-long command lines, ESPS provides a mechanism that uses
a distinguished ASCII file called the parameter file.  Parameters are
specified in this file using a C-like syntax that allows the user
either to provide specific values for the parameters within the
parameter file or to have the program prompt the user for their
values at run time.  The default convention for the parameter file
name is "params" in the current directory, but for all programs this
can be changed using the \fB\-P\fP command-line option.
.lp
For example, \fIrefco\fP (1\-\s-1ESPS\s+1) computes 
reflection coefficients for fixed-length segments of sampled-data.  
To do so it requires parameters that specify the starting point,
the segment size, the number of segments, the coefficients of 
a pole-zero filter than optionally can be used to pre-filter the
data, and the method used for computing reflection coefficients.  
The call
.nf

    %refco \-P params.3 john.sd john.fana

.fi
indicates that reflection coefficients are to be computed for data in
the file john.sd using parameter values in the file params.3 (the
user may be prompted for some of the values), and that the results
are to be written to the file john.fana.
.lp
The ESPS parameter file provides a convenient means for users to
communicate parameter values to signal processing programs.  In many
signal processing applications, however, there is also a need for one
program to communicate parameter values to another program that is run
subsequently.  In ESPS, this need is met by the ESPS common file.  
If the common file exists and was written more recently than the 
parameter file, then parameter values in the common file supersede 
those in the parameter file.  Thus, a program can write a value into
the common file and have that value be used by a subsequent program.  
For example, suppose that
.i plotsd
(1\-\s-1ESPS\s+1) is used to plot the first 10,000 points of an SD
file in a graphics window:
.nf
 
	%plotsd \-p1:10000 file.sd
 
.fi
After this plot is made, the user can run
.i range
(1\-\s-1ESPS\s+1) to select a portion of the displayed data (using the mouse).
When 
.i range
exits, it writes the selected range and the filename "file.sd" into the
ESPS common file.  If the user then runs 
.nf
 
	%plotsd

.fi
(i.e., without any command line options), the selected range of the same
file will be displayed.  Similarly, if the user runs 
.nf

	%play

.fi
(again, without options), the selected range of the same file will be 
played out over the system D/A converter.  
.lp
The default ESPS common file is ".spscom " in the user's home
directory, but this default can be changed by using the \s-1UNIX\s+1
shell environment variable SPSCOM.  Thus, for csh users, 
.nf
 
	%setenv SPSCOM /u/shore/common.3

.fi
resets the common file to /u/shore/common.3.  This facility for
changing the common file is needed so that users can prepare and run
several shell scripts without having them interfere with each other.
.lp
To summarize, ESPS programs get their parameters from three sources:
.SM .5i
.ip \(bu 3
the ESPS parameter file
.ip \(bu 3
the ESPS common file
.ip \(bu 3
command line options
.RM
.lp
In general, if a command-line option is available to set a parameter
value, its use overrides any of the other mechanisms by which programs
get parameter values.  
.sh 1 "PROGRAMMING WITH ESPS FILES"
.lp
This section contains a brief introduction to the C structures used
for ESPS headers and records, as well as to some of the ESPS library
routines that facilitate ESPS file processing.  If you are not
interested in ESPS programming, skip to Section 7.
.sh 2 "ESPS File Headers"
.lp
The standard ESPS file header consists of two primary parts, the
universal section and the type-specific section.  All header
items (including generics) are referred to by name in programs.
This makes it easier to write, read, and maintain programs.
Also, when headers are output in ASCII form using
.i psps
(1\-\s-1ESPS\s+1), all of the items (including generics) are 
identified by name.  
.sh 3 "The Universal Section of the Header"
.lp
As the name implies, the universal section of the ESPS header has the
same definition for all ESPS file types.  This section of the header
is divided into a fixed-length portion called the \fIcommon\fP
section, and a variable-length portion called the \fIvariable\fP
section.
.lp
The universal section of an ESPS header contains information about the
type of data in the file, the program that created the file, the user
who created the file, the creation date, version information,
housekeeping information required by the header access routines,
history data, etc.  When user programs need to refer directly to
these items, they do so by name.  For example, consider the items
"tag" in the common portion and "refer" in the variable portion.
"Tag" determines whether or not the records in the file each contain
a tag pointing to a particular record in some pre-existing source
file; if they do, then "refer" is the name of the source file to
which they refer.  Here is an example of how these header items are
referred to in source code:
.vS
.nf

    #include <esps/sps.h>
    struct header *h;
    . . .
    if (h->common.tag) printf("source file for tags is %s\n", h->variable.refer);

.fi
.vE
In most cases, ESPS programs do not refer directly to items in the
universal section of the header because these items are maintained 
directly or indirectly by utility routines in the ESPS library.  For 
example, the universal section of the header contains a
variable-length comment field that is used to record arbitrary
ASCII comments.  Programs add comments to an existing header though 
use of \fIadd_comment\fP (3\-\s-1ESPS\s+1), as in
.vS
.nf

    add_comment(h, "This file contains clipped values.\n");

.fi
.vE
The user-level program \fIcomment\fP (1\-\s-1ESPS\s+1), mentioned in 
Section 3 above, is implemented by means of calls to
\fIadd_comment\fP.  
.sh 3 "The Type-Specific Section of the Header"
.lp
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 file type are described in the manual page for
that file type in Section 5 of the ESPS Manual.  For example, see
SD (5\-\s-1ESPS\s+1) for the type-specific header definition for 
sampled data files.  
.lp
To facilitate a standard form for referring to the type-specific
header items, a C union is used.  For example, here is a code
fragment that might apply to a program that processes a SD
(sampled-data) file and produces a SPEC (spectral record) file ("sf" 
is a SD-header item giving the sampling frequency, and "nan" 
is SPEC-header item giving the number of points analyzed):
.vS
.nf

    struct header *ih;	    /*SD input file header*/
    struct header *oh;	    /*SPEC output file header*/
    long seconds;	    /*amount of input data to process (seconds)*/
    . . .
    /*now compute number of points of data*/
    oh->hd.spec->nan = seconds * ih->hd.sd->sf;

.fi 
.vE 
.sh 3 "Generic Header Items" 
.lp 
The pre-defined items in the universal and type-specific header
sections are intended to be useful in a broad range of typical
applications.  However, they cannot anticipate every application.
For example, the SD file type does not make provision for storing in
the file header the average rate of zero crossings, but applications
arise when it is convenient to do so.  To address such needs, ESPS
provides generic header items.
.lp 
Generic header items provide programmers with the
ability to create arbitrary named fields in the header of any ESPS
file.  Utility functions in the ESPS library facilitate the creation
and manipulation of generics.  For example, the function 
.i add_genhd_f 
(3\-\s-1ESPS\s+1) can be used to create a generic header comprising
one or more floats.  Here's one example of its use to create
and fill an item called "zero_cross_rate":  
.vS
.nf

    struct header *hd;
    float time;
    long nzeros;
    . . .
    *add_genhd_f("zero_cross_rate", NULL, 1L, hd) = nzeros / time;

.fi
.vE
.lp
Similarly, \fIget_genhd\fP (3\-\s-1ESPS\s+1) returns a pointer to
an existing generic and might be used as follows:
.vS
.nf

    struct header *hd;
    long estim_zeros;
    float time;
    . . .
    /*compute estimated number of zeros*/
    estim_zeros = time * (*(float *) get_genhd("zero_cross_rate", hd));

.fi
.vE
.lp
Generic header items can store any type of C variable values, including
characters (and strings).  Also provided are generic header items 
to store enumerated types (also called coded types).  These header
items store an integer value but allow those values to be expressed
symbolically via a set of pre-defined strings.	For example, this 
code creates and fills a generic header item called "filter_type":
.vS
.nf

    /*defined constants for filter_type*/
    #define MISC	0
    #define LOW_PASS	1
    #define HIGH_PASS	2
    #define BAND_PASS	3