Skip to content

Most visited

Recently visited

navigation

OpenSL ES for Android

This page provides details about how the NDK implementation of OpenSL ES™ differs from the reference specification for OpenSL ES 1.0.1. When using sample code from the specification, you may need to modify it to work on Android.

Unless otherwise noted, all features are available at Android 2.3 (API level 9) and higher. Some features are only available for Android 4.0 (API level 14); these are noted.

Note: The Android Compatibility Definition Document (CDD) enumerates the hardware and software requirements of a compatible Android device. See Android Compatibility for more information on the overall compatibility program, and CDD for the actual CDD document.

OpenSL ES provides a C language interface that is also accessible using C++. It exposes features similar to the audio portions of these Android Java APIs:

As with all of the Android Native Development Kit (NDK), the primary purpose of OpenSL ES for Android is to facilitate the implementation of shared libraries to be called using the Java Native Interface (JNI ). NDK is not intended for writing pure C/C++ applications. However, OpenSL ES is a full-featured API, and we expect that you should be able to accomplish most of your audio needs using only this API, without up-calls to code running in the Android runtime.

Note: Though based on OpenSL ES, the Android native audio (high-performance audio) API is not a conforming implementation of any OpenSL ES 1.0.1 profile (game, music, or phone). This is because Android does not implement all of the features required by any one of the profiles. Any known cases where Android behaves differently than the specification are described in the Android Extensions page.

Features Inherited from the Reference Specification

The Android NDK implementation of OpenSL ES inherits much of the feature set from the reference specification, with certain limitations.

Global entry points

OpenSL ES for Android supports all of the global entry points in the Android specification. These entry points include:

Objects and interfaces

The following table shows the objects and interfaces that the Android NDK implementation of OpenSL ES supports. If a Yes appears in the cell, then the feature is available in this implementation.

Android NDK support for objects and interfaces.

Feature Audio player Audio recorder Engine Output mix
Bass boost Yes No No Yes
Buffer queue Yes No No No
Buffer queue data locator Yes: Source No No No
Dynamic interface management Yes Yes Yes Yes
Effect send Yes No No No
Engine No No Yes No
Environmental reverb No No No Yes
Equalizer Yes No No Yes
I/O device data locator No Yes: Source No No
Metadata extraction Yes: Decode to PCM No No No
Mute solo Yes No No No
Object Yes Yes Yes Yes
Output mix locator Yes: Sink No No No
Play Yes No No No
Playback rate Yes No No No
Prefetch status Yes No No No
Preset reverb No No No Yes
Record No Yes No No
Seek Yes No No No
URI data locator Yes: Source No No No
Virtualizer Yes No No Yes
Volume Yes No No No

The next section explains the limitations for some of these features.

Limitations

Certain limitations apply to the features in Table 1. These limitations represent differences from the reference specification. The rest of this section provides information about these differences.

Dynamic interface management

OpenSL ES for Android does not support RemoveInterface or ResumeInterface.

Effect combinations: environment reverb and preset reverb

You cannot have both environmental reverb and preset reverb on the same output mix.

The platform might ignore effect requests if it estimates that the CPU load would be too high.

Effect send

SetSendLevel() supports a single send level per audio player.

Environmental reverb

Environmental reverb does not support the reflectionsDelay, reflectionsLevel, or reverbDelay fields of the SLEnvironmentalReverbSettings struct.

MIME data format

You can use the MIME data format only with the URI data locator, and only for an audio player. You cannot use this data format for an audio recorder.

The Android implementation of OpenSL ES requires you to initialize mimeType to either NULL or a valid UTF-8 string. You must also initialize containerType to a valid value. In the absence of other considerations, such as portability to other implementations or content formats that an app cannot identify by header, we recommend that you set mimeType to NULL and containerType to SL_CONTAINERTYPE_UNSPECIFIED.

OpenSL ES for Android supports the following audio formats, so long as the Android platform supports them as well:

Note: For a list of audio formats that Android supports, see Supported Media Formats.

The following limitations apply to the handling of these and other formats in this implementation of OpenSL ES:

Object-related methods

OpenSL ES for Android does not support the following methods for manipulating objects:

PCM data format

PCM is the only data format you can use with buffer queues. Supported PCM playback configurations have the following characteristics:

The configurations that OpenSL ES for Android supports for recording are device-dependent; usually, 16,000 Hz mono/16-bit signed is available regardless of the device.

