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-processing 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