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
17package android.media.audiofx;
18
19import 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
42public 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        } finally {
72            return agc;
73        }
74    }
75
76    /**
77     * Class constructor.
78     * <p> The constructor is not guarantied to succeed and throws the following exceptions:
79     * <ul>
80     *  <li>IllegalArgumentException is thrown if the device does not implement an AGC</li>
81     *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
82     *  pre-procesing are currently exceeded.</li>
83     *  <li>RuntimeException is thrown if a memory allocation error occurs.</li>
84     * </ul>
85     *
86     * @param audioSession system wide unique audio session identifier. The AutomaticGainControl
87     * will be applied to the AudioRecord with the same audio session.
88     *
89     * @throws java.lang.IllegalArgumentException
90     * @throws java.lang.UnsupportedOperationException
91     * @throws java.lang.RuntimeException
92     */
93    private AutomaticGainControl(int audioSession)
94            throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
95        super(EFFECT_TYPE_AGC, EFFECT_TYPE_NULL, 0, audioSession);
96    }
97}
98