Java tutorial
/* * 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)); } }