/*
* 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;
/**
* Bass boost is an audio effect to boost or amplify low frequencies of the sound. It is comparable
* to a simple equalizer but limited to one band amplification in the low frequency range.
* <p>An application creates a BassBoost object to instantiate and control a bass boost engine in
* the audio framework.
* <p>The methods, parameter types and units exposed by the BassBoost implementation are directly
* mapping those defined by the OpenSL ES 1.0.1 Specification (http://www.khronos.org/opensles/)
* for the SLBassBoostItf interface. Please refer to this specification for more details.
* <p>To attach the BassBoost to a particular AudioTrack or MediaPlayer, specify the audio session
* ID of this AudioTrack or MediaPlayer when constructing the BassBoost.
* <p>NOTE: attaching a BassBoost 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 BassBoost extends AudioEffect {
private final static String TAG = "BassBoost";
// These constants must be synchronized with those in
// frameworks/base/include/media/EffectBassBoostApi.h
/**
* Is strength parameter supported by bass boost engine. Parameter ID for getParameter().
*/
public static final int PARAM_STRENGTH_SUPPORTED = 0;
/**
* Bass boost effect strength. Parameter ID for
* {@link android.media.audiofx.BassBoost.OnParameterChangeListener}
*/
public static final int PARAM_STRENGTH = 1;
/**
* Indicates if strength parameter is supported by the bass boost engine
*/
private boolean mStrengthSupported = false;
/**
* 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 BassBoost
* 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 BassBoost 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 BassBoost(int priority, int audioSession)
throws IllegalStateException, IllegalArgumentException,
UnsupportedOperationException, RuntimeException {
super(EFFECT_TYPE_BASS_BOOST, EFFECT_TYPE_NULL, priority, audioSession);
if (audioSession == 0) {
Log.w(TAG, "WARNING: attaching a BassBoost to global output mix is deprecated!");
}
int[] value = new int[1];
checkStatus(getParameter(PARAM_STRENGTH_SUPPORTED, value));
mStrengthSupported = (value[0] != 0);
}
/**
* Indicates whether setting strength is supported. If this method returns false, only one
* strength is supported and the setStrength() method always rounds to that value.
* @return true is strength parameter is supported, false otherwise
*/
public boolean getStrengthSupported() {
return mStrengthSupported;
}
/**
* Sets the strength of the bass boost effect. If the implementation does not support per mille
* accuracy for setting the strength, it is allowed to round the given strength to the nearest
* supported value. You can use the {@link #getRoundedStrength()} method to query the
* (possibly rounded) value that was actually set.
* @param strength strength of the effect. The valid range for strength strength is [0, 1000],
* where 0 per mille designates the mildest effect and 1000 per mille designates the strongest.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public void setStrength(short strength)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
checkStatus(setParameter(PARAM_STRENGTH, strength));
}
/**
* Gets the current strength of the effect.
* @return the strength of the effect. The valid range for strength is [0, 1000], where 0 per
* mille designates the mildest effect and 1000 per mille the strongest
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public short getRoundedStrength()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
short[] value = new short[1];
checkStatus(getParameter(PARAM_STRENGTH, value));
return value[0];
}
/**
* The OnParameterChangeListener interface defines a method called by the BassBoost 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
* BassBoost engine.
* @param effect the BassBoost on which the interface is registered.
* @param status status of the set parameter operation.
* @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ...
* @param value the new parameter value.
*/
void onParameterChange(BassBoost effect, int status, int param, short 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 p = -1;
short v = -1;
if (param.length == 4) {
p = byteArrayToInt(param, 0);
}
if (value.length == 2) {
v = byteArrayToShort(value, 0);
}
if (p != -1 && v != -1) {
l.onParameterChange(BassBoost.this, status, p, 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 bass boost 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 strength;
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() != 3) {
throw new IllegalArgumentException("settings: " + settings);
}
String key = st.nextToken();
if (!key.equals("BassBoost")) {
throw new IllegalArgumentException(
"invalid settings for BassBoost: " + key);
}
try {
key = st.nextToken();
if (!key.equals("strength")) {
throw new IllegalArgumentException("invalid key name: " + key);
}
strength = Short.parseShort(st.nextToken());
} catch (NumberFormatException nfe) {
throw new IllegalArgumentException("invalid value for key: " + key);
}
}
@Override
public String toString() {
String str = new String (
"BassBoost"+
";strength="+Short.toString(strength)
);
return str;
}
};
/**
* Gets the bass boost properties. This method is useful when a snapshot of current
* bass boost settings must be saved by the application.
* @return a BassBoost.Settings object containing all current parameters values
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public BassBoost.Settings getProperties()
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
Settings settings = new Settings();
short[] value = new short[1];
checkStatus(getParameter(PARAM_STRENGTH, value));
settings.strength = value[0];
return settings;
}
/**
* Sets the bass boost properties. This method is useful when bass boost settings have to
* be applied from a previous backup.
* @param settings a BassBoost.Settings object containing the properties to apply
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
*/
public void setProperties(BassBoost.Settings settings)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
checkStatus(setParameter(PARAM_STRENGTH, settings.strength));
}
}
|
