NoiseSuppressor.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 * 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 * @hide
42 */
43
44public class NoiseSuppressor extends AudioEffect {
45
46    private final static String TAG = "NoiseSuppressor";
47
48    /**
49     * Checks if the device implements noise suppression.
50     * @return true if the device implements noise suppression, false otherwise.
51     */
52    public static boolean isAvailable() {
53        return AudioEffect.isEffectTypeAvailable(AudioEffect.EFFECT_TYPE_NS);
54    }
55
56    /**
57     * Creates a NoiseSuppressor and attaches it to the AudioRecord on the audio
58     * session specified.
59     * @param audioSession system wide unique audio session identifier. The NoiseSuppressor
60     * will be applied to the AudioRecord with the same audio session.
61     * @return NoiseSuppressor created or null if the device does not implement noise
62     * suppression.
63     */
64    public static NoiseSuppressor create(int audioSession) {
65        NoiseSuppressor ns = null;
66        try {
67            ns = new NoiseSuppressor(audioSession);
68        } catch (IllegalArgumentException e) {
69            Log.w(TAG, "not implemented on this device "+ns);
70        } catch (UnsupportedOperationException e) {
71            Log.w(TAG, "not enough resources");
72        } catch (RuntimeException e) {
73            Log.w(TAG, "not enough memory");
74        } finally {
75            return ns;
76        }
77    }
78
79    /**
80     * Class constructor.
81     * <p> The constructor is not guarantied to succeed and throws the following exceptions:
82     * <ul>
83     *  <li>IllegalArgumentException is thrown if the device does not implement an NS</li>
84     *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
85     *  pre-procesing are currently exceeded.</li>
86     *  <li>RuntimeException is thrown if a memory allocation error occurs.</li>
87     * </ul>
88     *
89     * @param audioSession system wide unique audio session identifier. The NoiseSuppressor
90     * will be applied to the AudioRecord with the same audio session.
91     *
92     * @throws java.lang.IllegalArgumentException
93     * @throws java.lang.UnsupportedOperationException
94     * @throws java.lang.RuntimeException
95     * @hide
96     */
97    private NoiseSuppressor(int audioSession)
98            throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
99        super(EFFECT_TYPE_NS, EFFECT_TYPE_NULL, 0, audioSession);
100    }
101}
102