LoudnessEnhancer.java revision c3c0b9921fc35472c2cae5ddcd0248f364495965
1/* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.media.audiofx; 18 19import android.media.AudioTrack; 20import android.media.MediaPlayer; 21import android.media.audiofx.AudioEffect; 22import android.util.Log; 23 24import java.util.StringTokenizer; 25 26 27/** 28 * LoudnessEnhancer is an audio effect for increasing audio loudness. 29 * The processing is parametrized by a target gain value, which determines the maximum amount 30 * by which an audio signal will be amplified; signals amplified outside of the sample 31 * range supported by the platform are compressed. 32 * An application creates a LoudnessEnhancer object to instantiate and control a 33 * this audio effect in the audio framework. 34 * To attach the LoudnessEnhancer to a particular AudioTrack or MediaPlayer, 35 * specify the audio session ID of this AudioTrack or MediaPlayer when constructing the effect 36 * (see {@link AudioTrack#getAudioSessionId()} and {@link MediaPlayer#getAudioSessionId()}). 37 */ 38 39public class LoudnessEnhancer extends AudioEffect { 40 41 private final static String TAG = "LoudnessEnhancer"; 42 43 // These parameter constants must be synchronized with those in 44 // /system/media/audio_effects/include/audio_effects/effect_loudnessenhancer.h 45 /** 46 * The maximum gain applied applied to the signal to process. 47 * It is expressed in millibels (100mB = 1dB) where 0mB corresponds to no amplification. 48 */ 49 public static final int PARAM_TARGET_GAIN_MB = 0; 50 51 /** 52 * Registered listener for parameter changes. 53 */ 54 private OnParameterChangeListener mParamListener = null; 55 56 /** 57 * Listener used internally to to receive raw parameter change events 58 * from AudioEffect super class 59 */ 60 private BaseParameterListener mBaseParamListener = null; 61 62 /** 63 * Lock for access to mParamListener 64 */ 65 private final Object mParamListenerLock = new Object(); 66 67 /** 68 * @hide 69 * Class constructor. 70 * @param audioSession system-wide unique audio session identifier. The LoudnessEnhancer 71 * will be attached to the MediaPlayer or AudioTrack in the same audio session. 72 * 73 * @throws java.lang.IllegalStateException 74 * @throws java.lang.IllegalArgumentException 75 * @throws java.lang.UnsupportedOperationException 76 * @throws java.lang.RuntimeException 77 */ 78 public LoudnessEnhancer(int audioSession) 79 throws IllegalStateException, IllegalArgumentException, 80 UnsupportedOperationException, RuntimeException { 81 super(EFFECT_TYPE_LOUDNESS_ENHANCER, EFFECT_TYPE_NULL, 0, audioSession); 82 83 if (audioSession == 0) { 84 Log.w(TAG, "WARNING: attaching a LoudnessEnhancer to global output mix is deprecated!"); 85 } 86 } 87 88 /** 89 * @hide 90 * Class constructor for the LoudnessEnhancer audio effect. 91 * @param priority the priority level requested by the application for controlling the 92 * LoudnessEnhancer engine. As the same engine can be shared by several applications, 93 * this parameter indicates how much the requesting application needs control of effect 94 * parameters. The normal priority is 0, above normal is a positive number, below normal a 95 * negative number. 96 * @param audioSession system-wide unique audio session identifier. The LoudnessEnhancer 97 * will be attached to the MediaPlayer or AudioTrack in the same audio session. 98 * 99 * @throws java.lang.IllegalStateException 100 * @throws java.lang.IllegalArgumentException 101 * @throws java.lang.UnsupportedOperationException 102 * @throws java.lang.RuntimeException 103 */ 104 public LoudnessEnhancer(int priority, int audioSession) 105 throws IllegalStateException, IllegalArgumentException, 106 UnsupportedOperationException, RuntimeException { 107 super(EFFECT_TYPE_LOUDNESS_ENHANCER, EFFECT_TYPE_NULL, priority, audioSession); 108 109 if (audioSession == 0) { 110 Log.w(TAG, "WARNING: attaching a LoudnessEnhancer to global output mix is deprecated!"); 111 } 112 } 113 114 /** 115 * Set the target gain for the audio effect. 116 * The target gain is the maximum value by which a sample value will be amplified when the 117 * effect is enabled. 118 * @param gainmB the effect target gain expressed in mB. 0mB corresponds to no amplification. 119 * @throws IllegalStateException 120 * @throws IllegalArgumentException 121 * @throws UnsupportedOperationException 122 */ 123 public void setTargetGain(int gainmB) 124 throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { 125 checkStatus(setParameter(PARAM_TARGET_GAIN_MB, gainmB)); 126 } 127 128 /** 129 * Return the target gain. 130 * @return the effect target gain expressed in mB. 131 * @throws IllegalStateException 132 * @throws IllegalArgumentException 133 * @throws UnsupportedOperationException 134 */ 135 public float getTargetGain() 136 throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { 137 int[] value = new int[1]; 138 checkStatus(getParameter(PARAM_TARGET_GAIN_MB, value)); 139 return value[0]; 140 } 141 142 /** 143 * @hide 144 * The OnParameterChangeListener interface defines a method called by the LoudnessEnhancer 145 * when a parameter value has changed. 146 */ 147 public interface OnParameterChangeListener { 148 /** 149 * Method called when a parameter value has changed. The method is called only if the 150 * parameter was changed by another application having the control of the same 151 * LoudnessEnhancer engine. 152 * @param effect the LoudnessEnhancer on which the interface is registered. 153 * @param param ID of the modified parameter. See {@link #PARAM_GENERIC_PARAM1} ... 154 * @param value the new parameter value. 155 */ 156 void onParameterChange(LoudnessEnhancer effect, int param, int value); 157 } 158 159 /** 160 * Listener used internally to receive unformatted parameter change events from AudioEffect 161 * super class. 162 */ 163 private class BaseParameterListener implements AudioEffect.OnParameterChangeListener { 164 private BaseParameterListener() { 165 166 } 167 public void onParameterChange(AudioEffect effect, int status, byte[] param, byte[] value) { 168 // only notify when the parameter was successfully change 169 if (status != AudioEffect.SUCCESS) { 170 return; 171 } 172 OnParameterChangeListener l = null; 173 synchronized (mParamListenerLock) { 174 if (mParamListener != null) { 175 l = mParamListener; 176 } 177 } 178 if (l != null) { 179 int p = -1; 180 int v = Integer.MIN_VALUE; 181 182 if (param.length == 4) { 183 p = byteArrayToInt(param, 0); 184 } 185 if (value.length == 4) { 186 v = byteArrayToInt(value, 0); 187 } 188 if (p != -1 && v != Integer.MIN_VALUE) { 189 l.onParameterChange(LoudnessEnhancer.this, p, v); 190 } 191 } 192 } 193 } 194 195 /** 196 * @hide 197 * Registers an OnParameterChangeListener interface. 198 * @param listener OnParameterChangeListener interface registered 199 */ 200 public void setParameterListener(OnParameterChangeListener listener) { 201 synchronized (mParamListenerLock) { 202 if (mParamListener == null) { 203 mBaseParamListener = new BaseParameterListener(); 204 super.setParameterListener(mBaseParamListener); 205 } 206 mParamListener = listener; 207 } 208 } 209 210 /** 211 * @hide 212 * The Settings class regroups the LoudnessEnhancer parameters. It is used in 213 * conjunction with the getProperties() and setProperties() methods to backup and restore 214 * all parameters in a single call. 215 */ 216 public static class Settings { 217 public int targetGainmB; 218 219 public Settings() { 220 } 221 222 /** 223 * Settings class constructor from a key=value; pairs formatted string. The string is 224 * typically returned by Settings.toString() method. 225 * @throws IllegalArgumentException if the string is not correctly formatted. 226 */ 227 public Settings(String settings) { 228 StringTokenizer st = new StringTokenizer(settings, "=;"); 229 //int tokens = st.countTokens(); 230 if (st.countTokens() != 3) { 231 throw new IllegalArgumentException("settings: " + settings); 232 } 233 String key = st.nextToken(); 234 if (!key.equals("LoudnessEnhancer")) { 235 throw new IllegalArgumentException( 236 "invalid settings for LoudnessEnhancer: " + key); 237 } 238 try { 239 key = st.nextToken(); 240 if (!key.equals("targetGainmB")) { 241 throw new IllegalArgumentException("invalid key name: " + key); 242 } 243 targetGainmB = Integer.parseInt(st.nextToken()); 244 } catch (NumberFormatException nfe) { 245 throw new IllegalArgumentException("invalid value for key: " + key); 246 } 247 } 248 249 @Override 250 public String toString() { 251 String str = new String ( 252 "LoudnessEnhancer"+ 253 ";targetGainmB="+Integer.toString(targetGainmB) 254 ); 255 return str; 256 } 257 }; 258 259 260 /** 261 * @hide 262 * Gets the LoudnessEnhancer properties. This method is useful when a snapshot of current 263 * effect settings must be saved by the application. 264 * @return a LoudnessEnhancer.Settings object containing all current parameters values 265 * @throws IllegalStateException 266 * @throws IllegalArgumentException 267 * @throws UnsupportedOperationException 268 */ 269 public LoudnessEnhancer.Settings getProperties() 270 throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { 271 Settings settings = new Settings(); 272 int[] value = new int[1]; 273 checkStatus(getParameter(PARAM_TARGET_GAIN_MB, value)); 274 settings.targetGainmB = value[0]; 275 return settings; 276 } 277 278 /** 279 * @hide 280 * Sets the LoudnessEnhancer properties. This method is useful when bass boost settings 281 * have to be applied from a previous backup. 282 * @param settings a LoudnessEnhancer.Settings object containing the properties to apply 283 * @throws IllegalStateException 284 * @throws IllegalArgumentException 285 * @throws UnsupportedOperationException 286 */ 287 public void setProperties(LoudnessEnhancer.Settings settings) 288 throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { 289 checkStatus(setParameter(PARAM_TARGET_GAIN_MB, settings.targetGainmB)); 290 } 291} 292