wplay.1

speech signal process tools

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1991 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)wplay.1	1.11 8/14/91 ESI/ERL
.ds ]W (c) 1991 Entropic Research Laboratory, Inc.
.TH WPLAY 1\-ESPS 8/14/91
.SH NAME
wplay - send portions of an ESPS file to the DSP32 digital to analog converter.
.br
play - send portions of an ESPS file to the digital to analog converter.
.SH SYNOPSIS
.B wplay
[
.BI \-x " debug-level"
] [
.BI \-{psf} " range"
] [
.BI \-g " gain"
] [
.BI \-w " width"
] [
.BI \-r " nrepeat"
] [
.BI \-i 
] [
.BI \-a
] [
.BI \-h " hist-file"
] [
.BI \-b " shift-value"
] [
.BI \-q 
]
.I file
[
.I more-files
]
.SH DESCRIPTION
.PP
.I Wplay
sends a portion of one or more ESPS or SIGnal sampled data files to a
\s-1DSP32\s+1 digital-to-analog converter.  A subrange of data within
the files may be chosen; this subrange may be specified in seconds,
frames, or points. Furthermore, a repeat count, a scaling factor
(gain), shift factor, and an alternate channel number may be
specified.  
.PP
This program works with either the DSP32-FAB2 board, or the DSP32C-VME
Surfboard.
.PP
If the ESPS SD file header item \fImax_value\fR is non-zero (likewise
for SIGnal header items \fImaximum\fP and \fIminimum\fP), then the
\fB-a\fP option may be used to scale the data so that the sample with
the maximum value is output as \s-1MAXDA\s+1/ If \fImax_value\fP is
less than \s-1MAXDA\s+1/, \fB-a\fP will amplify the data.  If
\fImax_value\fP is greater than \s-1MAXDA\s+1/, \fB-a\fP will
attenuate the data.  (Note that scaling is based on the maximum value
in the entire file, not the maximum value in the range being played.)  
.PP
Playback may be aborted by sending the terminal's interrupt character
(normally control-C) after playback has started.
.PP
This program is installed under the name \fIwplay\fR and \fIplay\fR.
Since this program is specific to \s-1DSP32\s+1 systems, a different
play program is used on non-\s-1DSP32\s+1 systems.  These system
dependent play programs all have a common user interface and are
installed under their system dependent name (eg. \fIwplay\fR,
\fInetplay\fR, \fImcplay\fR, etc) and the name \fIplay\fR.
.PP
If "\-" is given for a filename, then the input is taken from standard
input and must be an ESPS SD file (i.e., SIGnal files cannot be used
with standard input).  When input is taken from standard input, only
the first 10 seconds are played.  
.PP
To avoid mutual interference, all of the programs that make use of the
DSP32 board (\fIwaves\fP+, \fIwplay\fP, \fIwrecord\fP, and
\fIdspsgram\fP) cooperate by means of a lock file on
/tmp.  Before using the board for an operation, these programs attempt
to create the lock file.  If the attempt succeeds, the program
proceeds with the operation and then removes the lock file.  The
attempt will fail if the lock file already exists, indicating that
the board is in use. 
.PP
When an attempt to create the lock file fails because the file exists,
the program will repeat the attempt at one-second intervals for five
seconds.  If it does not succeed, it gives up and prints a message
giving the name of the lock file and saying that the board is in use.
.PP
File-system problems may keep programs from creating the lock file
even though it does not already exist.  In that case, the programs
quit waiting and print an error message immediately.
.PP
Three messages on \fIstderr\fP are possible in connection with lock files:
.nf

	set_lock: lock file \fIfilename\fP exists

.fi
when the program has tried for 5 seconds and the file still exists;
.nf

	set_lock: can't create lock file \fIfilename\fP

.fi
when the program fails to create the lock file for some other reason;
and
.nf

	rem_lock: can't remove lock file \fIfilename\fP

.fi
when the program has a problem removing a lock file that it has
created.  The name of the lock file has the form
.nf

	/tmp/dspLCK\fIhostname\fP

