page.title=Configuring Pre-Processing Effects
@jd:body

<!--
    Copyright 2016 The Android Open Source Project

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<div id="qv-wrapper">
  <div id="qv">
    <h2>In this document</h2>
    <ol id="auto-toc">
    </ol>
  </div>
</div>

<p>The Android platform provides audio effects on supported devices in the
<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx</a>
package, which is available for developers to access. For example, the Nexus 10
supports the following pre-processing effects:</p>

<ul>
<li>
<a href="http://developer.android.com/reference/android/media/audiofx/AcousticEchoCanceler.html">Acoustic
Echo Cancellation</a></li>
<li>
<a href="http://developer.android.com/reference/android/media/audiofx/AutomaticGainControl.html">Automatic Gain Control</a></li>
<li>
<a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">Noise
Suppression</a></li>
</ul>

<h2 id=audiosources>Pairing with AudioSources</h2>
<p>Pre-processing effects are paired with the use case mode in which the
pre-processing is requested. In Android app development, a use case is referred
to as an <code>AudioSource</code>; and app developers request to use the
<code>AudioSource</code> abstraction instead of the actual audio hardware
device. The Android Audio Policy Manager maps an <code>AudioSource</code> to a
given capture path configuration (device, gain, pre processing, etc.) according
to product-specific rules. The following sources are exposed to developers:</p>

<ul>
<li><code>android.media.MediaRecorder.AudioSource.CAMCORDER</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_COMMUNICATION</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_CALL</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_DOWNLINK</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_UPLINK</code></li>
<li><code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code></li>
<li><code>android.media.MediaRecorder.AudioSource.MIC</code></li>
<li><code>android.media.MediaRecorder.AudioSource.DEFAULT</code></li>
</ul>

<p>The default pre-processing effects applied for each <code>AudioSource</code>
are specified in the <code>/system/etc/audio_effects.conf</code> file. To
specify your own default effects for every <code>AudioSource</code>, create a
<code>/system/vendor/etc/audio_effects.conf</code> file and specify the
pre-processing effects to turn on. For an example, see the implementation for
the Nexus 10 in <code>device/samsung/manta/audio_effects.conf</code>.
AudioEffect instances acquire and release a session when created and destroyed,
enabling the effects (such as the Loudness Enhancer) to persist throughout the
duration of the session.</p>

<p class="warning"><strong>Warning:</strong> For the
<code>VOICE_RECOGNITION</code> use case, do not enable the noise suppression
pre-processing effect. It should not be turned on by default when recording from
this audio source, and you should not enable it in your own audio_effects.conf
file. Turning on the effect by default will cause the device to fail the
<a href="{@docRoot}compatibility/index.html"> compatibility requirement</a>
regardless of whether this was on by default due to configuration file , or the
audio HAL implementation's default behavior.</p>

<p>The following example enables pre-processing for the VoIP
<code>AudioSource</code> and Camcorder <code>AudioSource</code>. By declaring
the <code>AudioSource</code> configuration in this manner, the framework will
automatically request from the audio HAL the use of those effects.</p>

<p><pre>
pre_processing {
   voice_communication {
       aec {}
       ns {}
   }
   camcorder {
       agc {}
   }
}
</pre></p>

<h2 id=tuning>Source tuning</h2>

<p><code>AudioSource</code> tuning does not have explicit requirements on audio
gain or audio processing with the exception of voice recognition
(<code>VOICE_RECOGNITION</code>). Requirements for voice recognition include:</p>

<ul>
<li>Flat frequency response (+/- 3dB) from 100Hz to 4kHz</li>
<li>Close-talk config: 90dB SPL reads RMS of 2500 (16bit samples)</li>
<li>Level tracks linearly from -18dB to +12dB relative to 90dB SPL</li>
<li>THD &lt; 1% (90dB SPL in 100 to 4000Hz range)</li>
<li>Near-ultrasound requirements (for testing, see
<a href="{@docRoot}compatibility/cts/near-ultrasound.html">Near Ultrasound
Tests</a>):
<ul>
<li>Support for SUPPORT_PROPERTY_MIC_NEAR_ULTRASOUND as defined in section 7.8.3
of the CDD.</li>
<li>Support one or both of 44100 or 48000 sampling rates with no band-pass or
anti-aliasing filters.</li>
</ul></li>
<li>Effects/pre-processing must be disabled by default</li>
</ul>

<p>Examples of tuning different effects for different sources are:</p>

<ul>
<li>Noise Suppressor
<ul>
<li>Tuned for wind noise suppressor for <code>CAMCORDER</code></li>
<li>Tuned for stationary noise suppressor for <code>VOICE_COMMUNICATION</code></li>
</ul>
</li>
<li>Automatic Gain Control
<ul>
<li>Tuned for close-talk for <code>VOICE_COMMUNICATION</code> and main phone
mic</li>
<li>Tuned for far-talk for <code>CAMCORDER</code></li>
</ul>
</li>
</ul>

<h2 id="resources">Resources</h2>

<p>For more information, refer to the following resources:</p>

<ul>
<li>Android documentation for
<a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx
package</a></li>

<li>Android documentation for
<a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">Noise
Suppression audio effect</a></li>

<li><code>device/samsung/manta/audio_effects.conf</code> file for the Nexus 10</li>
</ul>