histo.1

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" @(#)histo.1	1.4	11/24/87 ESI
.TH HISTO 1\-ESPS 11/24/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"
histo \- compute histograms of frame types and 2400 bps quantization indices,
for input to the Huffman table generator.
.SH "SYNOPSIS"
.B histo
[
.BI \-P " param_file"
][
.BI \-m " mode"
]
.I " infile.fea outfile.fea"
.SH "DESCRIPTION"
.PP
\fIHisto\fR computes histograms of FEA_ANA frame types, and of the quantization
indices in the expanded FEA_ANA file \fIinfile.fea\fR, and writes the results
to the FEA_QHIST file \fIoutfile.fea\fR. A detailed description of the FEA
file subtype FEA_QHIST is given in \fIfea_qhist\fR (5\-ESPS).
.PP
The type histogram is based on the number of pulses in a frame, where an
unvoiced frame is taken to have a single pulse. An extension code is used to
specify the voicing in a frame with one pulse \- a histogram is gathered for
this, as well.
.PP
The remaining histograms are generated from intraframe and interframe differences
in the FEA_ANA extension fields \fIraw_power_idx\fR, \fIpulse_len_idx\fR, and
\fIspec_param_idx\fR, which are created when \fIqlsf\fR (1\-ESPS) operates on
a standard FEA_ANA file. More details regarding the auxiliary FEA_ANA record
fields can be found in \fIaux_ana\fR (5\-ESPS).
.PP
By default, the histogram arrays for spectral data are stored separately
for voiced and unvoiced frames, as well as for different LSP center and
offset frequency indices. The \fB\-m\fR option can be used to combine the
spectral histograms, as described below. No distinction between voiced
and unvoiced frames is made with regard to the histograms for power or
pulse length.
.PP
On voicing transitions, the default handling of power indices is as follows:
In an unvoiced frame, the power is omitted from the histogram; in a voiced
frame, the first pulse power is omitted. By default, differences in spectral
indices are taken with respect to a combination of static average values and
adjacent indices, for transition frames of both types. A continuous difference
mode, in which voicing transitions are ignored, can be specified for either
the power or spectral data, using the \fB\-m\fR option.
.PP
If \fIinfile.fea\fR is equal to "\-", standard input is used. If \fIoutfile.fea\fR
is equal to "\-", standard output is used.  
.SH OPTIONS
.TP
.BI \-P " param_file"
Uses the ESPS parameter file \fIparam_file\fR, rather than the default,
which is \fIparams\fR.
.TP
.BI \-m " mode"
Four modes of handling the data are supported by \fIhisto\fR. These are
identified by the strings \fIcomb_frq\fR, \fIcomb_vcg\fR, \fIcont_pwr\fR,
and \fIcont_spc\fR. The former two specify combinations of the histogram
arrays; the latter two control the treatment of power and spectral indices
in transition frames.
.IP
As mentioned above, spectral histograms are individually computed for voiced
and unvoiced frames, and for different values of the LSF index, unless one
of the combination modes is invoked. The \fIcomb_frq\fR mode indicates that
the data for different frequencies are to be combined; the \fIcomb_vcg\fR
mode effects similar treatment for voiced and unvoiced data. These actions
are independent of one another, e.g., the separation among frequencies is
maintained when the voiced and unvoiced data are combined, and vice versa.
To combine the data in both modes, the \fB\-m\fR option must be invoked for
each mode.
.IP
The default handling of power and spectral indices on voicing transitions
can likewise be overridden by the \fIcont_pwr\fR and \fIcont_spc\fR modes of
the \fB\-m\fR option. The \fIcont_pwr\fR mode indicates that continuous
differences in power indices are to be taken: In a voiced frame, the change
in index from the previous (unvoiced) frame to the first pulse power is
computed; in an unvoiced frame, the index change from the last pulse power
of the previous (voiced) frame to the current frame is taken. The
\fIcont_spc\fR mode specifies that interframe differences in the spectral
indices are to be computed. The reference frame in this case is the most
recent frame of the same type.
.SH "ESPS PARAMETERS"
.PP
The parameters \fIu_lsf_avg\fR and \fIv_lsf_avg\fR are read from the parameter
file. These are arrays of type \fBint\fR, which specify the respective long-term
average values of the quantization indices for unvoiced and voiced LSFs. The 
arrays should have a maximum length of MAX_ORD, a constant defined in
\fI<esps/feaqhist.h>\fR.
.SH ESPS COMMON
.PP
ESPS Common is not used.
.SH ESPS HEADERS
.PP
The parameters \fIlsf_quant\fR, \fIpitch_quant\fR, and \fIpower_quant\fR
are read from the generic header of the input file. These are used to determine
whether or not the file has been quantized by \fIqlsf\fR (1\-ESPS). The following
generic header items are also read: \fIorder_unvcd\fR, \fIorder_vcd\fR, and
\fIuvced_frmlen\fR.
.PP
A new file header is created for the output file. The input file header is
added as a source in the output header, and the command line is added to the
comment field.
.SH "FUTURE CHANGES"
.PP
A number of modifications to \fIhisto\fR will be required to complete the
design of the 2400 bps bitstream. Details are given in [1].
.SH WARNINGS
.PP
\fIHisto\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).
.SH "SEE ALSO"
.PP
huffgen (1\-ESPS), qlsf (1\-ESPS), aux_ana (5\-ESPS), fea_qhist (5\-ESPS).
.SH "BUGS"
.PP
None known.
.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.