diff --git a/api/current.xml b/api/current.xml index b1414758f81a0..52b534264b025 100644 --- a/api/current.xml +++ b/api/current.xml @@ -84353,1079 +84353,6 @@ > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -95073,7 +94478,7 @@ deprecated="not deprecated" visibility="public" > - + @@ -95092,7 +94497,7 @@ visibility="public" > - + @@ -95430,7 +94835,7 @@ deprecated="not deprecated" visibility="public" > - + @@ -95447,7 +94852,7 @@ deprecated="not deprecated" visibility="public" > - + diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java index 74691334f03f1..b97c3c4ed31d6 100644 --- a/media/java/android/media/AudioTrack.java +++ b/media/java/android/media/AudioTrack.java @@ -963,14 +963,17 @@ public class AudioTrack //-------------------- /** - * Attaches an auxiliary effect to the audio track. A typical auxiliary effect is a - * reverberation effect which can be applied on any sound source that directs a certain - * amount of its energy to this effect. This amount is defined by setAuxEffectSendLevel(). + * Attaches an auxiliary effect to the audio track. A typical auxiliary + * effect is a reverberation effect which can be applied on any sound source + * that directs a certain amount of its energy to this effect. This amount + * is defined by setAuxEffectSendLevel(). * {@see #setAuxEffectSendLevel(float)}. - *

