man.diff

speech signal process tools

.\" Copyright (c) 1998 Entropic, Inc. All rights reserved.
.\" @(#)mbsdist.1	1.3 9/23/98 ERL
.ds ]W (c) 1998 Entropic, Inc.
.if n .ds - ---
.if t .ds - \-\h'-0.2m'\-
.TH MBS_DIST 1\-ESPS 9/23/98
.SH NAME
mbs_dist \- Computes the modified bark spectral distortion
.SH SYNOPSIS
.B
mbs_dist
[
.BI \-a
] [
.BI \-{pr} " range1"
[
.BI \-{pr} " range2"
]] [
.BI \-x " debug_level"
] [
.BI \-A
] [
.BI \-P " param_file"
]
.I inFile1
.I inFile2
[
.I outFile
]
.SH DESCRIPTION
.IR mbs_dist (1\-ESPS)
computes the Modified Bark Spectral Distortion (MBSD) [1]
of one signal with respect to another,
given power-spectrum estimates for the two signals such as produced by
.IR fft (1\-ESPS).
The program accepts two input FEA_SPEC files
.RI ( FEA_SPEC (5\-ESPS)):
.I inFile1,
assumed to pertain to the reference signal, and
.I inFile2,
assumed to pertain to a processed or corrupted version
of the reference signal.
If either input filename is "\-", standard input is used.
However, the input files cannot both be standard input.
By default,
.I mbs_dist
writes an output FEA file
.RI ( FEA (5\-ESPS)),
.I outFile,
containing frame-by-frame distortion values.
Optionally, the overall distortion
may be written in ASCII to standard output (see option
.BR \-A ),
and the output file may be suppressed (see
.BR \-a ).
If standard output is not used for ASCII output,
.I outFile
may be "\-" for standard output.
The output should not be the same file as either input;
however, it is okay to run the program as a filter
by specifying "\-" for both
.I outFile
and one of the inputs.
.PP
For each input file
the program first computes "spread" critical-band spectrum estimates
similar (but not identical) to those produced by
.IR barkspec (1\-ESPS).
It then applies a perceptual transformation to compensate for the
differing sensitivity of the human ear at different frequencies,
converting intensity levels in dB to loudness levels in phons.
This is followed by another psychoacoustically based transformation,
resulting in
.I subjective
loudness in sones,
.IR Ls ( m )
for the reference signal and
.IR Ld ( m )
for the other signal, where
.I m
denotes the band number.
These transformations are similar to those performed by
.IR bs_dist (1\-ESPS)
[2] with some differences of detail [1].
.PP
The distortion for a single frame (say frame number
.IR k )
is given by
.nf
.ft B

	MBSDk = SUMm max{|Ls(m) \- Ld(m)| \- M(m), 0}

.ft
.fi
where
.I SUMm
denotes summation over the critical bands, and
.IR M ( m )
is a
.I noise masking threshold,
computed for each frame by a method detailed in [3].
.PP
A record containing a single-frame distortion
is written to the output file
for each pair of input frames (reference and processed/distorted).
Not all these values, however,
contribute to the computation of overall distortion.
Two
.I silence thresholds
are established:
one for the reference file and one for the other input file.
A single-frame distortion value is included
when the total frame energy from each input file
exceeds the corresponding silence threshold;
otherwise the value is excluded.
Each output record contains a Boolean value
that indicates whether the distortion for that frame is included.
The overall distortion is simply
the mean of all the included single-frame distortions.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-a
When this option is specified,
.I mbs_dist
sends the final average distortion value to stdout in ASCII
but does not write an output file.
.TP
.BI \-p " range"
The option \fB\-p\fP is a synonym for \fB\-r\fP,
and the allowed forms for the range are the same.
.TP
.BI \-r " first" : "last" "\fR [1:(last in file)]\fP"
.TP
.BI \-r " first" :+ "incr"
.TP
.BI \-r " first"
This option specifies the range of data to analyze.
In the first form, a pair of unsigned integers specifies
the first and last records to analyze.  If
.IR "last" " = " " first" " + " " incr",
the second form (with the plus sign)
specifies the same range as the first form.  If \fIfirst\fP
is omitted, the default value of 1 is used.  If \fIlast\fP is
omitted, the range extends to the end of the file.
The third form (omitting the colon) specifies a single record.
.IP
This option may be used at most twice.
If used once, it applies to both input files.
If used twice, it applies to
.I inFile1
the first time and
.I inFile2
the second time.
If two
.B \-r
options specify definite range sizes that are inconsistent,
the program issues an error message.
If the end of one range is unspecified,
the size of the other range determines the number of records
processed.
If the ends of both ranges are unspecified,
processing continues until one input file is exhausted.
.TP
.BI \-x " debug_level" "\fR [0]\fP"
A positive value specifies that debugging output
is to be printed on the standard error output.
Larger values result in more output.
For the default value, 0, there is no output.
.TP
.BI \-A
When this option is specified,
.I mbs_dist
sends the final average distortion value to stdout in ASCII
after writing the output file.
In this case,
.I outFile
must not be "\-".
.TP
.BI \-P " param_file \fR[params]\fP"
Use the specified parameter file 
rather than the default, which is \fIparams\fP.
.SH ESPS PARAMETERS
.PP
The parameter file is not required to be present, as there
are default parameter values that apply.  If the parameter
file does exist, the following parameters are read:
.TP
.I "start \- integer"
.IP
The first record in each input data file to process.
A value of 1 denotes the first record in the file.
The value may be either a single integer, applying to both input files,
or an array with two elements, one for each input file.
This is only read if the \fB\-p\fP and \fB\-r\fP options are not used.
.TP
.I "nan \- integer"
.IP
The total number of data records to process.
If
.I nan
is 0, processing continues
until one input file is exhausted.
This is read only if the
.B \-p
and
.B \-r
options are not used.
.SH ESPS COMMON
The ESPS common file is not used by this program.
.SH ESPS HEADERS
.PP
A new file header is created for the FEA output file.
The file headers from the input FEA data files
are added as source files in the output file header,
and the command line is added as a comment.
.PP
The output header contains definitions for a FLOAT field
.I MBSD,
to hold the distortion value for each frame,
and a CODED field
.I MBSD_included,
to hold a Boolean value (NO or YES)
indicating whether the distortion value is included
in the computation of the overall average distortion.
.PP
The program writes the usual values
into the common part of the output header.
.I mbs_dist
writes the following values into the specified generic header items:
.nf
.ft I

	start = (LONG, size 2) starting record numbers
	nan = (LONG) number of records analyzed in file
	distortion_type = (CODED) MBSD

