blob: b7e39af821aa341ba387f7d6013297d3eb3f1fc1 [file] [log] [blame]
Heidi von Markhamd0333d62016-07-08 12:05:46 -07001page.title=Configuring Pre-Processing Effects
2@jd:body
3
4<!--
5 Copyright 2016 The Android Open Source Project
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18-->
19<div id="qv-wrapper">
20 <div id="qv">
21 <h2>In this document</h2>
22 <ol id="auto-toc">
23 </ol>
24 </div>
25</div>
26
27<p>The Android platform provides audio effects on supported devices in the
28<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx</a>
29package, which is available for developers to access. For example, the Nexus 10
30supports the following pre-processing effects:</p>
31
32<ul>
33<li>
34<a href="http://developer.android.com/reference/android/media/audiofx/AcousticEchoCanceler.html">Acoustic
35Echo Cancellation</a></li>
36<li>
37<a href="http://developer.android.com/reference/android/media/audiofx/AutomaticGainControl.html">Automatic Gain Control</a></li>
38<li>
39<a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">Noise
40Suppression</a></li>
41</ul>
42
43<h2 id=audiosources>Pairing with AudioSources</h2>
44<p>Pre-processing effects are paired with the use case mode in which the
45pre-processing is requested. In Android app development, a use case is referred
46to as an <code>AudioSource</code>; and app developers request to use the
47<code>AudioSource</code> abstraction instead of the actual audio hardware
48device. The Android Audio Policy Manager maps an <code>AudioSource</code> to a
49given capture path configuration (device, gain, pre processing, etc.) according
50to product-specific rules. The following sources are exposed to developers:</p>
51
52<ul>
53<li><code>android.media.MediaRecorder.AudioSource.CAMCORDER</code></li>
54<li><code>android.media.MediaRecorder.AudioSource.VOICE_COMMUNICATION</code></li>
55<li><code>android.media.MediaRecorder.AudioSource.VOICE_CALL</code></li>
56<li><code>android.media.MediaRecorder.AudioSource.VOICE_DOWNLINK</code></li>
57<li><code>android.media.MediaRecorder.AudioSource.VOICE_UPLINK</code></li>
58<li><code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code></li>
59<li><code>android.media.MediaRecorder.AudioSource.MIC</code></li>
60<li><code>android.media.MediaRecorder.AudioSource.DEFAULT</code></li>
61</ul>
62
63<p>The default pre-processing effects applied for each <code>AudioSource</code>
64are specified in the <code>/system/etc/audio_effects.conf</code> file. To
65specify your own default effects for every <code>AudioSource</code>, create a
66<code>/system/vendor/etc/audio_effects.conf</code> file and specify the
67pre-processing effects to turn on. For an example, see the implementation for
68the Nexus 10 in <code>device/samsung/manta/audio_effects.conf</code>.
69AudioEffect instances acquire and release a session when created and destroyed,
70enabling the effects (such as the Loudness Enhancer) to persist throughout the
71duration of the session.</p>
72
73<p class="warning"><strong>Warning:</strong> For the
74<code>VOICE_RECOGNITION</code> use case, do not enable the noise suppression
75pre-processing effect. It should not be turned on by default when recording from
76this audio source, and you should not enable it in your own audio_effects.conf
77file. Turning on the effect by default will cause the device to fail the
78<a href="{@docRoot}compatibility/index.html"> compatibility requirement</a>
79regardless of whether this was on by default due to configuration file , or the
80audio HAL implementation's default behavior.</p>
81
82<p>The following example enables pre-processing for the VoIP
83<code>AudioSource</code> and Camcorder <code>AudioSource</code>. By declaring
84the <code>AudioSource</code> configuration in this manner, the framework will
85automatically request from the audio HAL the use of those effects.</p>
86
87<p><pre>
88pre_processing {
89 voice_communication {
90 aec {}
91 ns {}
92 }
93 camcorder {
94 agc {}
95 }
96}
97</pre></p>
98
99<h2 id="tuning">Source tuning</h2>
100
101<p><code>AudioSource</code> tuning does not have explicit requirements on audio
102gain or audio processing with the exception of voice recognition
103(<code>VOICE_RECOGNITION</code>). Requirements for voice recognition include:</p>
104
105<ul>
106<li>Flat frequency response (+/- 3dB) from 100Hz to 4kHz</li>
107<li>Close-talk config: 90dB SPL reads RMS of 2500 (16bit samples)</li>
108<li>Level tracks linearly from -18dB to +12dB relative to 90dB SPL</li>
109<li>THD &lt; 1% (90dB SPL in 100 to 4000Hz range)</li>
110<li>8kHz sampling rate (anti-aliasing)</li>
111<li>Effects/pre-processing must be disabled by default</li>
112</ul>
113
114<p>Examples of tuning different effects for different sources are:</p>
115
116<ul>
117<li>Noise Suppressor
118<ul>
119<li>Tuned for wind noise suppressor for <code>CAMCORDER</code></li>
120<li>Tuned for stationary noise suppressor for <code>VOICE_COMMUNICATION</code></li>
121</ul>
122</li>
123<li>Automatic Gain Control
124<ul>
125<li>Tuned for close-talk for <code>VOICE_COMMUNICATION</code> and main phone mic</li>
126<li>Tuned for far-talk for <code>CAMCORDER</code></li>
127</ul>
128</li>
129</ul>
130
131<h2 id="more">Resources</h2>
132
133<p>For more information, refer to the following resources:</p>
134
135<ul>
136<li>Android documentation for
137<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">
138audiofx package</a></li>
139
140<li>Android documentation for
141<a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">
142Noise Suppression audio effect</a></li>
143
144<li><code>device/samsung/manta/audio_effects.conf</code> file for the Nexus 10</li>
145</ul>