encode.1

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" @(#)encode.1	1.4	11/25/87 ESI
.TH ENCODE 1\-ESPS 11/25/87
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.ds ]Y "\fBESI INTERNAL\fP
.SH "NAME"
encode \- produce serial bitstream file, and compute bit rate and buffer
statistics for the 2400 bps encoder.
.SH "SYNOPSIS"
.B encode
[
.BI \-D " debug_file"
][
.BI \-P " param_file"
][
.BI \-d " "
][
.BI \-h " hist_file"
][
.BI \-x " debug_level"
]
.I " infile.fea huffile.fea outfile.fea"
.SH "DESCRIPTION"
.PP
\fIEncode\fR produces a FEA_2KB serial bitstream file \fIoutfile.fea\fR, and
computes bit rate and buffer statistics from the quantization
indices in the expanded FEA_ANA file \fIinfile.fea\fR, using the Huffman code
tables in the expanded FEA_QHIST file \fIhuffile.fea\fR. The FEA_2KB file
structure is defined in \fIfea_2kb\fR (5\-ESPS). Descriptions of the
auxiliary record fields in the expanded FEA_ANA and FEA_QHIST files are given
in \fIaux_ana\fR (5\-ESPS) and \fIaux_qhist\fR (5\-ESPS), respectively. The
\fIerror_mask\fR field of the FEA_2KB output record is set to zero by
\fIencode\fR.
.PP
The header information and data written to the FEA_2KB output file are
sufficient to allow an exact replica of \fIinfile.fea\fR to be reconstructed
by \fIdecode\fR (1\-ESPS) and \fIiqlsf\fR (1\-ESPS). This file is suitable
for input to the ESPS synthesis and listening programs [\fIsynt\fR (1\-ESPS) or
\fIdspsynt\fR (1\-ESPS), and \fIplay\fR (1\-ESPS)]. To simulate the effect of
channel errors, \fIoutfile.fea\fR can be passed through \fIcorrupt\fR (1\-ESPS)
prior to decoding and sythesizing.
.PP
A detailed breakdown of the bandwidth allocated to coding various parameters
is written to a history file. The default name of this file is \fIencode.his\fR,
but this can be overridden by the \fB\-h\fR option. In addition, a frame-by-frame
dump of coding statistics to the history file can be initiated via the \fB\-d\fR
option.
.PP
A debug capability allows details of the coding process to be monitored,
starting at the speech frame level, and proceeding down to bit packing operations
at the codestream level. This feature is controlled by the \fB\-x\fR option.
Debug output is normally written to \fIstderr\fR, but can be placed instead
in a file specified by the \fB\-D\fR option.
.PP
If \fIinfile.fea\fR is equal to "\-", standard input is used. Standard input
\fIcannot\fR be used for \fIhuffile.fea\fR. If \fIoutfile.fea\fR is equal to
"\-", standard output is used.
.SH OPTIONS
.TP
.BI \-D " debug_file"
Causes any debug output (see the \fB\-x\fR option) to be written to the
file \fIdebug_file\fR, rather than to the default file, which is \fIstderr\fR.
.TP
.BI \-P " param_file"
Uses the ESPS parameter file \fIparam_file\fR, rather than the default,
which is \fIparams\fR.
.TP
.BI \-d " "
Results in frame-by-frame details of the coding rate and buffer status
being output to the history file prior to the statistical summary. These
detailed items include: frame number, number of samples, number of bits
used to code spectral parameters, power, and pulse/frame length, total
number of bits, number of bits in the buffer, number of samples in the
buffer, and instantaneous bit rate (bits/sec). In transition frames, the
frame number is tagged with a '*', followed by a 'U' or 'V', denoting an
unvoiced or voiced frame. The computation of number of bits in the buffer
is identical to that in \fIrosframe2\fR (1\-ESPS).
.TP
.BI \-h " hist_file"
Causes the statistical summary and frame-by-frame details to be placed
in the file \fIhist_file\fR, instead of in the default file, which is
\fIencode.his\fR.
.TP
.BI \-x " debug_level"
Causes details of the coding process to be written to \fIstderr\fR, or
to the file specified by the \fB\-D\fR option. Values of \fIdebug_level\fR
in the range from 1 to 4 are currently supported, with the higher values
corresponding to greater levels of detail.
.SH "ESPS PARAMETERS"
.PP
The parameters \fIchan_rate\fR, \fIsync_intv\fR, and \fIsync_len\fR
are read from the parameter file \- all are of type
\fBint\fR. \fIChan_rate\fR specifies the transmission rate in bits/sec;
\fIsync_intv\fR represents interval, in numbers of frames, at which the
sync code is transmitted \- a value of zero inhibits sync transmission;
\fIsync_len\fR is the length, in bits, of the sync pattern.
.SH ESPS COMMON
.PP
ESPS Common is not used.
.SH ESPS HEADERS
.PP
The values of \fIcomb_vcg\fR, \fIcomb_frq\fR, \fIcont_pwr\fR, \fIcont_spc\fR,
\fIlsf_quant\fR, \fImax_steps\fR, \fIpitch_quant\fR, \fIpower_quant\fR,
\fIunvoiced_steps\fR, \fIvoiced_steps\fR, \fIu_avg\fR, and \fIv_avg\fR
are read from the generic header of \fIhuffile.fea\fR. For a description
of these quantities, see \fIfea_qhist\fR (5\-ESPS).
.PP
The values of \fIlsf_quant\fR, \fIpitch_quant\fR, and \fIpower_quant\fR
are read from the generic header of \fIinfile.fea\fR. These are used to
determine whether or not the file has been quantized by \fIqlsf\fR (1\-ESPS).
In addition, the values of \fIunvoiced_steps\fR and \fIvoiced_steps\fR are
used in conjunction with the previous three items to verify that the
quantization of \fIinfile.fea\fR is consistent with \fIhuffile.fea\fR.
If the \fI1.5_dB\fR power quantization has been used, the values of
\fImax_steps\fR are also checked for consistency between these two files.
Finally, the values of \fIorder_unvcd\fR, \fIorder_vcd\fR, \fIsrc_sf\fR,
and \fIuvced_frmlen\fR are read from the generic header of \fIinfile.fea\fR.
.PP
A new file header is created for the output file. The header of \fIinfile.fea\fR
is added as a source in the output header, and the command line is added to the
comment field. The \fIerr_rate\fR item in the output generic header is set to
"ZERO" by \fIencode\fR.
.SH "EXAMPLES"
.PP
The following example gives a model shell script which shows all the steps
required to simulate the 2400 bps coding of an analysis file. Assume we start
with a file \fIrc.ana\fR, containing reflection coefficients, which was produced
by \fIdspana\fR (1\-ESPS).
.nf