The value of the samplesPerSec field is in units of milliHz, despite the misleading name. To avoid accidentally using the wrong value, we recommend that you initialize this field using one of the symbolic constants defined for this purpose, such as SL_SAMPLINGRATE_44_1.

Android 5.0 (API level 21) and above support floating-point data.

Playback rate

An OpenSL ES playback rate indicates the speed at which an object presents data, expressed in thousandths of normal speed, or per mille. For example, a playback rate of 1,000 per mille is 1,000/1,000, or normal speed. A rate range is a closed interval that expresses a range of possible playback rates.

Support for playback rate ranges and other capabilities may vary depending on the platform version and implementation. Your app can determine these capabilities at runtime by using PlaybackRate::GetRateRange() or PlaybackRate::GetCapabilitiesOfRate() to query the device.

A device typically supports the same rate range for a data source in PCM format, and a unity rate range of 1000 per mille to 1000 per mille for other formats; that is, the unity rate range is effectively a single value.

Record

OpenSL ES for Android does not support the SL_RECORDEVENT_HEADATLIMIT or SL_RECORDEVENT_HEADMOVING events.

Seek

The SetLoop() method enables whole-file looping. To enable looping, set the startPos parameter to 0, and the endPos parameter to SL_TIME_UNKNOWN.

Buffer queue data locator

An audio player or recorder with a data locator for a buffer queue supports the PCM data format only.

I/O device data locator

OpenSL ES for Android only supports use of an I/O device data locator when you have specified the locator as the data source for Engine::CreateAudioRecorder(). Initialize the device data locator using the values contained in the following code snippet:

SLDataLocator_IODevice loc_dev =
  {SL_DATALOCATOR_IODEVICE, SL_IODEVICE_AUDIOINPUT,
  SL_DEFAULTDEVICEID_AUDIOINPUT, NULL};

URI data locator

OpenSL ES for Android can only use the URI data locator with the MIME data format, and only for an audio player. You cannot use a URI data locator for an audio recorder. The URI can only use the http: and file: schemes. Other schemes, such as https:, ftp:, or content: are not allowed.

We have not verified support for rtsp: with audio on the Android platform.

Data structures

Android supports these OpenSL ES 1.0.1 data structures:

Platform configuration

OpenSL ES for Android is designed for multi-threaded applications and is thread-safe. It supports a single engine per application and up to 32 objects per engine. Available device memory and CPU may further restrict the usable number of objects.

These engine options are recognized, but they're ignored by slCreateEngine:

OpenMAX AL and OpenSL ES may be used together in the same application. In this case, there is a single shared engine object internally, and the 32 object limit is shared between OpenMAX AL and OpenSL ES. The application should create both engines, use both engines, and finally destroy both engines. The implementation maintains a reference count on the shared engine so that it is correctly destroyed during the second destroy operation.

Programming Notes

OpenSL ES Programming Notes provides supplemental information to ensure proper implementation of OpenSL ES.

Note: For your convenience, we have included a copy of the OpenSL ES 1.0.1 specification with the NDK in docs/opensles/OpenSL_ES_Specification_1.0.1.pdf.

Platform Issues

This section describes known issues in the initial platform release that supports these APIs.

Dynamic interface management

DynamicInterfaceManagement::AddInterface does not work. Instead, specify the interface in the array that is passed to Create(), as shown in the example code for environmental reverb.

Planning for Future Versions of OpenSL ES

The Android high-performance audio APIs are based on Khronos Group OpenSL ES 1.0.1. Khronos has released a revised version 1.1 of the standard. The revised version includes new features, clarifications, corrections of typographical errors, and some incompatibilities. Most of the expected incompatibilities are relatively minor or are in areas of OpenSL ES that are not supported by Android.

An application developed with this version should work on future versions of the Android platform, provided that you follow the guidelines that are outlined in the Planning for binary compatibility section below.

Note: Future source compatibility is not a goal. That is, if you upgrade to a newer version of the NDK, you may need to modify your application source code to conform to the new API. We expect that most such changes will be minor; see details below.

Planning for binary compatibility

We recommend that your application follow these guidelines to improve future binary compatibility:

Note: See the Buffer queue behavior section below for more details.

Planning for source compatibility

As mentioned, source code incompatibilities are expected in the next version of OpenSL ES from Khronos Group. The likely areas of change include:

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)