man.diff

来自「speech signal process tools」· DIFF 代码 · 共 223 行

.\" Copyright (c) 1987,1988,1990 Entropic Speech, Inc.; All rights reserved
.\" @(#)pwr.1	1.9 03 Apr 1997 ESI
.TH PWR 1\-ESPS 03 Apr 1997
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH "NAME"
pwr \- computes power of sampled data in FEA records 
.SH "SYNOPSIS"
.B pwr
[
.B \-l
] [
.BI \-P " params"
] [
.BI \-f " sd_field"
[
.BI \-f " power_field"
]] [
.BI \-r " range"
] [
.BI \-x " debug_level"
]
.I "input output"
.SH "DESCRIPTION"
.PP
.I Pwr
accepts a FEA file \fIinput\fP containing a vector sampled-data field
in each record (there may be other fields as well).  It produces a FEA
file \fIoutput\fP with records containing the raw power (or log raw
power) of the sampled-data field from that record.  Each field of
sampled data may be thought of as a separate frame of data, such as
might be produced by \fIframe\fP (1\-\s-1ESPS\s+1).  The default name
for the sampled data field in \fIinput\fP is \fIsd\fP, and the default
name for the power field in \fIoutput\fP is \fIraw_power\fP
(\fIlog_power\fP if \fB-l\fP option used). Both defaults can be
changed by means of the \fB\-f\fP option.  If \fIinput\fP is "\-",
standard input is used for the input file.  If \fIoutput\fP is "\-",
standard input is used for the output file.
.PP
The power is computed by summing the squares of the sampled data values and
dividing by the number of points in the frame.  If \fIinput\fP is not a
segment-labelled FEA file (see FEA (5\-\s-1ESPS\s+1)), the frame is
considered to comprise all of the points in the sampled data field, so the
frame length is a constant set to the size of the sampled data field (which
can be determined from the file header).  If \fIinput\fP is
segment-labelled, the size of the sampled data field is really a maximum
size, and the frame size for a particular record is given by the
\fIsegment_length\fP field (this field is always present in segment-labelled
files).  Thus, for segment-labelled files, the frame from any input record
is the first \fIsegment_length\fP points of the sampled data field.
.PP
If the \fB-l\fP is used, the (base 10) log of the raw power is stored
in the output file instead of the raw power itself.  To avoid
computational overflow, logs are not taken for power values less than 
10/DBL_MAX; in these cases the log power stored is log10(10/DBL_MAX),
which is approximately -307.55.  
.SH OPTIONS
.PP
The following options are supported:
.TP
.B \-l
Specifies that the log (base 10) of the raw power be computed instead
of the raw power.  If this option is used, the default name for the 
output power field is \fIlog_power\fP; this name can be changed via
the \fB-f\fP option.  
.TP
.BI \-P " param" " \fR[params]\fP"
Specifies the name of the parameter file.
.TP
.BI \-r " start" : "last" "\fR [1:(last in file)]"
.TP
.BI \-r " start" :+ "nan"
In the first form, a pair of unsigned integers specifies the range
of records to be processed.
Either
.I start
or
.I last
may be omitted; then the default value is used.
If
.IR last " = " start " + " nan,
the second form (with the plus sign) specifies the same range as the first.
The \fB\-r\fP overrides the values of \fIstart\fP and \fInan\fP from 
the parameter file.  
.TP
.BI \-f " field_name" 
If this option is used once, it specifies the name of the sampled data
field in \fIinput\fP.  If it is used twice, the second time it
specifies the name of the power field in \fIoutput\fP.  The default
names for these fields are "sd" and "raw_power", respectively. 
If the \fB-l\fP option is used, the default name for the power field
is "log_power".  
.SH "ESPS PARAMETERS"
.PP
The parameter file does not have to be present, since all the
parameters have default values.  The following parameters are read, if
present, from the parameter file:
.IP
.I "sd_field_name \- string"
.IP
This is the name of the sampled data field in \fIinput\fP.
The default is "sd".  A paramter file value (if present) is overidden
by the first use of the \fB\-f\fP option.  
.IP
.I "power_field_name \- string"
.IP
This is the name of the raw power field in \fIoutput\fP.  The default is
"raw_power".  A parameter file value (if present) is overidden by the second
use of the \fB\-f\fP option.
.IP
.I "power_function \- string"
.IP
This is the function to apply to value of the raw power before
storing in the output file.  The default is "none", which means that
the output file is to contain the raw power value.  The only other
recognized value is "log", which means that the output file is to 
contain the log of the raw power.  
.IP
.I "start \- integer"
.IP
This is the first record of \fIinput\fP to process.
The default is 1.
It is not read if the \fB\-r\fP option is used.  
.sp
.I "nan \- integer"
.IP
This is the number of records to process.  It is not read if the \fB\-r\fP
option is used.
A value of zero means all subsequent records in the file;
this is the default.
.PP
Remember that command line option values override 
parameter file values.
.SH "ESPS COMMON"
.PP
ESPS Common processing may be disabled by setting the environment
variable USE_ESPS_COMMON to "off".  The default ESPS Common 
file is .espscom in the user's home directory.  This may be overidden by
setting the environment variable ESPSCOM to the desired path.  User
feedback of Common processing is determined by the environment
variable ESPS_VERBOSE, with 0 causing no feedback and increasing
levels causing increasingly detailed feedback.  If ESPS_VERBOSE is not
defined, a default value of 3 is assumed.
.PP
ESPS Common is not processed by \fIpwr\fP if \fIinput\fP is standard
input.  Otherwise, provided that the Common file is newer than the
parameter file, and provided that the \fIfilename\fP entry in Common
matches \fIinput\fP, the Common values for \fIstart\fP and \fInan\fP
override those that may be present in the parameter file.
.PP
The following items are written into the ESPS Common file 
provided that \fIoutput\fP is not <stdout>.  
.IP
.I "start \- integer"
.IP
The starting record from the input file.
.sp
.I "nan \- integer"
.IP
The number of records in the selected range.
.sp
.I "prog \- string"
.IP
This is the name of the program 
.RI ( pwr
in this case).
.sp
.I "filename \- string"
.IP
The name of the input file \fIinput\fP.
.SH ESPS HEADERS
.PP
The \fIoutput\fP header is a new FEA file header.  If the generic
header item \fIsrc_sf\fP exists in the input file, it is copied to the
output file.  The items \fIstart\fP and \fInan\fP are written to
contain the starting record number and number of records processed.
.PP
The size of the input sampled data field is written to the generic 
\fIfrmlen\fP.  
.PP
The generic header item \fIstart_time\fP is written in the output
file.  The value written is computed by taking the \fIstart_time\fP
value from the header of the input file (or zero, if such a header
item doesn't exist), adding to it the relative time from the first
record in the file to the first record processed, and adding a
displacement corresponding to half of \fIfrmlen\fP.  The computation
of \fIstart_time\fP depends on the value of the generic header item
\fIsrc_sf\fP in the input file (which is assumed to be the sampling
rate of the actual data in each field).  If this item is not present,
\fIstart_time\fP is just copied from the input file to the output
file.
.PP
As usual, the command line is added as a
comment and the header of \fIinput\fP is added as a source file to
\fIoutput\fP.  Another comment gives the name of the field added by
\fIpwr\fP.
.SH "FUTURE CHANGES"
.PP
Control over the type of the output power field.  
.SH "SEE ALSO"
.PP
\fIframe\fP (1\-\s-1ESPS\s+1), FEA (5\-\s-1ESPS\s+1), \fIfea_stats\fP
(1\-\s-1ESPS\s+1), 
.br
\fIstats\fP (1\-\s-1ESPS\s+1) 
.SH "WARNINGS AND DIAGNOSTICS"
.PP
.I pwr
will exit with an error message if any of the 
following are true: 
.I input
does not exist or is not an ESPS FEA file; 
the sampled-data field does not exist in
.I input;
the power field already exists in
.I input.
.SH "BUGS"
.PP
None known.  
.SH "AUTHOR"
.PP
Manual page by John Shore.  Program by Rodney Johnson.