开始使用

警告：OpenSL ES 已 **弃用**。开发者应使用可在 GitHub 上获取的开源 Oboe 库。Oboe 是一个 C++ 包装器，提供了一个与 AAudio 非常相似的 API。当 AAudio 可用时，Oboe 会调用 AAudio，如果 AAudio 不可用，则回退到 OpenSL ES。

本节提供开始使用 OpenSL ES API 所需的信息。

将 OpenSL ES 添加到您的应用

您可以从 C 和 C++ 代码中调用 OpenSL ES。要将核心 OpenSL ES 功能集添加到您的应用，请包含 OpenSLES.h 头文件

#include <SLES/OpenSLES.h>

要添加 OpenSL ES Android 扩展，也请包含 OpenSLES_Android.h 头文件

#include <SLES/OpenSLES_Android.h>

当您包含 OpenSLES_Android.h 头文件时，以下头文件会自动包含

#include <SLES/OpenSLES_AndroidConfiguration.h>
#include <SLES/OpenSLES_AndroidMetadata.h>

注意： 这些头文件不是必需的，但显示出来是为了帮助学习 API。

构建和调试

您可以通过在用作 NDK 构建系统 Makefile 之一的 Android.mk 文件中指定它来将 OpenSL ES 整合到您的构建中。将以下行添加到 Android.mk

LOCAL_LDLIBS += -lOpenSLES

为了进行稳健的调试，我们建议您检查大多数 OpenSL ES API 返回的 SLresult 值。您可以使用 断言 或更高级的错误处理逻辑进行调试；两者在处理 OpenSL ES 时都没有内在优势，尽管其中一个可能更适合特定用例。

我们在我们的 示例 中使用了断言，因为它们有助于捕获表明编码错误的非现实条件。我们已针对在生产环境中更有可能出现的其他条件使用了显式错误处理。

许多 API 错误除了非零结果代码外，还会导致日志条目。此类日志条目可以提供更多详细信息，这对于 Engine::CreateAudioPlayer 等相对复杂的 API 尤其有用。

您可以从命令行或 Android Studio 中查看日志。要从命令行检查日志，请键入以下内容

$ adb logcat

要查看 Android Studio 的日志，请选择查看 > 工具窗口 > Logcat。有关更多信息，请参阅使用 Logcat 编写和查看日志。

示例代码

我们建议您使用受支持且经过测试的示例代码，这些代码可用作您自己代码的模型，位于 audio-echo 和 native-audio android-ndk GitHub 存储库的文件夹中。

注意：OpenSL ES 1.0.1 规范在附录中包含示例代码（有关更多详细信息，请参阅Khronos OpenSL ES 注册表）。但是，附录 B：示例代码和附录 C：用例示例代码中的示例使用了 Android 不支持的功能。一些示例还包含印刷错误，或使用可能发生更改的 API。参考这些示例时请谨慎操作；虽然代码可能有助于理解完整的 OpenSL ES 标准，但它不应在 Android 中按原样使用。

音频内容

以下是为您的应用程序打包音频内容的众多方法中的一些

  • 资源：通过将您的音频文件放入res/raw/文件夹中，可以通过关联的 Resources API 轻松访问它们。但是，没有直接的本机访问资源，因此您必须编写 Java 编程语言代码才能在使用前将它们复制出来。
  • 资产：通过将您的音频文件放入assets/文件夹中，Android 本机资产管理器 API 可以直接访问它们。有关这些 API 的更多信息，请参阅头文件android/asset_manager.h和android/asset_manager_jni.h。位于 android-ndk GitHub 存储库中的示例代码将这些本机资产管理器 API 与 Android 文件描述符数据定位器结合使用。
  • 网络：您可以使用 URI 数据定位器直接从网络播放音频内容。但是，请务必阅读安全性和权限。
  • 本地文件系统：URI 数据定位器支持file:方案用于本地文件，前提是应用程序可以访问这些文件。请注意，Android 安全框架通过 Linux 用户 ID 和组 ID 机制限制文件访问。
  • 录制：您的应用程序可以从麦克风输入录制音频数据，存储此内容，然后稍后播放它。示例代码使用此方法用于播放剪辑。
  • 编译并内联链接：您可以将音频内容直接链接到共享库中，然后使用具有缓冲区队列数据定位器的音频播放器播放它。这最适合短 PCM 格式剪辑。示例代码使用此技术用于Hello和Android剪辑。PCM 数据使用bin2c工具（未提供）转换为十六进制字符串。
  • 实时合成：您的应用程序可以动态合成 PCM 数据，然后使用具有缓冲区队列数据定位器的音频播放器播放它。这是一种相对高级的技术，音频合成的详细信息不在本文档的讨论范围内。

注意：查找或创建对您的应用程序有用的音频内容不在本文档的讨论范围内。您可以使用网络搜索词，例如交互式音频、游戏音频、声音设计和音频编程来查找更多信息。

注意：确保您有权合法播放或录制内容是您的责任。录制内容可能涉及隐私问题。

代码示例

这些示例应用程序可在我们的 GitHub 页面上获得

  • audio-echo 创建一个输入到输出的往返循环。
  • native-audio 是一个简单的音频录音机/播放器。

OpenSL ES 的 Android NDK 实现与 OpenSL ES 1.0.1 的参考规范在许多方面有所不同。这些差异是您直接从 OpenSL ES 参考规范中复制的示例代码可能无法在您的 Android 应用中运行的重要原因。

有关参考规范和 Android 实现之间差异的更多信息，请参阅适用于 Android 的 OpenSL ES。