# Reverberation Actor

last updated: Geoffrey Zheng, September 20, 1998

## Background

The artificial reverberation actor is based upon M. R. Schroeder's classical comb/all-pass filter network reverberator, and some other sources described at the end of this document. This kind of artificial reverberator is designed to imitate both the time and frequency responses of real reverberation of all sorts of environment, mainly enclosures like room and concert hall. Based on acoustics and experiments, a lot factors characterize enclosure reverberation. A network consists of cascaded reverberation units is appropriate to realize these characteristics.

The reverberator always map all the channels of the sound source down to 1 before all calculation. The localization actor can be used AFTER the reverberator to localize sound.

All the technical details of the reverberation network is described in a separate file for more inquisitive users. The following parameters can to be set by actor and handler messages for general use:

Parameter | Message | Valid range | Description
Reverberation mix | `SetMix` | [0,1] | The balance between dry (direct) and wet sound (reverberation). Setting it to 1 yields purely wet, and 0 purely dry.
Reverberation gain | `SetGain` | [0,10] | Scaling of reverberation sound BEFORE it is mixed with the dry sound. The bigger value the louder reerberation. Be aware that clipping may occur if the gain is too high. Combinations of reverberation gain and mix can produce arbitrary distance perception of the sound source.
Reverberation time | `SetTime` | (0,1] | Length of reverberation. The actual reverberation time depends on the subtle interation between almost all parameters including revberation mix, gain, time, brightness, and the volume that the sound is playing. The bigger value the longer reverberation. With default values, set the time to 1 will produce an approximate 15-second reverberation.
Reverberation brightness | `SetBright` | (0,1] | Brightness of reverberation. The bigger value, the brighter reverberation sounds. However, value greater than 0.4 is not recommended, because it will lead to annoying ringing and metallic sound. A "warm" reverberation can be produced by setting brightness low and raising the reverberation gain.
Damp ratio | `SetDampRatio` | [1,30] | Ratio of low-frequency reverberation time to high-frequency reverberation time. For any kind of enclosure, high-frequency components of a sound decay away faster than low-frequency components. The bigger value, the faster high-frequency components die out than low-frequency components.

The following table lists other parameters for more advanced user to have more controls over the reverberation.

Please note one thing special about the early reflection delays. The amount of delay of each early reflection denotes the amount of milliseconds that reflection will be heard after the PREVIOUS reflection, but not the original sound, with the exception of the first reflection. So if there're 3 early reflections and their delays are a, b, c respectively, they will be heard at a, a+b and a+b+c milliseconds after the original sound. Also for saving memory, the maximum delay is 500ms. (With 22050Hz sampling rate, a 500ms float data delay line requires 22050*0.5*4 = 44KByte of memory. With maximum number of early reflections, comb filters and all-pass filters, the ReverbActor requires about 313KB memory.) If any reflection delay longer than 500ms is required, multiple reflection delays can be added up, with the coefficients to be zeroes except the last one, as the preset `Canyon`.

Parameter | Message | Valid range | Description
Input bandpass filter pole | `SetPole` | [-0.5,0.5] | Pole position of the input bandpass filter. The bigger value, the low center frequency of the filter.
Early reflection Number Delay Coefficients | `SetEarlyRefNum SetEarlyRefDelay SetEarlyRefCoeff` | [0,6] [0.1,500](ms) [0,1] | Parameters controlling early reflections. Early reflection is simply a delayed and scaled version of the original sound.
Comb filter Number Delay | `SetCombNum SetCombDelay` | [0,6] [0.1,100](ms) | Parameters controlling comb filters.
All-pass filter Number Delay | `SetAllPassNum SetAllPassDelay` | [0,3] [0.1,10](ms) | Parameters controlling all-pass filters.

To find the right combination of all the parameters above for a specific kind of reverberation is not trivial. 5 presets are provided as a starting point for further adjustment for individual requirements:

Preset name | `Default` | `SmallRoom` | `Hall` | `Echo` | `Canyon`
Description | Default values for a moderate reverberation with mininum computational load. | Reverberation in a small-size room. | Reverberation in a midium-size hall. | Reverberation with distinct echoes. | Reverberation in a grand canyon.
Reverberation mix | 0.5 | 0.4 | 0.5 | 0.5 | 0.75
Reverberation gain | 1. | 1. | 1. | 1. | 1.5
Reverberation time | 0.3 | 0.2 | 0.5 | 0.5 | 0.7
Reverberation brightness | 0.15 | 0.15 | 0.15 | 0.15 | 0.1
Damp ratio | 1. | 5. | 8. | 8. | 10.
Pole | 0. | 0.25 | 0.25 | 0.25 | 0.45
Early reflection Number Delay Coefficients | 2 20. 18. .82 .63 | 5 20. 23. 30. 35. 39 .82 .82 .63 .72 .53 | 5 20. 23. 30. 35. 39 .82 .82 .63 .72 .53 | 0 | 6 500. 500. 450. 450. 400. 400. 0. .92 0. .8 0. .6
Comb filter Number Delay | 4 50. 56. 61 .68 | 6 50. 56. 61. 68. 72. 78. | 6 50. 56. 61. 68. 72. 78. | 1 100. | 6 50. 56. 61. 68. 72. 78.
All-pass filter Number Delay | 1 6. | 1 6. | 3 6. 1.7 .63 | 3 6. 1.7 .63 | 3 6. 1.7 .63

