AcousticEchoCanceler.java revision 855255d89fe0a14abe796355bebb64031ec6ff47 
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 * Acoustic Echo Canceler (AEC).
23 * <p>Acoustic Echo Canceler (AEC) is an audio pre-processing which removes the contribution of the
24 * signal received from the remote party from the captured audio signal.
25 * <p>AEC is used by voice communication applications (voice chat, video conferencing, SIP calls)
26 * where the presence of echo with significant delay in the signal received from the remote party
27 * is highly disturbing. AEC is often used in conjunction with noise suppression (NS).
28 * <p>An application creates an AcousticEchoCanceler object to instantiate and control an AEC
29 * engine in the audio capture path.
30 * <p>To attach the AcousticEchoCanceler to a particular {@link android.media.AudioRecord},
31 * specify the audio session ID of this AudioRecord when creating the AcousticEchoCanceler.
32 * The audio session is retrieved by calling
33 * {@link android.media.AudioRecord#getAudioSessionId()} on the AudioRecord instance.
34 * <p>On some devices, an AEC 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 AcousticEchoCanceler.getEnable() after creating the AEC to check the default AEC 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 * @hide
41 */
42
43public class AcousticEchoCanceler extends AudioEffect {
44
45    private final static String TAG = "AcousticEchoCanceler";
46
47    /**
48     * Checks if the device implements acoustic echo cancellation.
49     * @return true if the device implements acoustic echo cancellation, false otherwise.
50     */
51    public static boolean isAvailable() {
52        return AudioEffect.isEffectTypeAvailable(AudioEffect.EFFECT_TYPE_AEC);
53    }
54
55    /**
56     * Creates an AcousticEchoCanceler and attaches it to the AudioRecord on the audio
57     * session specified.
58     * @param audioSession system wide unique audio session identifier. The AcousticEchoCanceler
59     * will be applied to the AudioRecord with the same audio session.
60     * @return AcousticEchoCanceler created or null if the device does not implement AEC.
61     */
62    public static AcousticEchoCanceler create(int audioSession) {
63        AcousticEchoCanceler aec = null;
64        try {
65            aec = new AcousticEchoCanceler(audioSession);
66        } catch (IllegalArgumentException e) {
67            Log.w(TAG, "not implemented on this device"+ aec);
68        } catch (UnsupportedOperationException e) {
69            Log.w(TAG, "not enough resources");
70        } catch (RuntimeException e) {
71            Log.w(TAG, "not enough memory");
72        } finally {
73            return aec;
74        }
75    }
76
77    /**
78     * Class constructor.
79     * <p> The constructor is not guarantied to succeed and throws the following exceptions:
80     * <ul>
81     *  <li>IllegalArgumentException is thrown if the device does not implement an AEC</li>
82     *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
83     *  pre-procesing are currently exceeded.</li>
84     *  <li>RuntimeException is thrown if a memory allocation error occurs.</li>
85     * </ul>
86     *
87     * @param audioSession system wide unique audio session identifier. The AcousticEchoCanceler
88     * will be applied to the AudioRecord with the same audio session.
89     *
90     * @throws java.lang.IllegalArgumentException
91     * @throws java.lang.UnsupportedOperationException
92     * @throws java.lang.RuntimeException
93     * @hide
94     */
95    public AcousticEchoCanceler(int audioSession)
96            throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
97        super(EFFECT_TYPE_AEC, EFFECT_TYPE_NULL, 0, audioSession);
98    }
99}
100