Home | History | Annotate | Download | only in audiofx 
      1 /*
      2  * Copyright (C) 2011 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.util.Log;
     20 
     21 /**
     22  * Automatic Gain Control (AGC).
     23  * <p>Automatic Gain Control (AGC) is an audio pre-processor which automatically normalizes the
     24  * output of the captured signal by boosting or lowering input from the microphone to match a preset
     25  * level so that the output signal level is virtually constant.
     26  * AGC can be used by applications where the input signal dynamic range is not important but where
     27  * a constant strong capture level is desired.
     28  * <p>An application creates a AutomaticGainControl object to instantiate and control an AGC
     29  * engine in the audio framework.
     30  * <p>To attach the AutomaticGainControl to a particular {@link android.media.AudioRecord},
     31  * specify the audio session ID of this AudioRecord when creating the AutomaticGainControl.
     32  * The audio session is retrieved by calling
     33  * {@link android.media.AudioRecord#getAudioSessionId()} on the AudioRecord instance.
     34  * <p>On some devices, an AGC can be inserted by default in the capture path by the platform
     35  * according to the {@link android.media.MediaRecorder.AudioSource} used. The application should
     36  * call AutomaticGainControl.getEnable() after creating the AGC to check the default AGC activation
     37  * state on a particular AudioRecord session.
     38  * <p>See {@link android.media.audiofx.AudioEffect} class for more details on
     39  * controlling audio effects.
     40  */
     41 
     42 public class AutomaticGainControl extends AudioEffect {
     43 
     44     private final static String TAG = "AutomaticGainControl";
     45 
     46     /**
     47      * Checks if the device implements automatic gain control.
     48      * @return true if the device implements automatic gain control, false otherwise.
     49      */
     50     public static boolean isAvailable() {
     51         return AudioEffect.isEffectTypeAvailable(AudioEffect.EFFECT_TYPE_AGC);
     52     }
     53 
     54     /**
     55      * Creates an AutomaticGainControl and attaches it to the AudioRecord on the audio
     56      * session specified.
     57      * @param audioSession system wide unique audio session identifier. The AutomaticGainControl
     58      * will be applied to the AudioRecord with the same audio session.
     59      * @return AutomaticGainControl created or null if the device does not implement AGC.
     60      */
     61     public static AutomaticGainControl create(int audioSession) {
     62         AutomaticGainControl agc = null;
     63         try {
     64             agc = new AutomaticGainControl(audioSession);
     65         } catch (IllegalArgumentException e) {
     66             Log.w(TAG, "not implemented on this device "+agc);
     67         } catch (UnsupportedOperationException e) {
     68             Log.w(TAG, "not enough resources");
     69         } catch (RuntimeException e) {
     70             Log.w(TAG, "not enough memory");
     71         }
     72         return agc;
     73     }
     74 
     75     /**
     76      * Class constructor.
     77      * <p> The constructor is not guarantied to succeed and throws the following exceptions:
     78      * <ul>
     79      *  <li>IllegalArgumentException is thrown if the device does not implement an AGC</li>
     80      *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
     81      *  pre-procesing are currently exceeded.</li>
     82      *  <li>RuntimeException is thrown if a memory allocation error occurs.</li>
     83      * </ul>
     84      *
     85      * @param audioSession system wide unique audio session identifier. The AutomaticGainControl
     86      * will be applied to the AudioRecord with the same audio session.
     87      *
     88      * @throws java.lang.IllegalArgumentException
     89      * @throws java.lang.UnsupportedOperationException
     90      * @throws java.lang.RuntimeException
     91      */
     92     private AutomaticGainControl(int audioSession)
     93             throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
     94         super(EFFECT_TYPE_AGC, EFFECT_TYPE_NULL, 0, audioSession);
     95     }
     96 }
     97