wrecord.1

speech signal process tools

.\" Copyright (c) 1987, 1990 Entropic Speech, Inc.; All rights reserved
.\" @(#)wrecord.1	1.10 8/14/91 ESI 
.TH WRECORD  1\-ESPS 8/14/91
.ds ]W "Entropic Speech, Inc.
.SH NAME
wrecord  - digitize data using the \s-1DSP32\s+1 analog-to-digital (A/D) converter.
.br
record  - digitize data using an analog-to-digital (A/D) converter.
.SH SYNOPSIS
.B wrecord
[
.BI \-x " debug level"
] [
.BI \-{psf} " range"
] [
.BI \-r " sampling rate"
] [
.BI \-w " width"
] [
.BI \-t " comment text"
] [
.B \-I
]
.I file
.SH DESCRIPTION
.PP
.I Record
digitizes the input at the specified sampling rate and stores the data as SHORTs in 
.I file
(an ESPS sampled data (SD) file).
A range of data may be specified in one of three ways:
the number of samples, seconds of data, or number of frames at the specified width.
.PP
This program operates with either the AT&T DSP32-FAB2 board, or the 
AT&T DSP32C-VME (Surfboard) with an Ariel Pro-Port analog board installed.
.PP
The following options are supported:
.TP
.BI \-x " debug level"
Only debug level 1 is defined in this version;
this causes several messages to be printed.
The default level is zero, which causes no debug output.
.TP
.BI \-p " range"
Select the recording length, in number of points.
.TP
.BI \-s " range"
Select the recording length, in seconds.
.TP
.BI \-f " range"
Select the recording length, in frames. By default, a frame is
100 points, but this may be changed. See 
.I width
below.
.TP
.BI \-r " sampling rate"
Select the sampling rate (default is 8000 samples/second for the FAB2 board, 
and 12000 for the Surfboard/Ariel).
Only a limited number of rates are supported - see \fBWARNINGS\fP
below.
.TP
.BI \-w " width"
This switch defines the frame width. The width is ignored unless the
.B \-f
switch is also specified. (The default is 100 points.)
.TP
.BI \-t " comment text"
The argument following this option is added to the comment field of the
output ESPS SD file.  If the text is more than one word, it must be
enclosed in quotes.
.TP
.B \-I
Normally \fIrecord\fR prompts the user to hit return when it is to start
recording.  When this option is used, the recording starts as soon as
possible.   
.TP
.I \ file
The file to store the sampled speech data into.  By convention this
file ends with \fI.sd\fR, although it is not enforced.
.PP
.I Record
tells the user when all the setups are finished and the A/D conversion
process is ready to begin.  The data conversion starts when the user
hits a carriage return.
.PP
If \fIfile\fP is "\-", then the output sampled data file is directed
to standard output.  
.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 ESPS HEADER
.SH ESPS PARAMETERS
The ESPS parameter file is not referenced.
.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
The following items are written into the ESPS Common file if it is
enabled:
.IP
.I "start - integer"
.IP
This is always 1.
.sp
.I "nan - integer"
.IP
The number of points in the output file.
.sp
.I "prog - string"
.IP
This is the name of the program (\fIrecord\fP in this case).
.sp
.I "filename - string"
.IP
The name of the output file.
.SH "ESPS HEADERS"
.PP
Items in the SD header of output file are set as follows:
.IP
.nf
.IR sf " = sampling frequency"
.IR dcrem " = 0"
.IR nchan " = 1"
.IR equip " = default A/D type "
.IR scale " = 0"
.IR max_value " = absolute value of the maximum data point value"
.IR start " = 1"
.IR nan " = number of samples taken" 
.SH DIAGNOSTICS
.PP
.I Record
prints "Event Wait Timeout" if the the program quits before all the data is captured.
This can happen if the designated clock is not physically connected to the A/D converter, or if the
system load is too heavy to support the conversion.
.SH BUGS
.PP
If \fIwrecord\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 WARNINGS
.PP
With the FAB2 board
\fIwrecord\fP (1\-\s-1ESPS\s+1) samples at only two different
rate: 12000 samples/second and 16000 samples/second.
You can chose between the two rates by setting an environment variable.
If the variable \fBCODEC16\fP is defined,
\fIwrecord\fP (1\-\s-1ESPS\s+1) records data at 16000 samples/second;
otherwise it records at 12000 samples/second.
For each of the two rates,
there are a family of rates that \fIwrecord\fP (1\-\s-1ESPS\s+1) 
will convert to on the fly by doing a sample rate
conversion, but remember the real sampling rate is fixed and thus the
useable bandwidth is fixed at 1/2 the real sampling rate.
When recording at 12000 samples/second,
the following rates can be obtained:
6000, 6667, 8000, 10000, 12000, 16000, 20000, and 24000 samples/second.
When recording at 16000 samples/second,
the following rates can be obtained:
8000, 8889, 10666, 13333, 16000, 21333, 26667, and 32000 samples/second.
If you specify a rate that is not supported,
the closest supported rate gets used and a warning message is issued.
.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: 48Khz, 24Khz, 
12Khz, 6Khz, 3Khz, 1.5Khz, and 750 Hz.   See the Ariel manual for more details.
.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.    So do:
.nf
setenv \fBP8574_type\fR 1
.fi
.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), \fIwplay\fP
(1\-\s-1ESPS\s+1), \fIdspsgram\fP (1\-\s-1ESPS\s+1)
.SH AUTHOR
.PP
David Burton, Alan Parker, Jay Virdy.
Modified for DSP32 by Alan Parker.