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