1 page.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> 29 package, which is available for developers to access. For example, the Nexus 10 30 supports 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 35 Echo 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 40 Suppression</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 45 pre-processing is requested. In Android app development, a use case is referred 46 to as an <code>AudioSource</code>; and app developers request to use the 47 <code>AudioSource</code> abstraction instead of the actual audio hardware 48 device. The Android Audio Policy Manager maps an <code>AudioSource</code> to a 49 given capture path configuration (device, gain, pre processing, etc.) according 50 to 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> 64 are specified in the <code>/system/etc/audio_effects.conf</code> file. To 65 specify your own default effects for every <code>AudioSource</code>, create a 66 <code>/system/vendor/etc/audio_effects.conf</code> file and specify the 67 pre-processing effects to turn on. For an example, see the implementation for 68 the Nexus 10 in <code>device/samsung/manta/audio_effects.conf</code>. 69 AudioEffect instances acquire and release a session when created and destroyed, 70 enabling the effects (such as the Loudness Enhancer) to persist throughout the 71 duration 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 75 pre-processing effect. It should not be turned on by default when recording from 76 this audio source, and you should not enable it in your own audio_effects.conf 77 file. Turning on the effect by default will cause the device to fail the 78 <a href="{@docRoot}compatibility/index.html"> compatibility requirement</a> 79 regardless of whether this was on by default due to configuration file , or the 80 audio 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 84 the <code>AudioSource</code> configuration in this manner, the framework will 85 automatically request from the audio HAL the use of those effects.</p> 86 87 <p><pre> 88 pre_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 102 gain 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 < 1% (90dB SPL in 100 to 4000Hz range)</li> 110 <li>Near-ultrasound requirements (for testing, see 111 <a href="{@docRoot}compatibility/cts/near-ultrasound.html">Near Ultrasound 112 Tests</a>): 113 <ul> 114 <li>Support for SUPPORT_PROPERTY_MIC_NEAR_ULTRASOUND as defined in section 7.8.3 115 of the CDD.</li> 116 <li>Support one or both of 44100 or 48000 sampling rates with no band-pass or 117 anti-aliasing filters.</li> 118 </ul></li> 119 <li>Effects/pre-processing must be disabled by default</li> 120 </ul> 121 122 <p>Examples of tuning different effects for different sources are:</p> 123 124 <ul> 125 <li>Noise Suppressor 126 <ul> 127 <li>Tuned for wind noise suppressor for <code>CAMCORDER</code></li> 128 <li>Tuned for stationary noise suppressor for <code>VOICE_COMMUNICATION</code></li> 129 </ul> 130 </li> 131 <li>Automatic Gain Control 132 <ul> 133 <li>Tuned for close-talk for <code>VOICE_COMMUNICATION</code> and main phone 134 mic</li> 135 <li>Tuned for far-talk for <code>CAMCORDER</code></li> 136 </ul> 137 </li> 138 </ul> 139 140 <h2 id="resources">Resources</h2> 141 142 <p>For more information, refer to the following resources:</p> 143 144 <ul> 145 <li>Android documentation for 146 <a href="http://developer.android.com/reference/android/media/audiofx/package-summary.html">audiofx 147 package</a></li> 148 149 <li>Android documentation for 150 <a href="http://developer.android.com/reference/android/media/audiofx/NoiseSuppressor.html">Noise 151 Suppression audio effect</a></li> 152 153 <li><code>device/samsung/manta/audio_effects.conf</code> file for the Nexus 10</li> 154 </ul> 155
