Docs: Audio updates for N + nav changes
Adding Eric's feedback
Removing refs to audio_policy.h
Adding Clay's feedback
Cleaning up intro statement
Bug: 26686098
Change-Id: Ibe0a61b1a13111b3c45e3c41fcd9fbcaa054fc93
diff --git a/src/devices/audio/implement-pre-processing.jd b/src/devices/audio/implement-pre-processing.jd
new file mode 100644
index 0000000..b7e39af
--- /dev/null
+++ b/src/devices/audio/implement-pre-processing.jd
@@ -0,0 +1,145 @@
+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 < 1% (90dB SPL in 100 to 4000Hz range)</li>
+<li>8kHz sampling rate (anti-aliasing)</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="more">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>