formant.1

speech signal process tools

This option was made available primarily so that \fIformant\fP could be
used more easily with \fIadd_espsf\fP in \fIxwaves\fP.
.TP
.BI \-O " output_path" " \fR[<null>]\fP"
A directory pathname where all output files created by \fIformant\fP will be
placed.  If \fB\-O\fP is not specified, output files are placed in the
same directory as the input file.
.TP
.B \-F 
Only compute F0 and voicing information.  Pole frequency (".pole") and
formant frequency (".fb") files are not computed or written.
.TP
.BI \-B " max_buff_bytes" " \fR[2000000]\fP"
Maximum buffer size (in bytes) for holding input data signal.  Signals
larger than this will be truncated.  At 16,000 samples/second, 2
megabytes corresponds to 62.5 seconds of input data (represented as
SHORTS).  Increasing \fImax_buff_bytes\fP will allow longer input data
signals to be processed by \fIformant\fP.  The maximum buffer size
that your system can support is a function of available memory, swap
space size, and current system usage.
.TP
.BI \-R " maxrms_duration" " \fR[0]\fP"
Window (in seconds) of past data over which the maximum rms energy is
computed.  The maximum rms energy is needed when computing the
probability of voicing for each cross_correlation frame
(cross-correlation frames are fixed at .01 seconds each).  The value
used is the maximum rms energy value from all of the frames in the
preceeding maxrms_duration seconds of data.  If maxrms_duration is 0,
the maximum rms energy used is a constant, independent of frame
position; in this case, the value is the maximum of the rms energy of
all frames from the start of the file to the end.  (The case with
maxrms_duration == 0 corresponds to the previous behavior of
\fIformant\fP, before \fB\-R\fP was added.)  The \fB\-R\fP option cannot be
used at the same time as the \fB\-M\fP option.  
.TP
.BI \-M " maxrms_value" " \fR[0]\fP"
Fixed value to use as the maximum rms energy value need when computing
the probability of voicing for each cross_correlation frame.  The
\fB\-M\fP option cannot be used at the same time as the \fB\-R\fP
option.  If neither \fB\-R\fP nor \fB\-M\fP is used, the default is
\fB\-R\fP0.
.SH "EXAMPLES"
.PP
Here is a UNIX C-shell script that shows several featurs of
\fIformant\fP and its use with \fIxwaves\fP.  This is designed as a
tutorial example more than a serious proposal for getting work done!
We suggest that if large amounts of data are to be processed,
\fIformant\fP should be run in a "batch mode" and the results viewed
with \fIxwaves\fP the next day.

.nf

#!/bin/csh
# This script, which we shall call "formant_examp",
# works around the idiosyncratic behavior of formant and provides an
# xwaves plot of F0 and a spectrogram with estimated formants overlaid.
# It is designed to be called via an "add_op" menu function from
# xwaves.  When called this way, xwaves provides the script with
# arguments specifying the interval to be analyzed, the input file and
# an output file name.  This script uses the output file name for the
# F0 estimates.  Assuming the script is made executable and placed
# somewhere on your executable path, and that xwaves is running,
# it can be added as a waveform menu item with a shell command like
#
# send_xwaves add_op name FTRACK menu wave op formant_examp _range_samp \
#      _file _out.g.F0 _name _l_marker_time _r_marker_time

# Create a scratch area.
mkdir /tmp/fmt$$

# Determine the name of the xwaves display ensemble.
set ob = $4

# Start a spectrogram computation.
send_xwaves $ob spectrogram file $2 start $5 end $6

# Now run the formant/F0 tracker.  Put all output files in /tmp.
formant  -O /tmp/fmt$$ $1 $2