.ft
.fi
which are added to the output FEA file header.
.PP
If the input files are both tagged feature files,
then, for each file,
the value of the header item
.I src_sf
is obtained if present, or
.I sf
if
.I src_sf
is not present.
If the value is the same in both files,
it is recorded in a generic header item
.I src_sf
added to the output header, and the output file is tagged.
.PP
If generic header items
.I record_freq
are present in both input files and have the same value,
then the value is recorded in a header item
.I record_freq
in
.I outFile,
and a generic header item
.I start_time
(type DOUBLE) is also written in the output file.
The value of
.I start_time
is computed by taking the
.I start_time
value from the header of
.I inFile1
(or zero, if such a header item doesn't exist)
and adding to it the offset time (from the beginning of
.IR inFile1 )
of the first record processed.
.SH FUTURE CHANGES
.PP
None contemplated.
.SH EXAMPLES
.PP
Suppose
.I orig.sd
is a sampled-data file containing a reference speech signal, and
.I proc.sd
contains a processed or distorted version of the speech in
.I orig.sd.
For compatibility with ref. [1],
a sampling rate of 8000 Hz is recommended,
and the inputs to
.I mbs_dist
should be prepared by using
.IR rem_dc (1\-ESPS)
followed by
.IR fft (1\-ESPS)
with the options shown here.
.nf
.IP
.ft I
rem_dc orig.sd \- \\
	| fft \-wHANNING \-o10 \-l320 \-S160 \- orig.spec
rem_dc proc.sd \- \\
	| fft \-wHANNING \-o10 \-l320 \-S160 \- proc.spec
mbs_dist \-A orig.spec proc.spec dist.fea > dist.txt
.ft P
.fi
.LP
This set of commands should result in an output file
.I dist.fea,
containing frame-by-frame distortions,
and a one-line text file
.I dist.txt,
containing the overall average distortion in ASCII.
.SH ERRORS AND DIAGNOSTICS
.PP
The program prints a synopsis of command-line usage and exits
if an unknown option is specified,
if \fB\-r\fP is used more than twice,
or if the number of file names is wrong.
It prints a warning and exits if both input files are standard input,
if the same file is specified for both input and output,
or, when \fB\-A\fP is used, if the output file is standard output.
.PP
The program prints a warning and exits
unless the two input files either
(1) have consistent values of \fIrecord_freq\fP or
(2) are tagged and have consistent values for \fIsrc_sf\fP
(or \fIsf\fP, when \fIsrc_sf\fP is not present).
In the latter case,
if the the tag values in the two selected ranges of records do not match,
the program prints a warning and continues.
.PP
The program warns and exits if a \fB\-r\fP option
specifies a starting record before the beginning of the file
or specifies an empty range of records,
or if two \fB\-r\fP options
specify ranges with different explicit lengths.
.PP
If the generic header item values of \fIcontin\fP
in the two input files don't match,
or if the values of \fIfreq_format\fP are not both SYM_EDGE,
the program warns and exits.
.PP
The program warns and exits
if a parameter read from the parameter file has the wrong data type,
.SH BUGS
.PP
None known.
.SH "SEE ALSO"
.PP
.IR barkspec (1\-ESPS),
.IR bs_dist (1\-ESPS),
.IR fft (1\-ESPS),
.br
.IR rem_dc (1\-ESPS),
.IR FEA_SPEC (5\-ESPS),
.IR FEA (5\-ESPS),
.SH REFERENCES
[1]
W. Yang, M. Benbouchta, and R. Yantorno,
``\fIPerformance of the Modified Bark Spectral Distortion
as an Objective Speech Quality Measure\fP,''
1998 ICASSP Proceedings, pp 541\-544.
.sp
[2]
S. Wang, A. Sekey, and A. Gersho,
``An Objective Measure for Predicting Subjective Quality of Speech Coders,''
\fIIEEE Journal On Selected Areas In Communications\fP,
Vol. 10, no. 5, 819\-829 (June 1992).
.sp
[3]
J. Johnston,
``Transform Coding of Audio Signals Using Perceptual Noise Criteria,''
\fIIEEE Journal On Selected Areas In Communications\fP,
Vol. 6, no. 2, 314\-323 (February 1988).
.PP
.SH AUTHOR
.PP
Manual page by Rodney Johnson, based in part on
.I bs_dist
man page.
Program based on code supplied by Wonho Yang,
adapted to ESPS by Rodney Johnson.