am 7864c72b: Merge "Fix issue 3022800." into gingerbread

Merge commit '7864c72b91a21eeb282e2e38d688fbbc3cd3ecb8' into gingerbread-plus-aosp

* commit '7864c72b91a21eeb282e2e38d688fbbc3cd3ecb8':
  Fix issue 3022800.

10 files changed, 207 insertions, 88 deletions

diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java
index 7469133..b97c3c4 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)}.
-     * <p>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
+     * <p>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.
-     * <p>To detach the effect from the audio track, call this method with a null effect id.
+     * <p>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 280def9..cb46a29 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)}.
-     * <p>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.
+     * <p>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.
      * <p>To detach the effect from the player, call this method with a null effect id.
      * <p>This method must be called after one of the overloaded <code> setDataSource </code>
      * methods.
diff --git a/media/java/android/media/AudioEffect.java b/media/java/android/media/audiofx/AudioEffect.java
index ed7601e..3e54627 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.
- * <p>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.
- * <p>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.
- * <p>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.
+ * <p>Applications should not use the AudioEffect class directly but one of its derived classes to
+ * control specific effects:
+ * <ul>
+ *   <li> {@link android.media.audiofx.Equalizer}</li>
+ *   <li> {@link android.media.audiofx.Virtualizer}</li>
+ *   <li> {@link android.media.audiofx.BassBoost}</li>
+ *   <li> {@link android.media.audiofx.PresetReverb}</li>
+ *   <li> {@link android.media.audiofx.EnvironmentalReverb}</li>
+ * </ul>
+ * <p>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.
+ * <p>Creating an effect on the output mix (audio session 0) requires permission
+ * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
+ * <p>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.
+ * <p>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:<br>
+     * The effect descriptor contains information on a particular effect implemented in the
+     * audio framework:<br>
      * <ul>
-     *  <li>mType: UUID corresponding to the OpenSL ES interface implemented by this effect</li>
-     *  <li>mUuid: UUID for this particular implementation</li>
-     *  <li>mConnectMode: {@link #EFFECT_INSERT} or {@link #EFFECT_AUXILIARY}</li>
-     *  <li>mName: human readable effect name</li>
-     *  <li>mImplementor: human readable effect implementor name</li>
+     *  <li>type: UUID corresponding to the OpenSL ES interface implemented by this effect</li>
+     *  <li>uuid: UUID for this particular implementation</li>
+     *  <li>connectMode: {@link #EFFECT_INSERT} or {@link #EFFECT_AUXILIARY}</li>
+     *  <li>name: human readable effect name</li>
+     *  <li>implementor: human readable effect implementor name</li>
      * </ul>
+     * 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.
      * <p>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
index 476b056..ca55f0f 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.
- * <p>An application creates a BassBoost object to instantiate and control a bass boost engine
- * in the audio framework.
+ * <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. If the audio session ID 0
- * is specified, the BassBoost applies to the main audio output mix.
- * <p> 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.
+ * <p>Creating a BassBoost on the output mix (audio session 0) requires permission
+ * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
+ * <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 {
@@ -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
index b50febc..f1f582e 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.
  * <p>An application creates a EnvironmentalReverb object to instantiate and control a reverb engine
  * in the audio framework.
  * <p>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.
- * <p> See {@link android.media.AudioEffect} class for more details on controlling
+ * <p>Creating a reverb on the output mix (audio session 0) requires permission
+ * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
+ * <p>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
index 6fa48c5..b3bafa9 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;
  * <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. If the audio session ID 0
  * is specified, the Equalizer applies to the main audio output mix.
- * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
+ * <p>Creating an Equalizer on the output mix (audio session 0) requires permission
+ * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
+ * <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 {
@@ -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
index 65175ff..7a89ae7 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.
  * <p>An application creates a PresetReverb object to instantiate and control a reverb engine in the
  * audio framework.
  * <p>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.
- * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
+ * <p>Creating a reverb on the output mix (audio session 0) requires permission
+ * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
+ * <p>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
index b08f36e..a682a45 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;
  * <p>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.
- * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
+ * <p>Creating a Virtualizer on the output mix (audio session 0) requires permission
+ * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
+ * <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 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
index 33222ff..0c48556 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:<br>
  * <ul>
  *   <li>If the session is 0, the audio output mix is visualized</li>
- *   <li>If the session is not 0, the audio from a particular {@link MediaPlayer} or
- *   {@link AudioTrack}
+ *   <li>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 </li>
  * </ul>
  * <p>Two types of representation of audio content can be captured: <br>
@@ -57,6 +57,8 @@ import android.os.Message;
  * When data capture is not needed any more, the Visualizer should be disabled.
  * <p>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.
+ * <p>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 0000000..c6e4892
--- /dev/null
+++ b/media/java/android/media/audiofx/package.html
@@ -0,0 +1,5 @@
+<HTML>
+<BODY>
+Provides classes that manage audio effects implemented in the media framework.
+</BODY>
+</HTML>