| /* |
| * 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. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.media.audiofx; |
| |
| import android.media.audiofx.AudioEffect; |
| import java.util.StringTokenizer; |
| |
| |
| /** |
| * A sound generated within a room travels in many directions. The listener first hears the |
| * direct sound from the source itself. Later, he or she hears discrete echoes caused by sound |
| * bouncing off nearby walls, the ceiling and the floor. As sound waves arrive after |
| * undergoing more and more reflections, individual reflections become indistinguishable and |
| * the listener hears continuous reverberation that decays over time. |
| * Reverb is vital for modeling a listener's environment. It can be used in music applications |
| * to simulate music being played back in various environments, or in games to immerse the |
| * listener within the game's environment. |
| * 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 |
| * {@link android.media.audiofx.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 |
| * directly mapping those defined by the OpenSL ES 1.0.1 Specification |
| * (http://www.khronos.org/opensles/) for the SLPresetReverbItf interface. |
| * Please refer to this specification for more details. |
| * <p>The PresetReverb is an output mix auxiliary effect and should be created on |
| * Audio session 0. In order for a MediaPlayer or AudioTrack to be fed into this effect, |
| * 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. |
| * <p>Creating a reverb on the output mix (audio session 0) requires permission |
| * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} |
| * <p>See {@link android.media.audiofx.AudioEffect} class for more details on controlling |
| * audio effects. |
| */ |
| |
| public class PresetReverb extends AudioEffect { |
| |
| private final static String TAG = "PresetReverb"; |
| |
| // These constants must be synchronized with those in |
| // frameworks/base/include/media/EffectPresetReverbApi.h |
| |
| /** |
| * Preset. Parameter ID for |
| * {@link android.media.audiofx.PresetReverb.OnParameterChangeListener} |
| */ |
| public static final int PARAM_PRESET = 0; |
| |
| /** |
| * No reverb or reflections |
| */ |
| public static final short PRESET_NONE = 0; |
| /** |
| * Reverb preset representing a small room less than five meters in length |
| */ |
| public static final short PRESET_SMALLROOM = 1; |
| /** |
| * Reverb preset representing a medium room with a length of ten meters or less |
| */ |
| public static final short PRESET_MEDIUMROOM = 2; |
| /** |
| * Reverb preset representing a large-sized room suitable for live performances |
| */ |
| public static final short PRESET_LARGEROOM = 3; |
| /** |
| * Reverb preset representing a medium-sized hall |
| */ |
| public static final short PRESET_MEDIUMHALL = 4; |
| /** |
| * Reverb preset representing a large-sized hall suitable for a full orchestra |
| */ |
| public static final short PRESET_LARGEHALL = 5; |
| /** |
| * Reverb preset representing a synthesis of the traditional plate reverb |
| */ |
| public static final short PRESET_PLATE = 6; |
| |
| /** |
| * Registered listener for parameter changes. |
| */ |
| private OnParameterChangeListener mParamListener = null; |
| |
| /** |
| * Listener used internally to to receive raw parameter change event from AudioEffect super class |
| */ |
| private BaseParameterListener mBaseParamListener = null; |
| |
| /** |
| * Lock for access to mParamListener |
| */ |
| private final Object mParamListenerLock = new Object(); |
| |
| /** |
| * Class constructor. |
| * @param priority the priority level requested by the application for controlling the |
| * 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 |
| * 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 |
| * audio session 0 and to attach it to the MediaPLayer auxiliary output. |
| * |
| * @throws java.lang.IllegalArgumentException |
| * @throws java.lang.UnsupportedOperationException |
| * @throws java.lang.RuntimeException |
| */ |
| public PresetReverb(int priority, int audioSession) |
| throws IllegalArgumentException, UnsupportedOperationException, RuntimeException { |
| super(EFFECT_TYPE_PRESET_REVERB, EFFECT_TYPE_NULL, priority, audioSession); |
| } |
| |
| /** |
| * Enables a preset on the reverb. |
| * <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. |
| * e.g. {@link #PRESET_SMALLROOM} |
| * @throws IllegalStateException |
| * @throws IllegalArgumentException |
| * @throws UnsupportedOperationException |
| */ |
| public void setPreset(short preset) |
| throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { |
| checkStatus(setParameter(PARAM_PRESET, preset)); |
| } |
| |
| /** |
| * Gets current reverb preset. |
| * @return the preset that is set at the moment. |
| * @throws IllegalStateException |
| * @throws IllegalArgumentException |
| * @throws UnsupportedOperationException |
| */ |
| public short getPreset() |
| throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { |
| short[] value = new short[1]; |
| checkStatus(getParameter(PARAM_PRESET, value)); |
| return value[0]; |
| } |
| |
| /** |
| * The OnParameterChangeListener interface defines a method called by the PresetReverb |
| * when a parameter value has changed. |
| */ |
| public interface OnParameterChangeListener { |
| /** |
| * Method called when a parameter value has changed. The method is called only if the |
| * parameter was changed by another application having the control of the same |
| * PresetReverb engine. |
| * @param effect the PresetReverb on which the interface is registered. |
| * @param status status of the set parameter operation. |
| * @param param ID of the modified parameter. See {@link #PARAM_PRESET} ... |
| * @param value the new parameter value. |
| */ |
| void onParameterChange(PresetReverb effect, int status, int param, short value); |
| } |
| |
| /** |
| * Listener used internally to receive unformatted parameter change events from AudioEffect |
| * super class. |
| */ |
| private class BaseParameterListener implements AudioEffect.OnParameterChangeListener { |
| private BaseParameterListener() { |
| |
| } |
| public void onParameterChange(AudioEffect effect, int status, byte[] param, byte[] value) { |
| OnParameterChangeListener l = null; |
| |
| synchronized (mParamListenerLock) { |
| if (mParamListener != null) { |
| l = mParamListener; |
| } |
| } |
| if (l != null) { |
| int p = -1; |
| short v = -1; |
| |
| if (param.length == 4) { |
| p = byteArrayToInt(param, 0); |
| } |
| if (value.length == 2) { |
| v = byteArrayToShort(value, 0); |
| } |
| if (p != -1 && v != -1) { |
| l.onParameterChange(PresetReverb.this, status, p, v); |
| } |
| } |
| } |
| } |
| |
| /** |
| * Registers an OnParameterChangeListener interface. |
| * @param listener OnParameterChangeListener interface registered |
| */ |
| public void setParameterListener(OnParameterChangeListener listener) { |
| synchronized (mParamListenerLock) { |
| if (mParamListener == null) { |
| mParamListener = listener; |
| mBaseParamListener = new BaseParameterListener(); |
| super.setParameterListener(mBaseParamListener); |
| } |
| } |
| } |
| |
| /** |
| * The Settings class regroups all preset reverb parameters. It is used in |
| * conjuntion with getProperties() and setProperties() methods to backup and restore |
| * all parameters in a single call. |
| */ |
| public static class Settings { |
| public short preset; |
| |
| public Settings() { |
| } |
| |
| /** |
| * Settings class constructor from a key=value; pairs formatted string. The string is |
| * typically returned by Settings.toString() method. |
| * @throws IllegalArgumentException if the string is not correctly formatted. |
| */ |
| public Settings(String settings) { |
| StringTokenizer st = new StringTokenizer(settings, "=;"); |
| int tokens = st.countTokens(); |
| if (st.countTokens() != 3) { |
| throw new IllegalArgumentException("settings: " + settings); |
| } |
| String key = st.nextToken(); |
| if (!key.equals("PresetReverb")) { |
| throw new IllegalArgumentException( |
| "invalid settings for PresetReverb: " + key); |
| } |
| try { |
| key = st.nextToken(); |
| if (!key.equals("preset")) { |
| throw new IllegalArgumentException("invalid key name: " + key); |
| } |
| preset = Short.parseShort(st.nextToken()); |
| } catch (NumberFormatException nfe) { |
| throw new IllegalArgumentException("invalid value for key: " + key); |
| } |
| } |
| |
| @Override |
| public String toString() { |
| String str = new String ( |
| "PresetReverb"+ |
| ";preset="+Short.toString(preset) |
| ); |
| return str; |
| } |
| }; |
| |
| |
| /** |
| * Gets the preset reverb properties. This method is useful when a snapshot of current |
| * preset reverb settings must be saved by the application. |
| * @return a PresetReverb.Settings object containing all current parameters values |
| * @throws IllegalStateException |
| * @throws IllegalArgumentException |
| * @throws UnsupportedOperationException |
| */ |
| public PresetReverb.Settings getProperties() |
| throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { |
| Settings settings = new Settings(); |
| short[] value = new short[1]; |
| checkStatus(getParameter(PARAM_PRESET, value)); |
| settings.preset = value[0]; |
| return settings; |
| } |
| |
| /** |
| * 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 |
| */ |
| public void setProperties(PresetReverb.Settings settings) |
| throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { |
| checkStatus(setParameter(PARAM_PRESET, settings.preset)); |
| } |
| } |
