.TH WAVE 1carl CARL
.SH NAME
wave \- generates simple test tones on the standard output
.SH SYNOPSIS
.B wave 
[
.B flags
] > floatsams
.RS .5i
.nf
flags:
(N is a number or arithmetic expression, C is a character)
-RN	= set sampling rate to N (DLOSR Hz)
-fN	= set frequency	of waveform to N (440.0 Hz)
-wC	= select waveform C from following list:
	s = sine (default)
	r = ramp
	q = square
	t = triangle
	p = pulse train
	i = impulse response
	d = dc, where -aN determines the offset
	S = silence
-aN	= amplitude N, where N may be
	absolute amplitude in the range 0 to 1.0, 
	or 0dB to -90dB (you must supply ``dB'' postoperator)
-TN	= set waveform duration to N (1 second at prevailing -R)
-H	suppress generating a header.
-SN	append N seconds of silence at end of waveform.
Flag options may be expressions which can include postoperators.
Postoperators: S = time in samples, K = ``times 1024'', k = ``times
1000'', s = time in seconds (default postoperator for time values),
ms = milliseconds, m = minutes, dB = amplitude in dB.
.RE
.SH DESCRIPTION
.B wave
writes simple waveforms on stdout according to specifications supplied
by the flags.  The output 
data stream normally consists of binary, floating-point sample numbers
in the range of -1.0 to +1.0.
If the output is connected to a terminal, the samples are presented in
human-readable form instead of binary.
.PP
.I Waveforms 
available include: sine, square, triangle, sawtooth, pulse train,
dc offset, silence and 
impulse.  They are selected with the -w flag.  For instance,
.sp
% wave -wr
.sp
selects a ramp waveform.
.PP
.I Amplitude 
is set with the -a flag.  Amplitudes can be expressed either as
a magnitude between 0 and 1.0, or in dB, where 0dB is equivalent to a
magnitude of 1.0.  
These two examples are equivalent:
.sp
% wave -a.1
.sp
% wave -a-10dB
.sp
Note that in the illustration with dB, the second '-' is taken to be a minus
sign.
.PP
Similarly, 
.I frequency 
is set with -f followed by a number, sampling rate is
set with -R and a number, likewise for duration.  
.PP
By default, wave produces a sine wave at A440, sampling rate DLOSR FOR
one second, at full amplitude.  That is, if the defaults were made explicit:
.sp
% wave -ws -RDLOSR -f440 -d1 -a1 > file
.sp
and
.sp
% wave > file
.sp
are equivalent.  However, if you just say wave all by itself, and do
not direct its output to a pipe or file, you will be given a terse
help message, explaning all the flags and options.
.PP
The options to the flags may be arithmetic expressions.  (It is advisable
to put expressions inside double quotes, otherwise the shell may think
it is supposed to evaluate them).  Expression postoperators 's' and 'K' are
available.  For instance, -R48K sets the sampling rate to ``48*1024'' =
49152.  The time flags interpret duration in seconds by default.
If instead you want duration measured in samples, use the 's' postoperator.
For instance, -d500S will set the duration to be 500 samples long, regardless
of the sampling rate.
.PP
.SH AUTHOR
Gareth Loy
