将 Moonshine 语音库集成到自有应用JavaScript、Python、iOS、Android 与桌面平台的完整接入指南【免费下载链接】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 是一个主打低延迟的端侧语音工具集覆盖语音转文字STT、意图识别与文字转语音TTS。它在不同平台采用各自最主流的包管理分发方式JavaScript 走 npm 与 CDN、Python 走 PyPI、Apple 平台走 Swift Package Manager、Android 走 Maven Central、桌面平台则提供预编译原生库。读完本文你将掌握在 Node/浏览器、Python 脚本、iOS/macOS、Android、Linux、Windows 与 Raspberry Pi 上分别完成依赖引入、模型准备与首个调用并能对照仓库源码理解底层分发与加载机制。集成方式总览每个平台用什么分发渠道Moonshine 仓库在 docs/using/adding-the-library.md 中明确给出了各平台的分发策略优先使用该平台最通用的包管理器桌面平台Linux/Windows则因为难以统一包管理器而改为发布预编译库与头文件。下表汇总了原文的完整信息平台分发渠道核心产物推荐接口JavaScript / WebAssemblynpmmoonshine-ai/moonshine-wasmES 模块包MicTranscriber、ModelArchPythonPyPImoonshine-voicepip 包 moonshine-voiceCLImoonshine_voice模块iOS / macOSSwift Package Managermoonshine-swift仓库Swift 包import MoonshineVoiceAndroidMaven Centralai.moonshine:moonshine-voiceAAR 依赖Kotlin/Java APILinuxGitHub Releases 预编译共享库x86_64 / arm64libmoonshine.so 头文件C 绑定moonshine-cpp.hWindows下载脚本download-lib.bat拉取库与头文件include/lib/C 绑定moonshine-cpp.hRaspberry Pi复用 PyPI 上的moonshine-voice同 Python 包Python / CLI一个值得注意的共同点是所有示例工程都不内置模型权重。首次使用时会按需下载 STT、TTS、G2P 或 embedding 模型并缓存到本地Android 下是filesDirApple 平台是Caches/MoonshineModels之后即可离线运行。需要完全离线构建时可以提前抓取资源并用modelsFrom(path)指向本地路径取舍详见 docs/design/api-comparison.md。JavaScriptnpm 安装与 CDN 免安装引入WebAssembly 版本发布在 npm 上包名为moonshine-ai/moonshine-wasm。在 Node 或任意打包器bundler项目中直接安装npm install moonshine-ai/moonshine-wasm随后在代码中导入即可使用import { MicTranscriber, ModelArch } from moonshine-ai/moonshine-wasm;浏览器端则连安装步骤都不需要同一个包可以通过 jsDelivr CDN 直接以 ESM 形式引入import { MicTranscriber, ModelArch } from https://cdn.jsdelivr.net/npm/moonshine-ai/moonshine-wasm/dist/index.js;仓库中提供了完整的 Web 示例树作为开箱即用的参考examples/web/index.html 是主入口同目录下还有多个可运行的独立演示stt、tts、agent-flow、dictation、meeting-notes它们都是自包含归档解压后用node serve.mjs启动本地服务即可在浏览器中体验——识别与合成全部在浏览器内完成不上传任何音频。Wasm 绑定的源码位于 language-bindings/wasm/src由 moonshine-embind.cpp 通过 embind 将 C 核心暴露给 JavaScript。Pythonpip 安装与moonshine-voice命令行工具Python 包托管在 PyPI 上安装只需要一行命令然后即可在项目中导入pip install moonshine-voiceimport moonshine_voice安装 Python 包的同时会注册一个moonshine-voice命令另有更短的moonshine别名把内置工具组织成若干子命令。这个入口在 pyproject.toml 的[project.scripts]表中定义指向moonshine_voice.cli:main。子命令清单如下对应原文表格并补充了源码中实际存在的两个微调命令命令说明moonshine-voice mic将麦克风实时输入转写到终端。moonshine-voice transcribe转写 WAV 文件可选说话人 ID / 词级时间戳。moonshine-voice tts从文本合成语音输出到 WAV 文件或音频设备。moonshine-voice agent运行一个口语 Agent 流程wifi 配置并从麦克风交互。moonshine-voice download下载 STT、TTS、G2P 或 embedding 模型资源。moonshine-voice g2p将文本转换为音素IPA。moonshine-voice lora/finetune训练 LoRA 领域适配器需pip install moonshine-voice[lora]。运行moonshine-voice command --help可查看每个子命令支持的选项。这些 CLI 命令面向一次性使用场景如果同一任务需要多次调用 Moonshine建议在 Python 中只加载一次模型以获得更高效率。从源码看CLI 是一个薄分发层cli.py 用一张COMMANDS字典维护子命令 → 模块的映射再通过runpy.run_module(module_name, run_name__main__)以python -m的方式运行对应模块。因此文档中的等价关系是严格成立的moonshine-voice mic --language en python -m moonshine_voice.mic_transcriber --language en两者做的事情完全一样参数解析与帮助文本都各自留在具体模块里不会因调用方式不同而分叉。关于 Python 包本身还有几个值得了解的仓库事实见 pyproject.toml要求 Python3.8基础依赖仅包含numpy、sounddevice、requests、tqdm、filelock、platformdirs、google-crc32c等轻量库推理安装不会引入 PyTorch 或 Transformers领域微调是可选的 extrapip install moonshine-voice[finetune]别名[lora]该 extra 才额外引入torch、transformers、safetensors、onnx等包的顶层 API 在init.py 中导出包括Transcriber、MicTranscriber、TextToSpeech、AgentFlow、GraphemeToPhonemizer、EmbeddingModel以及get_model_for_language、supported_languages等辅助函数这些重型模块采用惰性导入避免脚本运行时产生无谓开销。iOS 与 macOSSwift Package Manager 接入Apple 平台使用 Swift Package Manager每个版本由自动更新的moonshine-swift仓库承载。接入步骤原文原样保留在 Xcode 左侧文件视图右键选择Add Package Dependencies...在弹出的对话框中把moonshine-swift仓库地址粘贴到顶部搜索框看到moonshine-swift后选中它点击Add Package完成添加在代码中import MoonshineVoice即可使用。需要注意你使用的任何模型文件都必须加入 App Bundle并确保在部署阶段被复制到设备上才能离线访问。仓库中提供了已完成上述配置的 Xcode 工程作为参考examples/ios/Transcriber以及 macOS 侧的 examples/macos/BasicTranscription该目录还带有project.yml可用 XcodeGen 重新生成工程。Swift 绑定源码位于 language-bindings/swift/Sources对应测试在 language-bindings/swift/Tests。AndroidMaven Central 与 Gradle 依赖配置Android 版发布在 Maven Central坐标是ai.moonshine:moonshine-voice。使用 Android Studio Gradle 集成分三步在gradle/libs.versions.toml的[versions]段添加版本号例如moonshineVoice 0.1.5在[libraries]段添加包引用moonshine-voice { group ai.moonshine, name moonshine-voice, version.ref moonshineVoice }在app/build.gradle.kts的dependencies列表中加入implementation(libs.moonshine.voice)。仓库里的 examples/android/Transcriber 与 examples/android/TextToSpeech 示例工程使用的正是这套坐标——例如 TextToSpeech 的 libs.versions.toml 中可见moonshineVoice 0.1.5与对应的[libraries]引用你可以直接照抄。Android 的 JNI 桥接层位于 language-bindings/android/moonshine-jniJava/Kotlin 封装在 language-bindings/android/java。Linux预编译共享库与 C 编译链接Linux 的 x86_64 与 arm64 预编译共享库随 GitHub Releases 发布最省事的拉取方式是使用 examples/c/download-library.sh 辅助脚本cd examples/c ./download-library.sh脚本会自动检测平台、下载匹配的预编译库归档并总是解压到名为moonshine-voice/的固定目录无论操作系统和架构因此后续编译命令永远不变。解压后你会得到include/下的头文件以及lib/下的libmoonshine.so含它依赖的 ONNX Runtime。Linux 下lib目录是自包含的libmoonshine.so与libonnxruntime.so.1放在一起且库本身带有$ORIGINrpath无需设置LD_LIBRARY_PATH即可找到 ONNX Runtime。将头文件路径与库路径加入编译和链接行并包含 C 绑定g your_app.cpp \ -Imoonshine-voice/include \ -Lmoonshine-voice/lib \ -lmoonshine \ -Wl,-rpath,$ORIGIN/moonshine-voice/lib \ -o your_app#include moonshine-cpp.h其中-Wl,-rpath,$ORIGIN/...会把运行时库搜索路径记录进编译出的二进制相对该二进制自身位置这样程序运行时能自动找到libmoonshine.so再经由它自身的$ORIGINrpath 找到libonnxruntime.so.1同样不需要LD_LIBRARY_PATH。若你更愿意手动指定也可以去掉 rpath 参数改为在运行前export LD_LIBRARY_PATH$(pwd)/moonshine-voice/lib。仓库中的 examples/c/transcriber.cpp 是一个最小端到端程序它把 WAV 文件切成约 21.4ms 的音频块送入moonshine::Transcriber注册TranscriptEventListener监听行级事件并按 0.481s 的间隔调用updateTranscription()刷新转写结果见 main 函数。默认使用medium-streaming-en模型与ModelArch::MEDIUM_STREAMING也支持用--model-path、--model-arch、--wav-path、--transcription-interval参数覆盖。macOSC 方式编译可选除了 SwiftPMmacOS 上也可以按 C 方式使用预编译库。仓库的 examples/c/README.md 给出了编译命令——macOS 下预编译产物是静态库libmoonshine.a链接时还需要额外带上 Apple 的框架g transcriber.cpp \ -Imoonshine-voice/include \ -Lmoonshine-voice/lib \ -lmoonshine \ -o transcriber \ -framework CoreFoundation \ -framework Foundationtext-to-speech.cpp用同样的方式编译替换源文件与-o输出名。注意 TTS 示例额外需要语音voice与 G2P 数据运行时要通过--asset-root指定其位置在仓库检出中即core/moonshine-tts/data。Windows下载脚本与 C 头文件绑定Windows 生态缺乏统一的包管理器因此 Moonshine 直接提供库与头文件的下载包。examples/windows/cli-transcriber/download-lib.bat 脚本会自动拉取这些文件解压后得到include目录把它加入项目设置的 include 搜索路径得到lib目录加入库搜索路径将lib目录中的所有库文件加入项目的链接器依赖列表。Windows 上推荐的接口是 C 语言绑定moonshine-cpp.h——它是一个纯头文件库提供了比底层 C 版本更高层的 API。若想看到以上所有配置整合在一起的完整示例参考 examples/windows/cli-transcriber自包含的 Visual Studio 工程编译后既可转写 WAV 也可转写实时麦克风输入。Raspberry Pi复用 Python 包Raspberry Pi OS 上可以直接复用桌面版 Python 包。接上 USB 麦克风后pip install moonshine-voice如果 pip 提示系统包冲突PEP 668 的 externally-managed-environment 保护可以改用虚拟环境或使用pip install --break-system-packages moonshine-voice。之后与在其他平台一样import moonshine_voice或直接使用moonshine-voiceCLI。Pi 专属示例见 examples/raspberry-pi/my-dalek/my-dalek.py一个趣味语音指令界面。C 绑定的能力边界哪些能用、哪些不在库里无论是 Linux、macOS 还是 WindowsC 绑定moonshine-cpp.h的语义是一致的理解它的边界有助于你选择正确的集成姿势。从 examples/c/README.md 与 core/moonshine-cpp.h 可以确认包含Transcriber、TextToSpeech、GraphemeToPhonemizer、EmbeddingModel、VoiceClone不包含因为它不打开任何设备、不建立任何网络连接从而保证可移植到任何能编译该库的平台MicTranscriber与AgentFlow需要采集设备、say()需要输出设备应改用synthesize()拿到采样数据自己播放、以及一切下载能力——所以 C 侧没有load()或进度回调模型路径与缓冲区需要你自行提供。取模型虽然是你的事但该取哪些模型不是C 绑定提供getDependencies()系列静态方法返回与其它绑定下载所用一致的 JSON 清单含文件名、URL、大小与校验和std::string stt moonshine::Transcriber::getDependencies(en); std::string diarization moonshine::Transcriber::getDiarizationDependencies(); std::string tts moonshine::TextToSpeech::getDependencies(en_us); std::string g2p moonshine::GraphemeToPhonemizer::getDependencies(en_us); std::string embedding moonshine::EmbeddingModel::getDependencies(embeddinggemma-300m);Transcriber::getCatalog()与EmbeddingModel::getCatalog()则列出所有已发布模型方便你浏览挑选。语音克隆在 C 侧同样可用——寻找参考片段的语音活动检测器被编译进库中、无需额外下载moonshine::TextToSpeech tts(en_us, {{g2p_root, assetRoot}}); tts.cloneFrom(recording, sampleRate, what the speaker said); moonshine::TtsSynthesisResult cloned tts.synthesize(Hello world!);若想从实时流而非成品录音中采集克隆片段使用startCloning()并持续addAudio()直到isReady()。接入之后的下一步完成依赖接入后可以顺着以下仓库文档继续深入示例总览与各平台示例树的完整清单docs/examples.md其中也说明了模型按需下载与缓存的机制Python 脚本示例离线/流式转写 examples/python/basic_transcription.py、麦克风实时转写 examples/python/mic_transcription.py、语音合成与克隆 examples/python/text_to_speech.py、生成器式对话 Agent examples/python/agent_flow.py使用层面的专项指南docs/using/transcription.md、docs/using/text-to-speech.md、docs/using/downloading-models.md若你的平台没有预编译产物也可以自行从源码构建核心库见 examples/c/README.md 中对cmake构建的说明构建入口在 core/CMakeLists.txt。一句话总结JavaScript、Python、Apple 与 Android 平台走标准包管理器 首次按需下载模型的路径Linux/macOS/Windows 则用预编译原生库配合 C 头文件绑定。按本文对应平台的步骤操作你就能把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
