Moonshine 命令行语音识别测试指南：4 步跑通本地离线转写-迪斯科星球

Moonshine 命令行语音识别测试指南：4 步跑通本地离线转写

【免费下载链接】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 做本地语音识别，又不想先学一套框架？Moonshine 是 Moonshine AI 开源的低延迟语音转写（ASR）库，整条链路可以在命令行里跑完：不经过云端、不上传音频，模型和录音都在本机。这份指南带你从克隆仓库走到第一条转写命令出结果，中间只依赖命令行。

读完后你能做到：

在本机用 Moonshine 命令行示例完成一次完整的离线语音识别
看懂-m、-a、-w、-t四个参数，按需换模型和音频
在 Windows 上用麦克风做实时转写，并知道如何停止
按排错表处理模型加载、音频格式这两类高频问题

动手清单：代码、库和模型一次备齐

克隆仓库（只需一次）：

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

准备预编译库、模型和示例音频：examples/c++/download-library.sh会按你的平台自动下载 Moonshine 预编译库到moonshine-voice/，同时把英文流式模型放进medium-streaming-en/、示例录音two_cities.wav放到脚本目录旁边。在examples/c++下执行：

cd examples/c++ ./download-library.sh

确认三样东西就位：moonshine-voice/（库和头文件）、medium-streaming-en/（模型）、two_cities.wav（音频，仓库test-assets/下另有beckett.wav等可选素材）。

跑通第一条转录命令

首次编译运行只做一件事：链接刚下好的库，生成可执行文件transcriber。下面是 Linux 下的完整命令，-Wl,-rpath让程序运行时无需再设置LD_LIBRARY_PATH就能找到库：

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

macOS 的编译命令在 examples/c++/README.md 里有对应版本，只需额外链接系统框架。

直接运行，不带任何参数：

./transcriber

预期输出是一行行滚动的转写事件：Line started:、Line text changed:会随音频推进不断更新同一句话，Line completed:出现时这句话定稿。示例默认读取medium-streaming-en模型和two_cities.wav（狄更斯《双城记》的有声节选），所以你会看到 "It was the best of times..." 这类文本逐步打出来。

参数速查：模型、架构与转写间隔

流式模型边接收音频边出文字，不必等整个文件读完；-a指定架构、-m指定模型目录，两者必须配套。

参数	含义	默认值	何时修改
`-m, --model-path`	模型目录，内含`encoder_model.ort`、`decoder_model_merged.ort`、`tokenizer.bin`	`medium-streaming-en`	换了模型，例如更小的`tiny-streaming-en`
`-a, --model-arch`	架构编号：`0=TINY`、`1=BASE`、`2=TINY_STREAMING`、`3=BASE_STREAMING`、`4=SMALL_STREAMING`、`5=MEDIUM_STREAMING`	`5`	与`-m`保持对应；跑小模型时改`2`，省内存
`-w, --wav-path`	要转写的 16 位 PCM WAV 文件	`two_cities.wav`	测试自己的录音时必改
`-t, --transcription-interval`	每隔多少秒触发一次转写更新（秒）	`0.481`	只出现在通用 C++ 示例里；机器慢、CPU 吃紧时调大

注意-a仅出现在 examples/c++/transcriber.cpp 里；Windows 工具多了-h帮助项，没有-t。各语言可选模型的参数量与错误率见 docs/models/available-models.md，支持的语种见下图：

Windows 麦克风模式：实时转写

命令行工具不止能转文件：examples/windows/cli-transcriber直接接麦克风，把麦克风里的声音实时变成文字。

用 Visual Studio 打开examples/windows/cli-transcriber/cli-transcriber.vcxproj，配置 Release x64 生成。它默认走models/medium-streaming-en，所以先保证模型下载到了对应目录，或自己指定路径。

cli-transcriber.exe -m ..\..\..\medium-streaming-en -a 5

启动后终端提示 Listening to microphone，说话即可看到文字逐字刷新。按 Ctrl+C 停止，进程退出并自动释放音频设备。

排错速查：模型加载失败与音频格式

现象	原因	处理
模型加载失败，提示找不到文件	模型目录里缺少`encoder_model.ort`、`decoder_model_merged.ort`、`tokenizer.bin`任一文件	重新执行`./download-library.sh`，或对照 docs/using/downloading-models.md 核对目录内容
报错与架构不匹配	`-a`编号和模型不是同一架构，比如给`tiny-streaming-en`传了`5`	按参数表把`-a`改成与模型目录对应的编号
提示 Only 16-bit PCM WAV files are supported	录音不是 16 位 PCM 格式，比如浮点 WAV 或压缩格式	用`ffmpeg -i in.wav -ac 1 -ar 16000 -acodec pcm_s16le out.wav`转成 16 位单声道
英文识别效果不理想	小模型词错误率偏高，或间隔太短	换更大的流式模型，或把`-t`调到 0.8 以上

下一步

想要更小或更准的模型：按 docs/models/available-models.md 选择语言与架构，把模型目录放到本机后用-m指定；docs/models/huggingface.md 里有各模型的获取地址。
换自己的音频：把本地 16 位 PCM WAV 传给-w。除了two_cities.wav，test-assets/ 下还有beckett.wav、intent.wav、endgame_nagg_nell.wav等可直接拿来做对照。
写进自己的程序：命令行示例背后就是 examples/c++/transcriber.cpp 里的moonshine::Transcriber类，把addAudio()换成你的音频来源即可；接口说明见 docs/api/classes.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析