CPAL - 跨平台音频库

纯 Rust 编写的低级音频输入输出库。

该库目前支持以下功能：

• 枚举支持的音频主机。
• 枚举所有可用的音频设备。
• 获取当前默认的输入和输出设备。
• 枚举设备已知支持的输入和输出流格式。
• 获取设备当前默认的输入和输出流格式。
• 在选定设备上以给定流格式构建和运行输入和输出 PCM 流。

目前支持的主机包括：

• Linux（通过 ALSA 或 JACK）
• Windows（默认通过 WASAPI，请参阅下方 ASIO 说明）
• macOS（通过 CoreAudio）
• iOS（通过 CoreAudio）
• Android（通过 Oboe）
• Emscripten

请注意，在 Linux 上需要 ALSA 开发文件。Debian 和 Ubuntu 发行版中这些文件包含在 libasound2-dev 包中，Fedora 中包含在 alsa-lib-devel 包中。

编译为 Web Assembly

如果您有兴趣将 CPAL 与 WASM 一起使用，请参阅我们 Wiki 中的本指南，其中详细介绍了如何从头开始设置新项目。

音频后端的功能标志

某些音频后端是可选的，只有在启用功能标志时才会编译。

• JACK（在 Linux 上）：jack
• ASIO（在 Windows 上）：asio

Oboe 可以使用共享或静态运行时。默认使用静态运行时，但激活 oboe-shared-stdcxx 功能会使其使用共享运行时，这需要在执行过程中提供 Android NDK 中的 libc++_shared.so。

Windows 上的 ASIO

ASIO 是 Steinberg 开发的音频驱动程序协议。虽然它可用于多个操作系统，但在 Windows 上最为常用，用于解决 WASAPI 的限制，包括访问大量通道和低延迟音频处理。

CPAL 允许在 Windows 上使用 ASIO SDK 作为音频主机，而不是 WASAPI。

定位 ASIO SDK

通过设置 CPAL_ASIO_DIR 环境变量来指定 ASIO SDK 的位置。

构建脚本将按以下顺序尝试查找 ASIO SDK：

1. 检查是否设置了 CPAL_ASIO_DIR，如果设置了则使用该路径指向 SDK。
2. 检查 ASIO SDK 是否已安装在临时目录中，如果是，则使用该目录并将 CPAL_ASIO_DIR 的路径设置为 std::env::temp_dir().join("asio_sdk") 的输出。
3. 如果 ASIO SDK 尚未安装，则从 https://www.steinberg.net/asiosdk 下载并安装到临时目录中。CPAL_ASIO_DIR 的路径将设置为 std::env::temp_dir().join("asio_sdk") 的输出。

在理想情况下，您无需担心此步骤。

准备构建环境

1. bindgen（用于生成 C++ SDK 绑定的库）需要 clang。从这里的"预构建二进制文件"部分下载并安装 LLVM。撰写本文时的版本是 17.0.1。

2. 将 LLVM 的 bin 目录添加到 LIBCLANG_PATH 环境变量中。如果您将 LLVM 安装在默认目录，可以在命令提示符中使用以下命令：

   setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"
   

3. 如果您没有可用的 ASIO 设备或驱动程序，可以下载并安装 ASIO4ALL。安装时请务必启用"离线"功能，尽管安装程序说它没有用。

4. 我们的构建脚本假设在 Windows 编译环境中已安装 Microsoft Visual Studio。脚本将尝试找到 vcvarsall.bat 并根据正确的主机和目标机器架构执行它，不考虑 Microsoft Visual Studio 的版本。 如果在这个过程中遇到任何错误（这种情况不太可能发生）， 您可以手动找到 vcvarsall.bat 并以您的机器架构作为参数执行它。 脚本将检测到这一点并跳过该步骤。

   64 位机器的手动执行命令示例：

   "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
   

   有关更多信息，请参阅 vcvarsall.bat 的文档。

5. 在程序开始时使用以下代码选择 ASIO 主机：

   let host;
   #[cfg(target_os = "windows")]
   {
      host = cpal::host_from_id(cpal::HostId::Asio).expect("failed to initialise ASIO host");
   }

   如果遇到 asio-sys 或 bindgen 产生的编译错误，请确保正确设置了 CPAL_ASIO_DIR，然后尝试 cargo clean。

6. 构建 CPAL 时确保启用 asio 功能：

   cargo build --features "asio"
   

   或者，如果您在下游项目中使用 CPAL 作为依赖项，请这样启用该功能：

   cpal = { version = "*", features = ["asio"] }

更新至 ASIO 版本 2.3.3。

交叉编译

当 Windows 是主机和目标操作系统时，asio-sys 的构建脚本支持 MSVC 编译器支持的所有交叉编译目标。这里可以找到详尽的组合列表，另外还有未记录的 arm64、arm64_x86、arm64_amd64 和 arm64_arm 目标。（2023年5月11日）

也可以在 Linux 和 macOS 上编译带有 ASIO 支持的 Windows 应用程序。

对于这两个平台，通常使用 MinGW-w64 工具链。

确保将 MinGW-w64 的 include 目录包含在 CPLUS_INCLUDE_PATH 环境变量中。 确保安装了 LLVM，并且其 include 目录也包含在 CPLUS_INCLUDE_PATH 环境变量中。

以下是 macOS 上针对 x86_64-pc-windows-gnu 目标的示例，其中 mingw-w64 通过 brew 安装：

export CPLUS_INCLUDE_PATH="$CPLUS_INCLUDE_PATH:/opt/homebrew/Cellar/mingw-w64/11.0.1/toolchain-x86_64/x86_64-w64-mingw32/include"