sherpa-onnx C API 示例完全指南：在 C 语言中实现流式语音识别、离线 TTS 与语音增强

sherpa-onnx C API 示例完全指南在 C 语言中实现流式语音识别、离线 TTS 与语音增强【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx本文以c-api-examples/目录及其 README 为核心系统讲解 sherpa-onnx 项目 C API 的示例集合如何准备构建环境并编译这些 C 示例、如何阅读最关键的三个典型示例流式 ASR 的 decode-file-c-api.c、离线 TTS 的 offline-tts-c-api.c、语音增强的 speech-enhancement-gtcrn-c-api.c以及每个关键 API 调用链的含义。读完后你将能够独立编写、编译并运行一个基于 sherpa-onnx C API 的语音识别或语音合成 C 程序。一、c-api-examples 目录是什么c-api-examples/README.md 说明该目录包含 sherpa-onnx 的 C API 使用示例完整的 C API 参考文档由 Doxygen 生成文档源码位于 sherpa-onnx/c-api/ 目录包含 Doxyfile 与 README.md其中给出了在 Ubuntu/Debian 或 macOS 上安装 doxygen、graphviz 后用doxygen ./Doxyfile生成文档的方法。C API 的声明集中在头文件 sherpa-onnx/c-api/c-api.h 中全部为纯 C 接口SherpaOnnx*前缀函数这也是 C/C 之外的语言如仓库中pascal-api、dart等绑定方向集成 sherpa-onnx 的入口。README 中逐一点名了 6 个核心示例下面完整继承并展开示例文件用途decode-file-c-api.c使用 C API 以流式模型做语音识别识别一个 wav 文件offline-tts-c-api.c使用 C API 以非流式模型把文本合成为语音speech-enhancement-gtcrn-c-api.c使用 GTCRN 模型做非流式语音增强speech-enhancement-dpdfnet-c-api.c使用 DPDFNet 模型做非流式语音增强下游接 ASR 时用 16 kHz 的dpdfnet_baseline.onnx、dpdfnet2.onnx、dpdfnet4.onnx或dpdfnet8.onnx需要 48 kHz 增强输出时用dpdfnet2_48khz_hr.onnxonline-speech-enhancement-gtcrn-c-api.c使用 GTCRN 模型做流式在线语音增强online-speech-enhancement-dpdfnet-c-api.c使用 DPDFNet 模型做流式语音增强dpdfnet_baseline.onnx、dpdfnet2.onnx、dpdfnet4.onnx、dpdfnet8.onnx均为 16 kHz 输出除上述 6 个外目录实际包含 50 余个.c示例覆盖 Whisper、Paraformer、SenseVoice、Moonshine、NeMo 等离线识别流式 Transducer/CTC/Paraformer 识别Whisper/Paraformer/SenseVoice/Moonshine 的 VAD 集成识别Whisper 语种识别、说话人识别、离线说话人分离、音频打标、离线/在线标点恢复、声纹聚类以及 VITS/Kokoro/Matcha/Kitten/Pocket/Supertonic/ZipVoice 等各系 TTS 模型完整清单见 c-api-examples/CMakeLists.txt。此外c-api-examples/asr-microphone-example/子目录提供了一个基于 PortAudio 的实时麦克风识别完整工程。二、编译前提先构建 sherpa-onnx 主工程所有 C 示例都依赖主工程编译产物。以 c-api-examples/Makefile 为例其编译与链接配置揭示了依赖关系CFLAGS : -I ../ -I ../build/_deps/cargs-src/include/ LDFLAGS : -L ../build/lib LDFLAGS -L ../build/_deps/onnxruntime-src/lib LDFLAGS -lsherpa-onnx-c-api -lsherpa-onnx-core -lkaldi-decoder-core -lsherpa-onnx-kaldifst-core -lsherpa-onnx-fstfar -lsherpa-onnx-fst -lkaldi-native-fbank-core -lkissfft-float -lpiper_phonemize -lespeak-ng -lucd -lcargs -lonnxruntime LDFLAGS -framework Foundation # macOS 专有 LDFLAGS -lc LDFLAGS -Wl,-rpath,${CUR_DIR}/../build/lib LDFLAGS -Wl,-rpath,${CUR_DIR}/../build/_deps/onnxruntime-src/lib从源码结构看可以推断出两点头文件搜索路径-I ../使#include sherpa-onnx/c-api/c-api.h命中仓库内的 c-api.hcargs.h则来自主工程 CMake 构建时拉取的依赖build/_deps/cargs-src。运行时通过-Wl,-rpath直接指向build/lib与build/_deps/onnxruntime-src/lib因此必须先完成主工程的 CMake 构建产出build/目录后再执行makeMakefile 默认只构建decode-file-c-api与offline-tts-c-api两个目标见 Makefile 第 15-21 行其余示例需自行追加目标。推荐做法是使用 CMake随主工程一起构建。c-api-examples/CMakeLists.txt 的写法非常统一include(cargs) include_directories(${PROJECT_SOURCE_DIR}) add_executable(decode-file-c-api decode-file-c-api.c) target_link_libraries(decode-file-c-api sherpa-onnx-c-api cargs)即只需链接sherpa-onnx-c-api一个目标底层依赖由该目标传递。注意条件开关TTS 类示例offline-tts-c-api、matcha/kokoro/kitten/pocket/supertonic/zipvoice等位于if(SHERPA_ONNX_ENABLE_TTS)块内CMakeLists.txt 第 33 行起说话人分离示例位于if(SHERPA_ONNX_ENABLE_SPEAKER_DIARIZATION)块内第 62-65 行——构建主工程时若未开启对应开关这些示例不会生成。三、示例精讲一decode-file-c-api.c——从文件模拟流式识别这是 README 首推的示例演示如何把整段 wav 文件切成小块、模拟流式输入用 streaming transducer 模型完成识别。3.1 命令行接口程序基于cargs库解析参数options 定义第 15-69 行参数含义默认值--tokenstokens 文本文件路径必填--encoder/--decoder/--joinertransducer 三个 ONNX 模型文件必填--num-threads推理线程数1--provider推理后端cpu默认、cuda、coremlcpu--decoding-methodgreedy_search默认或modified_beam_searchgreedy_search--hotwords-file热词文件每行一个词/短语BPE/中文字符之间用空格分隔如▁HE LL O ▁WORLD、你 好 世 界空--hotwords-score热词加分仅在modified_beam_search下生效0典型用法摘自程序内置 usage第 71-90 行./decode-file-c-api \ --tokens/path/to/tokens.txt \ --encoder/path/to/encoder.onnx \ --decoder/path/to/decoder.onnx \ --joiner/path/to/joiner.onnx \ --providercpu \ /path/to/foo.wav注意 usage 末尾的约束该文件仅支持流式 transducer 模型streaming transducer。3.2 默认配置参数解析前程序先填充一组默认值第 98-115 行这些字段与 C API 头文件中的SherpaOnnxOnlineRecognizerConfig一一对应SherpaOnnxOnlineRecognizerConfig config; memset(config, 0, sizeof(config)); config.model_config.debug 0; config.model_config.num_threads 1; config.model_config.provider cpu; config.decoding_method greedy_search; config.max_active_paths 4; config.feat_config.sample_rate 16000; // 输入采样率 16 kHz config.feat_config.feature_dim 80; // 80 维 Fbank config.enable_endpoint 1; // 开启端点检测 config.rule1_min_trailing_silence 2.4; // 规则1句尾静音 2.4s 判端点 config.rule2_min_trailing_silence 1.2; // 规则2已有文本且静音 1.2s 判端点 config.rule3_min_utterance_length 300; // 规则3已识别时长 300约20s判端点端点检测的三规则机制是该示例能够把长音频自动切分为多个“句子”并逐句输出的关键。3.3 核心调用链值得逐行学习创建识别器与流第 165-168 行const SherpaOnnxOnlineRecognizer *recognizer SherpaOnnxCreateOnlineRecognizer(config); const SherpaOnnxOnlineStream *stream SherpaOnnxCreateOnlineStream(recognizer);读取 wavSherpaOnnxReadWave(filename)返回SherpaOnnxWave含sample_rate、num_samples、samples指针失败需判空。模拟流式输入第 181-215 行以N 3200个采样16 kHz 下 0.2 秒为一块循环喂入while (k wave-num_samples) { int32_t start k; int32_t end (start N wave-num_samples) ? wave-num_samples : (start N); k N; SherpaOnnxOnlineStreamAcceptWaveform(stream, wave-sample_rate, wave-samples start, end - start); while (SherpaOnnxIsOnlineStreamReady(recognizer, stream)) { SherpaOnnxDecodeOnlineStream(recognizer, stream); } const SherpaOnnxOnlineRecognizerResult *r SherpaOnnxGetOnlineStreamResult(recognizer, stream); if (strlen(r-text)) { SherpaOnnxPrint(display, segment_id, r-text); } if (SherpaOnnxOnlineStreamIsEndpoint(recognizer, stream)) { if (strlen(r-text)) { segment_id; } SherpaOnnxOnlineStreamReset(recognizer, stream); // 重置流开始下一句 } SherpaOnnxDestroyOnlineRecognizerResult(r); }注意SherpaOnnxIsOnlineStreamReady是 while 条件而非 if——内部特征缓存可能一次攒够多个解码步必须解码到“不再就绪”为止。SherpaOnnxDestroyOnlineRecognizerResult每次取结果后必须调用防止内存泄漏。收尾第 217-234 行追加 0.3 秒静音尾垫4800 个 0让模型把尾部文本解码完整然后SherpaOnnxOnlineStreamInputFinished标记输入结束再次循环解码直到就绪条件不成立取出最终结果打印。资源释放顺序第 238-240 行DestroyDisplay→DestroyOnlineStream→DestroyOnlineRecognizer遵循“先流后识别器”的从内到外顺序。以上“配置 → 建识别器 → 建流 → 分块 AcceptWaveform → Ready/Decode 循环 → GetResult → 端点判断/Reset → 尾垫 InputFinished → 逐级销毁”就是 sherpa-onnx 流式 ASR 的标准 C 调用范式目录中其余流式示例streaming-zipformer-c-api.c、streaming-paraformer-c-api.c等结构完全一致可直接套用时把模型字段换成对应模型类型CTC、Paraformer 等。四、示例精讲二offline-tts-c-api.c——非流式文本转语音offline-tts-c-api.c 演示用 VITS 类非流式 TTS 模型把一句文本合成为 wav 文件。内置 usage第 93-130 行给出了可直接复制的运行方式./offline-tts-c-api \ --vits-model./vits-ljs.onnx \ --vits-lexicon./lexicon.txt \ --vits-tokens./tokens.txt \ --sid0 \ --output-filename./generated.wav \ liliana, the most beautiful and lovely assistant of our team!参数全集options 定义第 15-91 行参数含义默认值--vits-modelVITS 模型 ONNX 文件路径必填--vits-lexicon发音词典lexicon.txt必填若给了--vits-data-dir则被忽略--vits-tokenstokens.txt路径必填--vits-noise-scaleVITS 的 noise_scale0.667--vits-noise-scale-wVITS 的 noise_scale_w0.8--vits-length-scale语速控制越小越快、越大越慢1.0--num-threads推理线程数1--providercpu默认、cuda、coremlcpu--debug1 表示加载模型时打印调试信息0--sid说话人 ID单说话人模型不生效0--output-filename输出 wav 文件名./generated.wav--tts-rule-fsts逗号分隔的 rule FST 列表从左到右依次应用文本规整用空--max-num-sentences单批处理句数上限防止长文本 OOM设为 -1 表示全部句子单批处理2--vits-data-direspeak-ng-data 目录给出后忽略--vits-lexicon多语言 Piper 类模型用空--vits-noise-scale与--vits-noise-scale-w对应 VITS 采样时两个噪声向量的幅度--vits-length-scale则控制时长预测缩放——这两组参数是实际调音色稳定性与语速时最常调整的旋钮。五、示例精讲三语音增强四件套GTCRN / DPDFNet离线与流式README 中专门描述了四个语音增强示例它们分别覆盖“离线/在线” × “GTCRN/DPDFNet”的组合对应 C API 中SherpaOnnx*SpeechDenoiser*一族函数。5.1 非流式 GTCRN三十行代码讲清离线增强流程speech-enhancement-gtcrn-c-api.c 全文仅约 56 行是最短的完整“加载模型 → 处理整段音频 → 写回文件”流程main 函数第 22-56 行可视为离线语音增强的最小可运行模板SherpaOnnxOfflineSpeechDenoiserConfig config; memset(config, 0, sizeof(config)); config.model.gtcrn.model ./gtcrn_simple.onnx; // 指向 GTCRN 模型 const SherpaOnnxOfflineSpeechDenoiser *sd SherpaOnnxCreateOfflineSpeechDenoiser(config); const SherpaOnnxWave *wave SherpaOnnxReadWave(./inp_16k.wav); const SherpaOnnxDenoisedAudio *denoised SherpaOnnxOfflineSpeechDenoiserRun( sd, wave-samples, wave-num_samples, wave-sample_rate); SherpaOnnxWriteWave(denoised-samples, denoised-n, denoised-sample_rate, ./enhanced.wav); SherpaOnnxDestroyDenoisedAudio(denoised); SherpaOnnxFreeWave(wave); SherpaOnnxDestroyOfflineSpeechDenoiser(sd);调用链即SherpaOnnxCreateOfflineSpeechDenoiser创建→SherpaOnnxOfflineSpeechDenoiserRun整段处理返回SherpaOnnxDenoisedAudio→SherpaOnnxWriteWave落盘→ 三个 Destroy/Free 收尾。模型可从项目发布的 speech-enhancement-models 资源中下载如gtcrn_simple.onnx测试输入inp_16k.wav也是 16 kHz。5.2 模型与采样率选择DPDFNetREADME 对 DPDFNet 的选型给出了明确指引务必注意采样率匹配非流式speech-enhancement-dpdfnet-c-api.c增强结果还要送下游 ASR 时用16 kHz模型dpdfnet_baseline.onnx、dpdfnet2.onnx、dpdfnet4.onnx、dpdfnet8.onnx只追求 48 kHz 高保真增强输出时用dpdfnet2_48khz_hr.onnx。流式online-speech-enhancement-dpdfnet-c-api.cdpdfnet_baseline.onnx、dpdfnet2.onnx、dpdfnet4.onnx、dpdfnet8.onnx输出均为 16 kHz。流式两个示例online-speech-enhancement-gtcrn-c-api.c与online-speech-enhancement-dpdfnet-c-api.c对应 C API 中的在线降噪器接口其处理模式与第三章流式识别同构创建在线 denoiser → 按帧AcceptWaveform→ 判断就绪后Run取回增强帧适合麦克风实时场景。六、如何选用与扩展这些示例只读一个文件学流式 ASR以 decode-file-c-api.c 为模板改model_config中对应的模型字段如ctc、paraformer、whisper等见 c-api.h 中的各 Config 结构即可适配目录中其他 50 余个 ASR 示例。需要真实麦克风参考c-api-examples/asr-microphone-example/子目录含 CMake 工程、PortAudio 采集与麦克风识别完整工程。批量构建验证目录内提供了 run.sh 脚本用于在构建产物上运行各示例做端到端验证。CMake 集成若在自己的 CMake 工程中链接sherpa-onnx-c-api目标即可复用本章所有调用代码若以预编译库 Makefile 方式集成注意 Makefile 中的rpath写法在 macOS 上需替换为-rpath的 Mach-O 语法并去掉-framework Foundation一行在 Linux 上的不适用项该行仅 macOS 需要。七、小结c-api-examples/是理解 sherpa-onnx C 层的最佳切入口README 点名的 6 个示例分别对应“流式 ASR、离线 TTS、离线/流式语音增强GTCRN DPDFNet”四大能力而 CMakeLists.txt 与目录中其余 50 余个.c文件则展示了同一套 C API 在 Whisper、Paraformer、SenseVoice、说话人识别/分离、标点恢复、音频打标、各系 TTS 模型上的统一用法。掌握第三章的“分块喂入 Ready/Decode 循环 端点重置”范式与第四章的“配置 → 创建 → 运行 → 逐级销毁”资源纪律后编写新的 C API 程序基本只是更换 Config 字段与模型路径的工作。【免费下载链接】sherpa-onnxSpeech-to-text, text-to-speech, speaker diarization, speech enhancement, source separation, and VAD using next-gen Kaldi with onnxruntime without Internet connection. Support embedded systems, Android, iOS, HarmonyOS, Raspberry Pi, RISC-V, RK NPU, Axera NPU, Ascend NPU, x86_64 servers, websocket server/client, support 12 programming languages项目地址: https://gitcode.com/GitHub_Trending/sh/sherpa-onnx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考