This section provides the information needed to get started using the OpenSL ES APIs.
Adding OpenSL ES to your App
You can call OpenSL ES from both C and C++ code. To add the core OpenSL ES
feature set to your app, include the
OpenSLES.h header file:
To add the OpenSL ES
Android extensions as well, include the
OpenSLES_Android.h header file:
When you include the
OpenSLES_Android.h header file, the following headers are included
#include <SLES/OpenSLES_AndroidConfiguration.h> #include <SLES/OpenSLES_AndroidMetadata.h>
Note: These headers are not required, but are shown as an aid in learning the API.
Building and Debugging
LOCAL_LDLIBS += -lOpenSLES
For robust debugging, we recommend that you examine the
SLresult value that most of
the OpenSL ES APIs return. You can use
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.
We use asserts in our examples, 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.
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
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:
$ adb logcat
To examine the log from Android Studio, select View > Tool Windows > Logcat. For more information, see Write and View Logs with Logcat.
Caution: The OpenSL ES 1.0.1 specification contains example code in the appendices (see Khronos OpenSL ES Registry for more details). However, the examples in Appendix B: Sample Code and Appendix C: Use Case Sample Code use features that are not supported by Android. Some examples also contain typographical errors, or use APIs that are likely to change. Proceed with caution when referring to these; though the code may be helpful in understanding the full OpenSL ES standard, it should not be used as-is with Android.
The following are some of the many ways to package audio content for your application:
- Resources: By placing your audio files into the
res/raw/folder, they can be accessed easily by the associated APIs for
Resources. However, there is no direct native access to resources, so you must write Java programming language code to copy them out before use.
- Assets: By placing your audio files into the
assets/folder, they are directly accessible by the Android native asset manager APIs. See the header files
android/asset_manager_jni.hfor more information on these APIs. The example code located in the android-ndk GitHub repository uses these native asset manager APIs in conjunction with the Android file descriptor data locator.
- Network: You can use the URI data locator to play audio content directly from the network. However, be sure to read the Security and permissions section below.
- Local file system: The URI data locator supports the
file:scheme for local files, provided the files are accessible by the application. Note that the Android security framework restricts file access via the Linux user ID and group ID mechanisms.
- Recorded: Your application can record audio data from the microphone input, store this content, and then play it back later. The example code uses this method for the Playback clip.
- Compiled and linked inline: You can link your audio content directly into
the shared library, and then play it using an audio player with a buffer queue data locator. This
is most suitable for short PCM format clips. The example code uses this technique for the
Hello and Android clips. The PCM data was converted to hex strings using a
bin2ctool (not supplied).
- Real-time synthesis: Your application can synthesize PCM data on the fly and then play it using an audio player with buffer queue data locator. This is a relatively advanced technique, and the details of audio synthesis are beyond the scope of this article.
Note: Finding or creating useful audio content for your application is beyond the scope of this article. You can use web search terms such as interactive audio, game audio, sound design, and audio programming to locate more information.
Caution: It is your responsibility to ensure that you are legally permitted to play or record content. There may be privacy considerations for recording content.
These sample apps are available on our GitHub page:
- audio-echo creates an input-to-output roundtrip loop.
- native-audio is a simple audio recorder/player.
- SimpleSynth plays a sine wave. It shows how to obtain optimal audio latency and stable computational throughput.
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 why sample code that you copy directly from the OpenSL ES reference specification may not work in your Android app.
For more information on differences between the reference specification and the Android implementation, see OpenSL ES for Android.