audio_cpp/
lib.rs

1//! # audio-cpp
2//!
3//! audio.cpp（基于 ggml 的本地音频推理引擎）的高层安全 Rust 封装。
4//!
5//! 底层 FFI 位于 [`audio_cpp_sys`]；本 crate 在其之上提供类型安全的
6//! 注册表 / 模型 / 会话 API，并将所有跨 C 边界的资源管理（句柄释放、
7//! 字符串所有权、事件回调）封装在安全的 `Drop` 与类型系统中。
8//!
9//! ## 快速上手
10//!
11//! 枚举引擎能力：
12//! ```no_run
13//! use audio_cpp::Registry;
14//! let registry = Registry::new()?;
15//! println!("模型族: {:?}", registry.families()?);
16//! println!("设备: {:?}", Registry::devices()?);
17//! # Ok::<(), audio_cpp::Error>(())
18//! ```
19//!
20//! 加载模型并做一次离线 VAD（需 silero 权重与 wav 文件）：
21//! ```no_run
22//! use audio_cpp::{Backend, Registry, Request, RunMode, TaskKind};
23//!
24//! let registry = Registry::new()?;
25//! let model = registry.load("./silero_vad_16k.safetensors", None, None)?;
26//! let session = model.create_task_session(
27//!     TaskKind::Vad,
28//!     RunMode::Offline,
29//!     Backend::Cpu,
30//!     0,
31//!     4,
32//!     None,
33//! )?;
34//! let result = session.run_offline(
35//!     Request::vad("./sample.wav").option(audio_cpp::options::request::THRESHOLD, 0.5),
36//! )?;
37//! for seg in &result.speech_segments {
38//!     println!("语音: {:?}..{:?} 置信度={}", seg.span.start_sample, seg.span.end_sample, seg.confidence);
39//! }
40//! # Ok::<(), audio_cpp::Error>(())
41//! ```
42//!
43//! ## 资源生命周期
44//!
45//! - [`Registry`]、[`Model`]、[`Session`] 各自持有 C 句柄并在 `Drop` 中释放；
46//! - 所有权内部共享：[`Model`] 共享持有 C 注册表，[`Session`] 亦然。
47//!   因此加载/建会话之后即可释放上游持有者，无需 `_registry` / `_model`
48//!   三件套：
49//!   ```no_run
50//!   use audio_cpp::{Backend, Registry, Request, RunMode, TaskKind};
51//!   // 会话创建后，model / registry 可被释放
52//!   let session = {
53//!       let registry = Registry::new()?;
54//!       let model = registry.load("./model.gguf", None, None)?;
55//!       model.create_task_session(
56//!           TaskKind::Asr, RunMode::Offline, Backend::Cpu, 0, 4, None,
57//!       )?
58//!   };
59//!   let _ = session.run_offline(Request::asr("./sample.wav"))?;
60//!   # Ok::<(), audio_cpp::Error>(())
61//!   ```
62//! - **`Session` 独立于 `Model` 存活**（已验证族）：上游会话持有权重/资产的共享所有权
63//!   （`shared_ptr`，如 silero_vad 与 spec_backed 系列；本轮升级新增的 `yue2` /
64//!   `sheetsage2` 同样自持资产，已核对源码确认）。
65//!   注意这是各上游 loader 的实现选择而非类型系统保证：若未来某 loader
66//!   返回借用模型内存的会话，本签名无法在编译期拦截。升级上游 loader 时须
67//!   确认新会话自持资产（见 AGENTS.md 升级检查清单）。
68//! - 流式会话的事件回调要求 `Send` 闭包，回调可来自 C++ 侧线程。
69//!
70//! ## 便捷封装
71//!
72//! - [`StreamingSession`]：流式会话的一体化封装，自动收集事件回调，
73//!   [`Session::process_audio`] 的逐事件返回与回调重复问题由它消除
74//!   （`push_audio` 直接返回 `Vec<StreamEvent>`）。
75//! - [`ModelFamily::from_path`]：按文件名关键词推断模型族，GGUF 加载时
76//!   无需再手写家族匹配表；也支持 `#family=xxx` 片段显式覆盖。
77//! - [`Request::align`]：强制对齐请求（音频 + 文本 + 语言），结果的逐词
78//!   时间戳在 [`TaskResult::word_timestamps`]。
79//! - [`options`]：源码级核实过的选项键常量（`request` 随请求走，`session`
80//!   随会话走）与 [`options::SessionOptions`] 会话选项构造器；键名拼错在
81//!   编译期暴露，避免无类型字符串键被上游静默忽略。
82
83pub use audio_cpp_sys;
84
85mod error;
86pub use error::Error;
87
88mod ffi;
89
90mod request;
91pub use request::{
92    AlignRequest, AudioInput, AudioRequest, IntoRequest, Request, TtsRequest, VoiceCondition,
93};
94
95pub mod options;
96
97mod types;
98pub use types::{
99    AudioBufferInfo, Backend, Capabilities, CliInterface, CliOption, Device, LoaderInfo,
100    ModelFamily, ModelInspection, ModelMetadata, NamedAsset, NamedAudioOutput, RunMode,
101    SpeakerTurn, SpeechSegment, StreamEvent, StreamingPolicy, SupportedTask, TaskKind, TaskResult,
102    TextOutput, TimeSpan, VoiceActivityEvent, VoiceArtifact, WordTimestamp,
103};
104
105mod registry;
106pub use registry::Registry;
107
108mod model;
109pub use model::Model;
110
111pub mod session;
112pub use session::{Session, StreamingSession};
113
114mod audio;
115pub use audio::{WavAudio, load_wav};
audio_cpp/lib.rs

audio_cpp/
lib.rs
