esig2fea.1

speech signal process tools

.\" copyright (c) 1995 Entropic Research Laboratory, Inc. All rights reserved.
.\" @(#)esig2fea.1	1.5 10/4/97 ERL
.ds ]W (c) 1993 Entropic Research Laboratory, Inc.
.if t .ds - \-\h'-0.2m'\-
.if n .ds - ---
.TH ESIG2FEA 1\-ESPS 10/4/97
.SH NAME
.nf
esig2fea \- write Esignal file data to ESPS FEA file
.fi
.SH SYNOPSIS
.B esig2fea
[
.BI \-f " field"
] .\ .\ . [
.BI \-r " range"
] [
.BI \-x " debug_level"
] [
.BI \-F
] [
.BI \-T " subtype"
]
.I input.esig output.fea
.SH DESCRIPTION
.PP
.I esig2fea
accepts an input file
.I input.esig
in Esignal format (see Ref. [1]) and writes an output ESPS FEA file
.I output.fea
(see
.IR ESPS (5\-ESPS),
.IR FEA (5\-ESPS))
containing the same information
(or a subest thereof).
If
.I input.esig
is "\-", standard input is used for the input file.
If
.I output.fea
is "\-", standard output is used for the output file.
The input and output should not be the same file;
however, you can run the program as a filter
by specifying "\-" for both input and output.
.PP
Normally the program reads all input records and copies to the output
the contents of all fields in each record that meet certain requirements;
one output record is written for each input record.
However, with the
.B \-r
option, one can restrict processing to a subrange of the input records,
and with the
.B \-f
option, one can restrict processing to a specified subset of the input fields.
.PP
The requirements on fields
to be copied from input records to output records are the following.
.TP
(1)
Each such field must be a REQUIRED field.  OPTIONAL fields are ignored.
.TP
(2)
Each such field must be a top-level field\*-not a subfield of some
other field.  This means that its name does not contain a dot (".").
Subfields are ignored.
.TP
(3)
Each such field must have a data type that corresponds to an ESPS data
type according to the following table.
.nf
.RS
.ta 0.1i 1.3i 2.6i 4.3i

.if n \l'2.2i\-'\h'0.3i'\l'3.0i\-'
.if t \v'-0.2'\l'2.2i'\h'0.3i'\l'3.0i'\v'0.2'
	Esignal	ESPS	Esignal     	ESPS
.if n \l'2.2i\-'\h'0.3i'\l'3.0i\-'
.if t \v'-0.2'\l'2.2i'\h'0.3i'\l'3.0i'\v'0.2'
	DOUBLE	DOUBLE	DOUBLE_COMPLEX	DOUBLE_CPLX
	FLOAT	FLOAT	FLOAT_COMPLEX	FLOAT_CPLX
	LONG	LONG	LONG_COMPLEX	LONG_CPLX
	SHORT	SHORT	SHORT_COMPLEX	SHORT_CPLX
	SCHAR	BYTE	SCHAR_COMPLEX	BYTE_CPLX
	UCHAR	CHAR
	CHAR	CHAR
.if n \l'2.2i\-'\h'0.3i'\l'3.0i\-'
.if t \v'-0.2'\l'2.2i'\h'0.3i'\l'3.0i'\v'0.2'

.DT
.RE
.fi
Fields of types ARRAY, USHORT, ULONG, BOOL, and WCHAR
are ignored.
.LP
Fields that violate these requirements are allowed in input files;
however,
.I esig2fea
does not provide a mapping of such fields to FEA fields.
Each input field that satisfies the requirements (and is retained)
normally becomes an output field with the same name.
.PP
An exception is a REQUIRED field with data type LONG
and rank 0 (a scalar).
If such a field is present (and is retained), the output file is
tagged (see
.IR ESPS (5\-ESPS)),
and the "Tag" value in each Esignal record
furnishes the value for the tag in the corresponding FEA record,
rather than for an ordinary FEA field named "Tag".
.PP
Each top-level GLOBAL field with one of the Esignal types shown
in the following table
.nf
.RS
.ta 0.1i 1.3i 2.6i 3.8i

.if n \l'2.2i\-'\h'0.3i'\l'2.2i\-'
.if t \v'-0.2'\l'2.2i'\h'0.3i'\l'2.2i'\v'0.2'
	Esignal	ESPS	Esignal	ESPS
