public class

Equalizer

extends AudioEffect
java.lang.Object
   ↳ android.media.audiofx.AudioEffect
     ↳ android.media.audiofx.Equalizer

Class Overview

An Equalizer is used to alter the frequency response of a particular music source or of the main output mix.

An application creates an Equalizer object to instantiate and control an Equalizer engine in the audio framework. The application can either simply use predefined presets or have a more precise control of the gain in each frequency band controlled by the equalizer.

The methods, parameter types and units exposed by the Equalizer implementation are directly mapping those defined by the OpenSL ES 1.0.1 Specification (http://www.khronos.org/opensles/) for the SLEqualizerItf interface. Please refer to this specification for more details.

To attach the Equalizer to a particular AudioTrack or MediaPlayer, specify the audio session ID of this AudioTrack or MediaPlayer when constructing the Equalizer. If the audio session ID 0 is specified, the Equalizer applies to the main audio output mix.

Creating an Equalizer on the output mix (audio session 0) requires permission MODIFY_AUDIO_SETTINGS

See getAudioSessionId() for details on audio sessions.

See AudioEffect class for more details on controlling audio effects.

Summary

Nested Classes
interface Equalizer.OnParameterChangeListener The OnParameterChangeListener interface defines a method called by the Equalizer when a parameter value has changed. 
class Equalizer.Settings The Settings class regroups all equalizer parameters. 
Constants
int PARAM_BAND_FREQ_RANGE Band frequency range.
int PARAM_BAND_LEVEL Band level.
int PARAM_CENTER_FREQ Band center frequency.
int PARAM_CURRENT_PRESET Current preset.
int PARAM_GET_BAND Band for a given frequency.
int PARAM_GET_NUM_OF_PRESETS Request number of presets.
int PARAM_GET_PRESET_NAME Request preset name.
int PARAM_LEVEL_RANGE Band level range.
int PARAM_NUM_BANDS Number of bands.
int PARAM_STRING_SIZE_MAX Maximum size for preset name
[Expand]
Inherited Constants
From class android.media.audiofx.AudioEffect
Public Constructors
Equalizer(int priority, int audioSession)
Class constructor.
Public Methods
short getBand(int frequency)
Gets the band that has the most effect on the given frequency.
int[] getBandFreqRange(short band)
Gets the frequency range of the given frequency band.
short getBandLevel(short band)
Gets the gain set for the given equalizer band.
short[] getBandLevelRange()
Gets the level range for use by setBandLevel(short, short).
int getCenterFreq(short band)
Gets the center frequency of the given band.
short getCurrentPreset()
Gets current preset.
short getNumberOfBands()
Gets the number of frequency bands supported by the Equalizer engine.
short getNumberOfPresets()
Gets the total number of presets the equalizer supports.
String getPresetName(short preset)
Gets the preset name based on the index.
Equalizer.Settings getProperties()
Gets the equalizer properties.
void setBandLevel(short band, short level)
Sets the given equalizer band to the given gain value.
void setParameterListener(Equalizer.OnParameterChangeListener listener)
Registers an OnParameterChangeListener interface.
void setProperties(Equalizer.Settings settings)
Sets the equalizer properties.
void usePreset(short preset)
Sets the equalizer according to the given preset.
[Expand]
Inherited Methods
From class android.media.audiofx.AudioEffect
From class java.lang.Object

Constants

public static final int PARAM_BAND_FREQ_RANGE

Since: API Level 9

Band frequency range. Parameter ID for Equalizer.OnParameterChangeListener

Constant Value: 4 (0x00000004)

public static final int PARAM_BAND_LEVEL

Since: API Level 9

Band level. Parameter ID for OnParameterChangeListener

Constant Value: 2 (0x00000002)

public static final int PARAM_CENTER_FREQ

Since: API Level 9

Band center frequency. Parameter ID for OnParameterChangeListener

Constant Value: 3 (0x00000003)

public static final int PARAM_CURRENT_PRESET

Since: API Level 9

Current preset. Parameter ID for OnParameterChangeListener

Constant Value: 6 (0x00000006)

public static final int PARAM_GET_BAND

Since: API Level 9

Band for a given frequency. Parameter ID for OnParameterChangeListener

Constant Value: 5 (0x00000005)

public static final int PARAM_GET_NUM_OF_PRESETS

Since: API Level 9

Request number of presets. Parameter ID for OnParameterChangeListener

Constant Value: 7 (0x00000007)

public static final int PARAM_GET_PRESET_NAME

Since: API Level 9

Request preset name. Parameter ID for OnParameterChangeListener

Constant Value: 8 (0x00000008)

public static final int PARAM_LEVEL_RANGE

Since: API Level 9

Band level range. Parameter ID for OnParameterChangeListener

Constant Value: 1 (0x00000001)

public static final int PARAM_NUM_BANDS

Since: API Level 9

Number of bands. Parameter ID for OnParameterChangeListener

Constant Value: 0 (0x00000000)

public static final int PARAM_STRING_SIZE_MAX

Since: API Level 9

Maximum size for preset name

Constant Value: 32 (0x00000020)

Public Constructors

public Equalizer (int priority, int audioSession)

Since: API Level 9

Class constructor.

Parameters
priority the priority level requested by the application for controlling the Equalizer engine. As the same engine can be shared by several applications, this parameter indicates how much the requesting application needs control of effect parameters. The normal priority is 0, above normal is a positive number, below normal a negative number.
audioSession system wide unique audio session identifier. If audioSession is not 0, the Equalizer will be attached to the MediaPlayer or AudioTrack in the same audio session. Otherwise, the Equalizer will apply to the output mix.
Throws
java.lang.IllegalStateException
java.lang.IllegalArgumentException
java.lang.UnsupportedOperationException
RuntimeException
IllegalStateException
IllegalArgumentException
UnsupportedOperationException

Public Methods

public short getBand (int frequency)

Since: API Level 9

Gets the band that has the most effect on the given frequency.

Parameters
frequency frequency in milliHertz which is to be equalized via the returned band.
Returns
  • the frequency band that has most effect on the given frequency.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public int[] getBandFreqRange (short band)

Since: API Level 9

Gets the frequency range of the given frequency band.

Parameters
band frequency band whose frequency range is requested. The numbering of the bands starts from 0 and ends at (number of bands - 1).
Returns
  • the frequency range in millHertz in an array of integers. The first element is the lower limit of the range, the second element the upper limit.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public short getBandLevel (short band)

Since: API Level 9

Gets the gain set for the given equalizer band.

Parameters
band frequency band whose gain is requested. The numbering of the bands starts from 0 and ends at (number of bands - 1).
Returns
  • the gain in millibels of the given band.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public short[] getBandLevelRange ()

Since: API Level 9

Gets the level range for use by setBandLevel(short, short). The level is expressed in milliBel.

Returns
  • the band level range in an array of short integers. The first element is the lower limit of the range, the second element the upper limit.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public int getCenterFreq (short band)

Since: API Level 9

Gets the center frequency of the given band.

Parameters
band frequency band whose center frequency is requested. The numbering of the bands starts from 0 and ends at (number of bands - 1).
Returns
  • the center frequency in milliHertz
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public short getCurrentPreset ()

Since: API Level 9

Gets current preset.

Returns
  • the preset that is set at the moment.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public short getNumberOfBands ()

Since: API Level 9

Gets the number of frequency bands supported by the Equalizer engine.

Returns
  • the number of bands
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public short getNumberOfPresets ()

Since: API Level 9

Gets the total number of presets the equalizer supports. The presets will have indices [0, number of presets-1].

Returns
  • the number of presets the equalizer supports.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public String getPresetName (short preset)

Since: API Level 9

Gets the preset name based on the index.

Parameters
preset index of the preset. The valid range is [0, number of presets-1].
Returns
  • a string containing the name of the given preset.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException

public Equalizer.Settings getProperties ()

Since: API Level 9

Gets the equalizer properties. This method is useful when a snapshot of current equalizer settings must be saved by the application.

Returns
  • an Equalizer.Settings object containing all current parameters values
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public void setBandLevel (short band, short level)

Since: API Level 9

Sets the given equalizer band to the given gain value.

Parameters
band frequency band that will have the new gain. The numbering of the bands starts from 0 and ends at (number of bands - 1).
level new gain in millibels that will be set to the given band. getBandLevelRange() will define the maximum and minimum values.
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
See Also

public void setParameterListener (Equalizer.OnParameterChangeListener listener)

Since: API Level 9

Registers an OnParameterChangeListener interface.

Parameters
listener OnParameterChangeListener interface registered

public void setProperties (Equalizer.Settings settings)

Since: API Level 9

Sets the equalizer properties. This method is useful when equalizer settings have to be applied from a previous backup.

Parameters
settings an Equalizer.Settings object containing the properties to apply
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException

public void usePreset (short preset)

Since: API Level 9

Sets the equalizer according to the given preset.

Parameters
preset new preset that will be taken into use. The valid range is [0, number of presets-1].
Throws
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
IllegalStateException
IllegalArgumentException
UnsupportedOperationException
See Also