sherpa-onnx C#/.NET 示例实战dotnet-examples 目录全解与 C# API 集成指南【免费下载链接】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本文以 sherpa-onnx 仓库中的 dotnet-examples 目录为主体系统讲解这套 C# API 示例工程的组成结构、NuGet 集成方式、各功能类别示例离线/流式语音增强、零样本 TTS、离线 ASR 等的运行方法以及如何在解决方案中新增自己的示例项目帮助 .NET 开发者快速完成 sherpa-onnx 在 C# 项目中的接入与调用。一、这个目录解决什么问题sherpa-onnx 是支持离线语音识别ASR、语音合成TTS、说话人分离、语音增强、声源分离与端点检测VAD的推理框架。dotnet-examples 目录提供了官方维护的 C# 端示例集合每个功能点都是一个独立的可运行 console 项目通过统一的Common项目引用 NuGet 包org.k2fsa.sherpa.onnx配合各自的run.sh脚本一键下载模型并运行。整个示例集以 Visual Studio 解决方案 sherpa-onnx.sln 组织当前共包含 40 多个子项目覆盖离线语音增强speech-enhancement-gtcrn、speech-enhancement-dpdfnet流式在线语音增强streaming-speech-enhancement-gtcrn、streaming-speech-enhancement-dpdfnet零样本 TTSzipvoice-tts、zipvoice-tts-play带播放以及 pocket-tts-zero-shot、kokoro-tts、kitten-tts、supertonic-tts、offline-tts 等离线 ASRoffline-decode-filesParaformer、Whisper、SenseVoice 等多模型、non-streaming-canary、non-streaming-cohere-transcribe、non-streaming-funasr-nano、non-streaming-moonshine-v2、non-streaming-qwen3-asr 等流式 ASRonline-decode-files、streaming-hlg-decoding、speech-recognition-from-microphoneVAD ASR 组合vad-non-streaming-asr-paraformer、vad-non-streaming-funasr-nano、vad-non-streaming-qwen3-asr标点恢复offline-punctuation、online-punctuation说话人相关speaker-identification、offline-speaker-diarization其他offline-audio-tagging、spoken-language-identification、keyword-spotting-from-files / keyword-spotting-from-microphone、source-separation-spleeter / source-separation-uvr、version-test每个项目内的 Program.cs 文件头部通常都带有完整的操作注释下载哪个模型、如何运行是最直接的参考文档。二、解决方案结构与 NuGet 集成方式2.1 公共层Common 项目所有示例共享一个公共项目 Common.csproj其内容非常精简Project SdkMicrosoft.NET.Sdk PropertyGroup TargetFrameworknet8.0/TargetFramework AllowUnsafeBlockstrue/AllowUnsafeBlocks /PropertyGroup ItemGroup PackageReference Includeorg.k2fsa.sherpa.onnx Version* / /ItemGroup /Project三个关键信息目标框架为 .NET 8.0即所有示例的运行前提是安装了 .NET 8 SDKdotnet命令行工具C# API 通过 NuGet 包org.k2fsa.sherpa.onnx引入示例中版本号写作*自动取最新版实际生产项目中建议锁定具体版本以便复现开启了AllowUnsafeBlocks。从 C# 封装层源码见 scripts/dotnet 下的DenoisedAudio.cs、WaveReader.cs等文件它们就是 NuGet 包内 C# API 的原始实现看C# 层通过 P/Invoke 调用底层 C 库因此需要 unsafe 块支持。Common项目除引入 NuGet 包外还包含 WaveHeader.cs提供 WAV 文件头读写支持供各示例直接读写.wav文件使用。2.2 示例项目如何组织以 speech-enhancement-gtcrn.csproj 为例每个示例项目的 csproj 只有几行Project SdkMicrosoft.NET.Sdk PropertyGroup OutputTypeExe/OutputType TargetFrameworknet8.0/TargetFramework RootNamespacespeech_enhancement_gtcrn/RootNamespace ImplicitUsingsenable/ImplicitUsings Nullableenable/Nullable /PropertyGroup ItemGroup ProjectReference Include..\Common\Common.csproj / /ItemGroup /Project要点示例项目不直接引用 NuGet 包而是通过ProjectReference依赖Common项目间接获得org.k2fsa.sherpa.onnx。这样统一升级版本时只需改一处Common.csproj。三、标准运行流程run.sh 脚本模式每个示例目录下都有一个run.sh遵循统一的检查 → 下载 → 运行模式。以 speech-enhancement-gtcrn/run.sh 为例#!/usr/bin/env bash set -ex if [ ! -f ./gtcrn_simple.onnx ]; then curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/speech-enhancement-models/gtcrn_simple.onnx fi if [ ! -f ./inp_16k.wav ]; then curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/speech-enhancement-models/inp_16k.wav fi dotnet run可以看到模式为本地不存在模型/测试音频时才从 sherpa-onnx 官方 Releases 的speech-enhancement-models资产中下载然后直接dotnet run。这意味着模型文件不进入版本库首次运行会联网下载之后离线可复现。ASR 类示例的模型下载类似例如 offline-decode-files/run-paraformer.sh 会下载 Paraformer 中文模型包并解压再以命令行参数方式传给程序dotnet run \ --tokens./sherpa-onnx-paraformer-zh-2023-09-14/tokens.txt \ --paraformer./sherpa-onnx-paraformer-zh-2023-09-14/model.int8.onnx \ --num-threads2 \ --files ./sherpa-onnx-paraformer-zh-2023-09-14/test_wavs/0.wav \ ./sherpa-onnx-paraformer-zh-2023-09-14/test_wavs/1.wav \ ./sherpa-onnx-paraformer-zh-2023-09-14/test_wavs/2.wav \ ./sherpa-onnx-paraformer-zh-2023-09-14/test_wavs/8k.wavoffline-decode-files是目录内参数最多的示例Program.cs 使用 CommandLine 库定义了一组Options通过--tokens、--paraformer、--whisper-encoder、--whisper-decoder、--nemo-ctc、--zipformer-ctc、--moonshine-*等参数适配 Transducer、Paraformer、Whisper、NeMo CTC、Moonshine 等不同模型族同目录还配有 run-whisper.sh、run-sense-voice-ctc.sh、run-zipformer.sh 等十余个脚本分别演示不同模型的参数组合。命令行参数方式适合需要灵活切换模型的批处理场景而语音增强、TTS 类示例则把模型路径硬编码在Program.cs中更适合阅读 API 用法。四、代表性示例源码解析4.1 离线语音增强GTCRNspeech-enhancement-gtcrn/Program.cs 展示了离线降噪 API 的最小调用链using SherpaOnnx; class OfflineSpeechEnhancementDemo { static void Main(string[] args) { var model ./gtcrn_simple.onnx; var config new OfflineSpeechDenoiserConfig(); config.Model.Gtcrn.Model model; // 指定 GTCRN 模型路径 config.Model.Debug 1; // 打开调试日志 config.Model.NumThreads 1; // 推理线程数 var sd new OfflineSpeechDenoiser(config); WaveReader waveReader new WaveReader(./inp_16k.wav); var denoisedAudio sd.Run(waveReader.Samples, waveReader.SampleRate); var outputFilename ./enhanced.wav; var ok denoisedAudio.SaveToWaveFile(outputFilename); // ... } }调用要点配置对象为OfflineSpeechDenoiserConfig模型路径挂在config.Model.Gtcrn.Model上WaveReader读入 wav 后得到float[]采样和采样率sd.Run(samples, sampleRate)一次性处理整段音频返回DenoisedAudio对象再SaveToWaveFile输出enhanced.wav。4.2 离线语音增强DPDFNet与模型选择speech-enhancement-dpdfnet/Program.cs 与 GTCRN 示例结构完全一致仅模型字段不同var config new OfflineSpeechDenoiserConfig(); config.Model.Dpdfnet.Model ./dpdfnet_baseline.onnx; config.Model.Dpdfnet.AttenuationLimitDb 12.0f; // DPDFNet 特有增益限制dBREADME 与源码注释对 DPDFNet 模型的选择给出了明确指引模型文件适用场景dpdfnet_baseline.onnx、dpdfnet2.onnx、dpdfnet4.onnx、dpdfnet8.onnx16 kHz 输出适合下游接 ASR/语音识别dpdfnet2_48khz_hr.onnx48 kHz 增强输出适合直接听感/高质量增强AttenuationLimitDb用于限制增强时噪声衰减的幅度上限避免人声被过度压制。4.3 流式语音增强按帧推送与 Flushstreaming-speech-enhancement-gtcrn/Program.cs 演示了在线流式降噪 API 的标准循环模式var config new OnlineSpeechDenoiserConfig(); config.Model.Gtcrn.Model ./gtcrn_simple.onnx; config.Model.Debug 1; config.Model.NumThreads 1; var sd new OnlineSpeechDenoiser(config); WaveReader waveReader new WaveReader(./inp_16k.wav); var samples waveReader.Samples; var output new Listfloat(samples.Length); int frameShift sd.FrameShiftInSamples; // 每次应推送的帧长采样数 for (int start 0; start samples.Length; start frameShift) { int count Math.Min(frameShift, samples.Length - start); float[] chunk new float[count]; Array.Copy(samples, start, chunk, 0, count); var audio sd.Run(chunk, waveReader.SampleRate); output.AddRange(audio.Samples); } output.AddRange(sd.Flush().Samples); // 冲刷内部缓冲拿到剩余输出 var ok DenoisedAudio.SaveToWaveFile(output.ToArray(), sd.SampleRate, ./enhanced-online-gtcrn.wav);从源码结构看流式 API 的三个关键点是通过sd.FrameShiftInSamples属性获取引擎要求的帧长而不是自己拍脑袋取 320/480 之类的值保证与模型内部帧移严格一致每次Run传入一帧返回值是这一帧对应的增强采样输入结束后必须调用Flush()取回内部缓冲区里剩余的音频否则会丢失结尾片段。streaming-speech-enhancement-dpdfnet示例是同一模式的 DPDFNet 版本可直接对照阅读。4.4 ZipVoice 中英文零样本 TTSzipvoice-tts/Program.cs 演示了零样本zero-shotTTS用一段参考音频克隆音色后合成新文本。核心配置var config new OfflineTtsConfig(); config.Model.ZipVoice.Tokens ./sherpa-onnx-zipvoice-distill-int8-zh-en-emilia/tokens.txt; config.Model.ZipVoice.Encoder ./sherpa-onnx-zipvoice-distill-int8-zh-en-emilia/encoder.int8.onnx; config.Model.ZipVoice.Decoder ./sherpa-onnx-zipvoice-distill-int8-zh-en-emilia/decoder.int8.onnx; config.Model.ZipVoice.Vocoder ./vocos_24khz.onnx; config.Model.ZipVoice.DataDir ./sherpa-onnx-zipvoice-distill-int8-zh-en-emilia/espeak-ng-data; config.Model.ZipVoice.Lexicon ./sherpa-onnx-zipvoice-distill-int8-zh-en-emilia/lexicon.txt; config.Model.NumThreads 2; config.Model.Debug 1; config.Model.Provider cpu;ZipVoice 需要五件套tokens、encoder、decoder、vocoder独立下载的vocos_24khz.onnx以及 espeak-ng 发音数据目录加 lexicon。零样本音色由OfflineTtsGenerationConfig提供var reader new WaveReader(referenceWaveFilename); // 参考音频 genConfig.ReferenceAudio reader.Samples; genConfig.ReferenceSampleRate reader.SampleRate; genConfig.ReferenceText 那还是三十六年前, 一九八七年. 我呢考上了武汉大学的计算机系.; genConfig.NumSteps 4; genConfig.Extra[min_char_in_sentence] 10; // 分句时单句最少字数合成时还支持带进度回调的生成接口回调中返回 1 表示继续、0 表示中止var myCallback (IntPtr samples, int n, float progress, IntPtr arg) { float[] data new float[n]; Marshal.Copy(samples, data, 0, n); Console.WriteLine($Progress {progress * 100}%); return 1; // 1: 继续生成0: 停止生成 }; var callback new OfflineTtsCallbackProgressWithArg(myCallback); var audio tts.GenerateWithConfig(text, genConfig, callback); var ok audio.SaveToWaveFile(./generated-zipvoice-zh-en.wav);配套的 zipvoice-tts-play 在同样流程基础上增加了音频播放pocket-tts-zero-shot、supertonic-tts、offline-tts-play等示例也遵循OfflineTtsConfig GenerateWithConfig SaveToWaveFile的一致套路可按需对照切换模型。五、在解决方案中新增自己的示例项目dotnet-examples/README.md 给出了新增项目的两条标准命令在dotnet-examples目录下执行dotnet new console -n offline-tts-play dotnet sln ./sherpa-onnx.sln add ./offline-tts-play即先用dotnet new console创建 console 项目再用dotnet sln add把它挂进现有解决方案。创建后按第二节的模式修改新项目的 csproj目标框架设为net8.0并添加对..\Common\Common.csproj的ProjectReference即可获得完整的 C# API 依赖。README 还给出了 NuGet 本地缓存的清理命令用于排查包版本/缓存导致的异常dotnet nuget locals all --list dotnet nuget locals all --clear--list显示各缓存位置全局包目录、http-cache、temp 等--clear清空缓存之后重新构建时会从 NuGet 源重新拉取org.k2fsa.sherpa.onnx包。六、落地检查清单环境已安装 .NET 8 SDK所有示例均为net8.0dotnet --version可正常输出包通过 Common.csproj 引用 NuGet 包org.k2fsa.sherpa.onnx生产项目建议把Version*固定为具体版本号模型各run.sh会按需从 sherpa-onnx 官方 Releases 下载模型与测试音频语音增强模型在speech-enhancement-models资产组、TTS 模型在tts-models/vocoder-models资产组、ASR 模型在asr-models资产组首次运行需要网络运行bash run.sh或手动dotnet runASR 类示例注意按脚本传入--tokens、--paraformer等参数新示例dotnet new console -n 名称dotnet sln ./sherpa-onnx.sln add 名称 引用 Common 项目排障模型参数采样率、帧移、线程数以示例Program.cs中的配置为准流式场景务必使用FrameShiftInSamples并按需调用Flush()遇到包引用异常先执行dotnet nuget locals all --clear。整套dotnet-examples的价值在于它把 sherpa-onnx 的 C# API 按功能拆成了可独立编译运行的最小工程每个目录自带下载 运行脚本既可以作为 API 参考手册直接阅读也可以作为脚手架快速拷贝出适合自己业务的 C# 语音处理程序。【免费下载链接】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），仅供参考