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  * Noise Suppressor (NS).
     23  * <p>Noise suppression (NS) is an audio pre-processing which removes background noise from the
     24  * captured signal. The component of the signal considered as noise can be either stationary
     25  * (car/airplane engine, AC system) or non-stationary (other peoples conversations, car horn) for
     26  * more advanced implementations.
     27  * <p>NS is mostly used by voice communication applications (voice chat, video conferencing,
     28  * SIP calls).
     29  * <p>An application creates a NoiseSuppressor object to instantiate and control an NS
     30  * engine in the audio framework.
     31  * <p>To attach the NoiseSuppressor to a particular {@link android.media.AudioRecord},
     32  * specify the audio session ID of this AudioRecord when creating the NoiseSuppressor.
     33  * The audio session is retrieved by calling
     34  * {@link android.media.AudioRecord#getAudioSessionId()} on the AudioRecord instance.
     35  * <p>On some devices, NS can be inserted by default in the capture path by the platform
     36  * according to the {@link android.media.MediaRecorder.AudioSource} used. The application should
     37  * call NoiseSuppressor.getEnable() after creating the NS to check the default NS activation
     38  * state on a particular AudioRecord session.
     39  * <p>See {@link android.media.audiofx.AudioEffect} class for more details on
     40  * controlling audio effects.
     41  */
     42 
     43 public class NoiseSuppressor extends AudioEffect {
     44 
     45     private final static String TAG = "NoiseSuppressor";
     46 
     47     /**
     48      * Checks if the device implements noise suppression.
     49      * @return true if the device implements noise suppression, false otherwise.
     50      */
     51     public static boolean isAvailable() {
     52         return AudioEffect.isEffectTypeAvailable(AudioEffect.EFFECT_TYPE_NS);
     53     }
     54 
     55     /**
     56      * Creates a NoiseSuppressor and attaches it to the AudioRecord on the audio
     57      * session specified.
     58      * @param audioSession system wide unique audio session identifier. The NoiseSuppressor
     59      * will be applied to the AudioRecord with the same audio session.
     60      * @return NoiseSuppressor created or null if the device does not implement noise
     61      * suppression.
     62      */
     63     public static NoiseSuppressor create(int audioSession) {
     64         NoiseSuppressor ns = null;
     65         try {
     66             ns = new NoiseSuppressor(audioSession);
     67         } catch (IllegalArgumentException e) {
     68             Log.w(TAG, "not implemented on this device "+ns);
     69         } catch (UnsupportedOperationException e) {
     70             Log.w(TAG, "not enough resources");
     71         } catch (RuntimeException e) {
     72             Log.w(TAG, "not enough memory");
     73         } finally {
     74             return ns;
     75         }
     76     }
     77 
     78     /**
     79      * Class constructor.
     80      * <p> The constructor is not guarantied to succeed and throws the following exceptions:
     81      * <ul>
     82      *  <li>IllegalArgumentException is thrown if the device does not implement an NS</li>
     83      *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
     84      *  pre-procesing are currently exceeded.</li>
     85      *  <li>RuntimeException is thrown if a memory allocation error occurs.</li>
     86      * </ul>
     87      *
     88      * @param audioSession system wide unique audio session identifier. The NoiseSuppressor
     89      * will be applied to the AudioRecord with the same audio session.
     90      *
     91      * @throws java.lang.IllegalArgumentException
     92      * @throws java.lang.UnsupportedOperationException
     93      * @throws java.lang.RuntimeException
     94      */
     95     private NoiseSuppressor(int audioSession)
     96             throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
     97         super(EFFECT_TYPE_NS, EFFECT_TYPE_NULL, 0, audioSession);
     98     }
     99 }
    100