audio-cpp-sys 0.2.0

audio.cpp（ggml 音频推理框架）的底层绑定
docs.rs failed to build audio-cpp-sys-0.2.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

audio-cpp-sys

audio.cpp（基于 ggml 的本地音频推理引擎）的底层 FFI 绑定。

本 crate 是 audio-cpp-rs 工作区的一部分，只负责把 C++ 运行时构建出来并导出原始 C ABI：

  1. build.rs 用 CMake + Ninja 构建上游 engine_runtime 静态库，用 cc 编译 C shim（capi.cpp）；
  2. bindgen 从 capi.h 生成 Rust 绑定，lib.rs 以 audio_cpp_sys::* 导出。

需要高层、类型安全的 API 请使用 audio-cpp。

依赖

  • 上游源码：audio.cpp 以 git submodule 引入。构建脚本会断言 audio.cpp/CMakeLists.txt 存在，缺失时报错提示。
  • 工具链（win32 实测）：CMake、Ninja、MSVC（或 GCC/Clang）、bindgen 所需的 clang 与 MSVC INCLUDE/LIB 环境。

使用

把本 crate 加入依赖：

[dependencies]

audio-cpp-sys = "0.1"

构建默认的 core-models（引擎核心 + 内置 VAD）：

cargo build

使用预编译库（跳过 CMake 构建）

构建时默认会编译 audio.cpp 的 engine_runtime 及其依赖（耗时较长）。有以下两种方式 使用预编译静态库，跳过 整个 CMake 构建：

  1. 显式指定目录（任何情况都可用）：
# 目录内需包含 engine_runtime 及依赖库（*.lib / *.a），可放在

#   <dir>、<dir>/lib、<dir>/lib64 或 <dir>/bin

export AUDIOCPP_PREBUILT_DIR=/path/to/prebuilt


cargo build
  1. 自动下载（prebuilt feature，需发布对应 GitHub Release 资产）：
[dependencies]

audio-cpp-sys = { version = "0.1", features = ["prebuilt"] }


cargo build --features prebuilt

按当前平台/后端/模型组合自动拼资产名并下载，缓存到 target/audio-cpp-prebuilt-cache/<tag>/。资产命名 audio-cpp-prebuilt-{linux|macos|windows}-{target}-{backend}-{modelset}-static.tar.gz。

只发布 full 全模型资产（full 是任何 model 组合的超集，见下）。core / custom-<族> 组合会自动回退下载 full 资产（体积较大但保证可用），仍失败才 回落源码构建。

下载/缓存行为可用环境变量定制（适合内网或访问不了 GitHub 的环境）：

环境变量 作用
AUDIOCPP_PREBUILT_URL 下载地址。可含 {tag} / {asset} 占位符（镜像站场景：https://mirror.example.com/audio-cpp/{asset}）；不含占位符视为完整地址；file:// 前缀表示本地归档，直接复制不走网络
AUDIOCPP_PREBUILT_TAG Release tag，默认 v{version}
AUDIOCPP_PREBUILT_REPO GitHub 仓库，默认 launcher-rs/audio-cpp-rs
AUDIOCPP_PREBUILT_DIR 显式本地库目录（不下载，直接链接）
AUDIOCPP_PREBUILT_OFF 设为 1/true 禁用自动下载，强制源码构建

网络下载失败会自动重试 3 次（带退避）；HTTP 4xx（资源不存在等）为确定性 失败不重试，直接回落源码构建。

要点：

  • full 资产是任何模型组合的超集：无论开启哪些 model-* feature（或 AUDIOCPP_MODELS 指定多族），下载端都会先尝试精确资产名（core / custom-<族1>-<族2>...），404 时自动回退下载 full 资产，仍失败才回落 源码构建；
  • CUDA / Vulkan 仍需要本地 SDK 参与链接（静态库不传导其运行时依赖），只省编译；
  • C shim（capi.cpp）与 Rust 绑定仍从源码编译，因此上游 audio.cpp 源码树依然 需要（prebuilt 旁路会自动获取）；
  • 归档内 metadata.json 记录 audio_commit（打包时 audio.cpp submodule HEAD）与 msvc_ver（打包工具链的 _MSC_VER）。下载后自动校验：audio_commit 与本地 submodule 不一致，或本地 MSVC 版本低于归档的 msvc_ver，则删缓存回落源码构建 （避免 ABI 错配；MSVC 静态库绑定工具集版本）。

资产由 CI（.github/workflows/prebuilt-audio-cpp.yml）在打 v* tag 时生成并上传； 设计见 docs/prebuilt_pattern_report.md。

features

模型组合（互斥，默认 core-models）：

feature 说明
core-models（默认） 引擎核心 + 内置 VAD（silero_vad / marblenet_vad），权重随上游 vendored，开箱即用
custom-models 按需编译：配合 AUDIOCPP_MODELS 环境变量（逗号分隔 model alias）
model-<族> 常用模型族的专用开关（如 model-qwen3-asr、model-moss、model-demucs、model-sortformer-diar），无需环境变量
full-models 全量 44+ 模型族（编译慢，且仍要自行下载权重）

计算后端（可叠加，默认 CPU）：

feature 说明
cuda NVIDIA CUDA（需 CUDA Toolkit；与 hip 互斥）
hip AMD HIP/ROCm（与 cuda 互斥）
vulkan Vulkan 通用后端（需 Vulkan SDK）
metal Apple Metal（macOS 默认开启）
openmp OpenMP 并行（需对应运行时）
native 针对本机 CPU 优化（不移植）

C ABI 约定

所有绑定函数遵循同一套契约（详见 capi.h）：

  • 结构化数据以 JSON 字符串（UTF-8、\0 结尾）跨边界传递；
  • 音频采样以 float 数组传递；
  • 返回 0 成功、非 0 出错，错误信息用 audiocpp_last_error() 获取；
  • 返回的 char* / float* / 句柄若非空，必须用对应的 free() 释放（audiocpp_free_string / audiocpp_audio_free / audiocpp_*_free）。

三个核心句柄：

  • audiocpp_registry —— 模型注册表（audiocpp_registry_default / ..._load）；
  • audiocpp_model —— 已加载的模型（audiocpp_model_metadata_json / ..._create_task_session）；
  • audiocpp_session —— 一次任务会话，离线（run_offline）或流式（start / process_audio / finish）。

示例

# 枚举注册表与设备（无需任何模型文件）

cargo run -p audio-cpp-sys --example inspect


# 离线 VAD（需要 silero_vad_16k.safetensors 权重）

cargo run -p audio-cpp-sys --example vad_offline_ffi -- \

  ./silero_vad_16k.safetensors ./speech.wav

License

Apache-2.0