Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 1340ee8a: Merge "NEW_API: Unhide audio effect APIs." into gingerbread

Browse Source 
Merge commit '1340ee8a273a9b25a779f3b18d6f832ce496c68e' into gingerbread-plus-aosp

* commit '1340ee8a273a9b25a779f3b18d6f832ce496c68e':
  NEW_API: Unhide audio effect APIs.
This commit is contained in:
Eric Laurent
2010-08-04 08:52:27 -07:00
committed by Android Git Automerger
parent 9ee17b7dec 1340ee8a27
commit acc4e6838d
10 changed files with 3479 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3331
api/current.xml
View File

File diff suppressed because it is too large Load Diff

48
media/java/android/media/AudioEffect.java
View File

@@ -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;

14
media/java/android/media/AudioTrack.java
View File

@@ -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) {

17
media/java/android/media/BassBoost.java
View File

@@ -1,5 +1,5 @@
/*
* 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

42
media/java/android/media/EnvironmentalReverb.java
View File

@@ -1,5 +1,5 @@
/*
* 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

59
media/java/android/media/Equalizer.java
View File

@@ -1,5 +1,5 @@
/*
* 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.
@@ -41,10 +41,7 @@ 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.
// 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 Equalizer extends AudioEffect {
@@ -54,7 +51,7 @@ public class Equalizer extends AudioEffect {
// These constants must be synchronized with those in
// frameworks/base/include/media/EffectEqualizerApi.h
/**
* Number of bands. Parameter ID for {@link android.media.Equalizer.OnParameterChangeListener}
* Number of bands. Parameter ID for OnParameterChangeListener
*/
public static final int PARAM_NUM_BANDS = 0;
/**
@@ -70,11 +67,13 @@ public class Equalizer extends AudioEffect {
*/
public static final int PARAM_CENTER_FREQ = 3;
/**
* Band frequency range. Parameter ID for OnParameterChangeListener
* Band frequency range. Parameter ID for
* {@link android.media.Equalizer.OnParameterChangeListener}
*/
public static final int PARAM_BAND_FREQ_RANGE = 4;
/**
* Band for a given frequency. Parameter ID for OnParameterChangeListener
*
*/
public static final int PARAM_GET_BAND = 5;
/**
@@ -92,7 +91,7 @@ public class Equalizer extends AudioEffect {
// used by setProperties()/getProperties
private static final int PARAM_PROPERTIES = 9;
/**
* maximum size for perset name
* Maximum size for preset name
*/
public static final int PARAM_STRING_SIZE_MAX = 32;
@@ -131,7 +130,7 @@ public class Equalizer 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 Equalizer will be attached to the MediaPlayer or AudioTrack in the
* same audio session. Otherwise, the Equalizer will apply to the output mix.
*
@@ -189,7 +188,7 @@ public class Equalizer extends AudioEffect {
}
/**
* Gets the level range for use by {@link #setBandLevel(int,short)}. The level is expressed in
* Gets the level range for use by {@link #setBandLevel(short,short)}. The level is expressed in
* milliBel.
* @return the band level range in an array of short integers. The first element is the lower
* limit of the range, the second element the upper limit.
@@ -206,13 +205,14 @@ public class Equalizer extends AudioEffect {
/**
* Sets the given equalizer band to the given gain value.
* @param band Frequency band that will have the new gain. The numbering of the bands starts
* from 0 and ends at (number of bands - 1). See @see #getNumberOfBands().
* @param level New gain in millibels that will be set to the given band. getBandLevelRange()
* @param band frequency band that will have the new gain. The numbering of the bands starts
* from 0 and ends at (number of bands - 1).
* @param level new gain in millibels that will be set to the given band. getBandLevelRange()
* will define the maximum and minimum values.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
* @see #getNumberOfBands()
*/
public void setBandLevel(short band, short level)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
@@ -227,9 +227,9 @@ public class Equalizer extends AudioEffect {
/**
* Gets the gain set for the given equalizer band.
* @param band Frequency band whose gain is requested. The numbering of the bands starts
* @param band frequency band whose gain is requested. The numbering of the bands starts
* from 0 and ends at (number of bands - 1).
* @return Gain in millibels of the given band.
* @return the gain in millibels of the given band.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -249,9 +249,9 @@ public class Equalizer extends AudioEffect {
/**
* Gets the center frequency of the given band.
* @param band Frequency band whose center frequency is requested. The numbering of the bands
* @param band frequency band whose center frequency is requested. The numbering of the bands
* starts from 0 and ends at (number of bands - 1).
* @return The center frequency in milliHertz
* @return the center frequency in milliHertz
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -270,9 +270,9 @@ public class Equalizer extends AudioEffect {
/**
* Gets the frequency range of the given frequency band.
* @param band Frequency band whose frequency range is requested. The numbering of the bands
* @param band frequency band whose frequency range is requested. The numbering of the bands
* starts from 0 and ends at (number of bands - 1).
* @return The frequency range in millHertz in an array of integers. The first element is the
* @return the frequency range in millHertz in an array of integers. The first element is the
* lower limit of the range, the second element the upper limit.
* @throws IllegalStateException
* @throws IllegalArgumentException
@@ -291,8 +291,8 @@ public class Equalizer extends AudioEffect {
/**
* Gets the band that has the most effect on the given frequency.
* @param frequency Frequency in milliHertz which is to be equalized via the returned band.
* @return Frequency band that has most effect on the given frequency.
* @param frequency frequency in milliHertz which is to be equalized via the returned band.
* @return the frequency band that has most effect on the given frequency.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -311,7 +311,7 @@ public class Equalizer extends AudioEffect {
/**
* Gets current preset.
* @return Preset that is set at the moment.
* @return the preset that is set at the moment.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -325,11 +325,12 @@ public class Equalizer extends AudioEffect {
/**
* Sets the equalizer according to the given preset.
* @param preset New preset that will be taken into use. The valid range is [0,
* number of presets-1]. See {@see #getNumberOfPresets()}.
* @param preset new preset that will be taken into use. The valid range is [0,
* number of presets-1].
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
* @see #getNumberOfPresets()
*/
public void usePreset(short preset)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
@@ -339,7 +340,7 @@ public class Equalizer extends AudioEffect {
/**
* Gets the total number of presets the equalizer supports. The presets will have indices
* [0, number of presets-1].
* @return The number of presets the equalizer supports.
* @return the number of presets the equalizer supports.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -353,8 +354,8 @@ public class Equalizer extends AudioEffect {
/**
* Gets the preset name based on the index.
* @param preset Index of the preset. The valid range is [0, number of presets-1].
* @return A string containing the name of the given preset.
* @param preset index of the preset. The valid range is [0, number of presets-1].
* @return a string containing the name of the given preset.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -379,8 +380,7 @@ 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.
// TODO when AudioEffect is unhidden
// See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.
* 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.
@@ -539,6 +539,7 @@ public class Equalizer extends AudioEffect {
/**
* Sets the equalizer properties. This method is useful when equalizer settings have to
* be applied from a previous backup.
* @param settings an Equalizer.Settings object containing the properties to apply
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException

63
media/java/android/media/MediaPlayer.java
View File

@@ -273,6 +273,16 @@ import java.lang.ref.WeakReference;
* <td>Valid Sates </p></td>
* <td>Invalid States </p></td>
* <td>Comments </p></td></tr>
* <tr><td>attachAuxEffect </p></td>
* <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
* <td>{Idle, Error} </p></td>
* <td>This method must be called after setDataSource.
* Calling it does not change the object state. </p></td></tr>
* <tr><td>getAudioSessionId </p></td>
* <td>any </p></td>
* <td>{} </p></td>
* <td>This method can be called in any state and calling it does not change
* the object state. </p></td></tr>
* <tr><td>getCurrentPosition </p></td>
* <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
* PlaybackCompleted} </p></td>
@@ -340,6 +350,12 @@ import java.lang.ref.WeakReference;
* <td>Successful invoke of this method in a valid state does not change
* the state. Calling this method in an invalid state transfers the
* object to the <em>Error</em> state. </p></td></tr>
* <tr><td>setAudioSessionId </p></td>
* <td>{Idle} </p></td>
* <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
* Error} </p></td>
* <td>This method must be called in idle state as the audio session ID must be known before
* calling setDataSource. Calling it does not change the object state. </p></td></tr>
* <tr><td>setAudioStreamType </p></td>
* <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
* PlaybackCompleted}</p></td>
@@ -347,6 +363,10 @@ import java.lang.ref.WeakReference;
* <td>Successful invoke of this method does not change the state. In order for the
* target audio stream type to become effective, this method must be called before
* prepare() or prepareAsync().</p></td></tr>
* <tr><td>setAuxEffectSendLevel </p></td>
* <td>any</p></td>
* <td>{} </p></td>
* <td>Calling this method does not change the object state. </p></td></tr>
* <tr><td>setDataSource </p></td>
* <td>{Idle} </p></td>
* <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
@@ -423,26 +443,6 @@ import java.lang.ref.WeakReference;
* <td>Successful invoke of this method in a valid state transfers the
* object to the <em>Stopped</em> state. Calling this method in an
* invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
* <tr><td>setAudioSessionId </p></td>
* <td>{Idle} </p></td>
* <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
* Error} </p></td>
* <td>This method must be called in idle state as the audio session ID must be known before
* calling setDataSource. Calling it does not change the object state. </p></td></tr>
* <tr><td>getAudioSessionId </p></td>
* <td>any </p></td>
* <td>{} </p></td>
* <td>This method can be called in any state and calling it does not change
* the object state. </p></td></tr>
* <tr><td>attachAuxEffect </p></td>
* <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
* <td>{Idle, Error} </p></td>
* <td>This method must be called after setDataSource.
* Calling it does not change the object state. </p></td></tr>
* <tr><td>setAuxEffectSendLevel </p></td>
* <td>any</p></td>
* <td>{} </p></td>
* <td>Calling this method does not change the object state. </p></td></tr>
*
* </table>
*
@@ -1182,7 +1182,7 @@ public class MediaPlayer
/**
* Sets the audio session ID.
*
* @param sessionId: the audio session ID.
* @param sessionId the audio session ID.
* The audio session ID is a system wide unique identifier for the audio stream played by
* this MediaPlayer instance.
* The primary use of the audio session ID is to associate audio effects to a particular
@@ -1194,20 +1194,14 @@ public class MediaPlayer
* by calling this method.
* This method must be called before one of the overloaded <code> setDataSource </code> methods.
* @throws IllegalStateException if it is called in an invalid state
*
// FIXME: unhide.
// TODO when AudioEffect is unhidden
* @hide
*/
public native void setAudioSessionId(int sessionId) throws IllegalArgumentException, IllegalStateException;
/**
* Returns the audio session ID.
*
* @return the audio session ID. {@see #setAudioSessionId(int)}.
* @return the audio session ID. {@see #setAudioSessionId(int)}
* Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed.
// FIXME: unhide.
* @hide
*/
public native int getAudioSessionId();
@@ -1217,16 +1211,13 @@ public class MediaPlayer
* energy to this effect. This amount is defined by setAuxEffectSendLevel().
* {@see #setAuxEffectSendLevel(float)}.
// TODO when AudioEffect is 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 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.
*
* @param effectId system wide unique id of the effect to attach
// FIXME: unhide.
* @hide
*/
public native void attachAuxEffect(int effectId);
@@ -1241,8 +1232,6 @@ public class MediaPlayer
* x == 0 -> level = 0
* 0 < x <= R -> level = 10^(72*(x-R)/20/R)
* @param level send level scalar
// FIXME: unhide.
* @hide
*/
public native void setAuxEffectSendLevel(float level);
@@ -1676,8 +1665,4 @@ public class MediaPlayer
private OnInfoListener mOnInfoListener;
/**
* @hide
*/
public native static int snoop(short [] outData, int kind);
}

41
media/java/android/media/PresetReverb.java
View File

@@ -1,5 +1,5 @@
/*
* 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,8 +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
// TODO when EnvironmentalReverb is unhidden
// {_at_link android.media.EnvironmentalReverb} class.
* {@link android.media.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
@@ -53,10 +52,7 @@ 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 audio effects.
*
* {@hide Pending API council review}
* <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
*/
public class PresetReverb extends AudioEffect {
@@ -73,15 +69,32 @@ public class PresetReverb extends AudioEffect {
public static final int PARAM_PRESET = 0;
/**
* Room level. Parameter ID for
* {@link android.media.PresetReverb.OnParameterChangeListener}
* No reverb or reflections
*/
public static final int PRESET_NONE = 0;
/**
* Reverb preset representing a small room less than five meters in length
*/
public static final int PRESET_SMALLROOM = 1;
/**
* Reverb preset representing a medium room with a length of ten meters or less
*/
public static final int PRESET_MEDIUMROOM = 2;
/**
* Reverb preset representing a large-sized room suitable for live performances
*/
public static final int PRESET_LARGEROOM = 3;
/**
* Reverb preset representing a medium-sized hall
*/
public static final int PRESET_MEDIUMHALL = 4;
/**
* Reverb preset representing a large-sized hall suitable for a full orchestra
*/
public static final int PRESET_LARGEHALL = 5;
/**
* Reverb preset representing a synthesis of the traditional plate reverb
*/
public static final int PRESET_PLATE = 6;
/**
@@ -105,7 +118,7 @@ public class PresetReverb extends AudioEffect {
* PresetReverb 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 PresetReverb will be attached to the MediaPlayer or AudioTrack in the
* same audio session. Otherwise, the PresetReverb will apply to the output mix.
* As the PresetReverb is an auxiliary effect it is recommended to instantiate it on
@@ -125,7 +138,7 @@ public class PresetReverb extends AudioEffect {
* <p>The reverb PRESET_NONE disables any reverb from the current output but does not free the
* resources associated with the reverb. For an application to signal to the implementation
* to free the resources, it must call the release() method.
* @param preset This must be one of the the preset constants defined in this class.
* @param preset this must be one of the the preset constants defined in this class.
* e.g. {@link #PRESET_SMALLROOM}
* @throws IllegalStateException
* @throws IllegalArgumentException
@@ -138,7 +151,7 @@ public class PresetReverb extends AudioEffect {
/**
* Gets current reverb preset.
* @return Preset that is set at the moment.
* @return the preset that is set at the moment.
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
@@ -161,8 +174,7 @@ 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.
// 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_PRESET} ...
* @param value the new parameter value.
*/
@@ -285,6 +297,7 @@ public class PresetReverb extends AudioEffect {
/**
* Sets the preset reverb properties. This method is useful when preset reverb settings have to
* be applied from a previous backup.
* @param settings a PresetReverb.Settings object containing the properties to apply
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException

17
media/java/android/media/Virtualizer.java
View File

@@ -1,5 +1,5 @@
/*
* 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.
@@ -42,10 +42,7 @@ 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.
// 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 Virtualizer extends AudioEffect {
@@ -89,7 +86,7 @@ public class Virtualizer 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 Virtualizer will be attached to the MediaPlayer or AudioTrack in the
* same audio session. Otherwise, the Virtualizer will apply to the output mix.
*
@@ -122,7 +119,7 @@ public class Virtualizer 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
@@ -135,7 +132,7 @@ public class Virtualizer 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
@@ -159,8 +156,7 @@ 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.
// 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.
*/
@@ -283,6 +279,7 @@ public class Virtualizer extends AudioEffect {
/**
* Sets the virtualizer properties. This method is useful when virtualizer settings have to
* be applied from a previous backup.
* @param settings a Virtualizer.Settings object containing the properties to apply
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException

20
media/java/android/media/Visualizer.java
View File

@@ -57,8 +57,6 @@ 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.
*
* {@hide Pending API council review}
*/
public class Visualizer {
@@ -84,8 +82,8 @@ public class Visualizer {
public static final int STATE_ENABLED = 2;
// to keep in sync with frameworks/base/media/jni/audioeffect/android_media_Visualizer.cpp
protected static final int NATIVE_EVENT_PCM_CAPTURE = 0;
protected static final int NATIVE_EVENT_FFT_CAPTURE = 1;
private static final int NATIVE_EVENT_PCM_CAPTURE = 0;
private static final int NATIVE_EVENT_FFT_CAPTURE = 1;
// Error codes:
/**
@@ -127,28 +125,28 @@ public class Visualizer {
/**
* Indicates the state of the Visualizer 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 Identifier of the visualizer engine used by this Visualizer instance
*/
protected int mId;
private int mId;
/**
* Lock to protect listeners updates against event notifications
*/
protected final Object mListenerLock = new Object();
private final Object mListenerLock = new Object();
/**
* Handler for events coming from the native code
*/
protected NativeEventHandler mNativeEventHandler = null;
private NativeEventHandler mNativeEventHandler = null;
/**
* PCM and FFT capture listener registered by client
*/
protected OnDataCaptureListener mCaptureListener = null;
private OnDataCaptureListener mCaptureListener = null;
// accessed by native methods
private int mNativeVisualizer;
@@ -159,7 +157,7 @@ public class Visualizer {
//--------------------
/**
* Class constructor.
* @param audioSession System wide unique audio session identifier. If audioSession
* @param audioSession system wide unique audio session identifier. If audioSession
* is not 0, the visualizer will be attached to the MediaPlayer or AudioTrack in the
* same audio session. Otherwise, the Visualizer will apply to the output mix.
*