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, * <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 * the application must specify the audio session ID of that instance when calling the AudioEffect
* constructor. * constructor.
*
* { @hide Pending API council review }
*/ */
public class AudioEffect { public class AudioEffect {
static { static {
@@ -107,15 +105,15 @@ public class AudioEffect {
/** /**
* Event id for engine state change notification. * 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. * 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. * 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. * Successful operation.
@@ -203,15 +201,15 @@ public class AudioEffect {
/** /**
* Indicates the state of the AudioEffect instance * Indicates the state of the AudioEffect instance
*/ */
protected int mState = STATE_UNINITIALIZED; private int mState = STATE_UNINITIALIZED;
/** /**
* Lock to synchronize access to mState * Lock to synchronize access to mState
*/ */
protected final Object mStateLock = new Object(); private final Object mStateLock = new Object();
/** /**
* System wide unique effect ID * System wide unique effect ID
*/ */
protected int mId; private int mId;
// accessed by native methods // accessed by native methods
private int mNativeAudioEffect; private int mNativeAudioEffect;
@@ -227,27 +225,27 @@ public class AudioEffect {
* *
* @see #setEnableStatusListener(OnEnableStatusChangeListener) * @see #setEnableStatusListener(OnEnableStatusChangeListener)
*/ */
protected OnEnableStatusChangeListener mEnableStatusChangeListener = null; private OnEnableStatusChangeListener mEnableStatusChangeListener = null;
/** /**
* Listener for effect engine control ownership change notifications. * Listener for effect engine control ownership change notifications.
* *
* @see #setControlStatusListener(OnControlStatusChangeListener) * @see #setControlStatusListener(OnControlStatusChangeListener)
*/ */
protected OnControlStatusChangeListener mControlChangeStatusListener = null; private OnControlStatusChangeListener mControlChangeStatusListener = null;
/** /**
* Listener for effect engine control ownership change notifications. * Listener for effect engine control ownership change notifications.
* *
* @see #setParameterListener(OnParameterChangeListener) * @see #setParameterListener(OnParameterChangeListener)
*/ */
protected OnParameterChangeListener mParameterChangeListener = null; private OnParameterChangeListener mParameterChangeListener = null;
/** /**
* Lock to protect listeners updates against event notifications * 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 * Handler for events coming from the native code
*/ */
protected NativeEventHandler mNativeEventHandler = null; public NativeEventHandler mNativeEventHandler = null;
// -------------------------------------------------------------------------- // --------------------------------------------------------------------------
// Constructor, Finalize // Constructor, Finalize
@@ -275,7 +273,7 @@ public class AudioEffect {
* how much the requesting application needs control of effect * how much the requesting application needs control of effect
* parameters. The normal priority is 0, above normal is a * parameters. The normal priority is 0, above normal is a
* positive number, below normal a negative number. * 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 * is not 0, the effect will be attached to the MediaPlayer or
* AudioTrack in the same audio session. Otherwise, the effect * AudioTrack in the same audio session. Otherwise, the effect
* will apply to the output mix. * will apply to the output mix.
@@ -337,7 +335,7 @@ public class AudioEffect {
/** /**
* Get the effect descriptor. * Get the effect descriptor.
* *
//TODO when AudioEffect class is unhidden @ see android.media.AudioEffect.Descriptor * @see android.media.AudioEffect.Descriptor
* @throws IllegalStateException * @throws IllegalStateException
*/ */
public Descriptor getDescriptor() 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 * 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 * @throws IllegalStateException
*/ */
@@ -967,7 +965,7 @@ public class AudioEffect {
// Utility methods // Utility methods
// ------------------ // ------------------
protected void checkState(String methodName) throws IllegalStateException { public void checkState(String methodName) throws IllegalStateException {
synchronized (mStateLock) { synchronized (mStateLock) {
if (mState != STATE_INITIALIZED) { if (mState != STATE_INITIALIZED) {
throw (new IllegalStateException(methodName throw (new IllegalStateException(methodName
@@ -976,7 +974,7 @@ public class AudioEffect {
} }
} }
protected void checkStatus(int status) { public void checkStatus(int status) {
switch (status) { switch (status) {
case AudioEffect.SUCCESS: case AudioEffect.SUCCESS:
break; break;
@@ -991,37 +989,37 @@ public class AudioEffect {
} }
} }
protected int byteArrayToInt(byte[] valueBuf) { public int byteArrayToInt(byte[] valueBuf) {
return byteArrayToInt(valueBuf, 0); return byteArrayToInt(valueBuf, 0);
} }
protected int byteArrayToInt(byte[] valueBuf, int offset) { public int byteArrayToInt(byte[] valueBuf, int offset) {
ByteBuffer converter = ByteBuffer.wrap(valueBuf); ByteBuffer converter = ByteBuffer.wrap(valueBuf);
converter.order(ByteOrder.nativeOrder()); converter.order(ByteOrder.nativeOrder());
return converter.getInt(offset); return converter.getInt(offset);
} }
protected byte[] intToByteArray(int value) { public byte[] intToByteArray(int value) {
ByteBuffer converter = ByteBuffer.allocate(4); ByteBuffer converter = ByteBuffer.allocate(4);
converter.order(ByteOrder.nativeOrder()); converter.order(ByteOrder.nativeOrder());
converter.putInt(value); converter.putInt(value);
return converter.array(); return converter.array();
} }
protected short byteArrayToShort(byte[] valueBuf) { public short byteArrayToShort(byte[] valueBuf) {
return byteArrayToShort(valueBuf, 0); return byteArrayToShort(valueBuf, 0);
} }
protected short byteArrayToShort(byte[] valueBuf, int offset) { public short byteArrayToShort(byte[] valueBuf, int offset) {
ByteBuffer converter = ByteBuffer.wrap(valueBuf); ByteBuffer converter = ByteBuffer.wrap(valueBuf);
converter.order(ByteOrder.nativeOrder()); converter.order(ByteOrder.nativeOrder());
return converter.getShort(offset); return converter.getShort(offset);
} }
protected byte[] shortToByteArray(short value) { public byte[] shortToByteArray(short value) {
ByteBuffer converter = ByteBuffer.allocate(2); ByteBuffer converter = ByteBuffer.allocate(2);
converter.order(ByteOrder.nativeOrder()); converter.order(ByteOrder.nativeOrder());
short sValue = (short) value; short sValue = (short) value;
@@ -1029,7 +1027,7 @@ public class AudioEffect {
return converter.array(); return converter.array();
} }
protected byte[] concatArrays(byte[]... arrays) { public byte[] concatArrays(byte[]... arrays) {
int len = 0; int len = 0;
for (byte[] a : arrays) { for (byte[] a : arrays) {
len += a.length; 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 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 * @param sessionId Id of audio session the AudioTrack must be attached to
* @throws java.lang.IllegalArgumentException * @throws java.lang.IllegalArgumentException
// FIXME: unhide.
* @hide
*/ */
public AudioTrack(int streamType, int sampleRateInHz, int channelConfig, int audioFormat, public AudioTrack(int streamType, int sampleRateInHz, int channelConfig, int audioFormat,
int bufferSizeInBytes, int mode, int sessionId) int bufferSizeInBytes, int mode, int sessionId)
@@ -648,9 +646,6 @@ public class AudioTrack
* Returns the audio session ID. * Returns the audio session ID.
* *
* @return the ID of the audio session this AudioTrack belongs to. * @return the ID of the audio session this AudioTrack belongs to.
// FIXME: unhide.
// FIXME: link to AudioEffect class when public.
* @hide
*/ */
public int getAudioSessionId() { public int getAudioSessionId() {
return mSessionId; return mSessionId;
@@ -972,17 +967,14 @@ public class AudioTrack
* reverberation effect which can be applied on any sound source that directs a certain * 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(). * amount of its energy to this effect. This amount is defined by setAuxEffectSendLevel().
* {@see #setAuxEffectSendLevel(float)}. * {@see #setAuxEffectSendLevel(float)}.
// TODO when AudioEffect are unhidden * <p>After creating an auxiliary effect (e.g. {@link android.media.EnvironmentalReverb}),
* <p>After creating an auxiliary effect (e.g. {_at_link android.media.EnvironmentalReverb}), * retrieve its ID with {@link android.media.AudioEffect#getId()} and use it when calling
* retrieve its ID with {_at_link android.media.AudioEffect#getId()} and use it when calling
* this method to attach the audio track to the effect. * this method to attach the audio track to the effect.
* <p>To detach the effect from the audio track, call this method with a null effect id. * <p>To detach the effect from the audio track, call this method with a null effect id.
* *
* @param effectId system wide unique id of the effect to attach * @param effectId system wide unique id of the effect to attach
* @return error code or success, see {@link #SUCCESS}, * @return error code or success, see {@link #SUCCESS},
* {@link #ERROR_INVALID_OPERATION}, {@link #ERROR_BAD_VALUE} * {@link #ERROR_INVALID_OPERATION}, {@link #ERROR_BAD_VALUE}
// FIXME: unhide.
* @hide
*/ */
public int attachAuxEffect(int effectId) { public int attachAuxEffect(int effectId) {
if (mState != STATE_INITIALIZED) { if (mState != STATE_INITIALIZED) {
@@ -1005,8 +997,6 @@ public class AudioTrack
* @param level send level scalar * @param level send level scalar
* @return error code or success, see {@link #SUCCESS}, * @return error code or success, see {@link #SUCCESS},
* {@link #ERROR_INVALID_OPERATION} * {@link #ERROR_INVALID_OPERATION}
// FIXME: unhide.
* @hide
*/ */
public int setAuxEffectSendLevel(float level) { public int setAuxEffectSendLevel(float level) {
if (mState != STATE_INITIALIZED) { 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"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with 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 * <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 * 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. * is specified, the BassBoost applies to the main audio output mix.
// TODO when AudioEffect is unhidden * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
// <p> See {_at_link android.media.AudioEffect} class for more details on controlling audio effects.
*
* {@hide Pending API council review}
*/ */
public class BassBoost extends AudioEffect { 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 * 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 * 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. * 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 * 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. * 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 * 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 * supported value. You can use the {@link #getRoundedStrength()} method to query the
* (possibly rounded) value that was actually set. * (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. * where 0 per mille designates the mildest effect and 1000 per mille designates the strongest.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -134,7 +131,7 @@ public class BassBoost extends AudioEffect {
/** /**
* Gets the current strength of the effect. * 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 * mille designates the mildest effect and 1000 per mille the strongest
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -158,8 +155,7 @@ public class BassBoost extends AudioEffect {
* BassBoost engine. * BassBoost engine.
* @param effect the BassBoost on which the interface is registered. * @param effect the BassBoost on which the interface is registered.
* @param status status of the set parameter operation. * @param status status of the set parameter operation.
// TODO when AudioEffect is unhidden * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}.
// See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.
* @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ... * @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ...
* @param value the new parameter value. * @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 * Sets the bass boost properties. This method is useful when bass boost settings have to
* be applied from a previous backup. * be applied from a previous backup.
* @param settings a BassBoost.Settings object containing the properties to apply
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with 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 * 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 * global reverb environment and is more suitable for games. For basic control, more suitable for
* music applications, it is recommended to use the * music applications, it is recommended to use the
// TODO when PresetReverb is unhidden * {@link android.media.PresetReverb} class.
// {_at_link android.media.PresetReverb} class.
* <p>An application creates a EnvironmentalReverb object to instantiate and control a reverb engine * <p>An application creates a EnvironmentalReverb object to instantiate and control a reverb engine
* in the audio framework. * in the audio framework.
* <p>The methods, parameter types and units exposed by the EnvironmentalReverb implementation are * <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 * 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 * returned by getId() method to designate this particular effect when attaching it to the
* MediaPlayer or AudioTrack. * MediaPlayer or AudioTrack.
// TODO when AudioEffect is unhidden * <p> See {@link android.media.AudioEffect} class for more details on controlling
// <p> See {_at_link android.media.AudioEffect} class for more details on controlling
* audio effects. * audio effects.
*
* {@hide Pending API council review}
*/ */
public class EnvironmentalReverb extends AudioEffect { public class EnvironmentalReverb extends AudioEffect {
@@ -67,8 +63,7 @@ public class EnvironmentalReverb extends AudioEffect {
// frameworks/base/include/media/EffectEnvironmentalReverbApi.h // frameworks/base/include/media/EffectEnvironmentalReverbApi.h
/** /**
* Room level. Parameter ID for * Room level. Parameter ID for OnParameterChangeListener
* {@link android.media.EnvironmentalReverb.OnParameterChangeListener}
*/ */
public static final int PARAM_ROOM_LEVEL = 0; 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; 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; 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 * 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. * 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. * 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 * 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. * 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 * 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. * 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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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 * Sets the volume level at 5 kHz relative to the volume level at low frequencies of the
* overall reverb effect. * overall reverb effect.
* <p>This controls a low-pass filter that will reduce the level of the high-frequency. * <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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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. * 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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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 * Sets the ratio of high frequency decay time (at 5 kHz) relative to the decay time at low
* frequencies. * 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. * [100, 2000]. A ratio of 1000 indicates that all frequencies decay at the same rate.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -264,7 +260,7 @@ public class EnvironmentalReverb extends AudioEffect {
* Sets the volume level of the early reflections. * Sets the volume level of the early reflections.
* <p>This level is combined with the overall room level * <p>This level is combined with the overall room level
* (set using {@link #setRoomLevel(short)}). * (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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -293,7 +289,7 @@ public class EnvironmentalReverb extends AudioEffect {
* Sets the delay time for the early reflections. * 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 * <p>This method sets the time between when the direct path is heard and when the first
* reflection is heard. * 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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -321,7 +317,7 @@ public class EnvironmentalReverb extends AudioEffect {
/** /**
* Sets the volume level of the late reverberation. * Sets the volume level of the late reverberation.
* <p>This level is combined with the overall room level (set using {@link #setRoomLevel(short)}). * <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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -348,7 +344,7 @@ public class EnvironmentalReverb extends AudioEffect {
/** /**
* Sets the time between the first reflection and the reverberation. * 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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -376,7 +372,7 @@ public class EnvironmentalReverb extends AudioEffect {
/** /**
* Sets the echo density in the late reverberation decay. * Sets the echo density in the late reverberation decay.
* <p>The scale should approximately map linearly to the perceived change in reverberation. * <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. * [0, 1000]. A value of 1000 o/oo indicates a smooth reverberation decay.
* Values below this level give a more <i>grainy</i> character. * Values below this level give a more <i>grainy</i> character.
* @throws IllegalStateException * @throws IllegalStateException
@@ -409,7 +405,7 @@ public class EnvironmentalReverb extends AudioEffect {
* <p> The scale should approximately map linearly to the perceived change in reverberation. * <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 * A lower density creates a hollow sound that is useful for simulating small reverberation
* spaces such as bathrooms. * 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 * A value of 1000 o/oo indicates a natural sounding reverberation. Values below this level
* produce a more colored effect. * produce a more colored effect.
* @throws IllegalStateException * @throws IllegalStateException
@@ -448,8 +444,7 @@ public class EnvironmentalReverb extends AudioEffect {
* EnvironmentalReverb engine. * EnvironmentalReverb engine.
* @param effect the EnvironmentalReverb on which the interface is registered. * @param effect the EnvironmentalReverb on which the interface is registered.
* @param status status of the set parameter operation. * @param status status of the set parameter operation.
// TODO when AudioEffect is unhidden * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}.
// See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.
* @param param ID of the modified parameter. See {@link #PARAM_ROOM_LEVEL} ... * @param param ID of the modified parameter. See {@link #PARAM_ROOM_LEVEL} ...
* @param value the new parameter value. * @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 * Sets the environmental reverb properties. This method is useful when reverb settings have to
* be applied from a previous backup. * be applied from a previous backup.
* @param settings a EnvironmentalReverb.Settings object containing the properties to apply
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with 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 * <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 * 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. * is specified, the Equalizer applies to the main audio output mix.
// TODO when AudioEffect is unhidden * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
// <p> See {_at_link android.media.AudioEffect} class for more details on controlling audio effects.
*
* {@hide Pending API council review}
*/ */
public class Equalizer extends AudioEffect { public class Equalizer extends AudioEffect {
@@ -54,7 +51,7 @@ public class Equalizer extends AudioEffect {
// These constants must be synchronized with those in // These constants must be synchronized with those in
// frameworks/base/include/media/EffectEqualizerApi.h // 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; 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; 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; public static final int PARAM_BAND_FREQ_RANGE = 4;
/** /**
* Band for a given frequency. Parameter ID for OnParameterChangeListener * Band for a given frequency. Parameter ID for OnParameterChangeListener
*
*/ */
public static final int PARAM_GET_BAND = 5; public static final int PARAM_GET_BAND = 5;
/** /**
@@ -92,7 +91,7 @@ public class Equalizer extends AudioEffect {
// used by setProperties()/getProperties // used by setProperties()/getProperties
private static final int PARAM_PROPERTIES = 9; 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; 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 * 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 * 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. * 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 * 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. * 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. * milliBel.
* @return the band level range in an array of short integers. The first element is the lower * @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. * 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. * 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 * @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(). * from 0 and ends at (number of bands - 1).
* @param level New gain in millibels that will be set to the given band. getBandLevelRange() * @param level new gain in millibels that will be set to the given band. getBandLevelRange()
* will define the maximum and minimum values. * will define the maximum and minimum values.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
* @see #getNumberOfBands()
*/ */
public void setBandLevel(short band, short level) public void setBandLevel(short band, short level)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
@@ -227,9 +227,9 @@ public class Equalizer extends AudioEffect {
/** /**
* Gets the gain set for the given equalizer band. * 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). * 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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -249,9 +249,9 @@ public class Equalizer extends AudioEffect {
/** /**
* Gets the center frequency of the given band. * 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). * 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 IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -270,9 +270,9 @@ public class Equalizer extends AudioEffect {
/** /**
* Gets the frequency range of the given frequency band. * 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). * 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. * lower limit of the range, the second element the upper limit.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -291,8 +291,8 @@ public class Equalizer extends AudioEffect {
/** /**
* Gets the band that has the most effect on the given frequency. * 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. * @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. * @return the frequency band that has most effect on the given frequency.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -311,7 +311,7 @@ public class Equalizer extends AudioEffect {
/** /**
* Gets current preset. * Gets current preset.
* @return Preset that is set at the moment. * @return the preset that is set at the moment.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -325,11 +325,12 @@ public class Equalizer extends AudioEffect {
/** /**
* Sets the equalizer according to the given preset. * Sets the equalizer according to the given preset.
* @param preset New preset that will be taken into use. The valid range is [0, * @param preset new preset that will be taken into use. The valid range is [0,
* number of presets-1]. See {@see #getNumberOfPresets()}. * number of presets-1].
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
* @see #getNumberOfPresets()
*/ */
public void usePreset(short preset) public void usePreset(short preset)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { 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 * Gets the total number of presets the equalizer supports. The presets will have indices
* [0, number of presets-1]. * [0, number of presets-1].
* @return The number of presets the equalizer supports. * @return the number of presets the equalizer supports.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -353,8 +354,8 @@ public class Equalizer extends AudioEffect {
/** /**
* Gets the preset name based on the index. * Gets the preset name based on the index.
* @param preset Index of the preset. The valid range is [0, number of presets-1]. * @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. * @return a string containing the name of the given preset.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -379,8 +380,7 @@ public class Equalizer extends AudioEffect {
* Equalizer engine. * Equalizer engine.
* @param effect the Equalizer on which the interface is registered. * @param effect the Equalizer on which the interface is registered.
* @param status status of the set parameter operation. * @param status status of the set parameter operation.
// TODO when AudioEffect is unhidden * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}.
// See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.
* @param param1 ID of the modified parameter. See {@link #PARAM_BAND_LEVEL} ... * @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 param2 additional parameter qualifier (e.g the band for band level parameter).
* @param value the new parameter value. * @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 * Sets the equalizer properties. This method is useful when equalizer settings have to
* be applied from a previous backup. * be applied from a previous backup.
* @param settings an Equalizer.Settings object containing the properties to apply
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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>Valid Sates </p></td>
* <td>Invalid States </p></td> * <td>Invalid States </p></td>
* <td>Comments </p></td></tr> * <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> * <tr><td>getCurrentPosition </p></td>
* <td>{Idle, Initialized, Prepared, Started, Paused, Stopped, * <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
* PlaybackCompleted} </p></td> * 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 * <td>Successful invoke of this method in a valid state does not change
* the state. Calling this method in an invalid state transfers the * the state. Calling this method in an invalid state transfers the
* object to the <em>Error</em> state. </p></td></tr> * 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> * <tr><td>setAudioStreamType </p></td>
* <td>{Idle, Initialized, Stopped, Prepared, Started, Paused, * <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
* PlaybackCompleted}</p></td> * 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 * <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 * target audio stream type to become effective, this method must be called before
* prepare() or prepareAsync().</p></td></tr> * 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> * <tr><td>setDataSource </p></td>
* <td>{Idle} </p></td> * <td>{Idle} </p></td>
* <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, * <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 * <td>Successful invoke of this method in a valid state transfers the
* object to the <em>Stopped</em> state. Calling this method in an * 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> * 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> * </table>
* *
@@ -1182,7 +1182,7 @@ public class MediaPlayer
/** /**
* Sets the audio session ID. * 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 * The audio session ID is a system wide unique identifier for the audio stream played by
* this MediaPlayer instance. * this MediaPlayer instance.
* The primary use of the audio session ID is to associate audio effects to a particular * 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. * by calling this method.
* This method must be called before one of the overloaded <code> setDataSource </code> methods. * This method must be called before one of the overloaded <code> setDataSource </code> methods.
* @throws IllegalStateException if it is called in an invalid state * @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; public native void setAudioSessionId(int sessionId) throws IllegalArgumentException, IllegalStateException;
/** /**
* Returns the audio session ID. * 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. * 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(); public native int getAudioSessionId();
@@ -1217,16 +1211,13 @@ public class MediaPlayer
* energy to this effect. This amount is defined by setAuxEffectSendLevel(). * energy to this effect. This amount is defined by setAuxEffectSendLevel().
* {@see #setAuxEffectSendLevel(float)}. * {@see #setAuxEffectSendLevel(float)}.
// TODO when AudioEffect is unhidden // TODO when AudioEffect is unhidden
* <p>After creating an auxiliary effect (e.g. {_at_link android.media.EnvironmentalReverb}), * <p>After creating an auxiliary effect (e.g. {@link android.media.EnvironmentalReverb}),
* retrieve its ID with {_at_link android.media.AudioEffect#getId()} and use it when calling * retrieve its ID with {@link android.media.AudioEffect#getId()} and use it when calling
* this method to attach the player to the effect. * 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>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> * <p>This method must be called after one of the overloaded <code> setDataSource </code>
* methods. * methods.
*
* @param effectId system wide unique id of the effect to attach * @param effectId system wide unique id of the effect to attach
// FIXME: unhide.
* @hide
*/ */
public native void attachAuxEffect(int effectId); public native void attachAuxEffect(int effectId);
@@ -1241,8 +1232,6 @@ public class MediaPlayer
* x == 0 -> level = 0 * x == 0 -> level = 0
* 0 < x <= R -> level = 10^(72*(x-R)/20/R) * 0 < x <= R -> level = 10^(72*(x-R)/20/R)
* @param level send level scalar * @param level send level scalar
// FIXME: unhide.
* @hide
*/ */
public native void setAuxEffectSendLevel(float level); public native void setAuxEffectSendLevel(float level);
@@ -1676,8 +1665,4 @@ public class MediaPlayer
private OnInfoListener mOnInfoListener; 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"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with 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. * 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 * 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 * requiring control over a more advanced environmental reverb are advised to use the
// TODO when EnvironmentalReverb is unhidden * {@link android.media.EnvironmentalReverb} class.
// {_at_link android.media.EnvironmentalReverb} class.
* <p>An application creates a PresetReverb object to instantiate and control a reverb engine in the * <p>An application creates a PresetReverb object to instantiate and control a reverb engine in the
* audio framework. * audio framework.
* <p>The methods, parameter types and units exposed by the PresetReverb implementation are * <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 * 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 * returned by getId() method to designate this particular effect when attaching it to the
* MediaPlayer or AudioTrack. * MediaPlayer or AudioTrack.
// TODO when AudioEffect is unhidden * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
// <p> See {_at_link android.media.AudioEffect} class for more details on controlling audio effects.
*
* {@hide Pending API council review}
*/ */
public class PresetReverb extends AudioEffect { public class PresetReverb extends AudioEffect {
@@ -73,15 +69,32 @@ public class PresetReverb extends AudioEffect {
public static final int PARAM_PRESET = 0; public static final int PARAM_PRESET = 0;
/** /**
* Room level. Parameter ID for * No reverb or reflections
* {@link android.media.PresetReverb.OnParameterChangeListener}
*/ */
public static final int PRESET_NONE = 0; 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; 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; 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; public static final int PRESET_LARGEROOM = 3;
/**
* Reverb preset representing a medium-sized hall
*/
public static final int PRESET_MEDIUMHALL = 4; 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; public static final int PRESET_LARGEHALL = 5;
/**
* Reverb preset representing a synthesis of the traditional plate reverb
*/
public static final int PRESET_PLATE = 6; 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 * 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. * 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. * 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 * 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. * 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 * 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 * <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 * resources associated with the reverb. For an application to signal to the implementation
* to free the resources, it must call the release() method. * 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} * e.g. {@link #PRESET_SMALLROOM}
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -138,7 +151,7 @@ public class PresetReverb extends AudioEffect {
/** /**
* Gets current reverb preset. * Gets current reverb preset.
* @return Preset that is set at the moment. * @return the preset that is set at the moment.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
@@ -161,8 +174,7 @@ public class PresetReverb extends AudioEffect {
* PresetReverb engine. * PresetReverb engine.
* @param effect the PresetReverb on which the interface is registered. * @param effect the PresetReverb on which the interface is registered.
* @param status status of the set parameter operation. * @param status status of the set parameter operation.
// TODO when AudioEffect is unhidden * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}.
// See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.
* @param param ID of the modified parameter. See {@link #PARAM_PRESET} ... * @param param ID of the modified parameter. See {@link #PARAM_PRESET} ...
* @param value the new parameter value. * @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 * Sets the preset reverb properties. This method is useful when preset reverb settings have to
* be applied from a previous backup. * be applied from a previous backup.
* @param settings a PresetReverb.Settings object containing the properties to apply
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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"); * Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with 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 * <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 * 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. * is specified, the Virtualizer applies to the main audio output mix.
// TODO when AudioEffect is unhidden * <p> See {@link android.media.AudioEffect} class for more details on controlling audio effects.
// <p> See {_at_link android.media.AudioEffect} class for more details on controlling audio effects.
*
* {@hide Pending API council review}
*/ */
public class Virtualizer extends AudioEffect { 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 * 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 * 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. * 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 * 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. * 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 * 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 * supported value. You can use the {@link #getRoundedStrength()} method to query the
* (possibly rounded) value that was actually set. * (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. * where 0 per mille designates the mildest effect and 1000 per mille designates the strongest.
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -135,7 +132,7 @@ public class Virtualizer extends AudioEffect {
/** /**
* Gets the current strength of the effect. * 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 * mille designates the mildest effect and 1000 per mille the strongest
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
@@ -159,8 +156,7 @@ public class Virtualizer extends AudioEffect {
* Virtualizer engine. * Virtualizer engine.
* @param effect the Virtualizer on which the interface is registered. * @param effect the Virtualizer on which the interface is registered.
* @param status status of the set parameter operation. * @param status status of the set parameter operation.
// TODO when AudioEffect is unhidden * See {@link android.media.AudioEffect#setParameter(byte[], byte[])}.
// See {_at_link android.media.AudioEffect#setParameter(byte[], byte[])}.
* @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ... * @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ...
* @param value the new parameter value. * @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 * Sets the virtualizer properties. This method is useful when virtualizer settings have to
* be applied from a previous backup. * be applied from a previous backup.
* @param settings a Virtualizer.Settings object containing the properties to apply
* @throws IllegalStateException * @throws IllegalStateException
* @throws IllegalArgumentException * @throws IllegalArgumentException
* @throws UnsupportedOperationException * @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. * 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 * <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. * anymore to free up native resources associated to the Visualizer instance.
*
* {@hide Pending API council review}
*/ */
public class Visualizer { public class Visualizer {
@@ -84,8 +82,8 @@ public class Visualizer {
public static final int STATE_ENABLED = 2; public static final int STATE_ENABLED = 2;
// to keep in sync with frameworks/base/media/jni/audioeffect/android_media_Visualizer.cpp // to keep in sync with frameworks/base/media/jni/audioeffect/android_media_Visualizer.cpp
protected static final int NATIVE_EVENT_PCM_CAPTURE = 0; private static final int NATIVE_EVENT_PCM_CAPTURE = 0;
protected static final int NATIVE_EVENT_FFT_CAPTURE = 1; private static final int NATIVE_EVENT_FFT_CAPTURE = 1;
// Error codes: // Error codes:
/** /**
@@ -127,28 +125,28 @@ public class Visualizer {
/** /**
* Indicates the state of the Visualizer instance * Indicates the state of the Visualizer instance
*/ */
protected int mState = STATE_UNINITIALIZED; private int mState = STATE_UNINITIALIZED;
/** /**
* Lock to synchronize access to mState * 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 * 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 * 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 * Handler for events coming from the native code
*/ */
protected NativeEventHandler mNativeEventHandler = null; private NativeEventHandler mNativeEventHandler = null;
/** /**
* PCM and FFT capture listener registered by client * PCM and FFT capture listener registered by client
*/ */
protected OnDataCaptureListener mCaptureListener = null; private OnDataCaptureListener mCaptureListener = null;
// accessed by native methods // accessed by native methods
private int mNativeVisualizer; private int mNativeVisualizer;
@@ -159,7 +157,7 @@ public class Visualizer {
//-------------------- //--------------------
/** /**
* Class constructor. * 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 * 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. * same audio session. Otherwise, the Visualizer will apply to the output mix.
* *