.TH LPREV 1carl CARL
.SH NAME
lprev \- configurable sound reverberator
.SH SYNOPSIS
.B lprev 
[
.B -Dn
] [
.B -dN
] [
.B -gN
] [
.B -RN
] [
.B -TN
] [
.B -fX
] [
.B -CN
] [
.B -bN
] [
.B -c
]
< floatsams > floatsams
.SH FLAGS
Input and output must be a file or pipe.
flags:
.TP
.B -D
set dsig to N (0.3); sets ratio of direct/reverb. signal
.TP
.B -dN
set ring-time to N (4 sec. at prevailing sample rate)
.TP
.B -gN
set reverb time coefficient to N (0.9) (must be < 1.0)
.TP
.B -RN
set sample rate to N, derived from input header (DHISR Hz)
.TP
.B -TN
set tap coefficient input scaler to N (1.0)
.TP
.B -fX
specify configuration file X
.TP
.B -CN
scale input to comb reverbs by N (1.0)
.TP
.B -bN
set debug variable to N (0); values:
.br
	1 = print configuration on stdout,
.br
	2 = only output tap signal,
.br
	4 = only output comb filter signal,
.br
	8 = only output tap/comb mix.
.TP
.B -c
print diagnostics about location of clipped signals.
.PP
All durations are in seconds.  Use postop 'S' for sample times.
Arguments may be expressions.
.SH DESCRIPTION
.B lprev
reads binary floating point sound sample data (floatsams), reverberates
them, and writes the reverberated sound on its standard output, likewise
as floatsams.  It implements a reverberation scheme described by
Andy Moorer [``About This Reverberation Business'', 
.I CMJ,
Vol. 3, #2.], which utilizes a tap delay line to simulate early reflections,
and a section of comb filters with low-pass filters as feedback terms to
simulate the decay of high frequency information through time because of
air and wall absorption.
.PP
It does the ``right thing'' by default to act as a simple reverberator
for any sound, to wit:
.sp
 % sndin | lprev | sndout
.sp
but its main claim to glory is its modifiability, see below.
.SH Flags
.IP -R
sets sampling rate N.  
If the input signal has a header and no -R flag is given, the
rate is determined from the header, otherwise, the flag overrides the
value determined by the header.  If no flag or header occur, the rate
defaults to DHISR.  The sampling rate is computed in this manner before
any delay lengths, or other time-dependent parameters.
.IP -g
This controls the total reverberation time.  It defaults
to 0.9, which seems to be about 3.5 seconds.
A value of .87 for g provides a reverb time of about 1 second, 
.99 rings for 10-14 seconds.
The reverberation time can be estimated as
.sp
.EQ
{ 1 - .366 } over T
.EN
.sp
where T is the reverberation time desired in seconds.
A value of 0.98 gives
a cathedral-like quality; 0.99 puts you in
the Taj Mahal.  Higher values, like .99999, are possible but silly.
The value must never equal or exceed 1.0, or the reverberator
will become unstable.
.IP -d
sets the ``ring-time'' in seconds to N, that is, it says how
long to continue running the reverberator after the
input sound file has quit, allowing for the energy in the reverb to die away.
It defaults to 4 seconds at the prevailing sampling rate, 
which is generally not enough, and should certainly be
augmented for any value of -gN greater than 0.9.
.IP -D
sets the ratio of the direct/reverberated signal level to N.  The default
of 0.3 means that 30% of the signal put out will be direct signal, 70%
will be the reverberated part.  Adjust accordingly.
.IP -T
Because of its implementation, 
.B lprev
cuts the overall level of the signal down somewhat.  It can be scaled
up or down with -T, where N is the gain scale, which defaults to 1.0.
The coefficient N specified by -T is multiplied against the actual gain
values used in the individual taps of the taped delay line.
To adjust overall amplitude, take a loud section of your sound, reverberate
it without -T, and pass it to 
.I hist(1carl).
.I hist
might
show that the peak reverberated signal is -18dB down, for instance; 
saying -T18dB
scales the signal up by 18dB.  Caution must be excersized, since it
is possible that the signal will overflow if scaled up too far.
Note, this is a relatively efficient way to scale the signal, and is
preferable to rescaling the output with, for instance, 
.I gain(1carl).  
This is because the -T flag affects a multiply which will be done in any
case.
.IP -fX
specifies UNIX file X as a ``configuration file'', containing information
about the number of unit reverberators and their
delays and gains.   With this facility, plus the flags,
you can totally rearrange the
performance of the reverberator.  
A configuration file consists of a series of text lines.
Here is the syntax:
.sp
.nf
 line_format	:== <spec_char> <blank> <coeff> <blank> <length> <'\n'>
   spec_char	:== t | c | a  (tap, comb, or allpass respectively)
   coeff		:== floating pt. number (between 0 and 1.0)
   length		:== floating pt. number (seconds delay length)
.fi
.sp
Lines may begin
with a single letter, either 't', 'c' or 'a' for ``tap'',
``comb'' or ``allpass''.
The next field is a gain associated with that unit, followed by a field
giving the delay length in seconds at the prevailing sampling rate.
Here are examples of single entries:
.sp
.nf
	t	.134	0.0797
	c	.26	.056 
	a	.7	.006  
.fi
.sp
The number of 't', 'c' and 'a' entries determine the number of such sections;
their lengths are specified in seconds;
their coefficients are interpreted depending on what kind of unit is
specified.  Order of lines is irrelevant.  Usually, 't' sections correspond
to a peak in the impulse response in the first 50 - 100 ms. of a
real room, where the gain is the normalized amplitude of the peak.
For 'c' comb filter reverb sections, the gain terms adjust the rolloff of
high frequencies through time.  The delay lengths usually correspond to the
periods between the 3 major parallel walls of the target room.
The values of allpass are suggested to be a gain of .7 and a
delay of 6 ms.  Subsequent allpass sections are scaled by .9 for gain, and
the nearest prime number of samples to .9 times the delay.
.SH DIAGNOSTICS
Because this routine uses complex filtering and signal delay and mixing,
it is difficult to normalize its behavior for all signals.  The
defaults have been chosen very conservatively so as to work for most
signals.  The most likely cause of difficulty is clipping caused by
summing variously delayed signals.  The 
.B -c
flag is useful to determine where the clipping is taking place.
The following points are monitored for clipping, and are reported
separately for each block of input samples processed by 
.B lprev.
.TP
.B Input signal;
The input signal has clipped.  Attend to your input.
.TP
.B Tapped delay line output;
The sum of the tapped delay lines has clipped.  Indicates that
more than one tap has the same delay, or a tap gain is greater than 1.0.
.TP
.B Comb filter outputs;
The sum of the parallel comb filters has clipped.
.TP
.B Mixed tap and comb filter outputs;
The sum of the comb filters and tapped delay lines has clipped.
.TP
.B Allpass output;
The signal after the allpass filters has clipped.
.TP
Combined dsig and allpass;
The combined direct and reverberant signal has clipped.
.PP
To eliminated clipping, adjust the various internal gain controls
for the different stages of
.B lprev.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
``Lprev - Configurable Tap-delay/Low-pass Reverberator'', in file
/mnt/tutorials/lprev.dgl at CARL.
.sp
Andy Moorer, ``About This Reverberation Business'',
.I CMJ,
Vol. 3, #2.
