.TH RECORD 1csound CARL
.SH NAME
record 
- record sound file through analog-to-digital converters
.SH SYNOPSIS
.sp 2
.B record 
[flags [file]]
.RS 1i
.nf
flags: flag = (values:default)
-cN = set number of channels to N (1, 2, 4:1),
-RN =sample rate (DHISR),
-FN = set filters to N (0,1,2,3:0),
-q  = quiet mode,
-TN = set file size to N (expressed as time in seconds),
-CN = set file size to N cylinders (1),
-r  =  remark(NULL),
-I  =  include(NULL),
-p  =  protection(0644)
-M  =  monitor mode
-B  =  broadcast mode
-h  =  print help message
.fi
File test in your current sound file directory is used by default.
Filters used track the sampling rate unless specified with -F.
.SH DESCRIPTION
.B record 
reads sound samples from the ADCs into the named 
.I csound
file.  
.PP
When run, it prompts you by saying:
.RS .5i
press [RETURN] to record, anything else to abort.
.RE
and waits until you do so before immediately starting to record.
.PP
If the 
.B delete 
key is struck during a recording, the recording is stopped,
and the length of the file truncated to the elapsed time.  A message appears
on the screen indicating the time at which the file will be truncated.
.PP
If the 
.I core
signal is given by pressing
\fBctrl-\\\fR
then the recording is aborted, and the program allows you to retry
by jumping back to the prompt:
.RS .5i
press [RETURN] to record, anything else to abort.
.RE
.PP
The flags behave in the same way they do in 
.B sndout(1csound).  
The process
is similar to 
.B sndout, 
since the only difference is the source of the
samples.  Differences from 
.B sndout: 
there is no -t flag
(recorded files will all be realtime), and no -i or -o flags (packing is
determined by the ADCs).  Additional flags: -FN selects the numbered
filter.
At CARL, correct Nyquist filters exist for DHISR and DLOSR sampling rates,
and are selected by 0 and 1 respectively.
.B record
will set this automatically to the right one for the selected sampling
rate.
Filter 2 is BYPASS mode, i.e., no analog filtering of the output at all.
Filter 3 is not installed at CARL.
The -q flag is for quiet mode, no prompts, no diagnostics.
.PP
The flags, -M and -B set 
.I monitor 
mode and 
.I broadcast
mode respectively.  
.I Monitor
mode causes the digitized signal from an ADC to be wrapped immediately
around to its like-numbered DAC.
.I Broadcast
mode causes the digitized signal from an ADC to be wrapped immediately
around to all DACs.  Whether this works on any given DSC system depends
on the hardware configuration of the Nyquist filters.  Refer to the
Field Print set for your system.
.SH SEE ALSO
play(1csound), sndio(1csound).
.SH DIAGNOSTICS
.PP
While other recording rates than DHISR Hz are available (via the -R
flag), these are quantized to the nearest available actual sampling rate 
supported by the DSC converters.
You are notified of the actual sampling rate only when
there is a difference.  Appropriate filters
are silently selected automatically from the actual sampling rate.
.PP
Various errors may be reported, of which "disk error" and
"converter error" are the two most frequent.  The former indicates that,
a buffer being sent to disk has not completed in time.
The latter usually indicates that the converters have experienced
a "data late" condition, indicating that they couldn't get enough throughput
on the unibus.
.SH AUTHOR
Gareth Loy
.SH BUGS
File truncation via pressing
the delete key seems to cause the length of the file
to be slightly overestimated, by a value in the range of 8 to 80 milliseconds.
.PP
The converter system can be subject to occasional hiccups, resulting
in clicks in your sound file for a variety of reasons.  The usual
reason is
having too much conflicting activity on the disk or the unibus
to support the required data rate.  
The only sure cure for this is to
eliminate all vestiges of timesharing, running the system in single user
mode.  Or, if your data can suffer it, running at a slower sampling rate.
.SH BANDWIDTH
Experience with our system has shown that with a single unibus VAX-11/780
system, where the disks and converters are on the same unibus (the worst case), 
an aggregate peak throughput is around 92160 samples per second, allowing for
guaranteed mono recording up to 50ks.  For the same VAX with either two
unibuses or with massbus disks, the aggregate peak is such as to afford
guaranteed stereo at 50ks.  These are very conservative figures.
Performance varies with the phase of
the moon, sample rates may be slightly higher west of the Rockies,
New York residents add 5% disk latency, don't call us, we'll call you.