ana2fea rc.ana rc.fana
spectrans \-p LSF rc.fana lsf.fana
qlsf [\-opt ...] lsf.fana qlsf.xfana
histo [\-opt ...] qlsf.xfana hist.fqhist
huffgen hist.fqhist huff.xfqhist
encode qlsf.xfana huff.xfqhist bits.f2kb

.fi
.PP
To play back the quantized speech, only the output from \fIqlsf\fR is needed.
The steps are as follows:
.nf

spectrans \-p RC qlsf.xfana qrc.xfana
fea2ana qrc.xfana qrc.ana
dspsynt qrc.ana qrc.syn
play [\-opt ... ] qrc.syn

.fi
.PP
An equivalent, lengthier procedure for listening can be based on a quantized
file which has been reconstructed from a FEA_2KB file [see \fIcorrupt\fR (1\-ESPS),
\fIdecode\fR (1\-ESPS), and \fIiqlsf\fR (1\-ESPS)]. This would be the approach
taken in a study of error sensitivity, for example.
.SH "FUTURE CHANGES"
.PP
A number of modifications to \fIencode\fR will be required to complete the
design of the 2400 bps bitstream. Details are given in [1].
.SH WARNINGS
.PP
\fIEncode\fR issues a warning and exits if \fIinfile.fea\fR is not a
FEA_ANA file, or if it lacks the generic header items which are written by
\fIqlsf\fR (1\-ESPS), or if the quantization methods used to generate
\fIinfile.fea\fR are inconsistent with \fIhuffile.fea\fR. The same actions
are taken if \fIhuffile.fea\fR is not a FEA_QHIST file.
.SH "SEE ALSO"
.PP
corrupt (1\-ESPS), decode (1\-ESPS), huffgen (1\-ESPS), iqlsf (1\-ESPS), qlsf (1\-ESPS),
aux_ana (5\-ESPS), aux_qhist (5\-ESPS), fea_2kb (5\-ESPS), fea_qhist (5\-ESPS).
.SH "BUGS"
.PP
\fIEncode\fR does not check for meaningful (non-zero) code lengths when it
reads the Huffman data. It will, therefore, accept a standard FEA_QHIST file
for \fIhuffile.fea\fR, and produce misleading results.
.SH REFERENCES
.PP
[1] ETM-S-87-08:jpe, \fIRemaining Tasks in the 2400 bps Coding Development\fR,
Version 1.0, 07/13/87.
.SH "AUTHOR"
.PP
Program and manual page by Jim Elliott.