/*
* Copyright (C) 2010 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.media.audiofx;
import android.media.audiofx.AudioEffect;
import android.util.Log;
import java.util.StringTokenizer;
/**
* An Equalizer is used to alter the frequency response of a particular music source or of the main
* output mix.
* <p>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.
* <p>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.
* <p>To attach the Equalizer to a particular AudioTrack or MediaPlayer, specify the audio session
* ID of this AudioTrack or MediaPlayer when constructing the Equalizer.
* <p>NOTE: attaching an Equalizer to the global audio output mix by use of session 0 is deprecated.
* <p>See {@link android.media.MediaPlayer#getAudioSessionId()} for details on audio sessions.
* <p>See {@link android.media.audiofx.AudioEffect} class for more details on controlling audio
* effects.
*/
public class Equalizer extends AudioEffect {
private final static String TAG = "Equalizer";
// These constants must be synchronized with those in
// frameworks/base/include/media/EffectEqualizerApi.h
/**
* Number of bands. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_NUM_BANDS = 0;
/**
* Band level range. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_LEVEL_RANGE = 1;
/**
* Band level. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_BAND_LEVEL = 2;
/**
* Band center frequency. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_CENTER_FREQ = 3;
/**
* Band frequency range. Parameter ID for
* {@link android.media.audiofx.Equalizer.OnParameterChangeListener}
*/
public static final int PARAM_BAND_FREQ_RANGE = 4;
/**
* Band for a given frequency. Parameter ID for OnParameterChangeListener
*
*/
public static final int PARAM_GET_BAND = 5;
/**
* Current preset. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_CURRENT_PRESET = 6;
/**
* Request number of presets. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_GET_NUM_OF_PRESETS = 7;
/**
* Request preset name. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_GET_PRESET_NAME = 8;
// used by setProperties()/getProperties
private static final int PARAM_PROPERTIES = 9;
/**
* Maximum size for preset name
*/
public static final int PARAM_STRING_SIZE_MAX = 32;
/**
* Number of bands implemented by Equalizer engine
*/
private short mNumBands = 0;
/**
* Number of presets implemented by Equalizer engine
*/
private int mNumPresets;
/**
* Names of presets implemented by Equalizer engine
*/
private String[] mPresetNames;
/**
* Registered listener for parameter changes.
*/
private OnParameterChangeListener mParamListener = null;
/**
* Listener used internally to to receive raw parameter change event from AudioEffect super class
*/
private BaseParameterListener mBaseParamListener = null;
/**
* Lock for access to mParamListener
*/
private final Object mParamListenerLock = new Object();
/**
* Class constructor.
* @param 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.
* @param audioSession system wide unique audio session identifier. The Equalizer will be
* attached to the MediaPlayer or AudioTrack in the same audio session.
*
* @throws java.lang.IllegalStateException
* @throws java.lang.IllegalArgumentException
* @throws java.lang.UnsupportedOperationException
* @throws java.lang.RuntimeException
*/
public Equalizer(int priority, int audioSession)
throws IllegalStateException, IllegalArgumentException,
UnsupportedOperationException, RuntimeException {
super(EFFECT_TYPE_EQUALIZER, EFFECT_TYPE_NULL, priority, audioSession);
if (audioSession == 0) {
Log.w(TAG, "WARNING: attaching an Equalizer to global output mix is deprecated!");
}
getNumberOfBands();
mNumPresets = (int)getNumberOfPresets();
if (mNumPresets != 0) {
mPresetNames = new String[mNumPresets];
byte[] value = new byte[PARAM_STRING_SIZE_MAX];
int[] param = new int[2];
param[0] = PARAM_GET_PRESET_NAME;
for (int i = 0; i < mNumPresets; i++) {
param[1] = i;
checkStatus(getParameter(param, value));
int length = 0;
while (value[length] != 0) length++;
try {
mPresetNames[i] = new String(value, 0, length, "ISO-8859-1");
} catch (java.io.UnsupportedEncodingException e) {
Log.e(TAG, "preset name decode error");
}
}
}
}
/**
* Gets the number of frequency bands supported by the Equalizer engine.
* @return the number of bands
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short getNumberOfBands()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
if (mNumBands != 0) {
return mNumBands;
}
int[] param = new int[1];
param[0] = PARAM_NUM_BANDS;
short[] result = new short[1];
checkStatus(getParameter(param, result));
mNumBands = result[0];
return mNumBands;
}
/**
* Gets the level range for use by {@link #setBandLevel(short,short)}. The level is expressed in
* milliBel.
* @return 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
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short[] getBandLevelRange()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
short[] result = new short[2];
checkStatus(getParameter(PARAM_LEVEL_RANGE, result));
return result;
}
/**
* Sets the given equalizer band to the given gain value.
* @param band frequency band that will have the new gain. The numbering of the bands starts
* from 0 and ends at (number of bands - 1).
* @param level new gain in millibels that will be set to the given band. getBandLevelRange()
* will define the maximum and minimum values.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
* @see #getNumberOfBands()
*/
public void setBandLevel(short band, short level)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
int[] param = new int[2];
short[] value = new short[1];
param[0] = PARAM_BAND_LEVEL;
param[1] = (int)band;
value[0] = level;
checkStatus(setParameter(param, value));
}
/**
* Gets the gain set for the given equalizer band.
* @param band frequency band whose gain is requested. The numbering of the bands starts
* from 0 and ends at (number of bands - 1).
* @return the gain in millibels of the given band.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short getBandLevel(short band)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
int[] param = new int[2];
short[] result = new short[1];
param[0] = PARAM_BAND_LEVEL;
param[1] = (int)band;
checkStatus(getParameter(param, result));
return result[0];
}
/**
* Gets the center frequency of the given band.
* @param band frequency band whose center frequency is requested. The numbering of the bands
* starts from 0 and ends at (number of bands - 1).
* @return the center frequency in milliHertz
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public int getCenterFreq(short band)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
int[] param = new int[2];
int[] result = new int[1];
param[0] = PARAM_CENTER_FREQ;
param[1] = (int)band;
checkStatus(getParameter(param, result));
return result[0];
}
/**
* Gets the frequency range of the given frequency band.
* @param band frequency band whose frequency range is requested. The numbering of the bands
* starts from 0 and ends at (number of bands - 1).
* @return 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
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public int[] getBandFreqRange(short band)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
int[] param = new int[2];
int[] result = new int[2];
param[0] = PARAM_BAND_FREQ_RANGE;
param[1] = (int)band;
checkStatus(getParameter(param, result));
return result;
}
/**
* Gets the band that has the most effect on the given frequency.
* @param frequency frequency in milliHertz which is to be equalized via the returned band.
* @return the frequency band that has most effect on the given frequency.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short getBand(int frequency)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
int[] param = new int[2];
short[] result = new short[1];
param[0] = PARAM_GET_BAND;
param[1] = frequency;
checkStatus(getParameter(param, result));
return result[0];
}
/**
* Gets current preset.
* @return the preset that is set at the moment.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short getCurrentPreset()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
short[] result = new short[1];
checkStatus(getParameter(PARAM_CURRENT_PRESET, result));
return result[0];
}
/**
* Sets the equalizer according to the given preset.
* @param preset new preset that will be taken into use. The valid range is [0,
* number of presets-1].
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
* @see #getNumberOfPresets()
*/
public void usePreset(short preset)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
checkStatus(setParameter(PARAM_CURRENT_PRESET, preset));
}
/**
* Gets the total number of presets the equalizer supports. The presets will have indices
* [0, number of presets-1].
* @return the number of presets the equalizer supports.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short getNumberOfPresets()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
short[] result = new short[1];
checkStatus(getParameter(PARAM_GET_NUM_OF_PRESETS, result));
return result[0];
}
/**
* Gets the preset name based on the index.
* @param preset index of the preset. The valid range is [0, number of presets-1].
* @return a string containing the name of the given preset.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public String getPresetName(short preset)
{
if (preset >= 0 && preset < mNumPresets) {
return mPresetNames[preset];
} else {
return "";
}
}
/**
* The OnParameterChangeListener interface defines a method called by the Equalizer when a
* parameter value has changed.
*/
public interface OnParameterChangeListener {
/**
* Method called when a parameter value has changed. The method is called only if the
* parameter was changed by another application having the control of the same
* Equalizer engine.
* @param effect the Equalizer on which the interface is registered.
* @param status status of the set parameter operation.
* @param param1 ID of the modified parameter. See {@link #PARAM_BAND_LEVEL} ...
* @param param2 additional parameter qualifier (e.g the band for band level parameter).
* @param value the new parameter value.
*/
void onParameterChange(Equalizer effect, int status, int param1, int param2, int value);
}
/**
* Listener used internally to receive unformatted parameter change events from AudioEffect
* super class.
*/
private class BaseParameterListener implements AudioEffect.OnParameterChangeListener {
private BaseParameterListener() {
}
public void onParameterChange(AudioEffect effect, int status, byte[] param, byte[] value) {
OnParameterChangeListener l = null;
synchronized (mParamListenerLock) {
if (mParamListener != null) {
l = mParamListener;
}
}
if (l != null) {
int p1 = -1;
int p2 = -1;
int v = -1;
if (param.length >= 4) {
p1 = byteArrayToInt(param, 0);
if (param.length >= 8) {
p2 = byteArrayToInt(param, 4);
}
}
if (value.length == 2) {
v = (int)byteArrayToShort(value, 0);;
} else if (value.length == 4) {
v = byteArrayToInt(value, 0);
}
if (p1 != -1 && v != -1) {
l.onParameterChange(Equalizer.this, status, p1, p2, v);
}
}
}
}
/**
* Registers an OnParameterChangeListener interface.
* @param listener OnParameterChangeListener interface registered
*/
public void setParameterListener(OnParameterChangeListener listener) {
synchronized (mParamListenerLock) {
if (mParamListener == null) {
mParamListener = listener;
mBaseParamListener = new BaseParameterListener();
super.setParameterListener(mBaseParamListener);
}
}
}
/**
* The Settings class regroups all equalizer parameters. It is used in
* conjuntion with getProperties() and setProperties() methods to backup and restore
* all parameters in a single call.
*/
public static class Settings {
public short curPreset;
public short numBands = 0;
public short[] bandLevels = null;
public Settings() {
}
/**
* Settings class constructor from a key=value; pairs formatted string. The string is
* typically returned by Settings.toString() method.
* @throws IllegalArgumentException if the string is not correctly formatted.
*/
public Settings(String settings) {
StringTokenizer st = new StringTokenizer(settings, "=;");
int tokens = st.countTokens();
if (st.countTokens() < 5) {
throw new IllegalArgumentException("settings: " + settings);
}
String key = st.nextToken();
if (!key.equals("Equalizer")) {
throw new IllegalArgumentException(
"invalid settings for Equalizer: " + key);
}
try {
key = st.nextToken();
if (!key.equals("curPreset")) {
throw new IllegalArgumentException("invalid key name: " + key);
}
curPreset = Short.parseShort(st.nextToken());
key = st.nextToken();
if (!key.equals("numBands")) {
throw new IllegalArgumentException("invalid key name: " + key);
}
numBands = Short.parseShort(st.nextToken());
if (st.countTokens() != numBands*2) {
throw new IllegalArgumentException("settings: " + settings);
}
bandLevels = new short[numBands];
for (int i = 0; i < numBands; i++) {
key = st.nextToken();
if (!key.equals("band"+(i+1)+"Level")) {
throw new IllegalArgumentException("invalid key name: " + key);
}
bandLevels[i] = Short.parseShort(st.nextToken());
}
} catch (NumberFormatException nfe) {
throw new IllegalArgumentException("invalid value for key: " + key);
}
}
@Override
public String toString() {
String str = new String (
"Equalizer"+
";curPreset="+Short.toString(curPreset)+
";numBands="+Short.toString(numBands)
);
for (int i = 0; i < numBands; i++) {
str = str.concat(";band"+(i+1)+"Level="+Short.toString(bandLevels[i]));
}
return str;
}
};
/**
* Gets the equalizer properties. This method is useful when a snapshot of current
* equalizer settings must be saved by the application.
* @return an Equalizer.Settings object containing all current parameters values
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public Equalizer.Settings getProperties()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
byte[] param = new byte[4 + mNumBands * 2];
checkStatus(getParameter(PARAM_PROPERTIES, param));
Settings settings = new Settings();
settings.curPreset = byteArrayToShort(param, 0);
settings.numBands = byteArrayToShort(param, 2);
settings.bandLevels = new short[mNumBands];
for (int i = 0; i < mNumBands; i++) {
settings.bandLevels[i] = byteArrayToShort(param, 4 + 2*i);
}
return settings;
}
/**
* Sets the equalizer properties. This method is useful when equalizer settings have to
* be applied from a previous backup.
* @param settings an Equalizer.Settings object containing the properties to apply
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public void setProperties(Equalizer.Settings settings)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
if (settings.numBands != settings.bandLevels.length ||
settings.numBands != mNumBands) {
throw new IllegalArgumentException("settings invalid band count: " +settings.numBands);
}
byte[] param = concatArrays(shortToByteArray(settings.curPreset),
shortToByteArray(mNumBands));
for (int i = 0; i < mNumBands; i++) {
param = concatArrays(param,
shortToByteArray(settings.bandLevels[i]));
}
checkStatus(setParameter(PARAM_PROPERTIES, param));
}
}
|
