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 */ isAvailable()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 */ create(int audioSession)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 */ AutomaticGainControl(int audioSession)92 private AutomaticGainControl(int audioSession) 93 throws IllegalArgumentException, UnsupportedOperationException, RuntimeException { 94 super(EFFECT_TYPE_AGC, EFFECT_TYPE_NULL, 0, audioSession); 95 } 96 } 97