警告：OpenSL ES 已弃用。开发者应使用开源的 Oboe 库，该库可在 GitHub 上获取。Oboe 是一个 C++ 封装容器，提供与 AAudio 非常相似的 API。AAudio 可用时，Oboe 会调用 AAudio；AAudio 不可用时，会回退到 OpenSL ES。
本页面详细介绍了 OpenSL ES™ 的 NDK 实现与 OpenSL ES 1.0.1 参考规范之间的差异。使用规范中的示例代码时，您可能需要对其进行修改才能使其在 Android 上运行。
除非另有说明，所有功能均在 Android 2.3 (API 级别 9) 及更高版本中提供。部分功能仅适用于 Android 4.0 (API 级别 14)；这些功能均已注明。
注意：Android 兼容性定义文档 (CDD) 列出了兼容 Android 设备的硬件和软件要求。如需了解整个兼容性计划的详细信息，请参阅Android 兼容性；如需查看实际的 CDD 文档，请参阅 CDD。
OpenSL ES 提供了一个 C 语言接口，该接口也可通过 C++ 访问。它提供的功能与以下 Android Java API 的音频部分类似：
与所有 Android Native Development Kit (NDK) 一样，Android 版 OpenSL ES 的主要目的是便于实现可通过 Java Native Interface (JNI) 调用的共享库。NDK 不适用于编写纯 C/C++ 应用。不过，OpenSL ES 是一个功能齐全的 API，我们希望您只需使用此 API 即可满足大多数音频需求，而无需向上调用在 Android 运行时中运行的代码。
注意：虽然基于 OpenSL ES，但 Android 原生音频（高性能音频）API 并非任何 OpenSL ES 1.0.1 配置文件（游戏、音乐或手机）的符合性实现。这是因为 Android 并未实现任何配置文件所需的所有功能。Android 与规范行为不同的任何已知情况均在本页面Android 扩展中介绍。
继承自参考规范的功能
Android NDK 实现的 OpenSL ES 继承了参考规范的大部分功能集，但存在某些限制。
全局入口点
Android 版 OpenSL ES 支持 Android 规范中的所有全局入口点。这些入口点包括
slCreateEngineslQueryNumSupportedEngineInterfacesslQuerySupportedEngineInterfaces
对象和接口
下表列出了 OpenSL ES 的 Android NDK 实现支持的对象和接口。如果单元格中显示是，则表示此实现提供该功能。
Android NDK 对对象和接口的支持。
| 功能 | 音频播放器 | 录音器 | 引擎 | 输出混音器 |
|---|---|---|---|---|
| 低音增强 | 是 | 否 | 否 | 是 |
| 缓冲区队列 | 是 | 否 | 否 | 否 |
| 缓冲区队列数据定位器 | 是：源 | 否 | 否 | 否 |
| 动态接口管理 | 是 | 是 | 是 | 是 |
| 效果发送 | 是 | 否 | 否 | 否 |
| 引擎 | 否 | 否 | 是 | 否 |
| 环境混响 | 否 | 否 | 否 | 是 |
| 均衡器 | 是 | 否 | 否 | 是 |
| I/O 设备数据定位器 | 否 | 是：源 | 否 | 否 |
| 元数据提取 | 是：解码为 PCM | 否 | 否 | 否 |
| 静音/独奏 | 是 | 否 | 否 | 否 |
| 对象 | 是 | 是 | 是 | 是 |
| 输出混音定位器 | 是：接收器 | 否 | 否 | 否 |
| 播放 | 是 | 否 | 否 | 否 |
| 播放速率 | 是 | 否 | 否 | 否 |
| 预加载状态 | 是 | 否 | 否 | 否 |
| 预设混响 | 否 | 否 | 否 | 是 |
| 录制 | 否 | 是 | 否 | 否 |
| 搜寻 | 是 | 否 | 否 | 否 |
| URI 数据定位器 | 是：源 | 否 | 否 | 否 |
| 虚拟器 | 是 | 否 | 否 | 是 |
| 音量 | 是 | 否 | 否 | 否 |
下一节说明其中某些功能的限制。
限制
表 1 中的功能适用某些限制。这些限制表示与参考规范的差异。本节的其余部分提供有关这些差异的信息。
动态接口管理
Android 版 OpenSL ES 不支持 RemoveInterface 或 ResumeInterface。
效果组合：环境混响和预设混响
同一个输出混音器上不能同时使用环境混响和预设混响。
如果平台估算 CPU 负载过高，则可能会忽略效果请求。
效果发送
SetSendLevel() 支持每个音频播放器有一个发送级别。
环境混响
环境混响不支持 SLEnvironmentalReverbSettings 结构体中的 reflectionsDelay、reflectionsLevel 或 reverbDelay 字段。
MIME 数据格式
MIME 数据格式只能与 URI 数据定位器一起使用，且仅适用于音频播放器。您不能将此数据格式用于录音器。
OpenSL ES 的 Android 实现要求您将 mimeType 初始化为 NULL 或有效的 UTF-8 字符串。您还必须将 containerType 初始化为有效值。在没有其他考虑因素（例如移植到其他实现或应用无法通过头识别的内容格式）的情况下，我们建议您将 mimeType 设置为 NULL，将 containerType 设置为 SL_CONTAINERTYPE_UNSPECIFIED。
Android 版 OpenSL ES 支持以下音频格式，前提是 Android 平台也支持这些格式：
- WAV PCM。
- WAV alaw。
- WAV ulaw。
- MP3 Ogg Vorbis。
- AAC LC。
- HE-AACv1 (AAC+)。
- HE-AACv2（增强型 AAC+）。
- AMR。
- FLAC。
注意：如需查看 Android 支持的音频格式列表，请参阅支持的媒体格式。
在此 OpenSL ES 实现中，处理这些格式和其他格式时适用以下限制：
- AAC 格式必须位于 MP4 或 ADTS 容器内。
- Android 版 OpenSL ES 不支持 MIDI。
- WMA 不属于 AOSP 的一部分，我们尚未验证其与 Android 版 OpenSL ES 的兼容性。
- OpenSL ES 的 Android NDK 实现不支持直接播放 DRM 或加密内容。要播放受保护的音频内容，您必须先在应用中对其进行解密，并在播放前由应用强制执行任何 DRM 限制。
与对象相关的方法
Android 版 OpenSL ES 不支持以下用于操纵对象的方法：
Resume()RegisterCallback()AbortAsyncOperation()SetPriority()GetPriority()SetLossOfControlInterfaces()
PCM 数据格式
PCM 是唯一可与缓冲区队列配合使用的数据格式。支持的 PCM 播放配置具有以下特征：
- 8 位无符号或 16 位有符号。
- 单声道或立体声。
- 小端字节序。
- 采样率包括：
- 8,000 Hz。
- 11,025 Hz。
- 12,000 Hz。
- 16,000 Hz。
- 22,050 Hz。
- 24,000 Hz。
- 32,000 Hz。
- 44,100 Hz。
- 48,000 Hz。
Android 版 OpenSL ES 支持的录制配置取决于设备；通常情况下，无论设备如何，都会提供 16,000 Hz 单声道/16 位有符号配置。
尽管名称具有误导性，但 samplesPerSec 字段的值以毫赫兹为单位。为避免意外使用错误的值，我们建议您使用为此目的定义的符号常量之一来初始化此字段，例如 SL_SAMPLINGRATE_44_1。
Android 5.0 (API 级别 21) 及更高版本支持浮点数据。
播放速率
OpenSL ES 播放速率表示对象呈现数据的速度，以正常速度的千分之一（即千分率）表示。例如，1,000 千分率的播放速率表示 1,000/1,000，即正常速度。速率范围是一个封闭区间，表示可能的播放速率范围。
对播放速率范围及其他功能的支持可能因平台版本和实现而异。您的应用可以在运行时使用 PlaybackRate::GetRateRange() 或 PlaybackRate::GetCapabilitiesOfRate() 查询设备来确定这些功能。
对于 PCM 格式的数据源，设备通常支持相同的速率范围；对于其他格式，则支持 1000 千分率到 1000 千分率的单一速率范围；也就是说，单一速率范围实际上是一个单一值。
录制
Android 版 OpenSL ES 不支持 SL_RECORDEVENT_HEADATLIMIT 或 SL_RECORDEVENT_HEADMOVING 事件。
搜寻
SetLoop() 方法启用整个文件的循环播放。要启用循环播放，请将 startPos 参数设置为 0，并将 endPos 参数设置为 SL_TIME_UNKNOWN。
缓冲区队列数据定位器
使用缓冲区队列数据定位器的音频播放器或录音器仅支持 PCM 数据格式。
I/O 设备数据定位器
Android 版 OpenSL ES 仅当您将 I/O 设备数据定位器指定为 Engine::CreateAudioRecorder() 的数据源时才支持使用它。使用以下代码段中包含的值初始化设备数据定位器：
SLDataLocator_IODevice loc_dev = {SL_DATALOCATOR_IODEVICE, SL_IODEVICE_AUDIOINPUT, SL_DEFAULTDEVICEID_AUDIOINPUT, NULL};
URI 数据定位器
Android 版 OpenSL ES 只能将 URI 数据定位器与 MIME 数据格式配合使用，并且只能用于音频播放器。您不能将 URI 数据定位器用于录音器。URI 只能使用 http: 和 file: 方案。其他方案，如 https:、ftp: 或 content:，均不允许。
我们尚未验证 Android 平台对带音频的 rtsp: 的支持。
数据结构
Android 支持以下 OpenSL ES 1.0.1 数据结构：
SLDataFormat_MIMESLDataFormat_PCMSLDataLocator_BufferQueueSLDataLocator_IODeviceSLDataLocator_OutputMixSLDataLocator_URISLDataSinkSLDataSourceSLEngineOptionSLEnvironmentalReverbSettingsSLInterfaceID
平台配置
Android 版 OpenSL ES 专为多线程应用设计，是线程安全的。它支持每个应用有一个引擎，每个引擎最多支持 32 个对象。可用的设备内存和 CPU 可能会进一步限制可用的对象数量。
这些引擎选项是可以识别的，但 slCreateEngine 会忽略它们：
SL_ENGINEOPTION_THREADSAFESL_ENGINEOPTION_LOSSOFCONTROL
OpenMAX AL 和 OpenSL ES 可在同一个应用中一起使用。在这种情况下，内部只有一个共享引擎对象，且 32 个对象限制由 OpenMAX AL 和 OpenSL ES 共享。应用应创建两个引擎，使用两个引擎，最后销毁两个引擎。实现会维护共享引擎的引用计数，以便在第二次销毁操作期间正确销毁它。
编程注意事项
OpenSL ES 编程注意事项提供补充信息，以确保 OpenSL ES 的正确实现。
注意：为方便起见，我们已将 OpenSL ES 1.0.1 规范的副本包含在 NDK 中，路径为 docs/opensles/OpenSL_ES_Specification_1.0.1.pdf。
平台问题
本节介绍支持这些 API 的初始平台版本中的已知问题。
动态接口管理
DynamicInterfaceManagement::AddInterface 不起作用。相反，请在传递给 Create() 的数组中指定接口，如环境混响的示例代码所示。
未来版本的 OpenSL ES 计划
Android 高性能音频 API 基于 Khronos Group OpenSL ES 1.0.1。Khronos 发布了标准的修订版 1.1。修订版包括新功能、澄清、排印错误的更正以及一些不兼容之处。大多数预期的不兼容之处相对较小，或者位于 Android 不支持的 OpenSL ES 领域。
使用此版本开发的应用应可在未来版本的 Android 平台上运行，前提是您遵循下文二进制兼容性计划部分中概述的指南。
注意：未来的源代码兼容性并非目标。也就是说，如果您升级到较新版本的 NDK，您可能需要修改应用源代码以符合新的 API。我们预计大多数此类更改将是微小的；详见下文。
二进制兼容性计划
我们建议您的应用遵循以下指南，以提高未来的二进制兼容性：
- 仅使用 OpenSL ES 1.0.1 中 Android 支持功能的已记录子集。
- 不要依赖于失败操作的特定结果代码；请准备好处理不同的结果代码。
- 应用回调处理程序通常在受限的环境中运行。应编写它们以快速完成工作，并尽快返回。不要在回调处理程序中运行复杂的操作。例如，在缓冲区队列完成回调中，您可以将另一个缓冲区入队，但不要创建音频播放器。
- 回调处理程序应准备好以或多或少的频率被调用，接收其他事件类型，并忽略无法识别的事件类型。配置了由已启用事件类型组成的事件掩码的回调应准备好同时设置多个事件类型位被调用。使用 "&" 来测试每个事件位，而不是使用 switch case。
- 使用预加载状态和回调作为进度的通用指示，但不要依赖于特定的硬编码填充级别或回调序列。预加载状态填充级别的含义以及预加载期间检测到的错误的行为可能会更改。
注意：如需了解详情，请参阅下文的缓冲区队列行为部分。
源代码兼容性计划
如前所述，Khronos Group 下一个版本的 OpenSL ES 预计会出现源代码不兼容。可能的变化领域包括：
- 预计缓冲区队列接口将发生重大变化，尤其是在
BufferQueue::Enqueue、slBufferQueueCallback的参数列表以及SLBufferQueueState.playIndex字段的名称方面。我们建议您的应用代码改用 Android 简单缓冲区队列。因此，在 NDK 提供的示例代码中，我们已使用 Android 简单缓冲区队列进行播放。（我们还使用 Android 简单缓冲区队列进行录制和解码为 PCM，但这是因为标准 OpenSL ES 1.0.1 不支持录制或解码到缓冲区队列数据接收器。） - 对于按引用传递的输入参数以及用作输入值的
SLchar *结构体字段，将添加const。这应该不需要更改您的代码。 - 对于一些当前为有符号的参数，将替换为无符号类型。您可能需要将参数类型从
SLint32更改为SLuint32或类似类型，或者添加强制转换。 Equalizer::GetPresetName会将字符串复制到应用内存中，而不是返回指向实现内存的指针。这将是一个重大更改，因此我们建议您要么避免调用此方法，要么隔离对此方法的使用。- 结构体类型中将有额外的字段。对于输出参数，这些新字段可以忽略，但对于输入参数，需要初始化这些新字段。幸运的是，所有这些字段预计都在 Android 不支持的领域。
- 接口 GUID 将更改。通过符号名称而不是 GUID 引用接口，以避免依赖。
SLchar将从unsigned char更改为char。这主要影响 URI 数据定位器和 MIME 数据格式。SLDataFormat_MIME.mimeType将重命名为pMimeType，SLDataLocator_URI.URI将重命名为pURI。我们建议您使用大括号括起来的逗号分隔值列表来初始化SLDataFormat_MIME和SLDataLocator_URI数据结构，而不是按字段名称初始化，以隔离您的代码不受此更改的影响。示例代码中使用了此技术。SL_DATAFORMAT_PCM不允许应用指定数据表示为有符号整数、无符号整数或浮点数。Android 实现假定 8 位数据是无符号整数，16 位数据是有符号整数。此外，字段samplesPerSec的名称有误导性，因为实际单位是毫赫兹。这些问题预计将在 OpenSL ES 的下一个版本中解决，该版本将引入一种新的扩展 PCM 数据格式，允许应用明确指定表示并更正字段名称。由于这将是一个新的数据格式，并且当前的 PCM 数据格式仍将可用（尽管已弃用），因此不应需要立即更改您的代码。