Moonshine Voice 全平台快速上手从麦克风转写到语音代理的一条命令入门【免费下载链接】moonshineVery low latency speech to text, intent recognition, and text to speech, for building voice agents and interfaces项目地址: https://gitcode.com/GitHub_Trending/moonshine3/moonshineMoonshine Voice 是一个面向实时语音应用的开源 AI 工具包主打低延迟、端上运行转写、意图识别与语音合成都在本机完成无需账号、API Key 或 GPU。本文以官方 docs/quickstart.md 为主线逐平台讲解从安装、跑通到定制的最小可用路径并结合作者仓库中的源码与示例把每条命令背后发生了什么一并讲透。读完你可以在 JavaScript/WASM、Python、iOS、Android、Linux、Windows、树莓派上分别用最短的代码启动一个实时语音转写器、一个能听懂口令的语音代理以及一个会说中文或英文的 TTS 引擎。先看清全貌一份文档覆盖七种平台docs/quickstart.md采用标签页结构组织每一种平台都有独立的开箱即用方案但核心 API 高度一致——load()负责下载并装载模型start()负责打开麦克风开始工作回调onText/onLine负责把正在说的和已定稿的转写文本交还给你。理解了这个共同骨架再逐个平台看差异即可平台安装/引入方式入口 API仓库中的对应实现JavaScript / WASMnpm install moonshine-ai/moonshine-wasm或 CDN 直引MicTranscriberModelArchlanguage-bindings/wasmPythonpip install moonshine-voiceCLImoonshine-voice mic/agent/ttslanguage-bindings/python/src/moonshine_voiceiOS / macOSSwift Package Manager 添加moonshine-swiftSwift 版MicTranscriberlanguage-bindings/swiftAndroidGradle 依赖ai.moonshine:moonshine-voice:0.1.5Java 版MicTranscriberlanguage-bindings/androidLinux预编译.sox86_64 / arm64CTranscriberexamples/cWindows自包含归档 Visual StudioCcli-transcriberexamples/windows/cli-transcriberRaspberry Pi优化的 Python pip 包同 Pythonexamples/raspberry-pi/my-dalek下面按平台逐节展开命令与代码均以仓库实际内容为准。JavaScript / WASM浏览器里 30 秒跑起实时转写Node 环境直接安装 npm 包npm install moonshine-ai/moonshine-wasmWeb 场景则从 CDN 直接导入。原文档给出的最小示例import { MicTranscriber, ModelArch } from https://cdn.jsdelivr.net/npm/moonshine-ai/moonshine-wasm/dist/index.js; const mic new MicTranscriber() .modelArch(ModelArch.MediumStreaming) .onText((text) showInProgress(text)) .onLine((line) appendLine(line.text, line.lastTranscriptionLatencyMs)); await mic.load(); await mic.start();这段代码的语义值得拆解modelArch(ModelArch.MediumStreaming)显式指定使用Medium Streaming 英文模型。它正是当前英文 STT 的推荐档位——Python 端MicTranscriber在未显式指定时也默认落到该架构见 mic_transcriber.py 中self._model_arch None且注释说明None 表示目录推荐的模型对英文即 medium streaming。流式架构意味着模型在用户讲话过程中就持续产出结果而不是等一句话说完。onText回调接收进行中的文本模型会随着更多音频到来而改写之前的词所以这里适合渲染实时高亮/占位文本。onLine回调在一行定稿后触发line.text是最终文本line.lastTranscriptionLatencyMs给出该行的最新一次转写延迟毫秒这是评估端到端低延迟体验的关键指标。load()是阻塞的首次调用需要下载模型start()打开麦克风开始聆听。体验现成的 Web 示例仓库 examples/web 下已经内置了五类可直接运行的页面应用stt/语音转写、tts/语音合成、agent-flow/语音代理、dictation/听写、meeting-notes/会议纪要。快速开始文档建议从官方 releases 页面下载对应的web-stt.tar.gz、web-tts.tar.gz、web-agent-flow.tar.gz、web-dictation.tar.gz、web-meeting-notes.tar.gz归档解压后用仓库自带的静态服务器启动node serve.mjs然后浏览器访问http://localhost:8080/即可逐个体验。serve.mjs 就是这些示例的本地托管入口。Python一个 pip 包三个核心命令Python 是探索 Moonshine Voice 最快的方式。安装pip install moonshine-voice安装后即获得moonshine-voice命令行工具另有更短的moonshine别名。快速开始文档给出的三条命令覆盖了三大核心能力# 1. 实时麦克风转写边听边打印更新中的转写文本 moonshine-voice mic --language en # 2. 语音代理跑一段语音配置 WiFi的多轮对话 moonshine-voice agent # 3. 语音合成把文本说出来 moonshine-voice tts --language en_us --text Hello worldmoonshine-voice agent值得特别说明它运行的是一段有触发词、有提问、有确认的口语化 WiFi 配置流程并且匹配是语义级的——用户用不同的自然语言变体表达同一意图都能被识别而不是死板的关键字匹配。CLI 背后的分发结构moonshine-voice命令并非一个巨型入口而是薄分发器每个子命令都等价于python -m moonshine_voice.module。看 cli.py 中定义的子命令表子命令对应模块用途micmic_transcriber实时麦克风转写输出到终端transcribetranscriber转写 WAV 文件可带说话人 ID / 词级时间戳ttstts文本合成语音到 WAV 或音频设备agentagent_flow从麦克风运行语音代理流程WiFi 配置示例downloaddownload下载 STT / TTS / G2P / 嵌入模型资产g2pg2p用 G2P 引擎把文本转成音素IPAlora/finetunelora训练 LoRA 领域适配器需pip install moonshine-voice[lora]或[finetune]额外依赖因此moonshine-voice mic --language en与python -m moonshine_voice.mic_transcriber --language en完全等价参数解析与帮助文本都定义在各自模块中。mic子命令本身也支持--model-arch参数ModelArch枚举的整数值用于选择模型档位。在 Python 代码中使用 MicTranscriberCLI 之外更常用的是直接在 Python 里构建转写器。仓库 language-bindings/python/README.md 给出了最小完整示例import time from moonshine_voice import MicTranscriber mic ( MicTranscriber() .on_text(lambda text: print(f\r{text}, end, flushTrue)) .on_line(lambda line: print(f\r{line.text})) ) mic.load() # 首次调用会下载并缓存模型 mic.start() # 打开麦克风开始听 print(Listening to the microphone, press CtrlC to stop...) while True: time.sleep(0.1)设计要点均可在 mic_transcriber.py 源码中核实配置全部可链式调用且都有可用默认值language()默认en、model_arch()、device()按索引或名称指定输入设备、update_interval()自动流式更新间隔默认 0.5 秒、on_progress()下载进度条回调。旧的构造参数传模型路径写法已被移除统一改为.models_from(directory)等 setter。load()幂等第二次调用直接返回不会重复下载。on_text与on_line的差别前者是正在说、可能被改写的进行时文本后者是定稿行TranscriptLine。如果还需要行 ID、说话人区间、词级时间戳或行开始事件应改用add_listener()挂一个TranscriptEventListener对象两种风格可以混用。内部音频流水线MicTranscriber通过 PortAudio 回调采集音频把数据放入线程安全队列再由独立 worker 线程批量喂给转写流源码注释明确说明这是为了避免在时间敏感的采集回调里跑推理导致输入溢出对应 issue #196。它还会自动处理采样率回退当请求的 16000 Hz 不被设备支持时查询设备默认采样率并回退由底层 C API 负责重采样。此外MicTranscriber还支持set_keyterms()/set_context()在聆听过程中对关键词/上下文做解码偏置、mute()静音输入常用于防止助手转录自己合成的语音、spelling_model()字母拼写模式用于口述验证码/密码时提升准确率以及transcribe_flags()打开MOONSHINE_FLAG_SPELLING_MODE拼写融合路径。自定义音频源Transcriber 流式接口不接麦克风时可以用底层Transcriber直接喂任意音频源from moonshine_voice import Transcriber, get_model_for_language model_path, model_arch get_model_for_language(en) transcriber Transcriber(model_pathmodel_path, model_archmodel_arch) stream transcriber.create_stream(update_interval0.5) stream.start() # 循环调用 stream.add_audio(chunk, sample_rate) 喂入音频块get_model_for_language(es)这类调用会按语言代码下载对应模型并返回构建Transcriber所需的路径与架构信息。当前 Python 框架支持的语言包括英语、西班牙语、普通话、日语、韩语、越南语、阿拉伯语、乌克兰语可在运行时用supported_languages()查看你安装版本的实际列表。TTS 与语音克隆from moonshine_voice import TextToSpeech tts TextToSpeech().language(en_us).voice(kokoro_af_heart) tts.load() tts.say(Hello from Moonshine.) tts.wait()say()立即返回并排队合成同时会预合成下一条因此连续调用之间没有间隙wait()阻塞到队列排空stop()取消is_talking()轮询状态。若只想拿音频采样而不是播放用synthesize()。链式 setter 包括language()、voice()、output_device()、volume()、models_from()、on_progress()。语音克隆只需几秒参考录音tts TextToSpeech().language(en_us).cloning() tts.load() tts.clone_from(some-speech.wav) tts.say(Now I sound like you.).cloning()要在load()之前调用——它会让load()一并拉取 ZipVoice 克隆模型与克隆 ASR也可以用start_cloning()从麦克风实时采集参考片段。语音代理 AgentFlow注册你关心的口令短语AgentFlow会下载 STT、TTS 与短语匹配模型、打开麦克风、做语义匹配并回调你的处理函数from moonshine_voice import AgentFlow def lights_on(d): print(LIGHTS ON!) runner AgentFlow().always(turn on the lights, lights_on) runner.load() runner.start_listening()多轮对话提问→确认→拼写密码则用listen_for()注册生成器式流程。源码 agent_flow.py 开头的setup_wifi示例演示了yield d.ask(...)/yield d.confirm(...)的完整形态并且cancel / start over这类短语无需注册、在流程任意位置都生效。AgentFlow不依赖 asyncio流程由交付转写事件的线程同步驱动因此可以脱离音频/TTS 做纯单元测试。iOS 与 macOS同构的 Swift API两个平台的用法完全相同原文档明确写道This code is identical to the iOS version。首先在 Xcode 中通过 Swift Package Manager 把moonshine-swift仓库添加为项目依赖然后import MoonshineVoice let mic MicTranscriber() .onText { [weak self] text in Task { MainActor in self?.liveText text } } .onLine { [weak self] line in Task { MainActor in self?.lines.append(line.text) } } try await mic.load() try mic.start()注意 Swift 版的差异load()是异步的await回调里通过MainActor切回主线程更新 UI。仓库 language-bindings/swift 下是完整的 Swift 源码与测试想直接看工程样例可从 releases 页面下载 iOS 的ios-Transcriber.tar.gz或 macOS 的macos-MicTranscription.tar.gz解压后用 Xcode 打开对应.xcodeproj即可运行对应目录可对照 examples/ios/Transcriber 与 examples/macos/MicTranscription。AndroidGradle 依赖 Java 回调在build.gradle.kts中添加依赖implementation(ai.moonshine:moonshine-voice:0.1.5)Java 侧代码import ai.moonshine.voice.MicTranscriber; mic new MicTranscriber(this) .onText(text - transcriptText.setText(finishedLines text)) .onLine(line - { finishedLines.append(line.text).append(\n); transcriptText.setText(finishedLines.toString()); }); worker.execute(() - { mic.load(); mic.start(); });由于load()和start()会做模型下载与音频设备操作原文档明确建议放到工作线程worker.execute(...)里执行避免阻塞主线程。仓库 language-bindings/android 提供完整的 Java 绑定与 JNI 层从 releases 页面下载android-Transcriber.tar.gz解压后用 Android Studio 打开Transcriber目录即可直接构建对应 examples/android/Transcriber。LinuxC 预编译库的一行式体验Moonshine Voice 为 x86_64 与 arm64 Linux 都发布了预编译共享库最省事的方式是走官方 examples/c/README.md 描述的便携 C 示例——它会自动下载库、英文转写模型与示例录音然后编译并运行一个转写器curl -O -L https://github.com/moonshine-ai/moonshine/releases/latest/download/cpp-examples.tar.gz tar xzf cpp-examples.tar.gz cd c ./download-library.sh g transcriber.cpp -Imoonshine-voice/include -Lmoonshine-voice/lib -lmoonshine -Wl,-rpath,$ORIGIN/moonshine-voice/lib -o transcriber ./transcriber几个工程细节值得留意均来自 examples/c/README.md 与 download-library.shdownload-library.sh会检测平台、下载匹配的预编译归档并总是解压到名为moonshine-voice的目录因此无论操作系统与架构后续编译命令完全一致。它还会把 Medium Streaming English 模型放到medium-streaming-en/并下载示例录音two_cities.wav。解压出的lib目录在 Linux 上是自包含的libmoonshine.so与它依赖的libonnxruntime.so.1同目录存放库本身以$ORIGINrpath 构建因此无需设置LD_LIBRARY_PATH即可找到 ONNX Runtime。编译参数-Wl,-rpath,$ORIGIN/moonshine-voice/lib把运行时库搜索路径记录进可执行文件也可以去掉 rpath改用export LD_LIBRARY_PATH$(pwd)/moonshine-voice/lib。默认转写two_cities.wav可通过--model-path、--model-arch、--wav-path指向你自己的模型与音频。C API 的能力边界examples/c/README.md 特别强调了 C 绑定是header-only的且不打开任何设备、不发起任何网络连接因此它提供了Transcriber、TextToSpeech、GraphemeToPhonemizer、EmbeddingModel、VoiceClone但没有MicTranscriber或AgentFlow它们需要采集设备、没有say()它需要输出设备synthesize()会把采样交给你自己播放、也没有下载能力没有load()/ 进度回调。模型获取由你负责但该下载哪些模型不用猜——getDependencies()会返回命名文件、URL、大小与校验和的 JSON 清单例如moonshine::Transcriber::getDependencies(en)。TTS 的 C 示例 text-to-speech.cpp 还需要 TTS 语音与 G2P 数据运行时通过--asset-root指定数据目录在仓库检出版本中即core/moonshine-tts/data。macOS 编译时额外链接CoreFoundation与Foundation两个框架。Windows自包含的 Visual Studio 工程从 releases 页面下载windows-cli-transcriber.tar.gz解压后用 Visual Studio 打开cli-transcriber\cli-transcriber.vcxproj工程文件。该归档自包含库与模型因此直接CtrlShiftB或F7即可构建出可执行文件。仓库中对应工程为 examples/windows/cli-transcriber内含解决方案、工程文件与源码。Raspberry Pi针对 Pi 优化的 pip 包树莓派需要外接 USB 麦克风获取音频输入。Python pip 包已针对 Pi 做了优化直接安装运行sudo pip install --break-system-packages moonshine-voice moonshine-voice mic --language en--break-system-packages用于绕过新版 Debian 系 Python 对系统级 pip 安装的限制若不想用该参数原文档建议改用虚拟环境可参考 examples/raspberry-pi/my-dalek/README.md。仓库里还有 Pi 专属的趣味示例 my-dalek.py。值得一提的实现细节是正是由于 Pi 上单次推理可能阻塞数百毫秒MicTranscriber才把转写放到独立 worker 线程并从采集回调脱耦——这也是源码中 issue #196 的修复动机直接受益者就是这类低算力设备。给 Coding Agent 用Agent Skills 快速集成如果你在用 Cursor、Claude Code、Codex 或其他支持 Agent Skills 的客户端原文档给出的集成路径是把仓库中的.agents/skills/moonshine-voice/目录复制进你项目的.agents/skills/文件夹或者直接运行npx skills add moonshine-ai/moonshine --skill moonshine-voice这个 skill 会向 Agent 传授当前版本的 API 形态README 中特别提到它能让 Agent 不再下意识地使用 Whisper 或旧版DialogFlow命名是接入本库的快乐路径。但原文档也强调它只是辅助不能替代上述各平台文档——集成出错时仍应以官方文档为准。从快速开始走向深入跑通上面的示例后按需深入转写进阶流式/非流式转写、说话人识别diarization、词级时间戳见 docs/using/transcription.md 与 docs/using/word-level-timestamps.md。TTS 与语音克隆语言、音色kokoro_*/zipvoice_*、克隆流程见 docs/using/text-to-speech.md音色试听可在 docs/audio 找到对应 WAV。会话式语音代理AgentFlow 的完整多轮对话设计见 docs/using/conversational-agent.md。模型与领域定制可用模型清单、量化、LoRA 领域适配见 docs/models/available-models.md 与 docs/models/domain-customization.md。API 参考类、选项与 C API 说明见 docs/api/classes.md。C/C 内核核心实现在 core 目录C API 声明见 core/moonshine-c-api.h。需要留意的前提条件快速开始中的下载式流程Web 归档、pip 模型下载、download-library.sh都依赖联网获取模型资产首次运行因下载模型会偏慢后续运行使用本地缓存。各平台示例展示的是开箱即用的体验路径若要定制模型档位、语言或音频设备请回到上文各平台的链式配置 API。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考