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
19/**
20 * Noise Suppressor (NS).
21 * <p>Noise suppression (NS) is an audio pre-processing which removes background noise from the
22 * captured signal. The component of the signal considered as noise can be either stationary
23 * (car/airplane engine, AC system) or non-stationary (other peoples conversations, car horn) for
24 * more advanced implementations.
25 * <p>NS is mostly used by voice communication applications (voice chat, video conferencing,
26 * SIP calls).
27 * <p>An application creates a NoiseSuppressor object to instantiate and control an NS
28 * engine in the audio framework.
29 * <p>To attach the NoiseSuppressor to a particular {@link android.media.AudioRecord},
30 * specify the audio session ID of this AudioRecord when constructing the NoiseSuppressor.
31 * The audio session is retrieved by calling
32 * {@link android.media.AudioRecord#getAudioSessionId()} on the AudioRecord instance.
33 * <p>On some devices, NS can be inserted by default in the capture path by the platform
34 * according to the {@link android.media.MediaRecorder.AudioSource} used. The application can
35 * query which pre-processings are currently applied to an AudioRecord instance by calling
36 * {@link android.media.audiofx.AudioEffect#queryPreProcessings(int)} with the audio session of the
37 * AudioRecord.
38 * <p>See {@link android.media.audiofx.AudioEffect} class for more details on
39 * controlling audio effects.
40 * @hide
41 */
42
43public class NoiseSuppressor extends AudioEffect {
44
45    private final static String TAG = "NoiseSuppressor";
46
47    /**
48     * Class constructor.
49     * <p> The application must catch exceptions when creating an NoiseSuppressor as the
50     * constructor is not guarantied to succeed:
51     * <ul>
52     *  <li>IllegalArgumentException is thrown if the device does not implement an NS</li>
53     *  <li>UnsupportedOperationException is thrown is the resources allocated to audio
54     *  pre-procesing are currently exceeded.</li>
55     * </ul>
56     *
57     * @param audioSession system wide unique audio session identifier. The NoiseSuppressor
58     * will be applied to the AudioRecord with the same audio session.
59     *
60     * @throws java.lang.IllegalArgumentException
61     * @throws java.lang.UnsupportedOperationException
62     * @throws java.lang.RuntimeException
63     */
64    public NoiseSuppressor(int audioSession)
65            throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
66        super(EFFECT_TYPE_NS, EFFECT_TYPE_NULL, 0, audioSession);
67    }
68}
69