# Overlay the formant tracks on the just-created spectrogram.
send_xwaves $ob overlay file /tmp/fmt$$/*.fb.sig

# Put the F0 (pitch) estimate file where xwaves expects to find it.
mv /tmp/fmt$$/*.f0 $3

# Remove all scratch files
/usr/bin/rm -f /tmp/ob$$ /tmp/fmt$$/* ; rmdir /tmp/fmt$$

.fi

.SH "ESPS PARAMETERS"
.PP
ESPS parameter files are not processed.
.SH ESPS COMMON
.PP
ESPS Common is not processed or written.
.SH ESPS HEADERS
.PP
Standard ESPS record keeping is provided via embedded source file
headers.
.PP
All output files have the generic \fIstart_time\fP, which gives 
the starting time (in seconds) of the first record.  All FEA files 
have the generic \fIrecord_freq\fP, which gives the number of records
per second of original data.  
.PP
Analysis parameters that can be set by command line options are
recorded as generics in the ".f0" file.  In particular, the following
generics are included: \fIpreemphasis, window_duration,
frame_step, lpc_order, lpc_type\fP, and \fIwindow_type\fP.
.SH "FILE FORMATS"
.PP
The ".fb" file is an ESPS FEA file with two fields per record, with
field size \fInum_formants\fP (\fB\-n\fP option).  The field \fIfm\fP
stores the formant frequencies and the field \fIbw\fP stores the
corresponding formant bandwidths.  Both fields have type DOUBLE.
.PP
The ".f0" file is an ESPS FEA file with the following five fields (all
of type DOUBLE):  
.nf

	\fIF0\fP - estimate of fundamental frequency

	\fIprob_voice\fP \- probability of voicing

	\fIrms\fP \- rms in rectangular window

	\fIac_peak\fP \- peak value of cross correlation at the estimated F0

	\fIk1\fP \- ratio of the first two cross-correlation values

.fi
.PP
The ".pole" file is an ASCII file.  After the ASCII header, the
variable-length records each contain the following:
.IP
(1) The total number of values in the record.  This number is (2*N)+2,
where N is the number of pole frequencies and bandwidths stored in
items (4) and (5).
.IP
(2) The rms in the LPC analysis window (typically preemphasized).  
.IP
(3) Zero (yeah, not used). 
.IP
(4) N complex pole frequencies in Hz.
.IP
(5) N complex pole bandwidths in Hz.  
.PP
The data in the ".fb" file is also output in a SIGnal format file
".fb.sig".  This is provided because \fIxwaves\fP has formant display
and interaction facilities that are specially tuned for these files.
Although the equivalent ESPS FEA file can also be viewed and modified
through \fIxwaves\fP, the ".fb.sig" is often preferable, especially
when formants are overlaid on spectrograms.  The need for the
(anachronistic) SIGnal format files will be eliminated in the Spring
1993 software update.  The FEA files are more convenient for use with
standard ESPS tools (e.g., \fIepsps\fP, \fIselect\fP, \fIfea_stats\fP,
\fIfea_edit\fP, \fIgenplot\fP, \fIclassify\fP, etc.).
.SH "FUTURE CHANGES"
.PP
A complete rewrite is planned to provide much faster computation and
the potential for pipelined operation.  (This has already been done
for the F0 estimator\*-see \fIget_f0\fR(1-ESPS).)
.PP
Output file specifications will be normalized.  Automatic output
filename generation will be eliminated.
.PP
The voicing decision will be integrated with the F0 estimation to
improve accuracy and robustness.  This is the case for \fIget_f0\fR.

.SH "SEE ALSO"
.PP
.nf
\fIformsy\fP(1\-\s-1ESPS\s+1), \fIFEA\fP(5\-\s-1ESPS\s+1), \fIFEA_SD\fP(5\-\s-1ESPS\s+1), 
\fIselect\fP(1\-\s-1ESPS\s+1), \fIfea_stats\fP(1\-\s-1ESPS\s+1), \fIpsps\fP(1\-\s-1ESPS\s+1), 
\fIrefcof\fP(1\-\s-1ESPS\s+1), \fItranspec\fP(1\-\s-1ESPS\s+1), \fIclassify\fP(1\-\s-1ESPS\s+1),
\fIget_feasd_recs\fP(1\-\s-1ESPS\s+1)
.nf
.SH "BUGS"
.PP
Sampled data are read in as SHORTs; hence, accuracy may be lost
when processing FLOAT or DOUBLE data.  
.PP
The default LPC order and number of formants to track (\fB\-o\fP and \fB\-n\fP
options) are only appropriate for 10kHz input data.  Unless specified,
these should scale automatically with input sample frequency.  In a
future program version, they will.
.PP
The interpretation of the start and end points (\fB\-r\fP option)
may be off by 1 when the input is a NIST Sphere file.
.SH "AUTHOR"
.PP
Code by David Talkin, AT&T Bell Laboratories; ESPS and other
enhancements by John Shore.  Manual page by John Shore, David
Burton and David Talkin.
.SH REFERENCES
.PP
The F0 tracking algorithm implemented in \fIformant\fP is related to
the one described in:
.PP
B.G. Secrest and G.R. Doddington, "An integrated pitch tracking
algorithm for speech systems", \fIProceedings ICASSP83\fP, pp.
1352-1355.