readme file for CDP reverb programs

ROOMRESP

simple utility program to generate early reflections for reverbs, using "mirror room" model.

The format for early reflection data is a series of lines containing
<time> <value> pairs. The first time is non-zero (since the direct sound
is presumed to be there):

0.0082 0.500000
0.0121 0.204198
0.0134 0.169094
0.0145 0.143638
0.0170 0.093391
0.0180 0.084478
0.0200 0.067530
.. etc

Data obtained from roomresp is used internally for the early reflections in both "rmverb" and "reverb". 
Roomresp usually generates many more taps than are necessary or efficient; typically the first
19 taps (say) will be used. The two reverb programs offer the facility to import reflection data from
roomresp directly into the reverb (see the -e flag option).  As a FIR filter is used to process
these, the CPU load of the program is directly affected by the number of reflections used.

the choice of early reflections has an influence on the character and tonality of the reverb 
- experimentation is recommended here. Hand-written reflection data is especially good for "creative" reverbs
with heavy ringing and colour!

RMVERB

The program "rmverb" uses nested allpass filters based on Bill Gardner's published models; hence three 
room models are offered, "small", "medium" and "large".
 
The "large room" model is modified with smaller delays (so really "large-ish"), to reduce the 
obviousness of the slap-back echoes generated by the model. 

Note that this relies on the fact that each reverb element is implemented in a self-contained manner, 
unit-generator style (e.g. including plain delays between elements). If it is required to optimise 
the architecture by having all elements share one delay line,  this change will not work - the outer 
delay will need to be smaller than the  inner ones.

Two allpass filters per channel are aded to the output, to obtain
a stereo effect from the internal mono reverb. According to Gardner, his concept was to use one "diffuser" 
(configuration of nested allpass filters) per speaker; this suggests that any thinness in the output can 
be overcome (at the cost of processing time) by paralleling several diffusers per channel, with slightly 
different parameters.

Additionally (NEW from CDP!) each nested allpass filter has been extended with the addition of a first-order
filter in the outer feedback loop. This acts in addition to the global feedback loop defined by Gardner.
This is indicated in "rmverb" by the -d flag ("double damping"). This seems to reduce the metallic 
ringing at the very end of the reverb decay, at the cost of shortening the overall decay time. It would
easily be possible, with this change, to eliminate the global feedback filter and rely entirely on the
filter inside the nested allpasses, to recover some of the decay time. This feature is experimental.

As Gardner notes, pushing the feedback amount to obtain long decay times is not recommended, as the timbre
deteriorates. The program is implemented in a relatively "raw" state; with a raw feedback level parameter 
rather than a "reverb time"; some mapping will need to be computed for this!

The programs also allow the delay between direct sound and first reflection (as defined in the reflection data)
to be modified - see the -p flag option.	  Standard filters are provided to filter the input signal itself,
and the signal entering the reverb. The latter is usual, the former is rarely necessary. 
Some filters are second-order, offering a 12dB slope (currently fixed in the program). It would be easy to 
make the slope variable as another user parameter.	 The sources include a library of low and high pass filters,
first order and second order (shelving).


 REVERB

The program "reverb" uses a standard moorer/schroeder comb+allpass structure, with	6 comb filters 
(with lp filters in the fedback loop) feeding 4 allpass filters. A conventional,"reverb time" is provided, but
no "room size". This wouild have to be obtained via more or less extensive early reflections. 


Not shown in the programs usage message is a possble extra argument which gives the name of a text data file
containing delay times (in msecs) for the comb and allpass filters.	 This will be a plain text file containing
10 positive floating-point values. The internal preset times corresponds to this data file:

50 56 61 68 72 78 20 14 9 6

 - which gives the canonical Moorer values.


NOTE one importnat difference in the "absorb" argument to the programs.
Reverb:  range 0 - 1, large values = more absorption.
Rmverb:  value in Hzf for feedback filter (See Gardner for details). He suggests:
	small room: 4200 Hz
	medium:  2500 Hz
	large:  2600 Hz

Rmverb offers direct setting of this value. This then applies both the the global feedback loop
and to the internal nested-allpass loop as described above.

In both reverb programs, ~all~ delay times are adjusted to give prime number integral lengths in samples. This means
that performance will not be ~identical~ at all sample rates. Naturally, if the sample rate is to be fixed, in a
dsp implementation, the possibility exists to fine-tune delays for that sample rate.


Both programs generate multi-channel (surround) signals by using a separate allpass filter on each channel for
de-correlation. The direct sound is fed only to the front stereo pair.


Note that these are command-line programs, and the various dsp elements are not fully re-entrant in terms of 
running re-initializations.	 This would not be hard to do, howewver, especially given the goal is a 
re-implementation on a DSP architecture.

CDP plans to extend these algorithms with variable delay lines, and also to increase density by addition of 
elements.  To say nothing of real-time versions in plugin form!

 Richard Dobson
 CDP
 September 14th 2004









