1 page.title=High-Performance Audio Basics 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>On this page</h2> 7 8 <ol> 9 <li><a href="#overview">Building Great Audio Apps</a></li> 10 <li><a href="#adding">Adding OpenSL ES to Your App</a></li> 11 <li><a href="#building">Building and Debugging</a></li> 12 <li><a href="#power">Audio Power Consumption</a></li> 13 <li><a href="#samples">Samples</a></li> 14 </ol> 15 </div> 16 </div> 17 18 <a href="https://www.youtube.com/watch?v=d3kfEeMZ65c" class="notice-developers-video"> 19 <div> 20 <h3>Video</h3> 21 <p>Google I/O 2013 - High Performance Audio</p> 22 </div> 23 </a> 24 25 <p> 26 The Khronos Group's OpenSL ES standard exposes audio features 27 similar to those in the {@link android.media.MediaPlayer} and {@link android.media.MediaRecorder} 28 APIs in the Android Java framework. OpenSL ES provides a C language interface as well as 29 C++ bindings, allowing you to call it from code written in either language. 30 </p> 31 32 <p> 33 This page describes the typical use cases for these high-performance audio APIs, how to add them 34 into your app's source code, and how to incorporate them into the build process. 35 </p> 36 37 <h2 id="overview">Building Great Audio Apps</h2> 38 39 <p> 40 The OpenSL ES APIs are available to help you develop and improve your app's audio performance. 41 Some typical use cases include the following:</p> 42 43 <ul> 44 <li>Digital Audio Workstations (DAWs).</li> 45 <li>Synthesizers.</li> 46 <li>Drum machines.</li> 47 <li>Music learning apps.</li> 48 <li>Karaoke apps.</li> 49 <li>DJ mixing.</li> 50 <li>Audio effects.</li> 51 <li>Video/audio conferencing.</li> 52 </ul> 53 54 <h2 id="adding">Adding OpenSL ES to your App</h2> 55 56 <p> 57 You can call OpenSL ES from both C and C++ code. To add the core OpenSL ES 58 feature set to your app, include the {@code OpenSLES.h} header file: 59 60 </p> 61 <pre> 62 #include <SLES/OpenSLES.h> 63 </pre> 64 65 <p> 66 To add the OpenSL ES <a href="{@docRoot}ndk/guides/audio/opensl-for-android.html#ae"> 67 Android extensions</a> as well, include the {@code OpenSLES_Android.h} header file: 68 </p> 69 <pre> 70 #include <SLES/OpenSLES_Android.h> 71 </pre> 72 73 <p> 74 When you include the {@code OpenSLES_Android.h} header file, the following headers are included 75 automatically: 76 </p> 77 <pre> 78 #include <SLES/OpenSLES_AndroidConfiguration.h> 79 #include <SLES/OpenSLES_AndroidMetadata.h> 80 </pre> 81 82 <p class="note"><strong>Note: </strong> 83 These headers are not required, but are shown as an aid in learning the API. 84 </p> 85 86 <h2 id="building">Building and Debugging</h2> 87 88 <p> 89 You can incorporate OpenSL ES into your build by specifying it in the 90 <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file that serves as one of the 91 NDK build system's makefiles. Add the following line to 92 <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>: 93 </p> 94 95 <pre> 96 LOCAL_LDLIBS += -lOpenSLES 97 </pre> 98 99 <p> 100 For robust debugging, we recommend that you examine the {@code SLresult} value that most of 101 the OpenSL ES APIs return. You can use 102 <a class="external-link" href="http://en.wikipedia.org/wiki/Assertion_(computing)">asserts</a> 103 or more advanced error-handling logic for debugging; neither offers 104 an inherent advantage for working with OpenSL ES, although one or the other might be more suitable 105 for a given use case. 106 </p> 107 108 <p> 109 We use asserts in our <a class="external-link" href="https://github.com/googlesamples/android-ndk"> 110 examples</a>, because they help catch unrealistic conditions that would indicate a coding error. We 111 have used explicit error handling for other conditions more likely to occur in production. 112 </p> 113 114 <p> 115 Many API errors result in a log entry, in addition to a non-zero result code. Such log entries 116 can provide additional detail that proves especially useful for relatively complex APIs such as 117 <a class="external-link" href="https://www.khronos.org/registry/sles/specs/OpenSL_ES_Specification_1.1.pdf"> 118 {@code Engine::CreateAudioPlayer}</a>. 119 </p> 120 121 <p> 122 You can view the log either from the command line or from Android Studio. To examine the log from 123 the command line, type the following: 124 </p> 125 126 <pre class="no-pretty-print"> 127 $ adb logcat 128 </pre> 129 130 <p> 131 To examine the log from Android Studio, either click the <strong>Logcat</strong> tab in the 132 <a href="{@docRoot}tools/debugging/debugging-studio.html#runDebug">Debug</a> 133 window, or click the <strong>Devices | logcat</strong> tab in the 134 <a href="{@docRoot}tools/debugging/debugging-studio.html#systemLogView">Android DDMS</a> 135 window. 136 </p> 137 <h2 id="power">Audio Power Consumption</h2> 138 <p>Constantly outputting audio incurs significant power consumption. Ensure that you stop the 139 output in the 140 <a href="{@docRoot}reference/android/app/Activity.html#onPause()">onPause()</a> method. 141 Also consider pausing the silent output after some period of user inactivity. 142 </p> 143 <h2 id="samples">Samples</h2> 144 145 <p> 146 Supported and tested example code that you can use as a model for your own code resides both locally 147 and on 148 <a class="external-link" href="https://github.com/googlesamples/android-audio-high-performance/"> 149 GitHub</a>. The local examples are located in 150 {@code platforms/android-9/samples/native-audio/}, under your NDK root installation directory. 151 On GitHub, they are available from the 152 <a class="external-link" href="https://github.com/googlesamples/android-ndk">{@code android-ndk}</a> 153 repository, in the 154 <a class="external-link" href="https://github.com/googlesamples/android-ndk/tree/master/audio-echo"> 155 {@code audio-echo}</a> and 156 <a class="external-link" href="https://github.com/googlesamples/android-ndk/tree/master/native-audio"> 157 {@code native-audio}</a> directories. 158 </p> 159 <p>The Android NDK implementation of OpenSL ES differs 160 from the reference specification for OpenSL ES 1.0.1 in a number of respects. 161 These differences are an important reason as to why sample code that 162 you copy directly from the OpenSL ES reference specification may not work in your 163 Android app. 164 </p> 165 <p> 166 For more information on differences between the reference specification and the 167 Android implementation, see 168 <a href="{@docRoot}ndk/guides/audio/opensl-for-android.html"> 169 OpenSL ES for Android</a>. 170
