AutomaticGainControl.java revision 0f7f4ece1b6b73caf608d533d833a8cdc11c8131 
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
19/**
20 * Automatic Gain Control (AGC).
21 * <p>Automatic Gain Control (AGC) is an audio pre-processing which automatically normalizes the
22 * output of the captured signal by boosting or lowering input from the microphone to match a preset
23 * level so that that the output signal level is virtually constant.
24 * AGC can be used by applications where the input signal dynamic range is not important but where
25 * a constant strong capture level is desired.
26 * <p>An application creates a AutomaticGainControl object to instantiate and control an AGC
27 * engine in the audio framework.
28 * <p>To attach the AutomaticGainControl to a particular {@link android.media.AudioRecord},
29 * specify the audio session ID of this AudioRecord when constructing the AutomaticGainControl.
30 * The audio session is retrieved by calling
31 * {@link android.media.AudioRecord#getAudioSessionId()} on the AudioRecord instance.
32 * <p>On some devices, an AGC can be inserted by default in the capture path by the platform
33 * according to the {@link android.media.MediaRecorder.AudioSource} used. The application can
34 * query which pre-processings are currently applied to an AudioRecord instance by calling
35 * {@link android.media.audiofx.AudioEffect#queryPreProcessings(int)} with the audio session of the
36 * AudioRecord.
37 * <p>See {@link android.media.audiofx.AudioEffect} class for more details on
38 * controlling audio effects.
39 * @hide
40 */
41
42public class AutomaticGainControl extends AudioEffect {
43
44    private final static String TAG = "AutomaticGainControl";
45
46    /**
47     * Class constructor.
48     * <p> The application must catch exceptions when creating an AutomaticGainControl as the
49     * constructor is not guarantied to succeed:
50     * <ul>
51     *  <li>IllegalArgumentException is thrown if the device does not implement an AGC</li>
52     *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
53     *  pre-procesing are currently exceeded.</li>
54     * </ul>
55     *
56     * @param audioSession system wide unique audio session identifier. The AutomaticGainControl
57     * will be applied to the AudioRecord with the same audio session.
58     *
59     * @throws java.lang.IllegalArgumentException
60     * @throws java.lang.UnsupportedOperationException
61     * @throws java.lang.RuntimeException
62     */
63    public AutomaticGainControl(int audioSession)
64            throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
65        super(EFFECT_TYPE_AGC, EFFECT_TYPE_NULL, 0, audioSession);
66    }
67}
68