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