.if n \l'2.2i\-'\h'0.3i'\l'2.2i\-'
.if t \v'-0.2'\l'2.2i'\h'0.3i'\l'2.2i'\v'0.2'
	DOUBLE	DOUBLE	SCHAR	CHAR
	FLOAT	FLOAT	UCHAR	CHAR
	LONG	LONG	CHAR	CHAR
	SHORT	SHORT
.if n \l'2.2i\-'\h'0.3i'\l'2.2i\-'
.if t \v'-0.2'\l'2.2i'\h'0.3i'\l'2.2i'\v'0.2'

.DT
.RE
.fi
becomes an ESPS generic header item with the same name,
the indicated corresponding ESPS type,
and the same number of data elements.
ESPS generic header items
do not contain rank and dimension information, however.
Thus for example a 15-element vector and a 3\(mu5 matrix in
Esignal GLOBAL fields both become simply 15-element generic header items.
.PP
If an Esignal GLOBAL or REQUIRED field with Esignal data type SHORT
has a subfield named "enumStrings",
the corresponding FEA file field or header item
has an ESPS CODED type, (see
.IR FEA (5\-ESPS))
rather than the normal corresponding ESPS type SHORT
indicated in the table.
The subfield must be a character matrix consisting of strings,
one per row, padded on the right with null characters ('\\0') to a
common length.
The strings become the list of string values associated with
the CODED type.
.PP
The output FEA file header has a single embedded source file header
(see
.IR ESPS (5\-ESPS),
.IR add_source_file (3\-ESPS))
which, like the output file header itself, is derived from the
field list in the input Esignal header.
The source header is thus usually similer to the output file header,
but there are some differences.
The source header records all the fields of the input file
that satisfy (1), (2), and (3) above, even if the
.B \-f
option is used to specify that only some of these fields
are retained in the output.
Within the source header,
there is a recursively embedded source header
for each VIRTUAL field (if any) with a name of the form
"source_0", "source_1", "source_2", etc.
The embedded source header is obtained by converting the subfield list
of the VIRTUAL field from an Esignal field list to an ESPS FEA file header.
If the VIRTUAL field has a data array,
it must be a one-dimensional CHAR array giving the source-file name
that goes with the corresponding header.
More deeply nested source-file headers are derived from VIRTUAL
subfields with names such as "source_0.source_2"
or "source_0.source_2.source_1".
.PP
If the input file has a scalar GLOBAL field
.I FeaSubtype
of type SHORT,
.I esig2fea
assigns its value to the FEA file subtype code
.I fea_type
(see
.IR FEA (5\-ESPS)).
This behavior can be overridden by the
.B \-T
option.
.PP
If the input file contains the waves GLOBAL fields
.I recordFreq
and
.I startTime,
the program creates corresponding waves generic header items
.I record_freq
and
.I start_time
in the output file.
These are the header items that
.IR xwaves (1\-ESPS)
uses for time alignment of displays of files with uniformly spaced records.
The value of
.I record_freq
is just that of
.I recordFreq.
The value of
.I start_time
is obtained from that of
.I startTime
by adding an offset that is the time difference
between the first record of the input file
and the first record that is copied to the output.
The offset is 0 unless the
.B \-r
option is used to specify a starting point other than the first input record.
(See the ``Options'' section.)
In that case, the offset is the result of dividing the starting record number
by the value of
.I recordFreq.
Like other input GLOBAL fields,
.I recordFreq
and
.I startTime,
if present, are represented in the output
by generic header items with the same names.
In this case, the header item
.I startTime
is simply a copy of the input GLOBAL field
.I startTime;
it is the header item
.I start_time
that contains the correct starting time of the output file.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-f " field"
specifies the name of a input field
to be retained in the output file records.
The field should be a top-level field (the name should not contain "."),
it should be a REQUIRED field (not OPTIONAL, for example),
and it should have a supported data type (not ARRAY, for example);
otherwise it is ignored.
The option may be repeated to specify several input fields to be retained.
If the option is not specified,
all top-level REQUIRED input fields of supported types are retained.
.TP
.BI \-r " start" : "last \fR[0:(last in file)]\fP"
.TP
.BI \-r " start" :+ "incr"
.TP
.BI \-r " start"
In the first form, a pair of unsigned integers specifies the range
of input records to be processed.
Input record numbers follow Esignal file conventions:
the first record in the file is number 0.
Either
.I start
or
.I last
may be omitted; then the default value is used.
If
.IR last " = " start " + " incr,
the second form (with the plus sign) specifies the same range as the first.
The third form (omitting the colon) specifies a single record.
.TP
.BI \-x " debug_level \fR[0]\fP"
If 
.I debug_level
is positive,
.I fea2esig
writes debugging messages on the standard error output.
Larger values result in more output.
The default is 0, for no output.
.TP
.BI \-F
specifies output in
.I field order.
If the option is not specified, the output is in
.I type order,
the default.
.TP
.BI \-T " subtype"
specifies that the subtype code
.I fea_type
of the output FEA file (see
.IR FEA (5\-ESPS))
is filled in to indicate the given subtype.
Allowed values include FEA_ANA, FEA_SD, FEA_SPEC, FEA_STAT,
and FEA_VQ.
The complete list of subtype names,
with the corresponding numeric codes,
is in the ESPS header file
.I esps/fea.h.
In addition,
.I subtype
may be NONE,
to specify that the output is not of any special FEA subtype.
If
.B \-T
is not specified,
.I esig2fea
looks in the input file for a GLOBAL field named "FeaSubtype"
and having data type SHORT.
It sets the subtype code according to the value of
.I FeaSubtype
if the field is present;
otherwise it sets the code to 0, for NONE.
The
.B \-T
option overrides any values specified by an input field
.I FeaSubtype.
.IP
Such a field
.I FeaSubtype
is created when the program
.IR fea2esig (1\-ESPS)
converts a file of a special FEA subtype to
.I Esignal
format.
This is done only so that
.I esig2fea
can restore the subtype when converting the file back to a FEA file;
the notion of a FEA subtype has no exact parallel in the Esignal
framework.
.IP
Use of
.B \-T
doesn't ensure that the output file has the correct format.
You should specify a subtype with this option only when you know
that a file with the correct fields and generic header items
will be produced.
See the section-5 manual pages for the individual FEA file types.
.SH ESPS PARAMETERS
.PP
The ESPS parameter file is not read.
.SH ESPS COMMON
.PP
The ESPS common file is not accessed.
.SH ESPS HEADERS
.PP
As mentioned under ``Description'' above,
generic header items corresponding to top-level GLOBAL fields
are added to the output header,
and the input field list, converted to a FEA header,
is added as an embedded source header.
As is usual in ESPS files, the command line that invoked the program
is added as a comment.
For the setting of the FEA subtype code
.I fea_type,
see
.B \-T
under ``Options''.
Generic header items
.I record_freq
and
.I start_time
are added to the output header if the input contains GLOBAL fields
.I recordFreq
and
.I startTime;
see ``Description'' above for details.
.SH FUTURE CHANGES
.PP
Fix some of the problems listed under ``Bugs''.
.SH EXAMPLES
.PP
.SH ERRORS AND DIAGNOSTICS
.PP
The program exits with a "Usage" message
if an unrecognized option is used on the command line.
or if too many or too few file names are specified.
It may exit with one of the following error messages
if the described conditions occur:
.nf
.RS
can't start before beginning of file
empty range of records specified
can't allocate memory for input record
failure converting input header to field list
output order neither TYPE_ORDER nor FIELD_ORDER
can't set field ordering of output
write header failed
.RE
.fi
.SH BUGS
.PP
Confusion is possible if field names in the input file
conflict with field names that
.I esig2fea
uses for special purposes\*-for example,
if there is a REQUIRED input field named "commandLine" or "source_0".
The program ignores subfields named "encoding"
(which flag their parent fields as containing
.if n .IR mu -law
.if t .IR \(*m -law
or
.IR A -law
compressed data.
.SH REFERENCES
.PP
[1] R. W. Johnson,
``The Esignal File Format'',
Entropic Research Laboratory, Inc., 1995
.SH "SEE ALSO"
.IR add_source_file (3\-ESPS),
.IR fea2esig (1\-ESPS),
.IR xwaves (1\-ESPS),
.br
.IR Esignal (3\-Esignal),
.IR ESPS (5\-ESPS),
.IR FEA (5\-ESPS).
.PP
.SH AUTHOR
.PP
Rod Johnson