Android 的 OpenSL ES

此页面提供有关 NDK 中 OpenSL ES™ 的实现与 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 规范中的所有全局入口点。这些入口点包括

  • slCreateEngine
  • slQueryNumSupportedEngineInterfaces
  • slQuerySupportedEngineInterfaces

对象和接口

下表显示了 Android NDK 中 OpenSL ES 的实现支持的对象和接口。如果单元格中显示“是”，则表示此实现中提供该功能。

Android NDK 对对象和接口的支持。

功能 音频播放器 音频录音机 引擎 输出混音器
低音增强 是 否 否 是
缓冲区队列 是 否 否 否
缓冲区队列数据定位器 是：源 否 否 否
动态接口管理 是 是 是 是
效果发送 是 否 否 否
引擎 否 否 是 否
环境混响 否 否 否 是
均衡器 是 否 否 是
I/O 设备数据定位器 否 是：源 否 否
元数据提取 是：解码为 PCM 否 否 否
静音独奏 是 否 否 否
对象 是 是 是 是
输出混音定位器 是：接收器 否 否 否
播放 是 否 否 否
播放速率 是 否 否 否
预取状态 是 否 否 否
预设混响 否 否 否 是
录制 否 是 否 否
查找 是 否 否 否
URI 数据定位器 是：源 否 否 否
虚拟化器 是 否 否 是
音量 是 否 否 否

下一节将解释其中一些功能的局限性。

局限性

表 1 中的功能存在某些局限性。这些局限性代表了与参考规范的差异。本节其余部分提供了有关这些差异的信息。

动态接口管理

Android 版 OpenSL ES 不支持 RemoveInterface 或 ResumeInterface。

效果组合：环境混响和预设混响

同一个输出混音中不能同时存在环境混响和预设混响。

如果平台估计 CPU 负载过高，它可能会忽略效果请求。

效果发送

SetSendLevel() 支持每个音频播放器一个发送级别。

环境混响

环境混响不支持 SLEnvironmentalReverbSettings 结构体的 reflectionsDelay、reflectionsLevel 或 reverbDelay 字段。

MIME 数据格式

MIME 数据格式只能与 URI 数据定位器一起使用，而且只能用于音频播放器。无法将此数据格式用于音频录制器。

Android 版 OpenSL ES 要求您将 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 的兼容性。
  • Android NDK 版 OpenSL ES 不支持直接播放 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 仅支持在将定位器指定为 Engine::CreateAudioRecorder() 的数据源时使用 I/O 设备数据定位器。使用以下代码片段中包含的值初始化设备数据定位器

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_MIME
  • SLDataFormat_PCM
  • SLDataLocator_BufferQueue
  • SLDataLocator_IODevice
  • SLDataLocator_OutputMix
  • SLDataLocator_URI
  • SLDataSink
  • SLDataSource
  • SLEngineOption
  • SLEnvironmentalReverbSettings
  • SLInterfaceID

平台配置

Android 版 OpenSL ES 专为多线程应用程序设计，并支持线程安全。它支持每个应用程序一个引擎，每个引擎最多支持 32 个对象。可用的设备内存和 CPU 可能会进一步限制可用的对象数量。

这些引擎选项已识别，但会被 slCreateEngine 忽略

  • SL_ENGINEOPTION_THREADSAFE
  • SL_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 数据格式仍然可用（虽然已弃用），因此它不应该要求您对代码进行任何立即更改。