javax.microedition.amms.control.audioeffect
Interface ReverbControl

All Superinterfaces:

javax.microedition.media.Control, EffectControl

public interface ReverbControl

extends EffectControl

ReverbControl is an interface for manipulating the settings of an audio effect called reverb. A ReverbControl can only be fetched from the GlobalManager and/or MediaProcessor (if ReverbControl is supported at all).

Reverb

Reverberation is essential in perceiving the properties of the room. Mainly, it tells the size of the room and gives some hints about the wall materials.

Presets and Parameters

In the API, there are several preset modes available for reverberation. A subset of the modes from "IA-SIG Interactive 3D Audio Rendering Guidelines (Level 2)" is used. The modes at least available for the reverb are:

Mandatory "environmental" presets

• alley
• arena
• auditorium
• bathroom
• cave
• hallway
• hangar
• livingroom
• mountains
• room
• underwater

Mandatory "musical" presets

• smallroom
• mediumroom
• largeroom
• mediumhall
• largehall
• plate

Additionally, there are some presets defined that might be available:

Other "environmental" presets

• carpetedhallway
• city
• concerthall
• forest
• paddedcell
• parkinglot
• plain
• quarry
• sewerpipe
• stonecorridor
• stoneroom

A preset can be chosen using the (inherited) method EffectControl.setPreset.

Parameters

The preset modes are tunable with two parameters, the reverberation time and the reverberation level. The reverberation time controls how long the reverberation appears to last after the sound source becomes silent. The reverberation level controls how loud the reverberation appears to be compared to the direct path signal of the sound source (before obstruction effects are applied).

Both parameters have a default value for every preset reverberation mode and then the user can, for example, make the preset room more reverberant by raising the values. Methods for setting and getting the reverberation time are setReverbTime and getReverbTime. Similarly, setReverbLevel and getReverbLevel are used for the reverberation level. It is recommended to first get the value of the preset, then scale it, and finally set the new, scaled value. setReverbLevel and setReverbTime invalidate the current preset regardless of their arguments.

NOTE: The reverb level and the reverb decay times can only be used to modify existing reverb presets. They cannot be used to morph between reverb presets. This is because reverb presets typically contain additional internal properties.

Default Values

"smallroom" is the default preset. (The default reverb level and reverb time are implementation-dependent.)

See Also:

EffectControl, ReverbSourceControl

Field Summary

Fields inherited from interface javax.microedition.amms.control.EffectControl

SCOPE_LIVE_AND_RECORD, SCOPE_LIVE_ONLY, SCOPE_RECORD_ONLY

Method Summary

int	getReverbLevel() Gets the gain level of the reverberation.
int	getReverbTime() Gets the reverberation time, as set either explicitly via setReverbTime or implicitly via setPreset (whichever was called last).
int	setReverbLevel(int level) Sets the gain level of the reverberation.
void	setReverbTime(int time) Sets the reverberation time of the reverb.

Methods inherited from interface javax.microedition.amms.control.EffectControl

getPreset, getPresetNames, getScope, isEnabled, isEnforced, setEnabled, setEnforced, setPreset, setScope

Method Detail

setReverbLevel

public int setReverbLevel(int level)
                   throws java.lang.IllegalArgumentException

Sets the gain level of the reverberation. The value defines what is the relative level of the first reflections compared to the sound source without possible distance attenuations, directivities or obstructions taken into account.

Parameters:

level - the new level of the reverberation in millibels

Returns:

the value that was actually set

Throws:

java.lang.IllegalArgumentException - if the given value is greater than 0

See Also:

getReverbLevel()

getReverbLevel

public int getReverbLevel()

Gets the gain level of the reverberation.

Returns:

the level of the reverberation in millibels

See Also:

setReverbLevel(int)

setReverbTime

public void setReverbTime(int time)
                   throws java.lang.IllegalArgumentException,
                          javax.microedition.media.MediaException

Sets the reverberation time of the reverb. The reverberation time is the time taken for the reverberant sound to attenuate by 60 dB from its initial level. Typical values are in the range from 100 to 20000 milliseconds.

The implementation might not support long reverberation times. Therefore, the actual time used might be shorter than the time specified with this method.

Parameters:

time - new reverberation time in milliseconds

Throws:

java.lang.IllegalArgumentException - when the given time is negative

javax.microedition.media.MediaException - if the changing of the reverb time is not supported

getReverbTime

public int getReverbTime()
                  throws javax.microedition.media.MediaException

Gets the reverberation time, as set either explicitly via setReverbTime or implicitly via setPreset (whichever was called last). If neither of these methods has been called, getReverbTime returns the default reverberation time (that corresponding to "smallroom").

Returns:

the current reverberation time in milliseconds

Throws:

javax.microedition.media.MediaException - if querying the reverb time is not supported