javax.microedition.amms.control.audioeffect
Interface ReverbControl

All Superinterfaces:

EffectControl, Control

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.

See Also:

EffectControl,

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" presetsalley arena auditorium bathroom cave hallway hangar livingroom mountains room underwater Mandatory "musical" presetssmallroom mediumroom largeroom mediumhall largehall plate

Additionally, there are some presets defined that might be available: Other "environmental" presetscarpetedhallway city concerthall forest paddedcell parkinglot plain quarry sewerpipe stonecorridor stoneroom

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

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.)

Since:

BlackBerry API 5.0.0

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

int setReverbLevel(int level)
                   throws 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 - @return the value that was actually set the new level of the reverberation in millibels

Throws:

IllegalArgumentException - if the given value is greater than 0

Since:

BlackBerry API 5.0.0

getReverbLevel

int getReverbLevel()

Gets the gain level of the reverberation.

Returns:

the level of the reverberation in millibels

Since:

BlackBerry API 5.0.0

setReverbTime

void setReverbTime(int time)
                   throws IllegalArgumentException,
                          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:

IllegalArgumentException - when the given time is negative

MediaException - if the changing of the reverb time is not supported

Since:

BlackBerry API 5.0.0

getReverbTime

int getReverbTime()
                  throws 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:

MediaException - if querying the reverb time is not supported

Since:

BlackBerry API 5.0.0