To play with all the parameters, use the standard testcase audpanel by running `make test` at command prompt. Five message groups are dedicated to adjust all parameters. The first contains all "global" parameters including RevMix, RevGain, RevTime, RevBright, DampRatio, Pole, EarlyRefNum, CombNum and AllPassNum. It is recommended to use the "hit" button instead of check "Send when changed". The second message group contains early reflection delays, the third for early reflection coefficients, the fourth for comb filter and all-pass filter delays, the fifth for preset.

## Usage

To use the reverberation actor, load `reverb.so` and create an actor of type `ReverbActor`. Then create a handler of the actor using `BeginSound`, and use `SetInput` to direct a sound source through the reverberator. It is recommended to use `sleep` command after creating a ReverbActor handler or setting preset to give time for allocating memory and setup reverberator.

## ReverbActor messages

In addition to the messages understood by all generator actors, the ReverbActor understands the following messages:

SetMix `hActor x`
  Set the default reverberation mix for new instances createdby this actor to `x`. Valid range is [0,1].
SetAllMix `hActor x time`
  Set the reverberation mix of all children to `x`, and set the default effect mix for all future children. If `time` is specified, children will modulate to the new value over the specified duration. Default value is always set immediately regardless of time.
SetTime `hActor x`
  Set the default reverberation time for new instances created by this actor to `x`. Valid range is (0,1].
SetAllTime `hActor x time`
  Set the reverberation time of all children to `x`, and set the default value for all future children.
SetGain `hActor x`
  Set the default reverberation gain for new instances created by this actor to `x`. Valid range is (0,10].
SetAllGain `hActor x time`
  Set the reverberation gain of all children to `x`, and set the default value for all future children.
SetBright `hActor x`
  Set the default reverberation brightness for new instances created by this actor to `x`. Valid range is (0,1].
SetAllBright `hActor x time`
  Set the reverberation brightness of all children to `x`, and set the default value for all future children.
SetDampRatio `hActor x`
  Set the default damp ratio for new instances created by this actor to `x`. Valid range is [1,30].
SetAllDampRatio `hActor x time`
  Set the damp ratio of all children to `x`, and set the default value for all future children.
SetPole `hActor x`
  Set the default pole for new instances created by this actor to `x`. Valid range is [-0.5,0.5].
SetAllPole `hActor x time`
  Set the pole of all children to `x`, and set the default value for all future children.

## ReverbActor handler messages

In addition to the messages understood by all handlers, the handler for the ReverbActor understands the following messages:

SetIdle `hHandler boolean`
  Set the handler idle state, 1 is idle, 0 is not. An idle handler doesn't do anything except receiving messages until it is set not to be idle. SetIdle can be used to reduce ReverbActor's machine usage when it is not currently in use.
SetInput `hHandler` `hSound`
  Set the input to come through the handler `hHandler`.
SetPreset `hHandler x`
SetPresetNum `hHandler x`
SetPresetFile `hHandler x`
  Set this handler to use preset x. Available presets are described above. `SetPreset` accepts preset name Default, SmallRoom, Hall, Echo or Canyon. `SetPresetNum` accepts preset number 0 to 4. `SetPresetFile` accepts preset data file name. A sample data file is given.
SetMix `hHandler x time`
  Set the reverberation mix for this handler to x. If `time` is specified, move to the new value over the specified duration.
SetGain `hHandler` `x time`
  Set the reverberation gain for this handler to `x`. Valid range is (0,10].
SetTime `hHandler` `x time`
  Set the reverberation time for this handler to `x`. Valid range is (0,1].
SetBright `hHandler` `x time`
  Set the reverberation brightness for this handler to x. Valid range is (0,1].
SetDampRatio `hHandler` `x time`
  Set the damp ratio for this handler to x. Valid range is [1,30].
SetPole `hHandler` `x time`
  Set the pole for this handler to x. Valid range is [-0.5,0.5].
SetEarlyRefNum `hHandler` `x`
  Set the number of early reflections for this handler to x. Valid range is [0,6]. 0 will let sound through directly. If no early reflection delays and coefficients are specified afterwards, default values will be used.
SetEarlyRefDelay `hHandler` `[x1 x2 x3 ...]`
  Set the early reflection delays. Valid range is from [0.1,500](ms). The number of delays must agree with the number previously set by SetEarlyRefNum. If delays provided are less than the number of early reflections, default values will be used. If more, the first several ones will be taken.
SetEarlyRefCoeff `hHandler` `[x1 x2 x3 ...]`
  Set the early reflection coefficients. Valid range is [0,1]. The number of coefficients must agree with the number previously set by SetEarlyRefNum. If coefficients provided are less than the number of early reflections, default values will be used. If more, the first several ones will be taken.
SetCombNum `hHandler` `x`
  Set the number of comb filters for this handler to x. Valid range is [1,6].
SetCombDelay `hHandler` `[x1 x2 x3 ...]`
  Set the comb filter delays. Valid range is [0.1,100](ms). The number of delays must agree with the number previously set by SetCombNum. If delays provided are less than the number of comb filters, default values will be used. If more, the first several ones will be taken.
SetAllPassNum `hHandler` `x`
  Set the number of all-pass filters for this handler to x. Valid range is [0,3]. 0 will let sound through directly. If no all-pass delays are specified afterwards, default values will be used.
SetAllPassDelay `hHandler` `[x1 x2 x3 ...]`
  Set the all-pass filter delays. Valid range is [0.1,10](ms). The number of delays must agree with the number previously set by SetAllPassNum. If delays provided are less than the number of all-pass filters, default values will be used. If more, the first several ones will be taken.