Add Audio Latency for App Developers
Change-Id: I17c2561faedc145cedd21a055aa408cf1af9d8e2
diff --git a/src/devices/audio/images/venn.png b/src/devices/audio/images/venn.png
new file mode 100644
index 0000000..1db4f53
--- /dev/null
+++ b/src/devices/audio/images/venn.png
Binary files differ
diff --git a/src/devices/audio/latency.jd b/src/devices/audio/latency.jd
index 59c3f73..a45bf20 100644
--- a/src/devices/audio/latency.jd
+++ b/src/devices/audio/latency.jd
@@ -50,4 +50,8 @@
<td>Round-trip audio latency results</td>
<td><a href="latency_measurements.html">Audio Latency Measurements</a></td>
</tr>
+<tr>
+ <td>Applications</td>
+ <td><a href="latency_app.html">Audio Latency for App Developers</a></td>
+</tr>
</table>
diff --git a/src/devices/audio/latency_app.jd b/src/devices/audio/latency_app.jd
new file mode 100644
index 0000000..22e3984
--- /dev/null
+++ b/src/devices/audio/latency_app.jd
@@ -0,0 +1,174 @@
+page.title=Audio Latency for App Developers
+@jd:body
+
+<!--
+ Copyright 2015 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>For the lowest audio latency possible, we recommend you use Android native audio
+based on OpenSL ES 1.0.1.</p>
+
+<h2 id=implementation>Implementation checklist</h2>
+
+<p>To use Android native audio:</p>
+
+<ol>
+
+<li>
+Download and install the
+<a href="https://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>.
+In the rest of this document, we'll assume <code>NDKroot</code> is the
+directory where you installed NDK.
+</li>
+
+<li>
+Read the <a href="#supporting">supporting documentation.</a>
+</li>
+
+<li>
+Check for API level 9 or higher.
+</li>
+
+<li>
+Check for feature
+<a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html#hw-features">android.hardware.audio.low_latency.</a>
+</li>
+
+<li>
+Use the recommended native buffer size and sample rate returned by
+<a href="http://developer.android.com/reference/android/media/AudioManager.html#getProperty(java.lang.String)">android.media.AudioManager.getProperty(java.lang.String)</a>
+<p> <strong>Note</strong>: the same buffer size and sample rate should also be used for input.</p>
+</li>
+
+<li>
+Usually an OpenSL ES buffer count of 1 is sufficient.
+</li>
+
+<li>
+Keep your callback handlers short, without bursty CPU usage or unbounded blocking. Avoid
+<a href="avoiding_pi.html">priority inversion.</a>
+</li>
+
+<li>
+Consider using
+<a href="avoiding_pi.html#nonBlockingAlgorithms">non-blocking algorithms</a>
+to communicate between input and output callback handlers,
+and between the callback handlers and the rest of your application.
+</li>
+
+</ol>
+
+<h2 id=supporting>Supporting documentation</h2>
+
+<h3 id=opensl_es_1_0_1>OpenSL ES 1.0.1</h3>
+
+<p>
+Use a PDF viewer to review the
+<a href="https://www.khronos.org/registry/sles/specs/OpenSL_ES_Specification_1.0.1.pdf">OpenSL 1.0.1 Specification.</a>
+This is a rather long reference, and not all of it will be relevant to you; but you
+will need to consult it for details on the API.
+</p>
+
+<p class="note">
+<strong>Note</strong>: this document describes the full OpenSL ES 1.0.1, but Android
+native audio is actually based on a subset of OpenSL ES 1.0.1 with some Android-specific extensions.
+</p>
+
+<p>
+Documents describing later versions of OpenSL ES, such as 1.1,
+are not relevant to Android.
+</p>
+
+<h3 id=opensl_es_for_android>OpenSL ES for Android</h3>
+
+<p>
+The document "OpenSL ES for Android" is provided in the NDK installation,
+and is not currently available online. Open this link in a browser:
+</p>
+
+<pre>
+NDKroot/docs/Additional_library_docs/opensles/index.html
+</pre>
+
+<p>
+You’ll want to skim the whole
+document, but pay special attention to the "Performance" subsection of the
+"Programming notes" section.
+</p>
+
+<p>
+Section "Supported features from OpenSL ES 1.0.1"
+describes the subset supported by Android.
+</p>
+
+<p>
+Section "Android extensions" describes Android-specific extensions
+that aren't included in base OpenSL ES 1.0.1.
+</p>
+
+<h3 id=relationship>Relationship with OpenSL ES 1.0.1</h3>
+
+<p>
+This Venn diagram shows the relationship between
+Android native audio and OpenSL ES 1.0.1.
+</p>
+
+<img src="images/venn.png" alt="Venn diagram" id="figure1" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Venn diagram
+</p>
+
+<h2 id=resources>Other resources</h2>
+
+<h3 id=source_android_com>source.android.com</h3>
+
+<p>
+The site <a href="{@docRoot}">source.android.com</a>
+is primarily designed for OEMs building Android
+devices, and the SoC vendors who supply components to these OEMs.
+</p>
+
+<p>
+However, there is a wealth of useful information about latency at this site, so
+you may want to review it. See the articles at
+<a href="latency.html">Audio Latency.</a>
+</p>
+
+<h3 id=android_ndk>android-ndk</h3>
+
+<p>
+If you have questions about how to use Android native audio, you can ask at the discussion group
+<a href="https://groups.google.com/forum/#!forum/android-ndk">android-ndk.</a>
+</p>
+
+<h3 id=videos>Videos</h3>
+
+<dl>
+
+<dt><a href="https://www.youtube.com/watch?v=d3kfEeMZ65c">Google I/O 2013 - High performance audio on Android</a></dt>
+<dd>The whole video is about latency.</dd>
+
+<dt><a href="https://www.youtube.com/watch?v=92fgcUNCHic">Google I/O 2014 - Building great multi-media experiences on Android</a></dt>
+<dd>The first 14 minutes are about audio in general and input latency in particular.</dd>
+
+</dl>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index d0d7c63..e5be658 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -46,6 +46,7 @@
<li><a href="<?cs var:toroot ?>devices/audio/testing_circuit.html">Light Testing Circuit</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/loopback.html">Audio Loopback Dongle</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/latency_measurements.html">Measurements</a></li>
+ <li><a href="<?cs var:toroot ?>devices/audio/latency_app.html">Applications</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>devices/audio/avoiding_pi.html">Priority Inversion</a></li>
