javax.microedition.amms.control.audioeffect
Interface EqualizerControl

All Superinterfaces:

EffectControl, Control

public interface EqualizerControl
extends EffectControl

EqualizerControl is an audio EffectControl for manipulating the equalization settings of a Player(s). Equalizers (EQ) are usually used for two reasons: to compensate an unideal frequency response of a system to make it sound more natural or to create intentionally some unnatural coloring to the sound to create an effect. The equalizer in this API serves both of these purposes.

Equalizer Settings

This interface allows the sound source to be filtered with an equalizer. The equalizer can be set up in three different ways: using presets, using bass and treble controls, or by setting individual frequency bands by hand.

The preset settings can directly be taken into use with the method setPreset. The current preset can be queried with the method getPreset. If none of the presets is set, null will be returned. null will also be returned when a preset has been set, but the equalizer settings have been altered later with setBandLevel, setBass, or setTreble.

There are convenient methods, setBass and setTreble, for altering the bass or treble only without the need to specify any frequencies. setBass and setTreble reset the current set-up on the band in question (bass or treble frequencies respectively). There are also methods for asking the current bass and treble setting (getBass and getTreble), but if the equalizer settings have been altered after the bass and treble set-up by setting presets or altering individual EQ-bands, the bass and treble settings are not anymore unambiguously defined and EqualizerControl.UNDEFINED will be returned.

There are also methods for getting and setting individual EQ-band gains (setBandLevel and getBandLevel) and methods for asking the number of the EQ-bands available (getNumberOfBands) or their center frequencies (getCenterFreq). People who are more familiar with EQ are able to create effects or to compensate the response of the system with these methods.

The gains in this class are defined in millibels (hundredths of decibel), but it has to be understood that many devices contain a dynamic range control (DRC) system that will affect the actual effect and therefore, the value in millibels will affect as a guideline rather than as a strict rule.

See Also:

Control, Player

Since:

BlackBerry API 5.0.0

Field Summary
static int	UNDEFINED

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

SCOPE_LIVE_AND_RECORD, SCOPE_LIVE_ONLY, SCOPE_RECORD_ONLY

Method Summary
int	getBand(int frequency) Gets the band that has the most effect on the given frequency.
int	getBandLevel(int band) Gets the gain set for the given equalizer band.
int	getBass() Gets the bass level.
int	getCenterFreq(int band) Gets the center frequency of the given band.
int	getMaxBandLevel()
int	getMinBandLevel()
int	getNumberOfBands() Gets the number of frequency bands that the equalizer supports.
int	getTreble() Gets the treble level.
void	setBandLevel(int level, int band) Sets the given equalizer band to the given gain value.
int	setBass(int level) Sets the bass level using a linear point scale with values between 0 and 100: a value of 0 applies the maximum available attenuation to frequencies in the bass band; a value of 50 gives a flat equalization of the bass band; and a value of 100 applies the maximum available amplification to frequencies in the bass band.
int	setTreble(int level) Sets the treble level using a linear point scale with values between 0 and 100: a value of 0 applies the maximum available attenuation to frequencies in the treble band; a value of 50 gives a flat equalization of the treble band; and a value of 100 applies the maximum available amplification to frequencies in the treble band.

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

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

Field Detail

UNDEFINED

static final int UNDEFINED

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Method Detail

getMinBandLevel

int getMinBandLevel()

Returns:

the minimum band level in millibels

Since:

BlackBerry API 5.0.0

getMaxBandLevel

int getMaxBandLevel()

Returns:

the maximum band level in millibels

Since:

BlackBerry API 5.0.0

setBandLevel

void setBandLevel(int level,
                  int band)
                  throws IllegalArgumentException

Sets the given equalizer band to the given gain value.

Parameters:

level - the new gain in millibels that will be set to the given band. getMinBandLevel() and getMaxBandLevel() will define the maximum and minimum values.

band - the frequency band that will have the new gain. The numbering of the bands starts from 0 and ends at (getNumberOfBands() - 1).

Throws:

IllegalArgumentException - when the given band or level is out of range

Since:

BlackBerry API 5.0.0

getBandLevel

int getBandLevel(int band)
                 throws IllegalArgumentException

Gets the gain set for the given equalizer band.

Parameters:

band - @return the gain set for the given band in millibels the frequency band whose gain is asked. The numbering of the bands starts from 0 and ends at (getNumberOfBands() - 1).

Throws:

IllegalArgumentException - when the given band is out of range

Since:

BlackBerry API 5.0.0

getNumberOfBands

int getNumberOfBands()

Gets the number of frequency bands that the equalizer supports. A valid equalizer MUST have at least two bands.

Returns:

the number of frequency bands that the equalizer supports

Since:

BlackBerry API 5.0.0

getCenterFreq

int getCenterFreq(int band)
                  throws IllegalArgumentException

Gets the center frequency of the given band.

Parameters:

band - @return the center frequency in milliHertz the frequency band whose center frequency is asked. The numbering of the bands starts from 0 and ends at (getNumberOfBands() - 1).

Throws:

IllegalArgumentException - when the given band does not exist

Since:

BlackBerry API 5.0.0

getBand

int getBand(int frequency)

Gets the band that has the most effect on the given frequency. If no band has effect on the given frequency, -1 is returned.

Parameters:

frequency - @return the frequency band that has most effect on the given frequency or -1 if no band has effect on the given frequencythe frequency in milliHertz which is to be equalized via the returned band

Since:

BlackBerry API 5.0.0

setBass

int setBass(int level)
            throws IllegalArgumentException

Sets the bass level using a linear point scale with values between 0 and 100: a value of 0 applies the maximum available attenuation to frequencies in the bass band; a value of 50 gives a flat equalization of the bass band; and a value of 100 applies the maximum available amplification to frequencies in the bass band. All the previous settings will be lost on the bass band.

Parameters:

level - @return the level that was actually set the new level on a linear point scale that will be set to the bass band

Throws:

IllegalArgumentException - when the given level is below 0 or above 100

Since:

BlackBerry API 5.0.0

setTreble

int setTreble(int level)
              throws IllegalArgumentException

Sets the treble level using a linear point scale with values between 0 and 100: a value of 0 applies the maximum available attenuation to frequencies in the treble band; a value of 50 gives a flat equalization of the treble band; and a value of 100 applies the maximum available amplification to frequencies in the treble band. All the previous settings will be lost on the treble band.

Parameters:

level - @return the level that was actually set the new level on a linear point scale that will be set to the treble band

Throws:

IllegalArgumentException - when the given level is below 0 or above 100

Since:

BlackBerry API 5.0.0

getBass

int getBass()

Gets the bass level.

Returns:

the current level that is set to the bass band. If the bass level cannot been defined EqualizerControl.UNDEFINED will be returned.

Since:

BlackBerry API 5.0.0

getTreble

int getTreble()

Gets the treble level.

Returns:

the current level that is set to the treble band. If the treble level cannot been defined EqualizerControl.UNDEFINED will be returned.

Since:

BlackBerry API 5.0.0