public class AudioEffect extends Object
Applications should not use the AudioEffect class directly but one of its derived classes to control specific effects:
To apply the audio effect to a specific AudioTrack or MediaPlayer instance,
the application must specify the audio session ID of that instance when creating the AudioEffect.
(see MediaPlayer.getAudioSessionId()
for details on audio sessions).
NOTE: attaching insert effects (equalizer, bass boost, virtualizer) to the global audio output mix by use of session 0 is deprecated.
Creating an AudioEffect object will create the corresponding effect engine in the audio framework if no instance of the same effect type exists in the specified audio session. If one exists, this instance will be used.
The application creating the AudioEffect object (or a derived class) will either receive control of the effect engine or not depending on the priority parameter. If priority is higher than the priority used by the current effect engine owner, the control will be transfered to the new object. Otherwise control will remain with the previous object. In this case, the new application will be notified of changes in effect engine state or control ownership by the appropriate listener.
Modifier and Type | Class and Description |
---|---|
static class |
AudioEffect.Descriptor
The effect descriptor contains information on a particular effect implemented in the
audio framework:
type: UUID identifying the effect type. |
static interface |
AudioEffect.OnControlStatusChangeListener
The OnControlStatusChangeListener interface defines a method called by the AudioEffect
when a the control of the effect engine is gained or lost by the application
|
static interface |
AudioEffect.OnEnableStatusChangeListener
The OnEnableStatusChangeListener interface defines a method called by the AudioEffect
when a the enabled state of the effect engine was changed by the controlling application.
|
static interface |
AudioEffect.OnParameterChangeListener
The OnParameterChangeListener interface defines a method called by the AudioEffect
when a parameter is changed in the effect engine by the controlling application.
|
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION
Intent to signal to the effect control application or service that an audio session
is closed and that effects should not be applied anymore.
|
static String |
ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL
Intent to launch an audio effect control panel UI.
|
static String |
ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION
Intent to signal to the effect control application or service that a new audio session
is opened and requires audio effects to be applied.
|
static int |
ALREADY_EXISTS
Internal operation status.
|
static int |
CONTENT_TYPE_GAME
Value for
EXTRA_CONTENT_TYPE when the type of content played is game audio |
static int |
CONTENT_TYPE_MOVIE
Value for
EXTRA_CONTENT_TYPE when the type of content played is video or movie |
static int |
CONTENT_TYPE_MUSIC
Value for
EXTRA_CONTENT_TYPE when the type of content played is music |
static int |
CONTENT_TYPE_VOICE
Value for
EXTRA_CONTENT_TYPE when the type of content played is voice audio |
static String |
EFFECT_AUXILIARY
Effect connection mode is auxiliary.
|
static String |
EFFECT_INSERT
Effect connection mode is insert.
|
static String |
EFFECT_PRE_PROCESSING
Effect connection mode is pre processing.
|
static UUID |
EFFECT_TYPE_AEC
UUID for Acoustic Echo Canceler (AEC)
|
static UUID |
EFFECT_TYPE_AGC
UUID for Automatic Gain Control (AGC)
|
static UUID |
EFFECT_TYPE_BASS_BOOST
UUID for bass boost effect
|
static UUID |
EFFECT_TYPE_ENV_REVERB
UUID for environmental reverberation effect
|
static UUID |
EFFECT_TYPE_EQUALIZER
UUID for equalizer effect
|
static UUID |
EFFECT_TYPE_LOUDNESS_ENHANCER
UUID for Loudness Enhancer
|
static UUID |
EFFECT_TYPE_NS
UUID for Noise Suppressor (NS)
|
static UUID |
EFFECT_TYPE_NULL
Null effect UUID.
|
static UUID |
EFFECT_TYPE_PRESET_REVERB
UUID for preset reverberation effect
|
static UUID |
EFFECT_TYPE_VIRTUALIZER
UUID for virtualizer effect
|
static int |
ERROR
Unspecified error.
|
static int |
ERROR_BAD_VALUE
Operation failed due to bad parameter value.
|
static int |
ERROR_DEAD_OBJECT
Operation failed due to dead remote object.
|
static int |
ERROR_INVALID_OPERATION
Operation failed because it was requested in wrong state.
|
static int |
ERROR_NO_INIT
Operation failed due to bad object initialization.
|
static int |
ERROR_NO_MEMORY
Operation failed due to lack of memory.
|
static String |
EXTRA_AUDIO_SESSION
Contains the ID of the audio session the effects should be applied to.
|
static String |
EXTRA_CONTENT_TYPE
Indicates which type of content is played by the application.
|
static String |
EXTRA_PACKAGE_NAME
Contains the package name of the calling application.
|
Object |
mListenerLock
Lock to protect listeners updates against event notifications
|
android.media.audiofx.AudioEffect.NativeEventHandler |
mNativeEventHandler
Handler for events coming from the native code
|
static int |
NATIVE_EVENT_CONTROL_STATUS
Event id for engine control ownership change notification.
|
static int |
NATIVE_EVENT_ENABLED_STATUS
Event id for engine state change notification.
|
static int |
NATIVE_EVENT_PARAMETER_CHANGED
Event id for engine parameter change notification.
|
static int |
STATE_INITIALIZED
State of an AudioEffect object that is ready to be used.
|
static int |
STATE_UNINITIALIZED
State of an AudioEffect object that was not successfully initialized upon
creation
|
static int |
SUCCESS
Successful operation.
|
Constructor and Description |
---|
AudioEffect(UUID type,
UUID uuid,
int priority,
int audioSession)
Class constructor.
|
Modifier and Type | Method and Description |
---|---|
static int |
byteArrayToInt(byte[] valueBuf) |
static int |
byteArrayToInt(byte[] valueBuf,
int offset) |
static short |
byteArrayToShort(byte[] valueBuf) |
static short |
byteArrayToShort(byte[] valueBuf,
int offset) |
void |
checkState(String methodName) |
void |
checkStatus(int status) |
int |
command(int cmdCode,
byte[] command,
byte[] reply)
Send a command to the effect engine.
|
static byte[] |
concatArrays(byte[]... arrays) |
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
AudioEffect.Descriptor |
getDescriptor()
Get the effect descriptor.
|
boolean |
getEnabled()
Returns effect enabled state
|
int |
getId()
Returns effect unique identifier.
|
int |
getParameter(byte[] param,
byte[] value)
Get effect parameter.
|
int |
getParameter(int[] param,
byte[] value)
Get effect parameter.
|
int |
getParameter(int[] param,
int[] value)
Get effect parameter.
|
int |
getParameter(int[] param,
short[] value)
Get effect parameter.
|
int |
getParameter(int param,
byte[] value)
Get effect parameter.
|
int |
getParameter(int param,
int[] value)
Get effect parameter.
|
int |
getParameter(int param,
short[] value)
Get effect parameter.
|
boolean |
hasControl()
Checks if this AudioEffect object is controlling the effect engine.
|
static byte[] |
intToByteArray(int value) |
static boolean |
isEffectTypeAvailable(UUID type)
Checks if the device implements the specified effect type.
|
static boolean |
isError(int status) |
static AudioEffect.Descriptor[] |
queryEffects()
Query all effects available on the platform.
|
static AudioEffect.Descriptor[] |
queryPreProcessings(int audioSession)
Query all audio pre-processing effects applied to the AudioRecord with the supplied
audio session ID.
|
void |
release()
Releases the native AudioEffect resources.
|
void |
setControlStatusListener(AudioEffect.OnControlStatusChangeListener listener)
Sets the listener AudioEffect notifies when the effect engine control is
taken or returned.
|
int |
setEnabled(boolean enabled)
Enable or disable the effect.
|
void |
setEnableStatusListener(AudioEffect.OnEnableStatusChangeListener listener)
Sets the listener AudioEffect notifies when the effect engine is enabled
or disabled.
|
int |
setParameter(byte[] param,
byte[] value)
Set effect parameter.
|
int |
setParameter(int[] param,
byte[] value)
Set effect parameter.
|
int |
setParameter(int[] param,
int[] value)
Set effect parameter.
|
int |
setParameter(int[] param,
short[] value)
Set effect parameter.
|
int |
setParameter(int param,
byte[] value)
Set effect parameter.
|
int |
setParameter(int param,
int value)
Set effect parameter.
|
int |
setParameter(int param,
short value)
Set effect parameter.
|
void |
setParameterListener(AudioEffect.OnParameterChangeListener listener)
Sets the listener AudioEffect notifies when a parameter is changed.
|
static byte[] |
shortToByteArray(short value) |
public static final UUID EFFECT_TYPE_ENV_REVERB
public static final UUID EFFECT_TYPE_PRESET_REVERB
public static final UUID EFFECT_TYPE_EQUALIZER
public static final UUID EFFECT_TYPE_BASS_BOOST
public static final UUID EFFECT_TYPE_VIRTUALIZER
public static final UUID EFFECT_TYPE_AGC
public static final UUID EFFECT_TYPE_AEC
public static final UUID EFFECT_TYPE_NS
public static final UUID EFFECT_TYPE_LOUDNESS_ENHANCER
public static final UUID EFFECT_TYPE_NULL
public static final int STATE_UNINITIALIZED
public static final int STATE_INITIALIZED
public static final int NATIVE_EVENT_CONTROL_STATUS
public static final int NATIVE_EVENT_ENABLED_STATUS
public static final int NATIVE_EVENT_PARAMETER_CHANGED
public static final int SUCCESS
public static final int ERROR
public static final int ALREADY_EXISTS
public static final int ERROR_NO_INIT
public static final int ERROR_BAD_VALUE
public static final int ERROR_INVALID_OPERATION
public static final int ERROR_NO_MEMORY
public static final int ERROR_DEAD_OBJECT
public static final String EFFECT_INSERT
public static final String EFFECT_AUXILIARY
Auxiliary effects must be created on session 0 (global output mix). In order for a MediaPlayer or AudioTrack to be fed into this effect, they must be explicitely attached to this effect and a send level must be specified.
Use the effect ID returned by getId()
to designate this particular effect when
attaching it to the MediaPlayer or AudioTrack.
public static final String EFFECT_PRE_PROCESSING
public final Object mListenerLock
public android.media.audiofx.AudioEffect.NativeEventHandler mNativeEventHandler
public static final String ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL
The goal of this intent is to enable separate implementations of music/media player applications and audio effect control application or services. This will allow platform vendors to offer more advanced control options for standard effects or control for platform specific effects.
The intent carries a number of extras used by the player application to communicate necessary pieces of information to the control panel application.
The calling application must use the
Activity.startActivityForResult(Intent, int)
method to launch the
control panel so that its package name is indicated and used by the control panel
application to keep track of changes for this particular application.
The EXTRA_AUDIO_SESSION
extra will indicate an audio session to which the
audio effects should be applied. If no audio session is specified, either one of the
follownig will happen:
- If an audio session was previously opened by the calling application with
ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION
intent, the effect changes will
be applied to that session.
- If no audio session is opened, the changes will be stored in the package specific storage area and applied whenever a new audio session is opened by this application.
The EXTRA_CONTENT_TYPE
extra will help the control panel application
customize both the UI layout and the default audio effect settings if none are already
stored for the calling application.
public static final String ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION
This is different from ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL
in that no
UI should be displayed in this case. Music player applications can broadcast this intent
before starting playback to make sure that any audio effect settings previously selected
by the user are applied.
The effect control application receiving this intent will look for previously stored settings for the calling application, create all required audio effects and apply the effect settings to the specified audio session.
The calling package name is indicated by the EXTRA_PACKAGE_NAME
extra and the
audio session ID by the EXTRA_AUDIO_SESSION
extra. Both extras are mandatory.
If no stored settings are found for the calling application, default settings for the
content type indicated by EXTRA_CONTENT_TYPE
will be applied. The default settings
for a given content type are platform specific.
public static final String ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION
The effect control application receiving this intent will delete all effects on this session and store current settings in package specific storage.
The calling package name is indicated by the EXTRA_PACKAGE_NAME
extra and the
audio session ID by the EXTRA_AUDIO_SESSION
extra. Both extras are mandatory.
It is good practice for applications to broadcast this intent when music playback stops and/or when exiting to free system resources consumed by audio effect engines.
public static final String EXTRA_AUDIO_SESSION
This extra is for use with ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL
,
ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION
and
ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION
intents.
The extra value is of type int and is the audio session ID.
public static final String EXTRA_PACKAGE_NAME
This extra is for use with ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION
and
ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION
intents.
The extra value is a string containing the full package name.
public static final String EXTRA_CONTENT_TYPE
This extra is for use with ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL
and
ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION
intents.
This information is used by the effect control application to customize UI and select appropriate default effect settings. The content type is one of the following:
If omitted, the content type defaults toCONTENT_TYPE_MUSIC
.public static final int CONTENT_TYPE_MUSIC
EXTRA_CONTENT_TYPE
when the type of content played is musicpublic static final int CONTENT_TYPE_MOVIE
EXTRA_CONTENT_TYPE
when the type of content played is video or moviepublic static final int CONTENT_TYPE_GAME
EXTRA_CONTENT_TYPE
when the type of content played is game audiopublic static final int CONTENT_TYPE_VOICE
EXTRA_CONTENT_TYPE
when the type of content played is voice audiopublic AudioEffect(UUID type, UUID uuid, int priority, int audioSession) throws IllegalArgumentException, UnsupportedOperationException, RuntimeException
type
- type of effect engine created. See EFFECT_TYPE_ENV_REVERB
,
EFFECT_TYPE_EQUALIZER
... Types corresponding to
built-in effects are defined by AudioEffect class. Other types
can be specified provided they correspond an existing OpenSL
ES interface ID and the corresponsing effect is available on
the platform. If an unspecified effect type is requested, the
constructor with throw the IllegalArgumentException. This
parameter can be set to EFFECT_TYPE_NULL
in which
case only the uuid will be used to select the effect.uuid
- unique identifier of a particular effect implementation.
Must be specified if the caller wants to use a particular
implementation of an effect type. This parameter can be set to
EFFECT_TYPE_NULL
in which case only the type will
be used to select the effect.priority
- the priority level requested by the application for
controlling the effect engine. As the same effect 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.
The effect will be attached to the MediaPlayer or AudioTrack in
the same audio session.IllegalArgumentException
UnsupportedOperationException
RuntimeException
public void release()
protected void finalize()
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
public AudioEffect.Descriptor getDescriptor() throws IllegalStateException
IllegalStateException
AudioEffect.Descriptor
public static AudioEffect.Descriptor[] queryEffects()
AudioEffect.Descriptor
objectsIllegalStateException
public static AudioEffect.Descriptor[] queryPreProcessings(int audioSession)
AudioEffect.Descriptor
objects.audioSession
- system wide unique audio session identifier.IllegalStateException
public static boolean isEffectTypeAvailable(UUID type)
type
- the requested effect type.public int setEnabled(boolean enabled) throws IllegalStateException
enabled
- the requested enable stateSUCCESS
in case of success, ERROR_INVALID_OPERATION
or ERROR_DEAD_OBJECT
in case of failure.IllegalStateException
public int setParameter(byte[] param, byte[] value) throws IllegalStateException
param
- the identifier of the parameter to setvalue
- the new value for the specified parameterSUCCESS
in case of success, ERROR_BAD_VALUE
,
ERROR_NO_MEMORY
, ERROR_INVALID_OPERATION
or
ERROR_DEAD_OBJECT
in case of failureIllegalStateException
public int setParameter(int param, int value) throws IllegalStateException
IllegalStateException
setParameter(byte[], byte[])
public int setParameter(int param, short value) throws IllegalStateException
IllegalStateException
setParameter(byte[], byte[])
public int setParameter(int param, byte[] value) throws IllegalStateException
IllegalStateException
setParameter(byte[], byte[])
public int setParameter(int[] param, int[] value) throws IllegalStateException
IllegalStateException
setParameter(byte[], byte[])
public int setParameter(int[] param, short[] value) throws IllegalStateException
IllegalStateException
setParameter(byte[], byte[])
public int setParameter(int[] param, byte[] value) throws IllegalStateException
IllegalStateException
setParameter(byte[], byte[])
public int getParameter(byte[] param, byte[] value) throws IllegalStateException
param
- the identifier of the parameter to setvalue
- the new value for the specified parameterERROR_BAD_VALUE
, ERROR_NO_MEMORY
, ERROR_INVALID_OPERATION
or ERROR_DEAD_OBJECT
in case of failure.IllegalStateException
public int getParameter(int param, byte[] value) throws IllegalStateException
IllegalStateException
getParameter(byte[], byte[])
public int getParameter(int param, int[] value) throws IllegalStateException
public int getParameter(int param, short[] value) throws IllegalStateException
public int getParameter(int[] param, int[] value) throws IllegalStateException
public int getParameter(int[] param, short[] value) throws IllegalStateException
public int getParameter(int[] param, byte[] value) throws IllegalStateException
IllegalStateException
getParameter(byte[], byte[])
public int command(int cmdCode, byte[] command, byte[] reply) throws IllegalStateException
IllegalStateException
public int getId() throws IllegalStateException
IllegalStateException
public boolean getEnabled() throws IllegalStateException
IllegalStateException
public boolean hasControl() throws IllegalStateException
IllegalStateException
public void setEnableStatusListener(AudioEffect.OnEnableStatusChangeListener listener)
listener
- public void setControlStatusListener(AudioEffect.OnControlStatusChangeListener listener)
listener
- public void setParameterListener(AudioEffect.OnParameterChangeListener listener)
listener
- public void checkState(String methodName) throws IllegalStateException
IllegalStateException
public void checkStatus(int status)
public static boolean isError(int status)
public static int byteArrayToInt(byte[] valueBuf)
public static int byteArrayToInt(byte[] valueBuf, int offset)
public static byte[] intToByteArray(int value)
public static short byteArrayToShort(byte[] valueBuf)
public static short byteArrayToShort(byte[] valueBuf, int offset)
public static byte[] shortToByteArray(short value)
public static byte[] concatArrays(byte[]... arrays)