Home | History | Annotate | Download | only in audiofx 
      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  * 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  */
     41 
     42 public class AcousticEchoCanceler extends AudioEffect {
     43 
     44     private final static String TAG = "AcousticEchoCanceler";
     45 
     46     /**
     47      * Checks if the device implements acoustic echo cancellation.
     48      * @return true if the device implements acoustic echo cancellation, false otherwise.
     49      */
     50     public static boolean isAvailable() {
     51         return AudioEffect.isEffectTypeAvailable(AudioEffect.EFFECT_TYPE_AEC);
     52     }
     53 
     54     /**
     55      * Creates an AcousticEchoCanceler and attaches it to the AudioRecord on the audio
     56      * session specified.
     57      * @param audioSession system wide unique audio session identifier. The AcousticEchoCanceler
     58      * will be applied to the AudioRecord with the same audio session.
     59      * @return AcousticEchoCanceler created or null if the device does not implement AEC.
     60      */
     61     public static AcousticEchoCanceler create(int audioSession) {
     62         AcousticEchoCanceler aec = null;
     63         try {
     64             aec = new AcousticEchoCanceler(audioSession);
     65         } catch (IllegalArgumentException e) {
     66             Log.w(TAG, "not implemented on this device"+ aec);
     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 aec;
     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 AEC</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 AcousticEchoCanceler
     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 AcousticEchoCanceler(int audioSession)
     94             throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
     95         super(EFFECT_TYPE_AEC, EFFECT_TYPE_NULL, 0, audioSession);
     96     }
     97 }
     98