企业官网建设流程全解析

Moonshine 命令行语音识别怎么跑通：文件转录与麦克风模式 5 步验证

【免费下载链接】moonshineVery low latency speech to text, intent recognition, and text to speech, for building voice agents and interfaces项目地址: https://gitcode.com/GitHub_Trending/moonshine3/moonshine

Moonshine 是面向边缘设备的本地语音工具库，低延迟、可离线。如果你想在几分钟内验证它能不能把一段 WAV 音频转成文字、能不能对着麦克风实时出字，这篇指南按“先跑通、再分流、再调参、再排障”的顺序带你走完一次。读完你会得到两个可运行的命令：一个转录文件，一个监听麦克风。

它能帮你解决什么问题

把麦克风或音频文件里的说话内容，在本机实时或离线地转成文本。不需要把音频上传到任何服务器，模型以 ONNX 权重形式放在本地磁盘。适合三类人：

• 独立开发者：验证语音输入链路，再接到自己的应用里
• 新手：用最少的代码看清“音频进、文字出”的完整流程
• 普通用户：在 Windows 上装一个麦克风工具，边说边看结果

能力速览：命令行工具能做什么

仓库里有两个可以直接编译的命令行入口，分工很明确：

边界也提前说清楚：

• 两个工具都只接受 16 位 PCM 的 WAV 文件，其他格式（比如压缩音频）需先转码
• 通用 C++ 示例不打开麦克风，麦克风模式只有 Windows 示例自带（WASAPI 采集，固定 16kHz 单声道）
• 工具本身不联网下载模型，模型目录要事先准备好

最小可运行路径：3 步跑通一次文件转录

以下路径在examples/c++/目录内执行，完整说明见 examples/c++/README.md。

第 1 步：获取代码

git clone https://gitcode.com/GitHub_Trending/moonshine3/moonshine cd moonshine/examples/c++

第 2 步：拉取预编译库和测试模型

./download-library.sh

脚本按你的平台下载moonshine-voice预编译库，同时把 Medium Streaming 英文模型放进medium-streaming-en/，并下载样例音频two_cities.wav。

成功标志：当前目录出现moonshine-voice/、medium-streaming-en/（内含encoder.ort、tokenizer.bin等权重文件）和two_cities.wav三样东西。

第 3 步：编译并运行

g++ transcriber.cpp -Imoonshine-voice/include -Lmoonshine-voice/lib \ -lmoonshine -Wl,-rpath,'$ORIGIN/moonshine-voice/lib' -o transcriber ./transcriber

macOS 把 rpath 参数换成-framework CoreFoundation -framework Foundation即可。

成功标志：终端开始滚动打印Line started:、Line text changed:、Line completed:三类行，Line completed出现一行，就代表一段话被完整识别出来。

场景分流：文件模式还是麦克风模式

文件模式：换一条音频再跑一次

把-w指向 test-assets/ 里的其他 16 位 PCM WAV：

./transcriber -w ../../test-assets/beckett.wav

• -m, --model-path：模型目录，默认medium-streaming-en
• -w, --wav-path：待转录的 WAV 文件，默认two_cities.wav
• -t, --transcription-interval：每隔多少秒刷新一次中间结果，默认 0.481 秒

想换一个模型，就同时改-m和-a（配对方法见下一节）。

麦克风模式：Windows 上边说边出字

用 Visual Studio 打开examples/windows/cli-transcriber/cli-transcriber.sln，编译后：

cli-transcriber.exe

不带-w参数时，工具会初始化默认麦克风并开始监听，屏幕上实时滚动已识别的文字，按 Ctrl+C 停止。如果加上-w 某段.wav，则变成文件模式，转完即退出。

cli-transcriber.exe -m models\medium-streaming-en

两种模式的区别在于：文件模式把整段音频切片喂入、跑完就结束，适合回归测试；麦克风模式是常驻监听，适合体验实时延迟。

参数与选择：model-arch 和模型目录怎么配对

-a, --model-arch指定模型架构，取值来自 core/moonshine-cpp.h 里的ModelArch枚举：

配对规则很简单：目录名里带 streaming 就选流式取值（2–5），不带就选 0 或 1。默认的medium-streaming-en对应-a 5。

什么时候需要调参：

• 出字太慢、想压低延迟 → 换流式模型，或增大-t的间隔
• CPU 占用太高 → 换更小的模型架构
• 中间结果抖动太多 → 减小-t，让刷新更平滑（注意-t只影响刷新频率，不影响最终结果本身）

排障清单：加载失败和无声输出先查这 4 项

1. 模型路径是否存在、是否完整：确认-m指向的目录里有encoder.ort、tokenizer.bin等权重文件。test-assets/下默认只放了medium-streaming-en，其他型号需要先按 docs/models/ 里的说明自行下载，路径以仓库文档为准
2. 架构参数是否匹配：拿流式模型配-a 0，或反之，都会加载失败。对照上一节的表格核对
3. 音频格式是不是 16 位 PCM WAV：两个工具的加载器遇到其他位深会直接报Only 16-bit PCM WAV files are supported。48kHz 或双声道都可以，程序会重采样并混成单声道；但 24 位、浮点 WAV 需要先转码
4. 运行时库找不到（Linux）：报libmoonshine.so或libonnxruntime.so.1找不到时，检查编译时是否带了-Wl,-rpath,'$ORIGIN/moonshine-voice/lib'，或临时export LD_LIBRARY_PATH=$PWD/moonshine-voice/lib

另外，麦克风模式只在 Windows 示例里实现。Linux/macOS 上想听实时效果，可以先把录音存成 WAV，走文件模式验证。

适用边界与下一步

适合：本地离线转录、实时语音输入验证、语音助手的链路原型、低延迟场景选型。

不适合：批量长音频离线批处理（请选非流式模型逐段喂入并自己调度）；非 WAV 输入的直连；对识别语种无把握时直接用默认英文模型——多语言模型需要另外下载。

跑通之后的建议路线：

• 想看更多语言或更精确的型号列表，翻 docs/models/available-models.md
• 想集成到自己的项目，从 core/moonshine-cpp.h 的Transcriber事件接口入手，监听LineCompleted拿到最终文本
• 有 TTS 需求时，examples/c++/text-to-speech.cpp可以用同一套库编译，语音合成与识别在同一进程内闭环

【免费下载链接】moonshineVery low latency speech to text, intent recognition, and text to speech, for building voice agents and interfaces项目地址: https://gitcode.com/GitHub_Trending/moonshine3/moonshine