sdk/sources/android-23/android/media/audiofx/LoudnessEnhancer.java

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