Crate audio_cpp 

audio-cpp

audio.cpp（基于 ggml 的本地音频推理引擎）的高层安全 Rust 封装。

底层 FFI 位于 audio_cpp_sys；本 crate 在其之上提供类型安全的 注册表 / 模型 / 会话 API，并将所有跨 C 边界的资源管理（句柄释放、 字符串所有权、事件回调）封装在安全的 Drop 与类型系统中。

快速上手

枚举引擎能力：

use audio_cpp::Registry;
let registry = Registry::new()?;
println!("模型族: {:?}", registry.families()?);
println!("设备: {:?}", Registry::devices()?);

加载模型并做一次离线 VAD（需 silero 权重与 wav 文件）：

use audio_cpp::{Backend, Registry, Request, RunMode, TaskKind};

let registry = Registry::new()?;
let model = registry.load("./silero_vad_16k.safetensors", None, None)?;
let session = model.create_task_session(
    TaskKind::Vad,
    RunMode::Offline,
    Backend::Cpu,
    0,
    4,
    None,
)?;
let result = session.run_offline(
    Request::vad("./sample.wav").option(audio_cpp::options::request::THRESHOLD, 0.5),
)?;
for seg in &result.speech_segments {
    println!("语音: {:?}..{:?} 置信度={}", seg.span.start_sample, seg.span.end_sample, seg.confidence);
}

资源生命周期

• Registry、Model、Session 各自持有 C 句柄并在 Drop 中释放；
• 所有权内部共享：Model 共享持有 C 注册表，Session 亦然。 因此加载/建会话之后即可释放上游持有者，无需 _registry / _model 三件套：

  use audio_cpp::{Backend, Registry, Request, RunMode, TaskKind};
  // 会话创建后，model / registry 可被释放
  let session = {
      let registry = Registry::new()?;
      let model = registry.load("./model.gguf", None, None)?;
      model.create_task_session(
          TaskKind::Asr, RunMode::Offline, Backend::Cpu, 0, 4, None,
      )?
  };
  let _ = session.run_offline(Request::asr("./sample.wav"))?;

• Session 独立于 Model 存活（已验证族）：上游会话持有权重/资产的共享所有权 （shared_ptr，如 silero_vad 与 spec_backed 系列；本轮升级新增的 yue2 / sheetsage2 同样自持资产，已核对源码确认）。 注意这是各上游 loader 的实现选择而非类型系统保证：若未来某 loader 返回借用模型内存的会话，本签名无法在编译期拦截。升级上游 loader 时须 确认新会话自持资产（见 AGENTS.md 升级检查清单）。
• 流式会话的事件回调要求 Send 闭包，回调可来自 C++ 侧线程。

便捷封装

• StreamingSession：流式会话的一体化封装，自动收集事件回调， Session::process_audio 的逐事件返回与回调重复问题由它消除 （push_audio 直接返回 Vec<StreamEvent>）。
• ModelFamily::from_path：按文件名关键词推断模型族，GGUF 加载时 无需再手写家族匹配表；也支持 #family=xxx 片段显式覆盖。
• Request::align：强制对齐请求（音频 + 文本 + 语言），结果的逐词 时间戳在 TaskResult::word_timestamps。
• options：源码级核实过的选项键常量（request 随请求走，session 随会话走）与 options::SessionOptions 会话选项构造器；键名拼错在 编译期暴露，避免无类型字符串键被上游静默忽略。

Re-exports

pub use session::Session;

pub use session::StreamingSession;

pub use audio_cpp_sys;

Modules

options

常用选项键常量与会话选项构造器。

session

任务会话（Session）：离线执行 + 流式处理。

Structs

AlignRequest

强制对齐（Alignment）的请求参数：音频 + 待对齐文本 + 文本语言。

AudioBufferInfo

音频输出的描述信息（采样率 / 声道 / 长度）。

AudioRequest

音频类任务（VAD / ASR / 说话人分离 / 源分离）的请求参数。

Capabilities

能力集合（audiocpp_model_capabilities_json / loader 声明）。

CliInterface

模型的三类 CLI 选项（请求 / 会话 / 加载）。

CliOption

CLI 选项信息（模型支持的请求 / 会话 / 加载选项）。

Device

计算设备（audiocpp_registry_devices_json 的一项）。

LoaderInfo

模型族 loader 的声明信息（audiocpp_registry_loaders_json 的一项）。

Model

已加载的模型。

ModelInspection

模型预检结果（Registry::inspect）。

ModelMetadata

已加载模型的元数据（audiocpp_model_metadata_json）。

NamedAsset

模型预检时发现的配置 / 权重资产。

NamedAudioOutput

带名字的音频输出（如 TTS 的多段输出）。

Registry

模型注册表。

SpeakerTurn

说话人分离中的一段发言（谁在什么时间说话）。

SpeechSegment

语音活动片段。

StreamEvent

流式会话产出的单个事件。

StreamingPolicy

流式策略描述（audiocpp_session_streaming_policy_json）。

SupportedTask

一个受支持的任务及其可用模式。

TaskResult

一次任务执行的完整结果（audiocpp_session_run_offline / finish）。

TextOutput

文本输出（如 ASR / TTS 的文本）。

TimeSpan

一段音频在采样轴上的时间范围。

TtsRequest

语音合成（TTS）的请求参数。

VoiceActivityEvent

语音活动事件（speech_start / speech_end / speech_segment）。

VoiceArtifact

模型产出的产物（embedding / 状态 / 对齐结果等）。

VoiceCondition

说话人参考 / 风格条件（映射到上游请求 JSON 的 voice 字段）。

WavAudio

从 WAV 文件读取的音频数据。

WordTimestamp

词级时间戳（ASR 逐词对齐）。

Enums

AudioInput

请求里的音频输入：本地文件路径，或内嵌采样数据。

Backend

计算后端（映射 audiocpp_model_create_task_session 的 backend 参数）。

Error

audio-cpp 高层 API 的错误类型。

ModelFamily

模型族（映射 Registry::load 的 family_hint 参数）。

Request

一次任务请求。

RunMode

会话运行模式（离线 / 流式）。

TaskKind

任务种类（映射 audiocpp_model_create_task_session 的 task 参数）。

Traits

IntoRequest

可转换为一次任务请求的参数。

Functions

load_wav

将 RIFF/WAVE 文件读取为 float 采样。