From d09af7d5518d0a5b3c8070784c13a1070f46f460 Mon Sep 17 00:00:00 2001 From: Eric Laurent Date: Mon, 13 Sep 2010 18:13:02 -0700 Subject: [PATCH] Added intents for audio effects control application Added intents to launch audio effects control panel UI and communicate playback state from media player applications to effect control application/service. Change-Id: Iede23ae11fa9f0802df5f36299dd80ea57eda376 --- media/java/android/media/AudioEffect.java | 130 +++++++++++++++++++++- media/java/android/media/MediaPlayer.java | 1 - 2 files changed, 127 insertions(+), 4 deletions(-) diff --git a/media/java/android/media/AudioEffect.java b/media/java/android/media/AudioEffect.java index 35038fa5ae927..ae67114a27fb8 100644 --- a/media/java/android/media/AudioEffect.java +++ b/media/java/android/media/AudioEffect.java @@ -16,12 +16,14 @@ package android.media; -import android.util.Log; -import java.lang.ref.WeakReference; -import java.io.IOException; +import android.annotation.SdkConstant; +import android.annotation.SdkConstant.SdkConstantType; import android.os.Handler; import android.os.Looper; import android.os.Message; +import android.util.Log; +import java.io.IOException; +import java.lang.ref.WeakReference; import java.nio.ByteOrder; import java.nio.ByteBuffer; import java.util.UUID; @@ -839,6 +841,128 @@ public class AudioEffect { byte[] value); } + + // ------------------------------------------------------------------------- + // Audio Effect Control panel intents + // ------------------------------------------------------------------------- + + /** + * This intent launches an audio effect control panel UI. The goal of this intent is to enable + * separate implementations of music/media player applications and audio effect control + * application or services. This will allow platform vendors to offer more advanced control + * options for standard effects or control for platform specific effects. + *

The intent carries a number of extras used by the player application to communicate + * necessary pieces of information to the control panel application. + *

The calling application must use the + * {@link android.app.Activity#startActivityForResult(Intent, int)} method to launch the + * control panel so that its package name is indicated and used by the control panel + * application to keep track of changes for this particular application. + *

The android.media.EXTRA_AUDIO_SESSION extra will indicate an audio session to which the + * audio effects should be applied. If no audio session is specified, either one of the + * follownig will happen: + * - If an audio session was previously opened by the calling application with + * {@link #ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION} intent, the effect changes will + * be applied to that session. + * - If no audio session is opened, the changes will be stored in the package specific storage + * area and applied whenever a new audio session is opened by this application. + *

The android.media.EXTRA_CONTENT_TYPE extra will help the control panel application + * customize both the UI layout and the default audio effect settings if none are already + * stored for the calling application. + * {@hide} pending API council approval + */ + @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) + public static final String ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL = + "android.media.action.DISPLAY_AUDIO_EFFECT_CONTROL_PANEL"; + + /** + * This intent indicates to the effect control application or service that a new audio session + * is opened and requires audio effects to be applied. This is different from + * {@link #ACTION_DISPLAY_AUDIO_EFFECT_CONTROL_PANEL} in that no UI should be displayed in + * this case. Music player applications can broadcast this intent before starting playback + * to make sure that any audio effect settings previously selected by the user are applied. + *

The effect control application receiving this intent will look for previously stored + * settings for the calling application, create all required audio effects and apply the + * effect settings to the specified audio session. + *

The calling package name is indicated by the {@link #EXTRA_PACKAGE_NAME} extra and the + * audio session ID by the {@link #EXTRA_AUDIO_SESSION} extra. Both extras are mandatory. + *

If no stored settings are found for the calling application, default settings for the + * content type indicated by {@link #EXTRA_CONTENT_TYPE} will be applied. The default settings + * for a given content type are platform specific. + * {@hide} pending API council approval + */ + @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) + public static final String ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION = + "android.media.action.OPEN_AUDIO_EFFECT_CONTROL_SESSION"; + + /** + * This intent indicates to the effect control application or service that an audio session + * is closed and that effects should not be applied anymore. + *

The effect control application receiving this intent will delete all effects on this + * session and store current settings in package specific storage. + *

The calling package name is indicated by the {@link #EXTRA_PACKAGE_NAME} extra and the + * audio session ID by the {@link #EXTRA_AUDIO_SESSION} extra. Both extras are mandatory. + *

It is good practice for applications to broadcast this intent when music playback stops + * and/or when exiting to free system resources consumed by audio effect engines. + * {@hide} pending API council approval + */ + @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) + public static final String ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION = + "android.media.action.CLOSE_AUDIO_EFFECT_CONTROL_SESSION"; + + /** + * This extra indicates the ID of the audio session the effects should be applied to. + *

The extra value is of type int and is the audio session ID. + * @see android.media.MediaPlayer#setAudioSessionId(int) for details on audio sessions. + * {@hide} pending API council approval + */ + public static final String EXTRA_AUDIO_SESSION = "android.media.extra.AUDIO_SESSION"; + + /** + * This extra indicates the package name of the calling application for + * {@link #ACTION_OPEN_AUDIO_EFFECT_CONTROL_SESSION} and + * {@link #ACTION_CLOSE_AUDIO_EFFECT_CONTROL_SESSION} intents. + *

The extra value is a string containing the full package name. + * {@hide} pending API council approval + */ + public static final String EXTRA_PACKAGE_NAME = "android.media.extra.PACKAGE_NAME"; + + /** + * This extra indicates which type of content is played by the application. This information is + * used by the effect control application to customize UI and default effect settings. + * The content type is one of the following: + *

+ * If omitted, the content type defaults to {@link #CONTENT_TYPE_MUSIC}. + * {@hide} pending API council approval + */ + public static final String EXTRA_CONTENT_TYPE = "android.media.extra.CONTENT_TYPE"; + + /** + * Value for {@link #EXTRA_CONTENT_TYPE} when the type of content played is music + * {@hide} pending API council approval + */ + public static final int CONTENT_TYPE_MUSIC = 0; + /** + * Value for {@link #EXTRA_CONTENT_TYPE} when the type of content played is video of movie + * {@hide} pending API council approval + */ + public static final int CONTENT_TYPE_MOVIE = 1; + /** + * Value for {@link #EXTRA_CONTENT_TYPE} when the type of content played is game audio + * {@hide} pending API council approval + */ + public static final int CONTENT_TYPE_GAME = 2; + /** + * Value for {@link #EXTRA_CONTENT_TYPE} when the type of content played is voice audio + * {@hide} pending API council approval + */ + public static final int CONTENT_TYPE_VOICE = 3; + + // --------------------------------------------------------- // Inner classes // -------------------- diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java index b8403e175235b..280def95fca69 100644 --- a/media/java/android/media/MediaPlayer.java +++ b/media/java/android/media/MediaPlayer.java @@ -1210,7 +1210,6 @@ public class MediaPlayer * effect which can be applied on any sound source that directs a certain amount of its * energy to this effect. This amount is defined by setAuxEffectSendLevel(). * {@see #setAuxEffectSendLevel(float)}. - // TODO when AudioEffect is unhidden *

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.