AcousticEchoCanceler.java revision 0f7f4ece1b6b73caf608d533d833a8cdc11c8131
10f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent/* 20f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * Copyright (C) 2011 The Android Open Source Project 30f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * 40f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * Licensed under the Apache License, Version 2.0 (the "License"); 50f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * you may not use this file except in compliance with the License. 60f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * You may obtain a copy of the License at 70f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * 80f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * http://www.apache.org/licenses/LICENSE-2.0 90f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * 100f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * Unless required by applicable law or agreed to in writing, software 110f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * distributed under the License is distributed on an "AS IS" BASIS, 120f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 130f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * See the License for the specific language governing permissions and 140f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * limitations under the License. 150f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent */ 160f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent 170f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurentpackage android.media.audiofx; 180f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent 190f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent/** 200f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * Acoustic Echo Canceler (AEC). 210f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p>Acoustic Echo Canceler (AEC) is an audio pre-processing which removes the contribution of the 220f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * signal received from the remote party from the captured audio signal. 230f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p>AEC is used by voice communication applications (voice chat, video conferencing, SIP calls) 240f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * where the presence of echo with significant delay in the signal received from the remote party 250f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * is highly disturbing. AEC is often used in conjunction with noise suppression (NS). 260f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p>An application creates an AcousticEchoCanceler object to instantiate and control an AEC 270f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * engine in the audio capture path. 280f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p>To attach the AcousticEchoCanceler to a particular {@link android.media.AudioRecord}, 290f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * specify the audio session ID of this AudioRecord when constructing the AcousticEchoCanceler. 300f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * The audio session is retrieved by calling 310f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * {@link android.media.AudioRecord#getAudioSessionId()} on the AudioRecord instance. 320f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p>On some devices, an AEC can be inserted by default in the capture path by the platform 330f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * according to the {@link android.media.MediaRecorder.AudioSource} used. The application can 340f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * query which pre-processings are currently applied to an AudioRecord instance by calling 350f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * {@link android.media.audiofx.AudioEffect#queryPreProcessings(int)} with the audio session of the 360f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * AudioRecord. 370f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p>See {@link android.media.audiofx.AudioEffect} class for more details on 380f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * controlling audio effects. 390f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * @hide 400f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent */ 410f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent 420f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurentpublic class AcousticEchoCanceler extends AudioEffect { 430f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent 440f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent private final static String TAG = "AcousticEchoCanceler"; 450f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent 460f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent /** 470f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * Class constructor. 480f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <p> The application must catch exceptions when creating an AcousticEchoCanceler as the 490f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * constructor is not guarantied to succeed: 500f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <ul> 510f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <li>IllegalArgumentException is thrown if the device does not implement an AEC</li> 520f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * <li>UnsupportedOperationException is thrown is the resources allocated to audio 530f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * pre-procesing are currently exceeded.</li> 540f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * </ul> 550f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * 560f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * @param audioSession system wide unique audio session identifier. The AcousticEchoCanceler 570f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * will be applied to the AudioRecord with the same audio session. 580f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * 590f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * @throws java.lang.IllegalArgumentException 600f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * @throws java.lang.UnsupportedOperationException 610f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent * @throws java.lang.RuntimeException 620f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent */ 630f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent public AcousticEchoCanceler(int audioSession) 640f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent throws IllegalArgumentException, UnsupportedOperationException, RuntimeException { 650f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent super(EFFECT_TYPE_AEC, EFFECT_TYPE_NULL, 0, audioSession); 660f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent } 670f7f4ece1b6b73caf608d533d833a8cdc11c8131Eric Laurent} 68