feasd.tme

speech signal process tools

The function attempts to read the next
.i num_records
FEA_SD records from stream
.i file
and store the contents of the "samples" fields
in the the structure pointed to by
.i rec,
beginning with element (or row) number
.i start.
Usually
.i start
will be 0,
for the first element or row;
the argument is provided for occasions when
one might wish to start reading into
the data buffer at some point after the beginning.
If any fields besides "samples" are present, their contents are ignored;
they do, however, make reading slower.
The sum
.i "start + num_records"
must not exceed
.i rec\->num_records.
The function returns the actual number of records read.
In particular, it returns 0 at end of file.
If the type of data in the file differs from
.i rec\->data_type,
the data are converted.
If fewer than the requested number
.i num_records
of records are read, the deficit is made up with zero fill.
.sh 3 "get_feasd_orecs"
.pp
To read overlapping or noncontiguous frames of sampled data, use the 
FEA_SD function analogous to the SD support functions
.i get_sd_orec {\c
.i dfs },
namely
.i get_feasd_orecs.
A call has the form
.ip
get_feasd_orecs(rec, start, framelen, step, hd, file)
.lp
Like
.i get_feasd_recs,
this function reads frames of sampled data from a FEA_SD file.
However, while
.i get_feasd_recs
moves a full frame length between calls,
.i get_feasd_orecs
moves by an arbitrary step.
.pp
A frame consists of the data from the "samples" fields of
.i framelen
records of the file.
Each frame after the first begins
.i step
records further along in the file than the previous frame;
thus frames overlap when
.i step<framelen,
are exactly abutted when
.i step==framelen,
and are separated by gaps when
.i step>framelen.
Each call of the function stores a frame in a buffer
that consists of a segment of the structure pointed to by
.i rec,
beginning with element or row number
.i start
(usually 0).
The sum
.i start+framelen
must not exceed
.i rec\->num_records,
and any elements or rows preceding number
.i start
or following number
.i start+framelen\-1
are left unchanged by the function.
All data read are converted, as necessary,
from the type indicated in the header to the type indicated in
.i rec\->data_type.
If a read attempt yields fewer records than required
(end of file),
the deficit is made up by zero fill.
The function returns the number of valid samples in the buffer.
This equals
.i framelen
when the requested number of records are successfully read;
otherwise it is some smaller number.
.pp
The buffer is assumed to contain data from a prior invocation of
.i get_feasd_orecs
or
.i get_feasd_recs.
Then, if
.i step<framelen,
the function drops the first
.i step
elements or rows of the buffer, shifts the next
.i step
positions toward the beginning, and attempts to read
.I step
more records to fill out the vacated positions at the end of the buffer.
The returned value is the number of records read plus
(\c
.i framelen\-step ).
.pp
If
.i step>=framelen,
the function ignores the previous contents of the buffer, skips
.i step\-framelen
records in the file,
and then attempts to read the next
.i framelen
records\*(--\c
.i i.e.,
after skipping a gap of
.i step\-framelen
records between frames,
.i get_feasd_orecs
operates like
.i get_feasd_recs.
Note that if
.i step==framelen,
the result is adjacent, non-overlapping frames such as
.i get_feasd_recs
produces.
.sh 3 "put_feasd_recs
.pp
To write data, use the
FEA_SD function analogous to the SD support functions
.i put_sd_rec {\c
.i dfs },
namely
.i put_feasd_recs.
A call has the form
.ip
put_feasd_recs(rec, start, num_records, hd, file)
.lp
The function takes data from the structure pointed to by
.i rec,
starting with element (or row) number
.i start
(usually 0 for the first element or row).
It puts the data into the "samples" fields of
.i num_records
FEA_SD records and writes the records to the stream
.i file.
Unlike
.i get_feasd_recs
and
.i get_feasd_orecs,
this function will not handle records containing fields other than "samples".
Programs that need to write FEA_SD files with additional fields
should use
.i put_fea_rec (3-ESPSu).
The sum
.i start+num_records
must not exceed
.i rec\->num_records.
If data type of the data in the file differs from the data type
.i rec\->data_type,
conversions are performed.
The file should be an open FEA_SD file.
The header must be written to the file before this function is called.
The function returns 0 upon successful completion
and a non-zero error code otherwise.
.sh 1 "BACKWARD COMPATIBILITY"
.pp
Two changes in ESPS library modules other than FEA_SD support
have been made to make it easier
to get existing programs working with FEA_SD files in addition to SD files.
.sh 2 "Using SD Support Functions with FEA_SD Files"
.pp
One set of changes involved the SD support functions:
they were extended
to work with single-channel FEA_SD files as well as SD files.
For example
.i get_sd_recd (3-ESPS),
if called with a pointer to a FEA_SD header as its third argument,
rather than a poiner to an SD header,
will simply go ahead and read the data from the FEA_SD file.
It will convert the data to
.i double
and put it in the same buffer it would use if reading from an SD file.
(This is a one-dimensional
.i double
array, not a
.i feasd
structure.)
Much code that works with SD files will thus now work wihout change
with FEA_SD files.
.sh 2 "Automatic Reading of SD Files as FEA_SD Files"
.pp
The other change involved the function
.i eopen (3-ESPSu),
which will open an ESPS file, read the header, and check the type.
The new behavior occurs when the call has the form
.ip
eopen(prog_name, file_name, "r", FT_FEA, FEA_SD, &hdr, &strm)
.lp
That is, the calling program expects to read a FEA_SD file and wants
.i eopen
to check for file type FEA and subtype FEA_SD.
If
.i eopen
finds an SD file instead,
it will on the spot convert the SD header to a FEA_SD header
and pass that out to the calling program instead of the SD header.
Thus the calling program is fooled into thinking
it is reading a FEA_SD file.
This works because the format of the non-header part of an SD file
is compatible with the FEA_SD format.
Thus simply replacing the header suffices to convert an SD file to FEA_SD.
The converted header is a new FEA_SD header that maintains ESPS
record keeping by containing the original SD header as a source header.
The conversion is done by the library function
.i sdtofea (3-ESPSu).
.sh 1 "PROGRAM CONVERSION"
.pp
With the enhancements to the SD support functions and
.i eopen (3-ESPSu)
covered in the previous section,
very few changes are usually necessary for a ``minimal conversion'':
making a program read single-channel, real FEA_SD files as well as
SD files and write single-channel FEA_SD files instead of SD files.
The strategy is to use the new
.i eopen
to open input sampled-data fies as FEA_SD files,
but to use the existing calls on SD ``get'' and ``put'' functions,
without change, for all reading of sampled data.
Then all statements that allocate buffers and access the data can be
left unchanged as well.
.pp
Near the beginning of the program put the lines
.ip
#include <esps/fea.h>
.br
#include <esps/feasd.h>
.lp
if they aren't there already.
You should retain the line that includes
.i esps/sd.h
as long as any SD support functions are used.
The line that includes
.i esps/feasd.h
is unnecessary if (\c
.i "struct feasd" )
is not mentioned and no FEA_SD support functions at all are used.
This may be the case if the program uses sampled-data files only for input.
.pp
Change statements such as
.ip
filename = eopen(ProgName, filename, "r", FT_SD, NONE, &hdr, &strm);
.lp
to
.ip
filename = eopen(ProgName, filename, "r", FT_FEA, FEA_SD, &hdr, &strm);
.lp
Statements that open output files probably won't have to be changed.
.pp
Change instances of
.i new_header (\c
.i FT_SD )
to
.i new_header (\c
.i FT_FEA ),
and use
.i init_feasd_hd (3-ESPSu)
instead of
.i set_sd_type (3-ESPSu).
.pp
Certain header items may have to be handled differently,
notably the sampling frequency.
For example, to get the sampling frequency of an input file,
you will have to change something like
.ip
freq = hdr\->hd.sd\->sf;
.lp
into something like
.ip
freq = get_genhd_val("record_freq", hdr, 0.0);
.pp
If the program uses
.i get_sd_recsize (3-ESPSu),
use
.i size_rec (3-ESPSu)
instead.
.pp
A program converted in this way will read complex sampled data without
complaint, but
.i get_sd_recd (3-ESPSu),
.i get_sd_recf (3-ESPSu),
or
.i get_sd_recs (3-ESPSu)
will convert the data to
.i double,
.i float,
or
.i short,
and converting complex data to a real type discards the imaginary part.
(See
.i type_convert (3-ESPSu).)
Depending on the application, it may or may not be useful to allow the
program to read complex data and discard the imaginary part.
If you want to insert a check for complex data, the functions
.i is_file_complex (3-ESPSu),
.i is_field_complex (3-ESPSu),
and
.i is_type_complex (3-ESPSu)
may be helpful.
To check for multichannel data, remember that the number of channels is
.ip
get_fea_siz("samples", hdr, (short) NULL, (long) NULL)
.pp
Much more extensive changes are necessary if a program is to be not merely
converted from SD to FEA_SD input/output but extended to deal in a useful
way with complex and multichannel data.
Then there will be no avoiding the need for a full-scale conversion
to using
.i feasd
structures to hold data and replacing SD support functions with corresponding
FEA_SD support functions.
A look at the source code of
.i fft (1-ESPS)
and
.i fftinv (1-ESPS)
may be helpful.
These programs have both been extended to deal with complex data in full
generality.
They can serve as examples of a program
that reads both real and complex FEA_SD files
and a program that writes such files.