After creating an auxiliary effect (e.g. {@link android.media.EnvironmentalReverb}), - * retrieve its ID with {@link android.media.AudioEffect#getId()} and use it when calling + *

After creating an auxiliary effect (e.g. + * {@link android.media.audiofx.EnvironmentalReverb}), retrieve its ID with + * {@link android.media.audiofx.AudioEffect#getId()} and use it when calling * this method to attach the audio track to the effect. - *

To detach the effect from the audio track, call this method with a null effect id. + *

To detach the effect from the audio track, call this method with a + * null effect id. * * @param effectId system wide unique id of the effect to attach * @return error code or success, see {@link #SUCCESS}, diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java index 280def95fca69..cb46a29dc4b04 100644 --- a/media/java/android/media/MediaPlayer.java +++ b/media/java/android/media/MediaPlayer.java @@ -1210,9 +1210,10 @@ public class MediaPlayer * effect which can be applied on any sound source that directs a certain amount of its * energy to this effect. This amount is defined by setAuxEffectSendLevel(). * {@see #setAuxEffectSendLevel(float)}. - *

After creating an auxiliary effect (e.g. {@link android.media.EnvironmentalReverb}), - * retrieve its ID with {@link android.media.AudioEffect#getId()} and use it when calling - * this method to attach the player to the effect. + *

After creating an auxiliary effect (e.g. + * {@link android.media.audiofx.EnvironmentalReverb}), retrieve its ID with + * {@link android.media.audiofx.AudioEffect#getId()} and use it when calling this method + * to attach the player to the effect. *

To detach the effect from the player, call this method with a null effect id. *

This method must be called after one of the overloaded setDataSource * methods. diff --git a/media/java/android/media/AudioEffect.java b/media/java/android/media/audiofx/AudioEffect.java similarity index 89% rename from media/java/android/media/AudioEffect.java rename to media/java/android/media/audiofx/AudioEffect.java index ed7601eb19c4b..3e54627518635 100644 --- a/media/java/android/media/AudioEffect.java +++ b/media/java/android/media/audiofx/AudioEffect.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; @@ -29,22 +29,35 @@ import java.nio.ByteBuffer; import java.util.UUID; /** - * AudioEffect is the base class for implementing audio effect control in Java - * applications. - *

Creating an AudioEffect object will create the effect engine in - * 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 appropiate listener. - *

If the effect is to be applied to a specific AudioTrack or MediaPlayer instance, - * the application must specify the audio session ID of that instance when calling the AudioEffect - * constructor. + * AudioEffect is the base class for controlling audio effects provided by the android audio + * framework. + *

Applications should not use the AudioEffect class directly but one of its derived classes to + * control specific effects: + *

    + *
  • {@link android.media.audiofx.Equalizer}
    • + *
  • {@link android.media.audiofx.Virtualizer}
    • + *
  • {@link android.media.audiofx.BassBoost}
    • + *
  • {@link android.media.audiofx.PresetReverb}
    • + *
  • {@link android.media.audiofx.EnvironmentalReverb}
    • + *
+ *

If the audio effect is to be applied to a specific AudioTrack or MediaPlayer instance, + * the application must specify the audio session ID of that instance when creating the AudioEffect. + * (see {@link android.media.MediaPlayer#getAudioSessionId()} for details on audio sessions). + * To apply an effect to the global audio output mix, session 0 must be specified when creating the + * AudioEffect. + *

Creating an effect on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} + *

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 + * appropiate listener. */ + public class AudioEffect { static { System.loadLibrary("audioeffect_jni"); @@ -62,32 +75,38 @@ public class AudioEffect { /** * UUID for environmental reverb effect + * @hide */ public static final UUID EFFECT_TYPE_ENV_REVERB = UUID .fromString("c2e5d5f0-94bd-4763-9cac-4e234d06839e"); /** * UUID for preset reverb effect + * @hide */ public static final UUID EFFECT_TYPE_PRESET_REVERB = UUID .fromString("47382d60-ddd8-11db-bf3a-0002a5d5c51b"); /** * UUID for equalizer effect + * @hide */ public static final UUID EFFECT_TYPE_EQUALIZER = UUID .fromString("0bed4300-ddd6-11db-8f34-0002a5d5c51b"); /** * UUID for bass boost effect + * @hide */ public static final UUID EFFECT_TYPE_BASS_BOOST = UUID .fromString("0634f220-ddd4-11db-a0fc-0002a5d5c51b"); /** * UUID for virtualizer effect + * @hide */ public static final UUID EFFECT_TYPE_VIRTUALIZER = UUID .fromString("37cc2c00-dddd-11db-8577-0002a5d5c51b"); /** * Null effect UUID. Used when the UUID for effect type of + * @hide */ public static final UUID EFFECT_TYPE_NULL = UUID .fromString("ec7178ec-e5e1-4432-a3f4-4657e6795210"); @@ -95,10 +114,12 @@ public class AudioEffect { /** * State of an AudioEffect object that was not successfully initialized upon * creation + * @hide */ public static final int STATE_UNINITIALIZED = 0; /** * State of an AudioEffect object that is ready to be used. + * @hide */ public static final int STATE_INITIALIZED = 1; @@ -106,14 +127,17 @@ public class AudioEffect { // frameworks/base/include/media/AudioEffect.h /** * Event id for engine control ownership change notification. + * @hide */ public static final int NATIVE_EVENT_CONTROL_STATUS = 0; /** * Event id for engine state change notification. + * @hide */ public static final int NATIVE_EVENT_ENABLED_STATUS = 1; /** * Event id for engine parameter change notification. + * @hide */ public static final int NATIVE_EVENT_PARAMETER_CHANGED = 2; @@ -151,15 +175,17 @@ public class AudioEffect { public static final int ERROR_DEAD_OBJECT = -7; /** - * The effect descriptor contains necessary information to facilitate - * effects enumeration:
+ * The effect descriptor contains information on a particular effect implemented in the + * audio framework:
*

    - *
  • mType: UUID corresponding to the OpenSL ES interface implemented by this effect
    • - *
  • mUuid: UUID for this particular implementation
    • - *
  • mConnectMode: {@link #EFFECT_INSERT} or {@link #EFFECT_AUXILIARY}
    • - *
  • mName: human readable effect name
    • - *
  • mImplementor: human readable effect implementor name
    • + *
  • type: UUID corresponding to the OpenSL ES interface implemented by this effect
    • + *
  • uuid: UUID for this particular implementation
    • + *
  • connectMode: {@link #EFFECT_INSERT} or {@link #EFFECT_AUXILIARY}
    • + *
  • name: human readable effect name
    • + *
  • implementor: human readable effect implementor name
    • *
+ * The method {@link #queryEffects()} returns an array of Descriptors to facilitate effects + * enumeration. */ public static class Descriptor { @@ -168,18 +194,39 @@ public class AudioEffect { public Descriptor(String type, String uuid, String connectMode, String name, String implementor) { - mType = UUID.fromString(type); - mUuid = UUID.fromString(uuid); - mConnectMode = connectMode; - mName = name; - mImplementor = implementor; + this.type = UUID.fromString(type); + this.uuid = UUID.fromString(uuid); + this.connectMode = connectMode; + this.name = name; + this.implementor = implementor; } - public UUID mType; - public UUID mUuid; - public String mConnectMode; - public String mName; - public String mImplementor; + /** + * Indicates the generic type of the effect (Equalizer, Bass boost ...). The UUID + * corresponds to the OpenSL ES Interface ID for this type of effect. + */ + public UUID type; + /** + * Indicates the particular implementation of the effect in that type. Several effects + * can have the same type but this uuid is unique to a given implementation. + */ + public UUID uuid; + /** + * Indicates if the effect is of insert category {@link #EFFECT_INSERT} or auxiliary + * category {@link #EFFECT_AUXILIARY}. Insert effects (Typically an Equalizer) are applied + * to the entire audio source and usually not shared by several sources. Auxiliary effects + * (typically a reverberator) are applied to part of the signal (wet) and the effect output + * is added to the original signal (dry). + */ + public String connectMode; + /** + * Human readable effect name + */ + public String name; + /** + * Human readable effect implementor name + */ + public String implementor; }; /** @@ -242,10 +289,12 @@ public class AudioEffect { private OnParameterChangeListener mParameterChangeListener = null; /** * Lock to protect listeners updates against event notifications + * @hide */ public final Object mListenerLock = new Object(); /** * Handler for events coming from the native code + * @hide */ public NativeEventHandler mNativeEventHandler = null; @@ -283,6 +332,7 @@ public class AudioEffect { * @throws java.lang.IllegalArgumentException * @throws java.lang.UnsupportedOperationException * @throws java.lang.RuntimeException + * @hide */ public AudioEffect(UUID type, UUID uuid, int priority, int audioSession) @@ -337,7 +387,7 @@ public class AudioEffect { /** * Get the effect descriptor. * - * @see android.media.AudioEffect.Descriptor + * @see android.media.audiofx.AudioEffect.Descriptor * @throws IllegalStateException */ public Descriptor getDescriptor() throws IllegalStateException { @@ -351,7 +401,7 @@ public class AudioEffect { /** * Query all effects available on the platform. Returns an array of - * {@link android.media.AudioEffect.Descriptor} objects + * {@link android.media.audiofx.AudioEffect.Descriptor} objects * * @throws IllegalStateException */ @@ -365,7 +415,11 @@ public class AudioEffect { // -------------------- /** - * Enable or disable effect engine. + * Enable or disable the effect. + * Creating an audio effect does not automatically apply this effect on the audio source. It + * creates the resources necessary to process this effect but the audio signal is still bypassed + * through the effect engine. Calling this method will make that the effect is actually applied + * or not to the audio content being played in the corresponding audio session. * * @param enabled the requested enable state * @return {@link #SUCCESS} in case of success, {@link #ERROR_INVALID_OPERATION} @@ -392,6 +446,7 @@ public class AudioEffect { * {@link #ERROR_NO_MEMORY}, {@link #ERROR_INVALID_OPERATION} or * {@link #ERROR_DEAD_OBJECT} in case of failure * @throws IllegalStateException + * @hide */ public int setParameter(byte[] param, byte[] value) throws IllegalStateException { @@ -403,6 +458,7 @@ public class AudioEffect { * Set effect parameter. The parameter and its value are integers. * * @see #setParameter(byte[], byte[]) + * @hide */ public int setParameter(int param, int value) throws IllegalStateException { byte[] p = intToByteArray(param); @@ -415,6 +471,7 @@ public class AudioEffect { * short integer. * * @see #setParameter(byte[], byte[]) + * @hide */ public int setParameter(int param, short value) throws IllegalStateException { @@ -428,6 +485,7 @@ public class AudioEffect { * array of bytes. * * @see #setParameter(byte[], byte[]) + * @hide */ public int setParameter(int param, byte[] value) throws IllegalStateException { @@ -440,6 +498,7 @@ public class AudioEffect { * the value is also an array of 1 or 2 integers * * @see #setParameter(byte[], byte[]) + * @hide */ public int setParameter(int[] param, int[] value) throws IllegalStateException { @@ -464,6 +523,7 @@ public class AudioEffect { * the value is an array of 1 or 2 short integers * * @see #setParameter(byte[], byte[]) + * @hide */ public int setParameter(int[] param, short[] value) throws IllegalStateException { @@ -489,6 +549,7 @@ public class AudioEffect { * the value is an array of bytes * * @see #setParameter(byte[], byte[]) + * @hide */ public int setParameter(int[] param, byte[] value) throws IllegalStateException { @@ -519,6 +580,7 @@ public class AudioEffect { * returning, value.length is updated with the actual size of the * returned value. * @throws IllegalStateException + * @hide */ public int getParameter(byte[] param, byte[] value) throws IllegalStateException { @@ -539,6 +601,7 @@ public class AudioEffect { * array of bytes. * * @see #getParameter(byte[], byte[]) + * @hide */ public int getParameter(int param, byte[] value) throws IllegalStateException { @@ -552,6 +615,7 @@ public class AudioEffect { * array of 1 or 2 integers * * @see #getParameter(byte[], byte[]) + * @hide */ public int getParameter(int param, int[] value) throws IllegalStateException { @@ -576,6 +640,7 @@ public class AudioEffect { * array of 1 or 2 short integers * * @see #getParameter(byte[], byte[]) + * @hide */ public int getParameter(int param, short[] value) throws IllegalStateException { @@ -600,6 +665,7 @@ public class AudioEffect { * the value is also an array of 1 or 2 integers * * @see #getParameter(byte[], byte[]) + * @hide */ public int getParameter(int[] param, int[] value) throws IllegalStateException { @@ -627,6 +693,7 @@ public class AudioEffect { * the value is an array of 1 or 2 short integers * * @see #getParameter(byte[], byte[]) + * @hide */ public int getParameter(int[] param, short[] value) throws IllegalStateException { @@ -654,6 +721,7 @@ public class AudioEffect { * the value is an array of bytes * * @see #getParameter(byte[], byte[]) + * @hide */ public int getParameter(int[] param, byte[] value) throws IllegalStateException { @@ -673,6 +741,7 @@ public class AudioEffect { * Send a command to the effect engine. This method is intended to send * proprietary commands to a particular effect implementation. * + * @hide */ public int command(int cmdCode, byte[] command, byte[] reply) throws IllegalStateException { @@ -709,7 +778,7 @@ public class AudioEffect { } /** - * Returns effect engine enable state + * Returns effect enabled state * * @return true if the effect is enabled, false otherwise. * @throws IllegalStateException @@ -768,6 +837,7 @@ public class AudioEffect { * Sets the listener AudioEffect notifies when a parameter is changed. * * @param listener + * @hide */ public void setParameterListener(OnParameterChangeListener listener) { synchronized (mListenerLock) { @@ -828,6 +898,7 @@ public class AudioEffect { /** * The OnParameterChangeListener interface defines a method called by the AudioEffect * when a parameter is changed in the effect engine by the controlling application. + * @hide */ public interface OnParameterChangeListener { /** @@ -914,8 +985,7 @@ public class AudioEffect { * {@link #ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION} and * {@link #ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION} intents. *

The extra value is of type int and is the audio session ID. - * - * @see android.media.MediaPlayer#setAudioSessionId(int) + * @see android.media.MediaPlayer#getAudioSessionId() for details on audio sessions. */ public static final String EXTRA_AUDIO_SESSION = "android.media.extra.AUDIO_SESSION"; @@ -1086,6 +1156,9 @@ public class AudioEffect { // Utility methods // ------------------ + /** + * @hide + */ public void checkState(String methodName) throws IllegalStateException { synchronized (mStateLock) { if (mState != STATE_INITIALIZED) { @@ -1095,6 +1168,9 @@ public class AudioEffect { } } + /** + * @hide + */ public void checkStatus(int status) { switch (status) { case AudioEffect.SUCCESS: @@ -1110,11 +1186,17 @@ public class AudioEffect { } } + /** + * @hide + */ public int byteArrayToInt(byte[] valueBuf) { return byteArrayToInt(valueBuf, 0); } + /** + * @hide + */ public int byteArrayToInt(byte[] valueBuf, int offset) { ByteBuffer converter = ByteBuffer.wrap(valueBuf); converter.order(ByteOrder.nativeOrder()); @@ -1122,6 +1204,9 @@ public class AudioEffect { } + /** + * @hide + */ public byte[] intToByteArray(int value) { ByteBuffer converter = ByteBuffer.allocate(4); converter.order(ByteOrder.nativeOrder()); @@ -1129,10 +1214,16 @@ public class AudioEffect { return converter.array(); } + /** + * @hide + */ public short byteArrayToShort(byte[] valueBuf) { return byteArrayToShort(valueBuf, 0); } + /** + * @hide + */ public short byteArrayToShort(byte[] valueBuf, int offset) { ByteBuffer converter = ByteBuffer.wrap(valueBuf); converter.order(ByteOrder.nativeOrder()); @@ -1140,6 +1231,9 @@ public class AudioEffect { } + /** + * @hide + */ public byte[] shortToByteArray(short value) { ByteBuffer converter = ByteBuffer.allocate(2); converter.order(ByteOrder.nativeOrder()); @@ -1148,6 +1242,9 @@ public class AudioEffect { return converter.array(); } + /** + * @hide + */ public byte[] concatArrays(byte[]... arrays) { int len = 0; for (byte[] a : arrays) { @@ -1162,5 +1259,4 @@ public class AudioEffect { } return b; } - } diff --git a/media/java/android/media/BassBoost.java b/media/java/android/media/audiofx/BassBoost.java similarity index 94% rename from media/java/android/media/BassBoost.java rename to media/java/android/media/audiofx/BassBoost.java index 476b0562ed42f..ca55f0f822bdc 100644 --- a/media/java/android/media/BassBoost.java +++ b/media/java/android/media/audiofx/BassBoost.java @@ -14,12 +14,12 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.app.Activity; import android.content.Context; import android.content.Intent; -import android.media.AudioEffect; +import android.media.audiofx.AudioEffect; import android.os.Bundle; import android.util.Log; @@ -32,15 +32,19 @@ 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. - *

An application creates a BassBoost object to instantiate and control a bass boost engine - * in the audio framework. + *

An application creates a BassBoost object to instantiate and control a bass boost engine in + * the audio framework. *

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. *

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

See {@link android.media.AudioEffect} class for more details on controlling audio effects. + * ID of this AudioTrack or MediaPlayer when constructing the BassBoost. + * If the audio session ID 0 is specified, the BassBoost applies to the main audio output mix. + *

Creating a BassBoost on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} + *

See {@link android.media.MediaPlayer#getAudioSessionId()} for details on audio sessions. + *

See {@link android.media.audiofx.AudioEffect} class for more details on + * controlling audio effects. */ public class BassBoost extends AudioEffect { @@ -55,7 +59,7 @@ public class BassBoost extends AudioEffect { public static final int PARAM_STRENGTH_SUPPORTED = 0; /** * Bass boost effect strength. Parameter ID for - * {@link android.media.BassBoost.OnParameterChangeListener} + * {@link android.media.audiofx.BassBoost.OnParameterChangeListener} */ public static final int PARAM_STRENGTH = 1; @@ -155,7 +159,6 @@ public class BassBoost extends AudioEffect { * BassBoost engine. * @param effect the BassBoost on which the interface is registered. * @param status status of the set parameter operation. - * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}. * @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ... * @param value the new parameter value. */ diff --git a/media/java/android/media/EnvironmentalReverb.java b/media/java/android/media/audiofx/EnvironmentalReverb.java similarity index 97% rename from media/java/android/media/EnvironmentalReverb.java rename to media/java/android/media/audiofx/EnvironmentalReverb.java index b50febce5d001..f1f582ed3c9d7 100644 --- a/media/java/android/media/EnvironmentalReverb.java +++ b/media/java/android/media/audiofx/EnvironmentalReverb.java @@ -14,12 +14,12 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.app.Activity; import android.content.Context; import android.content.Intent; -import android.media.AudioEffect; +import android.media.audiofx.AudioEffect; import android.os.Bundle; import android.util.Log; @@ -28,18 +28,18 @@ import java.nio.ByteBuffer; import java.util.StringTokenizer; /** - * A sound generated within a room travels in many directions. The listener first hears the - * direct sound from the source itself. Later, he or she hears discrete echoes caused by sound - * bouncing off nearby walls, the ceiling and the floor. As sound waves arrive after - * undergoing more and more reflections, individual reflections become indistinguishable and - * the listener hears continuous reverberation that decays over time. + * A sound generated within a room travels in many directions. The listener first hears the direct + * sound from the source itself. Later, he or she hears discrete echoes caused by sound bouncing off + * nearby walls, the ceiling and the floor. As sound waves arrive after undergoing more and more + * reflections, individual reflections become indistinguishable and the listener hears continuous + * reverberation that decays over time. * Reverb is vital for modeling a listener's environment. It can be used in music applications * to simulate music being played back in various environments, or in games to immerse the * listener within the game's environment. * The EnvironmentalReverb class allows an application to control each reverb engine property in a * global reverb environment and is more suitable for games. For basic control, more suitable for * music applications, it is recommended to use the - * {@link android.media.PresetReverb} class. + * {@link android.media.audiofx.PresetReverb} class. *

An application creates a EnvironmentalReverb object to instantiate and control a reverb engine * in the audio framework. *

The methods, parameter types and units exposed by the EnvironmentalReverb implementation are @@ -51,7 +51,9 @@ import java.util.StringTokenizer; * they must be explicitely attached to it and a send level must be specified. Use the effect ID * returned by getId() method to designate this particular effect when attaching it to the * MediaPlayer or AudioTrack. - *

See {@link android.media.AudioEffect} class for more details on controlling + *

Creating a reverb on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} + *

See {@link android.media.audiofx.AudioEffect} class for more details on controlling * audio effects. */ @@ -76,7 +78,7 @@ public class EnvironmentalReverb extends AudioEffect { public static final int PARAM_DECAY_TIME = 2; /** * Decay HF ratio. Parameter ID for - * {@link android.media.EnvironmentalReverb.OnParameterChangeListener} + * {@link android.media.audiofx.EnvironmentalReverb.OnParameterChangeListener} */ public static final int PARAM_DECAY_HF_RATIO = 3; /** @@ -444,7 +446,6 @@ public class EnvironmentalReverb extends AudioEffect { * EnvironmentalReverb engine. * @param effect the EnvironmentalReverb on which the interface is registered. * @param status status of the set parameter operation. - * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}. * @param param ID of the modified parameter. See {@link #PARAM_ROOM_LEVEL} ... * @param value the new parameter value. */ diff --git a/media/java/android/media/Equalizer.java b/media/java/android/media/audiofx/Equalizer.java similarity index 97% rename from media/java/android/media/Equalizer.java rename to media/java/android/media/audiofx/Equalizer.java index 6fa48c574ce07..b3bafa9149788 100644 --- a/media/java/android/media/Equalizer.java +++ b/media/java/android/media/audiofx/Equalizer.java @@ -14,12 +14,12 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.app.Activity; import android.content.Context; import android.content.Intent; -import android.media.AudioEffect; +import android.media.audiofx.AudioEffect; import android.os.Bundle; import android.util.Log; @@ -41,7 +41,11 @@ import java.util.StringTokenizer; *

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. - *

See {@link android.media.AudioEffect} class for more details on controlling audio effects. + *

Creating an Equalizer on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} + *

See {@link android.media.MediaPlayer#getAudioSessionId()} for details on audio sessions. + *

See {@link android.media.audiofx.AudioEffect} class for more details on controlling audio + * effects. */ public class Equalizer extends AudioEffect { @@ -68,7 +72,7 @@ public class Equalizer extends AudioEffect { public static final int PARAM_CENTER_FREQ = 3; /** * Band frequency range. Parameter ID for - * {@link android.media.Equalizer.OnParameterChangeListener} + * {@link android.media.audiofx.Equalizer.OnParameterChangeListener} */ public static final int PARAM_BAND_FREQ_RANGE = 4; /** @@ -380,7 +384,6 @@ public class Equalizer extends AudioEffect { * Equalizer engine. * @param effect the Equalizer on which the interface is registered. * @param status status of the set parameter operation. - * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}. * @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. diff --git a/media/java/android/media/PresetReverb.java b/media/java/android/media/audiofx/PresetReverb.java similarity index 96% rename from media/java/android/media/PresetReverb.java rename to media/java/android/media/audiofx/PresetReverb.java index 65175ffdb7227..7a89ae7d38a96 100644 --- a/media/java/android/media/PresetReverb.java +++ b/media/java/android/media/audiofx/PresetReverb.java @@ -14,12 +14,12 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.app.Activity; import android.content.Context; import android.content.Intent; -import android.media.AudioEffect; +import android.media.audiofx.AudioEffect; import android.os.Bundle; import android.util.Log; @@ -40,7 +40,7 @@ import java.util.StringTokenizer; * The PresetReverb class allows an application to configure the global reverb using a reverb preset. * This is primarily used for adding some reverb in a music playback context. Applications * requiring control over a more advanced environmental reverb are advised to use the - * {@link android.media.EnvironmentalReverb} class. + * {@link android.media.audiofx.EnvironmentalReverb} class. *

An application creates a PresetReverb object to instantiate and control a reverb engine in the * audio framework. *

The methods, parameter types and units exposed by the PresetReverb implementation are @@ -52,7 +52,10 @@ import java.util.StringTokenizer; * they must be explicitely attached to it and a send level must be specified. Use the effect ID * returned by getId() method to designate this particular effect when attaching it to the * MediaPlayer or AudioTrack. - *

See {@link android.media.AudioEffect} class for more details on controlling audio effects. + *

Creating a reverb on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} + *

See {@link android.media.audiofx.AudioEffect} class for more details on controlling + * audio effects. */ public class PresetReverb extends AudioEffect { @@ -64,7 +67,7 @@ public class PresetReverb extends AudioEffect { /** * Preset. Parameter ID for - * {@link android.media.PresetReverb.OnParameterChangeListener} + * {@link android.media.audiofx.PresetReverb.OnParameterChangeListener} */ public static final int PARAM_PRESET = 0; @@ -174,7 +177,6 @@ public class PresetReverb extends AudioEffect { * PresetReverb engine. * @param effect the PresetReverb on which the interface is registered. * @param status status of the set parameter operation. - * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}. * @param param ID of the modified parameter. See {@link #PARAM_PRESET} ... * @param value the new parameter value. */ diff --git a/media/java/android/media/Virtualizer.java b/media/java/android/media/audiofx/Virtualizer.java similarity index 95% rename from media/java/android/media/Virtualizer.java rename to media/java/android/media/audiofx/Virtualizer.java index b08f36e5d8e33..a682a45df5d07 100644 --- a/media/java/android/media/Virtualizer.java +++ b/media/java/android/media/audiofx/Virtualizer.java @@ -14,12 +14,12 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.app.Activity; import android.content.Context; import android.content.Intent; -import android.media.AudioEffect; +import android.media.audiofx.AudioEffect; import android.os.Bundle; import android.util.Log; @@ -42,7 +42,11 @@ import java.util.StringTokenizer; *

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

See {@link android.media.AudioEffect} class for more details on controlling audio effects. + *

Creating a Virtualizer on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} + *

See {@link android.media.MediaPlayer#getAudioSessionId()} for details on audio sessions. + *

See {@link android.media.audiofx.AudioEffect} class for more details on controlling + * audio effects. */ public class Virtualizer extends AudioEffect { @@ -56,7 +60,7 @@ public class Virtualizer extends AudioEffect { public static final int PARAM_STRENGTH_SUPPORTED = 0; /** * Virtualizer effect strength. Parameter ID for - * {@link android.media.Virtualizer.OnParameterChangeListener} + * {@link android.media.audiofx.Virtualizer.OnParameterChangeListener} */ public static final int PARAM_STRENGTH = 1; @@ -156,7 +160,6 @@ public class Virtualizer extends AudioEffect { * Virtualizer engine. * @param effect the Virtualizer on which the interface is registered. * @param status status of the set parameter operation. - * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}. * @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ... * @param value the new parameter value. */ diff --git a/media/java/android/media/Visualizer.java b/media/java/android/media/audiofx/Visualizer.java similarity index 98% rename from media/java/android/media/Visualizer.java rename to media/java/android/media/audiofx/Visualizer.java index 33222ffc91d8c..0c48556d97661 100755 --- a/media/java/android/media/Visualizer.java +++ b/media/java/android/media/audiofx/Visualizer.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package android.media; +package android.media.audiofx; import android.util.Log; import java.lang.ref.WeakReference; @@ -32,8 +32,8 @@ import android.os.Message; * visualized:
*

    *
  • If the session is 0, the audio output mix is visualized
    • - *
  • If the session is not 0, the audio from a particular {@link MediaPlayer} or - * {@link AudioTrack} + *
  • If the session is not 0, the audio from a particular {@link android.media.MediaPlayer} or + * {@link android.media.AudioTrack} * using this audio session is visualized
    • *
*

Two types of representation of audio content can be captured:
@@ -57,6 +57,8 @@ import android.os.Message; * When data capture is not needed any more, the Visualizer should be disabled. *

It is good practice to call the {@link #release()} method when the Visualizer is not used * anymore to free up native resources associated to the Visualizer instance. + *

Creating a Visualizer on the output mix (audio session 0) requires permission + * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} */ public class Visualizer { diff --git a/media/java/android/media/audiofx/package.html b/media/java/android/media/audiofx/package.html new file mode 100644 index 0000000000000..c6e4892f801fb --- /dev/null +++ b/media/java/android/media/audiofx/package.html @@ -0,0 +1,5 @@ + + +Provides classes that manage audio effects implemented in the media framework. + + diff --git a/media/jni/audioeffect/android_media_AudioEffect.cpp b/media/jni/audioeffect/android_media_AudioEffect.cpp index 8d9f4fee41073..b16372d54de55 100644 --- a/media/jni/audioeffect/android_media_AudioEffect.cpp +++ b/media/jni/audioeffect/android_media_AudioEffect.cpp @@ -37,7 +37,7 @@ using namespace android; #define AUDIOEFFECT_ERROR_DEAD_OBJECT -7 // ---------------------------------------------------------------------------- -static const char* const kClassPathName = "android/media/AudioEffect"; +static const char* const kClassPathName = "android/media/audiofx/AudioEffect"; struct fields_t { // these fields provide access from C++ to the... @@ -228,9 +228,9 @@ android_media_AudioEffect_native_init(JNIEnv *env) return; } - clazz = env->FindClass("android/media/AudioEffect$Descriptor"); + clazz = env->FindClass("android/media/audiofx/AudioEffect$Descriptor"); if (clazz == NULL) { - LOGE("Can't find android/media/AudioEffect$Descriptor class"); + LOGE("Can't find android/media/audiofx/AudioEffect$Descriptor class"); return; } fields.clazzDesc = (jclass)env->NewGlobalRef(clazz); @@ -241,7 +241,7 @@ android_media_AudioEffect_native_init(JNIEnv *env) "", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V"); if (fields.midDescCstor == NULL) { - LOGE("Can't find android/media/AudioEffect$Descriptor class constructor"); + LOGE("Can't find android/media/audiofx/AudioEffect$Descriptor class constructor"); return; } } diff --git a/media/jni/audioeffect/android_media_Visualizer.cpp b/media/jni/audioeffect/android_media_Visualizer.cpp index 31119f86e3a11..7b271cec448d5 100644 --- a/media/jni/audioeffect/android_media_Visualizer.cpp +++ b/media/jni/audioeffect/android_media_Visualizer.cpp @@ -40,7 +40,7 @@ using namespace android; #define NATIVE_EVENT_FFT_CAPTURE 1 // ---------------------------------------------------------------------------- -static const char* const kClassPathName = "android/media/Visualizer"; +static const char* const kClassPathName = "android/media/audiofx/Visualizer"; struct fields_t { // these fields provide access from C++ to the... diff --git a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/EnergyProbe.java b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/EnergyProbe.java index d339e06a721c5..4e4df3bfcd736 100644 --- a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/EnergyProbe.java +++ b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/EnergyProbe.java @@ -16,7 +16,7 @@ package com.android.mediaframeworktest.functional; -import android.media.Visualizer; +import android.media.audiofx.Visualizer; import android.util.Log; /** diff --git a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaAudioEffectTest.java b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaAudioEffectTest.java index fd939ae08ab3a..34025f69eac84 100644 --- a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaAudioEffectTest.java +++ b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaAudioEffectTest.java @@ -19,12 +19,12 @@ package com.android.mediaframeworktest.functional; import com.android.mediaframeworktest.MediaFrameworkTest; import com.android.mediaframeworktest.MediaNames; import android.content.res.AssetFileDescriptor; -import android.media.AudioEffect; +import android.media.audiofx.AudioEffect; import android.media.AudioFormat; import android.media.AudioManager; import android.media.AudioTrack; -import android.media.EnvironmentalReverb; -import android.media.Equalizer; +import android.media.audiofx.EnvironmentalReverb; +import android.media.audiofx.Equalizer; import android.media.MediaPlayer; import android.os.Looper; @@ -103,14 +103,14 @@ public class MediaAudioEffectTest extends ActivityInstrumentationTestCase2