如何快速跑通Moonshine语音识别：新手完整指南-开发者社区

如何快速跑通Moonshine语音识别：新手完整指南

【免费下载链接】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 是一个开源的低延迟语音识别库，它把"把语音变成文字"这件事完全放在你的设备本地完成：不需要上传音频、不依赖云服务，边播边出结果。适合想快速验证语音交互的开发者，也适合只是想体验离线转写的普通用户。照下面的步骤操作，5 分钟内你就能听到第一段音频被逐行转成文字。

图：Moonshine 语音识别的整体架构，音频从左侧进入，文本从右侧流出

📋 能力速览

文件转写：把一整段 WAV 音频离线转成文字，适合转写会议录音、采访素材。
流式转写（边说话边出结果，不用等整段说完）：音频播到哪儿就出字到哪儿，适合实时字幕类场景。
词级时间戳：每个词带开始/结束时间和置信度，适合做字幕对齐和高亮。
多语言模型：英文提供 Tiny 到 Medium 多个流式规格，另有日语、德语、西班牙语等语言可选，详见模型列表。
不止转写：同一个库里还有文本转语音（TTS）和声音克隆，后续可以无缝加进来。

⏱️ 三分钟跑通

以 C++ 通用示例为例，它跨平台、只读音频文件，是最短的上手路径。

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

这条命令把整个项目下载到本地，示例代码和辅助脚本都在里面。

下载预编译库和测试模型，一条脚本搞定：

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

脚本会自动识别你的系统，下载对应架构的库文件（解压到moonshine-voice/），并顺带拉取medium-streaming-en语音识别模型和示例音频two_cities.wav。

编译转录程序（Linux 命令，MacOS 见 README）：

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

这一步把示例源码transcriber.cpp编译成可执行文件，并让它在运行时自动找到上一步下载的库。

运行：

./transcriber

默认就用刚下载的模型转写two_cities.wav。如果终端开始滚动打印英文句子——恭喜，跑通了。

🔀 两种用法怎么选

想转写已有的录音文件就用上面的文件模式；想让麦克风实时出字，用 Windows 专属示例 cli-transcriber，它内置了麦克风采集。

文件模式（跨平台，参数如下）：

./transcriber -m medium-streaming-en -w test-assets/beckett.wav -t 0.5

换个 WAV 文件、调整更新频率，一条命令就能跑。

参数	作用	默认值	示例
`-m, --model-path`	模型目录路径	`medium-streaming-en`	`-m medium-streaming-en`
`-a, --model-arch`	模型架构：0=TINY、1=BASE、2=TINY_STREAMING、3=BASE_STREAMING、4=SMALL_STREAMING、5=MEDIUM_STREAMING	`5`	`-a 4`
`-w, --wav-path`	要转写的 WAV 文件	`two_cities.wav`	`-w test-assets/beckett.wav`
`-t, --transcription-interval`	转写更新间隔（秒）	`0.481`	`-t 0.5`

麦克风模式（仅 Windows）：

cli-transcriber.exe

不加参数直接运行，它会监听麦克风并实时打印字幕，按 Ctrl+C 结束；加上-w 某个.wav则改为转写文件后退出。参数与文件模式相同（-m、-a、-w，另有-h查看帮助）。

🛠️ 踩坑速查

现象：启动报找不到libmoonshine.so或libonnxruntime.so.1。原因：可执行文件被移动过，rpath 失效。解法：在examples/c++目录里直接运行，别挪位置。
现象：直接报错Only 16-bit PCM WAV files are supported。原因：音频不是 16 位 PCM 格式。解法：先用 ffmpeg 等工具转成 16 位 PCM WAV 再传入。
现象：模型加载失败、无输出。原因：-a的架构编号与模型目录不匹配。解法：示例自带的medium-streaming-en对应5，不确认前不要改-a。
现象：麦克风模式没有任何反应。原因：没有默认录音设备或设备被其他应用占用。解法：在系统声音设置里确认麦克风可用且没被独占。