Merge "NEW_API: Unhide audio effect APIs." into gingerbread (1340ee8a) · Commits · e / os / android_frameworks_base

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