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 的位置被暴露给 CPAL。

构建脚本将按照以下步骤尝试找到 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.11.5)

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

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

请确保您已将 MinGW-w64 包含目录添加到您的 CPLUS_INCLUDE_PATH 环境变量中。请确保已安装 LLVM，并将包含目录也添加到您的 CPLUS_INCLUDE_PATH 环境变量中。

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

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