Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 17cb280e authored by Eric Laurent's avatar Eric Laurent
Browse files

NEW_API: Unhide audio effect APIs. 

This change unhides all public APIs for controling audio effects exposed
by the following classes:
- AudioEffect
- BassBoost
- EnvironmentalReverb
- Equalizer
- PresetReverb
- Virtualizer
- Visualizer

Also fixes several problems in javadoc.

Change-Id: I541ee4ad0232312ec720545737cbcdb8c9a82597
parent 23796e3b

api/current.xml

+5539 −2208

File changed.

Preview size limit exceeded, changes collapsed.

media/java/android/media/AudioEffect.java

+23 −25
Original line number Diff line number Diff line
@@ -42,8 +42,6 @@ import java.util.UUID; 
 * <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.

 *

 * { @hide Pending API council review }

 */

public class AudioEffect {

    static {
@@ -107,15 +105,15 @@ public class AudioEffect { 
    /**

     * Event id for engine state change notification.

     */

    protected static final int NATIVE_EVENT_ENABLED_STATUS = 0;

    public static final int NATIVE_EVENT_ENABLED_STATUS = 0;

    /**

     * Event id for engine control ownership change notification.

     */

    protected static final int NATIVE_EVENT_CONTROL_STATUS = 1;

    public static final int NATIVE_EVENT_CONTROL_STATUS = 1;

    /**

     * Event id for engine parameter change notification.

     */

    protected static final int NATIVE_EVENT_PARAMETER_CHANGED = 2;

    public static final int NATIVE_EVENT_PARAMETER_CHANGED = 2;



    /**

     * Successful operation.
@@ -203,15 +201,15 @@ public class AudioEffect { 
    /**

     * Indicates the state of the AudioEffect instance

     */

    protected int mState = STATE_UNINITIALIZED;

    private int mState = STATE_UNINITIALIZED;

    /**

     * Lock to synchronize access to mState

     */

    protected final Object mStateLock = new Object();

    private final Object mStateLock = new Object();

    /**

     * System wide unique effect ID

     */

    protected int mId;

    private int mId;



    // accessed by native methods

    private int mNativeAudioEffect;
@@ -227,27 +225,27 @@ public class AudioEffect { 
     *

     * @see #setEnableStatusListener(OnEnableStatusChangeListener)

     */

    protected OnEnableStatusChangeListener mEnableStatusChangeListener = null;

    private OnEnableStatusChangeListener mEnableStatusChangeListener = null;

    /**

     * Listener for effect engine control ownership change notifications.

     *

     * @see #setControlStatusListener(OnControlStatusChangeListener)

     */

    protected OnControlStatusChangeListener mControlChangeStatusListener = null;

    private OnControlStatusChangeListener mControlChangeStatusListener = null;

    /**

     * Listener for effect engine control ownership change notifications.

     *

     * @see #setParameterListener(OnParameterChangeListener)

     */

    protected OnParameterChangeListener mParameterChangeListener = null;

    private OnParameterChangeListener mParameterChangeListener = null;

    /**

     * Lock to protect listeners updates against event notifications

     */

    protected final Object mListenerLock = new Object();

    public final Object mListenerLock = new Object();

    /**

     * Handler for events coming from the native code

     */

    protected NativeEventHandler mNativeEventHandler = null;

    public NativeEventHandler mNativeEventHandler = null;



    // --------------------------------------------------------------------------

    // Constructor, Finalize
@@ -275,7 +273,7 @@ public class AudioEffect { 
     *            how much the requesting application needs control of effect

     *            parameters. The normal priority is 0, above normal is a

     *            positive number, below normal a negative number.

     * @param audioSession System wide unique audio session identifier. If audioSession

     * @param audioSession system wide unique audio session identifier. If audioSession

     *            is not 0, the effect will be attached to the MediaPlayer or

     *            AudioTrack in the same audio session. Otherwise, the effect

     *            will apply to the output mix.
@@ -337,7 +335,7 @@ public class AudioEffect { 
    /**

     * Get the effect descriptor.

     *

     //TODO when AudioEffect class is unhidden @ see android.media.AudioEffect.Descriptor

     * @see android.media.AudioEffect.Descriptor

     * @throws IllegalStateException

     */

    public Descriptor getDescriptor() throws IllegalStateException {
@@ -351,7 +349,7 @@ public class AudioEffect { 


    /**

     * Query all effects available on the platform. Returns an array of

     //TODO when AudioEffect class is unhidden: {@ link android.media.AudioEffect.Descriptor} objects

     * {@link android.media.AudioEffect.Descriptor} objects

     *

     * @throws IllegalStateException

     */
@@ -967,7 +965,7 @@ public class AudioEffect { 
    // Utility methods

    // ------------------



    protected void checkState(String methodName) throws IllegalStateException {

    public void checkState(String methodName) throws IllegalStateException {

        synchronized (mStateLock) {

            if (mState != STATE_INITIALIZED) {

                throw (new IllegalStateException(methodName
@@ -976,7 +974,7 @@ public class AudioEffect { 
        }

    }



    protected void checkStatus(int status) {

    public void checkStatus(int status) {

        switch (status) {

        case AudioEffect.SUCCESS:

            break;
@@ -991,37 +989,37 @@ public class AudioEffect { 
        }

    }



    protected int byteArrayToInt(byte[] valueBuf) {

    public int byteArrayToInt(byte[] valueBuf) {

        return byteArrayToInt(valueBuf, 0);



    }



    protected int byteArrayToInt(byte[] valueBuf, int offset) {

    public int byteArrayToInt(byte[] valueBuf, int offset) {

        ByteBuffer converter = ByteBuffer.wrap(valueBuf);

        converter.order(ByteOrder.nativeOrder());

        return converter.getInt(offset);



    }



    protected byte[] intToByteArray(int value) {

    public byte[] intToByteArray(int value) {

        ByteBuffer converter = ByteBuffer.allocate(4);

        converter.order(ByteOrder.nativeOrder());

        converter.putInt(value);

        return converter.array();

    }



    protected short byteArrayToShort(byte[] valueBuf) {

    public short byteArrayToShort(byte[] valueBuf) {

        return byteArrayToShort(valueBuf, 0);

    }



    protected short byteArrayToShort(byte[] valueBuf, int offset) {

    public short byteArrayToShort(byte[] valueBuf, int offset) {

        ByteBuffer converter = ByteBuffer.wrap(valueBuf);

        converter.order(ByteOrder.nativeOrder());

        return converter.getShort(offset);



    }



    protected byte[] shortToByteArray(short value) {

    public byte[] shortToByteArray(short value) {

        ByteBuffer converter = ByteBuffer.allocate(2);

        converter.order(ByteOrder.nativeOrder());

        short sValue = (short) value;
@@ -1029,7 +1027,7 @@ public class AudioEffect { 
        return converter.array();

    }



    protected byte[] concatArrays(byte[]... arrays) {

    public byte[] concatArrays(byte[]... arrays) {

        int len = 0;

        for (byte[] a : arrays) {

            len += a.length;

media/java/android/media/AudioTrack.java

+2 −12
Original line number Diff line number Diff line
@@ -298,8 +298,6 @@ public class AudioTrack 
     * @param mode streaming or static buffer. See {@link #MODE_STATIC} and {@link #MODE_STREAM}

     * @param sessionId Id of audio session the AudioTrack must be attached to

     * @throws java.lang.IllegalArgumentException

     // FIXME: unhide.

     * @hide

     */

    public AudioTrack(int streamType, int sampleRateInHz, int channelConfig, int audioFormat,

            int bufferSizeInBytes, int mode, int sessionId)
@@ -648,9 +646,6 @@ public class AudioTrack 
     * Returns the audio session ID.

     *

     * @return the ID of the audio session this AudioTrack belongs to.

     // FIXME: unhide.

     // FIXME: link to AudioEffect class when public.

     * @hide

     */

    public int getAudioSessionId() {

        return mSessionId;
@@ -972,17 +967,14 @@ public class AudioTrack 
     * 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)}.

     // TODO when AudioEffect are unhidden

     * <p>After creating an auxiliary effect (e.g. {_at_link android.media.EnvironmentalReverb}),

     * retrieve its ID with {_at_link android.media.AudioEffect#getId()} and use it when calling

     * <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 audio track to the effect.

     * <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},

     *    {@link #ERROR_INVALID_OPERATION}, {@link #ERROR_BAD_VALUE}

     // FIXME: unhide.

     * @hide

     */

    public int attachAuxEffect(int effectId) {

        if (mState != STATE_INITIALIZED) {
@@ -1005,8 +997,6 @@ public class AudioTrack 
     * @param level send level scalar

     * @return error code or success, see {@link #SUCCESS},

     *    {@link #ERROR_INVALID_OPERATION}

     // FIXME: unhide.

     * @hide

     */

    public int setAuxEffectSendLevel(float level) {

        if (mState != STATE_INITIALIZED) {

media/java/android/media/BassBoost.java

+7 −10
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2009 The Android Open Source Project

 * Copyright (C) 2010 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.
@@ -40,10 +40,7 @@ import java.util.StringTokenizer; 
 * <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.

 // TODO when AudioEffect is unhidden

 // <p> See {_at_link android.media.AudioEffect} class for more details on controlling audio effects.

 *

 * {@hide Pending API council review}

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

 */



public class BassBoost extends AudioEffect {
@@ -88,7 +85,7 @@ public class BassBoost extends AudioEffect { 
     * engine. As the same engine can be shared by several applications, this parameter indicates

     * how much the requesting application needs control of effect parameters. The normal priority

     * is 0, above normal is a positive number, below normal a negative number.

     * @param audioSession  System wide unique audio session identifier. If audioSession

     * @param audioSession system wide unique audio session identifier. If audioSession

     *  is not 0, the BassBoost will be attached to the MediaPlayer or AudioTrack in the

     *  same audio session. Otherwise, the BassBoost will apply to the output mix.

     *
@@ -121,7 +118,7 @@ public class BassBoost extends AudioEffect { 
     * accuracy for setting the strength, it is allowed to round the given strength to the nearest

     * supported value. You can use the {@link #getRoundedStrength()} method to query the

     * (possibly rounded) value that was actually set.

     * @param strength Strength of the effect. The valid range for strength strength is [0, 1000],

     * @param strength strength of the effect. The valid range for strength strength is [0, 1000],

     * where 0 per mille designates the mildest effect and 1000 per mille designates the strongest.

     * @throws IllegalStateException

     * @throws IllegalArgumentException
@@ -134,7 +131,7 @@ public class BassBoost extends AudioEffect { 


    /**

     * Gets the current strength of the effect.

     * @return The strength of the effect. The valid range for strength is [0, 1000], where 0 per

     * @return the strength of the effect. The valid range for strength is [0, 1000], where 0 per

     * mille designates the mildest effect and 1000 per mille the strongest

     * @throws IllegalStateException

     * @throws IllegalArgumentException
@@ -158,8 +155,7 @@ 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.

         // TODO when AudioEffect is unhidden

         // See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.

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

         */
@@ -282,6 +278,7 @@ public class BassBoost extends AudioEffect { 
    /**

     * Sets the bass boost properties. This method is useful when bass boost settings have to

     * be applied from a previous backup.

     * @param settings a BassBoost.Settings object containing the properties to apply

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException

media/java/android/media/EnvironmentalReverb.java

+19 −23
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2009 The Android Open Source Project

 * Copyright (C) 2010 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.
@@ -39,8 +39,7 @@ import java.util.StringTokenizer; 
 * 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

 // TODO when PresetReverb is unhidden

 // {_at_link android.media.PresetReverb} class.

 * {@link android.media.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
@@ -52,11 +51,8 @@ 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.

 // TODO when AudioEffect is unhidden

 // <p> See {_at_link android.media.AudioEffect} class for more details on controlling

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

 * audio effects.

 *

 * {@hide Pending API council review}

 */



public class EnvironmentalReverb extends AudioEffect {
@@ -67,8 +63,7 @@ public class EnvironmentalReverb extends AudioEffect { 
    // frameworks/base/include/media/EffectEnvironmentalReverbApi.h



    /**

     * Room level. Parameter ID for

     * {@link android.media.EnvironmentalReverb.OnParameterChangeListener}

     * Room level. Parameter ID for OnParameterChangeListener

     */

    public static final int PARAM_ROOM_LEVEL = 0;

    /**
@@ -80,7 +75,8 @@ public class EnvironmentalReverb extends AudioEffect { 
     */

    public static final int PARAM_DECAY_TIME = 2;

    /**

     * Decay HF ratio. Parameter ID for OnParameterChangeListener

     * Decay HF ratio. Parameter ID for

     * {@link android.media.EnvironmentalReverb.OnParameterChangeListener}

     */

    public static final int PARAM_DECAY_HF_RATIO = 3;

    /**
@@ -133,7 +129,7 @@ public class EnvironmentalReverb extends AudioEffect { 
     * EnvironmentalReverb engine. As the same engine can be shared by several applications, this

     * parameter indicates how much the requesting application needs control of effect parameters.

     * The normal priority is 0, above normal is a positive number, below normal a negative number.

     * @param audioSession  System wide unique audio session identifier. If audioSession

     * @param audioSession  system wide unique audio session identifier. If audioSession

     *  is not 0, the EnvironmentalReverb will be attached to the MediaPlayer or AudioTrack in the

     *  same audio session. Otherwise, the EnvironmentalReverb will apply to the output mix.

     *  As the EnvironmentalReverb is an auxiliary effect it is recommended to instantiate it on
@@ -150,7 +146,7 @@ public class EnvironmentalReverb extends AudioEffect { 


    /**

     * Sets the master volume level of the environmental reverb effect.

     * @param room Room level in millibels. The valid range is [-9000, 0].

     * @param room room level in millibels. The valid range is [-9000, 0].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -179,7 +175,7 @@ public class EnvironmentalReverb extends AudioEffect { 
     * Sets the volume level at 5 kHz relative to the volume level at low frequencies of the

     * overall reverb effect.

     * <p>This controls a low-pass filter that will reduce the level of the high-frequency.

     * @param roomHF High frequency attenuation level in millibels. The valid range is [-9000, 0].

     * @param roomHF high frequency attenuation level in millibels. The valid range is [-9000, 0].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -206,7 +202,7 @@ public class EnvironmentalReverb extends AudioEffect { 


    /**

     * Sets the time taken for the level of reverberation to decay by 60 dB.

     * @param decayTime Decay time in milliseconds. The valid range is [100, 20000].

     * @param decayTime decay time in milliseconds. The valid range is [100, 20000].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -234,7 +230,7 @@ public class EnvironmentalReverb extends AudioEffect { 
    /**

     * Sets the ratio of high frequency decay time (at 5 kHz) relative to the decay time at low

     * frequencies.

     * @param decayHFRatio High frequency decay ratio using a permille scale. The valid range is

     * @param decayHFRatio high frequency decay ratio using a permille scale. The valid range is

     * [100, 2000]. A ratio of 1000 indicates that all frequencies decay at the same rate.

     * @throws IllegalStateException

     * @throws IllegalArgumentException
@@ -264,7 +260,7 @@ public class EnvironmentalReverb extends AudioEffect { 
     * Sets the volume level of the early reflections.

     * <p>This level is combined with the overall room level

     * (set using {@link #setRoomLevel(short)}).

     * @param reflectionsLevel Reflection level in millibels. The valid range is [-9000, 1000].

     * @param reflectionsLevel reflection level in millibels. The valid range is [-9000, 1000].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -293,7 +289,7 @@ public class EnvironmentalReverb extends AudioEffect { 
     * Sets the delay time for the early reflections.

     * <p>This method sets the time between when the direct path is heard and when the first

     * reflection is heard.

     * @param reflectionsDelay Reflections delay in milliseconds. The valid range is [0, 300].

     * @param reflectionsDelay reflections delay in milliseconds. The valid range is [0, 300].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -321,7 +317,7 @@ public class EnvironmentalReverb extends AudioEffect { 
    /**

     * Sets the volume level of the late reverberation.

     * <p>This level is combined with the overall room level (set using {@link #setRoomLevel(short)}).

     * @param reverbLevel Reverb level in millibels. The valid range is [-9000, 2000].

     * @param reverbLevel reverb level in millibels. The valid range is [-9000, 2000].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -348,7 +344,7 @@ public class EnvironmentalReverb extends AudioEffect { 


    /**

     * Sets the time between the first reflection and the reverberation.

     * @param reverbDelay Reverb delay in milliseconds. The valid range is [0, 100].

     * @param reverbDelay reverb delay in milliseconds. The valid range is [0, 100].

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException
@@ -376,7 +372,7 @@ public class EnvironmentalReverb extends AudioEffect { 
    /**

     * Sets the echo density in the late reverberation decay.

     * <p>The scale should approximately map linearly to the perceived change in reverberation.

     * @param diffusion Diffusion specified using a permille scale. The diffusion valid range is

     * @param diffusion diffusion specified using a permille scale. The diffusion valid range is

     * [0, 1000]. A value of 1000 o/oo indicates a smooth reverberation decay.

     * Values below this level give a more <i>grainy</i> character.

     * @throws IllegalStateException
@@ -409,7 +405,7 @@ public class EnvironmentalReverb extends AudioEffect { 
     * <p> The scale should approximately map linearly to the perceived change in reverberation.

     * A lower density creates a hollow sound that is useful for simulating small reverberation

     * spaces such as bathrooms.

     * @param density Density specified using a permille scale. The valid range is [0, 1000].

     * @param density density specified using a permille scale. The valid range is [0, 1000].

     * A value of 1000 o/oo indicates a natural sounding reverberation. Values below this level

     * produce a more colored effect.

     * @throws IllegalStateException
@@ -448,8 +444,7 @@ 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.

         // TODO when AudioEffect is unhidden

         // See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.

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

         */
@@ -649,6 +644,7 @@ public class EnvironmentalReverb extends AudioEffect { 
    /**

     * Sets the environmental reverb properties. This method is useful when reverb settings have to

     * be applied from a previous backup.

     * @param settings a EnvironmentalReverb.Settings object containing the properties to apply

     * @throws IllegalStateException

     * @throws IllegalArgumentException

     * @throws UnsupportedOperationException