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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.