.fi
where \fIhostname\fP is the hostname of the workstation.  Occasionally
a program may create the lock file and terminate abnormally without
removing it.  Then someone must remove the lock file with the UNIX
\fIrm\fP command before other programs can use the board.  Naturally
one should always check first that some other user is not actually
using the board.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-x " debug_level \fR[0]\fP"
Setting debug_level to 1 causes several messages to be printed as
internal processing proceeds.  If debug_level is 2, then the data that
is to be output (after any scaling) is printed prior to being output
over the D/A converter.  The default is level 0, which causes no debug
output.
.TP
.BI \-p " range"
Select a subrange of points to be played, using the format
.I start\-end
,
.I start:end 
or
.IR start:+count .
Either the start or the end may be omitted; the beginning or the end of the
file are used if no alternate is specified. 
.IP
If multiple files were specified, the same range from each file is played.
.TP
.BI \-s " range"
Select a subrange of speech, specified in seconds. For compatibility with
DSC LISTEN, the beginning of the file is 0.  The format for a subrange
is the same as the \fB\-f\fR option.  The arguments to the \fB-s\fR
option can be decimal numbers (eg. 1.5).
.TP
.BI \-f " range"
Select a subrange of speech, specified in frames. By default, a frame is
100 points, but this may be changed.
.TP
.BI \-w " width"
This switch defines the frame width. The width is ignored unless the
.B \-f
switch is also specified.
.TP
.BI \-r " count"
Repeat count. The selected speech is played
.I count
times. If multiple files were specified, the files are played in order, and
the order is repeated
.I count
times.
.TP
.BI \-g " gain"
Speech samples are multiplied by
.I gain
before playback.  Gain is a floating point value.  This option
overrides the automatic gain control described earlier.  The option
can't be used at the same time as \fB-a\fP or \fB-b\fP.  
.TP
.BI \-i 
If this flag is given and ESPS SD file header item \fImax_value\fR is
zero, then any samples with a value greater than the maximum of the
D/A converter will be clipped.  If clipping occurs, then an entry is
made in a history file for each sampled clipped.  This entry gives the
sample number and the value before clipping.  At the end of the file a
scale factor is given that will prevent clipping.  Use of this option
slows things down noticeably.
.TP
.BI \-a
Amplify the data in the file so that the maximum value (as given by
the \fImax_value\fP item in the ESPS SD header) is scaled to the
maximum value that can be output by the D/A converter.  The \fB-a\fP
will be ignored if \fImax_value\fP is zero (a message is printed 
unless \fB-q\fP is used), and the \fB-a\fP option cannot be used with
either \fB-g\fP or \fB-b\fP.
.TP
.BI \-h " hist-file"
Specifies an alternate history file.  The default is \fIplay.his\fR.
.TP
.BI \-b " shift-value"
If this option is given and \fIshift-value\fR is positive, then each
sample (after it is converted to integer format) is shifted to the right
by \fIshift-value\fR bits.   \fIShift-value\fR being negative causes a
left shift.   This option is useful to rescale data that has a higher
resolution than the D/A converter being used here.   For example, files
recorded by or synthesized from data recorded by a 16 bit A/D can be
shifted 4 bits to the right for correct output on a 12 bit D/A.    This
is preferred to using the \fB-g\fR option with a gain of .0625 because
the shift is faster than a floating multiply.   This difference is most
noticeable on large files.  The \fB-b\fP cannot be used at the same
time as \fB- a\fP or \fB-g\fP.
.TP
.BI \-q
This option (q for quiet) suppresses all terminal output (except for
fatal error messages) from the program.  It is useful when play is being
called by another program.
.SH ESPS PARAMETERS
.PP
The parameter file is not read.  
.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
If Common file processing is enabled the following are read from the
Common file if only one input file or no input file is given on the
command line and provided that standard input isn't used.
.IP
.I "filename - string"
.IP
This is the name of the input file.  If no input file is 
specified on the command line, \fIfilename\fP is taken to be the
input file.  If an input file is specified on the command line, 
that input file name must match \fIfilename\fP or the other 
items (below) are not read from Common. 
.IP
.I "start - integer"
.IP
This is the starting point in the input file to begin output.  It 
is not read if the \fB\-p, -f,\fP or \fB-s\fR option is used.  
.sp
.I "nan - integer"
.IP
This is the number of points to output from the input file.  It is not
read if the \fB\-p, -f\fP or \fB-s\fR option is used.  A value of zero
means the last point in the file.
.sp
.I "gain - float"
.IP
This value is the same as the argument to the \fB-g\fP option described
above.  This value is not read from Common if \fB-g\fR, \fB-a\fP, or
\fB-b\fR is used.
.sp
.I "shift - integer"
.IP
This value is the same as the argument to the -b option described
above.  A gain value and a shift value cannot both be used.  If both
are present in the common file, then only the shift value is used.
This value is not read from Common if \fB-g\fR, \fB-a\fP, or \fB-b\fR
is used.
.sp
.PP
Again, the values of \fIstart\fR and \fInan\fR are only used if the
input file on the command line is the same as \fIfilename\fP in the
common file, or if no input file was given on the command line.  If
\fIstart\fR and/or \fInan\fR are not given in the common file, or if
the common file can't be opened for reading, then \fIstart\fR
defaults to the beginning of the file and \fInan\fR defaults to the
number of points in the file.
.PP
The following items are written into the ESPS Common file:
.IP
.I "start - integer"
.IP
The starting point from the input file.
.sp
.I "nan - integer"
.IP
The number of points in the selected range.
.sp
.I "prog - string"
.IP
This is the name of the program (\fIplay\fP in this case).
.sp
.I "filename - string"
.IP
The name of the input file.  If multiple input files are processed, this
is the name of the first file.   
.sp
.I "gain - float"
.IP
The \fIgain\fP value is written if the \fB-g\fR option is used, or
if \fIgain\fR was read from Common.  If neither of these occurred, 
then the value 1.0 is written.  
.sp
.I "shift - integer"
.IP
The value is written if the \fB-b\fR option is used, or if \fIshift\fR
was read from Common.  If neither occurred, then the value 0 is
written.  
.PP
These items are not written to ESPS COMMON if the input file is <stdin>
or if there are more than one input files.
.SH DIAGNOSTICS
.PP
.I Wplay
informs the user if the input file does not exist, or is not an ESPS sampled
data file, or if inconsistent options are used, or if an unsupported 
sample rate is found in the file. Also see \fBWARNINGS\fP below.
.PP
If the starting point requested is greater than the last point in the
file, then a message is printed and the program exits with status 1.  If
the ending point requested is greater than the last point in the file,
it is reset to the last point, a warning is printed and processing
continues.
.SH WARNINGS
.PP
With the FAB2 board
\fIwplay\fP (1\-\s-1ESPS\s+1) supports only 4 playback rates, but
can sample rate convert the data on the fly to handle 15 different
sampling rates.
There are two D/A devices on the DSP32 board: a Burr Brown PCM56
chip and a AT&T 752X codec chip. If using the PCM56 chip,
the following sample rates are supported: 6667, 8000, 10000, 12000, 16000, 
20000, and 24000.
Actual playback occurs at 20000 or 24000 samples/second;
all other rates are up-converted before playback.
If using the AT&T codec chip and the environment variable CODEC16
is not defined, the following sampling rates are supported: 6000,
6667, 8000, 10000, 12000, 16000, 20000, and 24000.
The actual playback rate is 12000 samples/second, but the data 
at other sampling rates is converted
on the fly before playback.
Finally if using the AT&T codec chip and CODEC16 is defined,
the following sample rates are supported:
8000, 8889, 10666, 16000, 21333, 26667, and 32000.
Actual playback occurs at 16000 samples/second, but other rates
are converted to 16000 before playback.
If you play a file that is sampled at an unsupported rate,
\fIwplay\fP (1\-\s-1ESPS\s+1) plays the data at the closest supported
rate and issues a warning.
.PP
The sampling rates available for the Surfboard/Ariel combination, 
depend upon the crystal installed on the Ariel board.   With the standard
24.576 Mhz crystal, the following sample rates are available: 48 Khz, 24
Khz, 12 Khz, 6 Khz, 3 Khz, 1.5 Khz, and 750 Hz.   
With an alternate 16.384 Mhz crystal the following rates are available:
32 Khz, 16 Khz, 8 Khz, 4 Khz, 2 Khz, and 1 Khz.  The type of crystal in
your board should be on a label on the analog section shield.   If there
is no label, then the shield mus[ be removed to see the crystal.
.PP
The software cannot detect what crystal is installed.    If a 16 Mhz
crystal is installed, then the environment variable \fBARIEL_16\fR
should be defined (its value does not matter).   If the 24 Mhz crystal
is installed, then this environment variable should not be defined.
.PP
Some Ariel boards have been shipped with the wrong version of a particular 
part, which prevents the Surfboard from setting the sample rate on the
Ariel board.   If you get the following message when trying to run \fIwrecord\fR
or \fIwplay\fR:
.nf
iicack: bus error, sta=0x8, flag=0x0, goodbye!
.fi
then, you have this problem.   The fix is to either replace the 8574AP on the 
Ariel board with a P8574P, or to set the Unix environment variable 
\fBP8574_type\fR to 0. (Actually, the variable can have any value, it
just needs to be defined.)   So do:
.nf
setenv \fBP8574_type\fR 0
.fi
.SH FILES
.SH BUGS
.PP
If \fIwplay\fP terminates abnormally (e.g., ^C, system crash, bad bug,
etc.), the DSP32 lock file can be left on /tmp (see "USING THE THE
OPTIONAL DSP32 BOARD").  The lock file will interfere with \fIwaves\fP+,
\fIdspgram\fP, \fIwplay\fP, and \fIwrecord\fP until it is removed. 
.SH EXPECTED CHANGES
.PP
Allow a variable number of retries before giving up on the DSP32
board.
.SH SEE ALSO
.PP
SD (5\-\s-1ESPS\s+1), \fItestsd\fP (1\-\s-1ESPS\s+1), \fIcopysd\fP
(1\-\s-1ESPS\s+1), \fIsetmax\fP (1\-\s-1ESPS\s+1), \fIwrecord\fP
(1\-\s-1ESPS\s+1), \fIdspsgram\fP (1\-\s-1ESPS\s+1)
.PP
.SH AUTHOR
.PP
Alan Parker, based on the network play program by Joe Buck.  Modified
for DSP32 by Alan Parker.  Modified for SIGnal files and for the \fB-a\fP
option by John Shore.