使用入门

本部分提供开始使用 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 错误不仅会引起非零结果代码,还会生成日志条目。这种日志条目能够提供额外的详细信息,对相对复杂的 API(如 Engine::CreateAudioPlayer)十分有用。

您可以从命令行或 Android Studio 查看日志。要从命令行检查日志,请键入下列命令:

$ adb logcat

要从 Android Studio 检查日志,请选择 View > Tool Windows > Logcat。如需了解详细信息,请参阅使用 Logcat 写入和查看日志

示例代码

我们建议您使用受支持且经过测试的示例代码,代码位于 android-ndk GitHub 代码库的 audio-echonative-audio 文件夹中,您可将这些代码用作范本来编写自己的代码。

注意: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.handroid/asset_manager_jni.h。位于 android-ndk GitHub 代码库的示例代码将这些原生资源管理器 API 与 Android 文件描述符数据定位器结合使用。
  • 网络:您可以使用 URI 数据定位器直接从网络播放音频内容。不过,请务必阅读安全与权限
  • 本地文件系统:对于本地文件,URI 数据定位器支持 file: 方案,前提是这些文件可供应用访问。请注意,Android 安全框架限制通过 Linux 用户 ID 和组 ID 机制访问文件。
  • 录制的内容:您的应用可以从麦克风输入录制音频数据,存储此内容,然后回放。示例代码使用此方法来处理回放剪辑。
  • 编译和链接的内嵌内容:您可以将音频内容直接链接至共享库,然后使用支持缓冲区队列数据定位器的音频播放器播放。这最适合 PCM 格式的短剪辑。示例代码使用此技术处理 HelloAndroid 剪辑。PCM 数据已通过 bin2c 工具(未提供)转换为十六进制字符串。
  • 实时合成:您的应用可以动态合成 PCM 数据,然后使用支持缓冲区队列数据定位器的音频播放器播放。这是一种相对先进的技术,详细的音频合成介绍超出本文讨论的范围。

注:为您的应用寻找或创建有用的音频内容超出本文讨论的范围。您可以使用网页搜索字词(例如,互动音频游戏音频音效设计音频编程)查找更多信息。

注意:您必须确保在法律允许的情况下播放或录制内容。录制内容时,需要注意一些隐私权注意事项。

代码示例

我们的 GitHub 页面提供以下示例应用:

  • audio-echo 创建从输入到输出的往返循环。
  • native-audio 是一个简单的音频录制器/播放器。
  • SimpleSynth 播放正弦波,并说明如何实现最佳的音频延迟时间以及稳定的计算吞吐量。

OpenSL ES 的 Android NDK 实现在多个方面不同于 OpenSL ES 1.0.1 的参考规范。这些差异就是从 OpenSL ES 参考规范中直接复制的示例代码无法在您 Android 应用中使用的重要原因。

如需了解参考规范与 Android 实现之间差异的详细信息,请参阅面向 Android 的 OpenSL ES