Merge "Docs: Add Audio (OpenSL ES) section to NDK docs on DAC." into mnc-docs

page.title=OpenSL ES™ Basics

@jd:body

<div id="qv-wrapper">

    <div id="qv">

      <h2>On this page</h2>

      <ol>

        <li><a href="#adding">Adding OpenSL ES to Your App</a></li>

        <li><a href="#building">Building and Debugging</a></li>

        <li><a href="#samples">Samples</a></li>

      </ol>

    </div>

  </div>

<p>

The Khronos Group's OpenSL ES standard exposes audio features

similar to those in the {@link android.media.MediaPlayer} and {@link android.media.MediaRecorder}

APIs in the Android Java framework. OpenSL ES provides a C language interface as well as

C++ bindings, allowing you to call it from code written in either language.

</p>

<p>

This page describes how to add these audio APIs into your app's source code, and how to incorporate

them into the build process.

</p>

<h2 id="adding">Adding OpenSL ES to your App</h2>

<p>

You can call OpenSL ES from both C and C++ code. To add the core OpenSL ES

feature set to your app, include the {@code OpenSLES.h} header file:

</p>

<pre>

#include <SLES/OpenSLES.h>

</pre>

<p>

To add the OpenSL ES <a href="{@docRoot}ndk/guides/audio/opensl-for-android.html#ae">

Android extensions</a> as well, include the {@code OpenSLES_Android.h} header file:

</p>

<pre>

#include <SLES/OpenSLES_Android.h>

</pre>

<h2 id="building">Building and Debugging</h2>

<p>

You can incorporate OpenSL ES into your build by specifying it in the

<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file that serves as one of the

NDK build system's makefiles. Add the following line to

<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>:

</p>

<pre>

LOCAL_LDLIBS += -lOpenSLES

</pre>

<p>

For robust debugging, we recommend that you examine the {@code SLresult} value that most of

the OpenSL ES APIs return. You can use

<a class="external-link" href="http://en.wikipedia.org/wiki/Assertion_(computing)">asserts</a>

or more advanced error-handling logic for debugging; neither offers

an inherent advantage for working with OpenSL ES, although one or the other might be more suitable

for a given use case.

</p>

<p>

We use asserts in our <a href="https://github.com/googlesamples/android-ndk">examples</a>, because

they help catch unrealistic conditions that would indicate a coding error. We have used explicit

error handling for other conditions more likely to occur in production.

</p>

<p>

Many API errors result in a log entry, in addition to a non-zero result code. Such log entries

can provide additional detail that proves especially useful for relatively complex APIs such as

<a class="external-link" href="https://www.khronos.org/registry/sles/specs/OpenSL_ES_Specification_1.1.pdf">

{@code Engine::CreateAudioPlayer}</a>.

</p>

<p>

You can view the log either from the command line or from Android Studio. To examine the log from

the command line, type the following:

</p>

<pre class="no-pretty-print">

$ adb logcat

</pre>

<p>

To examine the log from Android Studio, either click the <em>Logcat</em> tab in the

<a href="{@docRoot}tools/debugging/debugging-studio.html#runDebug"><em>Debug</em></a>

window, or click the <em>Devices | logcat</em> tab in the

<a href="{@docRoot}tools/debugging/debugging-studio.html#systemLogView"><em>Android DDMS</em></a>

window.

</p>

<h2 id="samples">Samples</h2>

<p>

Supported and tested example code that you can use as a model for your own code resides both locally

and on GitHub. The local examples are located in

{@code platforms/android-9/samples/native-audio/}, under your NDK root installation directory.

On GitHub, they are available from the

<a class="external-link" href="https://github.com/googlesamples/android-ndk">{@code android-ndk}</a>

repository, in the

<a class="external-link" href="https://github.com/googlesamples/android-ndk/tree/master/audio-echo">

{@code audio-echo}</a> and

<a class="external-link" href="https://github.com/googlesamples/android-ndk/tree/master/native-audio">

{@code native-audio}</a> directories.

</p>

<p>The Android NDK implementation of OpenSL ES differs

from the reference specification for OpenSL ES 1.0.1 in a number of respects.

These differences are an important reason as to why sample code that

you copy directly from the OpenSL ES reference specification may not work in your

Android app.

</p>

<p>

For more information on differences between the reference specification and the

Android implementation, see

<a href="{@docRoot}ndk/guides/audio/opensl-for-android.html">

OpenSL ES™ for Android</a>.

page.title=NDK Audio: Open SL&#8482 ES

@jd:body

<p>The NDK package includes an Android-specific implementation of the

<a href="https://www.khronos.org/opensles/">Open SL ES</a> API

specification from the <a href="https://www.khronos.org">Khronos Group</a>. This library

allows you to use C or C++ to implement high-performance, low-latency audio in your game or other

demanding app.</p>

<p>This section begins by providing some

<a href="{@docRoot}ndk/guides/audio/basics.html">basic information</a> about the API, including how

to incorporate it into your app. It then explains what you need to know about the

<a href="{@docRoot}ndk/guides/audio/opensl-for-android.html">Android-specific implementation</a>

of OpenSL ES, focusing on differences between this implementation and the reference specification.

</p>

 No newline at end of file

      </ul>

   </li>

      <li class="nav-section">

      <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/audio/index.html">

      <span class="en">Audio</span></a></div>

      <ul>

      <li><a href="<?cs var:toroot ?>ndk/guides/audio/basics.html">Basics</a></li>

      <li><a href="<?cs var:toroot ?>ndk/guides/audio/opensl-for-android.html">OpenSL ES for

      Android</a></li>

      </ul>

   </li>

</ul>