Installation

Overview

Moonshine Voice provides native packages for all major platforms using standard package managers. Choose your platform below:

Python

pip install

iOS/macOS

Swift Package Manager

Android

Maven/Gradle

Windows

Visual Studio

Linux

CMake build

Raspberry Pi

Python pip

Python

The easiest way to get started with Moonshine Voice.

pip install moonshine-voice

Requirements

Python: 3.8 or newer
Dependencies: numpy, sounddevice, requests, tqdm, filelock, platformdirs (installed automatically)
Platforms: Linux, macOS, Windows

Quick Test

Verify installation by transcribing from your microphone:

python -m moonshine_voice.mic_transcriber --language en

Import in Code

from moonshine_voice import Transcriber, MicTranscriber
from moonshine_voice import download_model, load_wav_file

print("Moonshine Voice installed successfully!")

iOS and macOS

Moonshine Voice uses Swift Package Manager for iOS and macOS integration.

Swift Package Manager

Open Xcode Project

Open your project in Xcode.

Add Package Dependency

Right-click on the file view sidebar and choose:Add Package Dependencies…

Enter Repository URL

In the dialog, paste the repository URL:

https://github.com/moonshine-ai/moonshine-swift/

Select moonshine-swift when it appears and click Add Package.

Import in Swift

Import the framework in your Swift files:

import MoonshineVoice

Add Model Files

Download model files using the Python package:

pip install moonshine-voice
python -m moonshine_voice.download --language en

Add the downloaded model files to your app bundle and ensure they’re copied during deployment.

Requirements

iOS: 14.0 or later
macOS: 13.0 or later
Xcode: 13.0 or later

Example Projects

Download ready-to-run examples:

curl -L https://github.com/moonshine-ai/moonshine/releases/latest/download/ios-examples.tar.gz -o ios-examples.tar.gz
tar -xzf ios-examples.tar.gz
open Transcriber/Transcriber.xcodeproj

Package.swift (for Libraries)

If you’re building a library that depends on Moonshine:

Package.swift

// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "YourPackage",
    platforms: [
        .iOS(.v14),
        .macOS(.v13),
    ],
    dependencies: [
        .package(
            url: "https://github.com/moonshine-ai/moonshine-swift/",
            from: "0.0.49"
        )
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: [
                .product(name: "MoonshineVoice", package: "moonshine-swift")
            ]
        )
    ]
)

Android

Moonshine Voice is distributed via Maven Central for Android projects.

Gradle Setup

Add Version to libs.versions.toml

In your gradle/libs.versions.toml file, add:

gradle/libs.versions.toml

[versions]
moonshineVoice = "0.0.49"

[libraries]
moonshine-voice = { group = "ai.moonshine", name = "moonshine-voice", version.ref = "moonshineVoice" }

Add Dependency to build.gradle.kts

In your app/build.gradle.kts, add to dependencies:

app/build.gradle.kts

dependencies {
    implementation(libs.moonshine.voice)
    // ... other dependencies
}

Sync Project

Click Sync Now in Android Studio to download the library.

Import in Kotlin/Java

MainActivity.kt

import ai.moonshine.MoonshineVoice
import ai.moonshine.Transcriber

Requirements

Android SDK: 21 (Android 5.0) or higher
Build System: Gradle 7.0+
Languages: Kotlin or Java

Example Project

Download a complete Android Studio project:

curl -L https://github.com/moonshine-ai/moonshine/releases/latest/download/android-examples.tar.gz -o android-examples.tar.gz
tar -xzf android-examples.tar.gz
# Open the Transcriber folder in Android Studio

Maven Central

View the package on Maven Central: ai.moonshine:moonshine-voice

Windows

For Windows developers using Visual Studio and C++.

Download Library Files

Install Python Package

First, install the Python package for model management:

pip install moonshine-voice

Download C++ Library

Use the provided download script from the examples:

curl -L https://github.com/moonshine-ai/moonshine/releases/latest/download/windows-examples.tar.gz -o windows-examples.tar.gz
tar -xzf windows-examples.tar.gz
cd examples\windows\cli-transcriber
.\download-lib.bat

This downloads the library files and headers to a local directory.

Build Example Project

Build the example using MSBuild:

msbuild cli-transcriber.sln /p:Configuration=Release /p:Platform=x64

Download Models

python -m moonshine_voice.download --language en

Note the model path and architecture number from the output.

Run Example

x64\Release\cli-transcriber.exe --model-path <path> --model-arch <number>

Visual Studio Project Setup

To add Moonshine to your own Visual Studio project:

Add Include Directory: Add the include folder to your project’s include search paths
Add Library Directory: Add the lib folder to your library search paths
Link Libraries: Add all .lib files from the lib folder to linker dependencies
Include Header: #include "moonshine-cpp.h" in your C++ code

Requirements

Visual Studio: 2019 or later
Platform: x64 only
Language: C++17 or later

Linux

Build from source using CMake for native Linux applications.

Build from Source

Clone Repository

git clone https://github.com/moonshine-ai/moonshine.git
cd moonshine

Build with CMake

cd core
mkdir build
cd build
cmake ..
cmake --build .

Run Tests

cd ../test-assets
../build/moonshine-cpp-test

Python Installation (Easier)

For most Linux users, the Python package is the simplest option:

pip install moonshine-voice
python -m moonshine_voice.mic_transcriber --language en

Requirements

Compiler: GCC 7+ or Clang 6+
CMake: 3.15 or later
Dependencies: Included via submodules

Build Script

Use the automated test script:

./scripts/run-core-tests.sh

Raspberry Pi

Moonshine Voice is optimized for Raspberry Pi with special performance tuning.

Installation

Connect USB Microphone

Plug in a USB microphone for audio input.

Install Moonshine

sudo pip install --break-system-packages moonshine-voice

The --break-system-packages flag is needed on Raspberry Pi OS. Alternatively, use a virtual environment (see below).

Run Transcriber

python -m moonshine_voice.mic_transcriber --language en

Using Virtual Environment (Recommended)

To avoid system package conflicts:

python -m venv moonshine_env
source moonshine_env/bin/activate
pip install moonshine-voice
python -m moonshine_voice.mic_transcriber --language en

Performance

On Raspberry Pi 5:

Model	Latency
Tiny Streaming	237ms
Small Streaming	527ms
Medium Streaming	802ms

Use the Tiny or Small Streaming models for best real-time performance on Raspberry Pi.

Example Projects

Download Pi-specific examples:

curl -L https://github.com/moonshine-ai/moonshine/releases/latest/download/raspberry-pi-examples.tar.gz -o rpi-examples.tar.gz
tar -xzf rpi-examples.tar.gz

Video Tutorial

Watch the Raspberry Pi setup screencast on YouTube.

Model Installation

All platforms require downloading model files before use.

Download Models

pip install moonshine-voice
python -m moonshine_voice.download --language en

Supported Languages

Language	Code	Model Size
English	`en`	Multiple (tiny to medium)
Spanish	`es`	Base
Mandarin	`zh`	Base
Japanese	`ja`	Base
Korean	`ko`	Tiny
Vietnamese	`vi`	Base
Ukrainian	`uk`	Base
Arabic	`ar`	Base

Model Cache Location

Models are cached in:

macOS
Linux
Windows

~/Library/Caches/moonshine_voice/

~/.cache/moonshine_voice/

%LOCALAPPDATA%\moonshine_voice\

Customize cache location:

export MOONSHINE_VOICE_CACHE=/path/to/models
python -m moonshine_voice.download --language en

Available Model Architectures

From moonshine-c-api.h:

0 - Tiny (26M params, 12.66% WER)
1 - Base (58M params, 10.07% WER)
2 - Tiny Streaming (34M params, 12.00% WER)
3 - Small Streaming (123M params, 7.84% WER)
4 - Medium Streaming (245M params, 6.65% WER)

If no architecture is specified, the highest-quality model available for that language is downloaded.

Verification

Test your installation:

Python
Swift
Android
C++

from moonshine_voice import Transcriber
from moonshine_voice import download_model

model_path, model_arch = download_model(language="en")
transcriber = Transcriber(model_path=model_path, model_arch=model_arch)
print("✅ Moonshine Voice installed successfully!")

import MoonshineVoice

// If this compiles, installation successful
print("✅ Moonshine Voice installed successfully!")

import ai.moonshine.Transcriber

// If this compiles, installation successful
println("✅ Moonshine Voice installed successfully!")

#include "moonshine-cpp.h"

// If this compiles and links, installation successful
std::cout << "✅ Moonshine Voice installed successfully!" << std::endl;

Building from Source

For advanced users who want to customize the library.

Prerequisites

CMake: 3.15+
C++ Compiler: C++17 support
Git: For cloning submodules

Complete Build

git clone https://github.com/moonshine-ai/moonshine.git
cd moonshine

# Build core library
cd core
mkdir build && cd build
cmake ..
cmake --build . --config Release

# Run tests
cd ../test-assets
../build/moonshine-cpp-test

Build All Platform Packages

To build packages for all platforms (requires platform SDKs):

./scripts/build-all-platforms.sh

This builds:

Python wheel
Swift framework
Android AAR
Windows DLLs

Language Bindings

Binding source code locations:

Python: python/src/moonshine_voice/
Swift: swift/Sources/MoonshineVoice/
Android: android/src/main/java/
C++ Header: core/moonshine-cpp.h

Troubleshooting

Python: Module not found

# Ensure pip installed to correct Python
python --version
pip --version

# Reinstall
pip install --force-reinstall moonshine-voice

iOS/macOS: Package not found

Ensure Xcode is up to date
Try deleting derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
Verify internet connection (SPM needs to download)
Check minimum deployment target (iOS 14+, macOS 13+)

Android: Build errors

Verify Gradle version is 7.0+
Check minSdk is 21 or higher
Sync Gradle files
Clean and rebuild: ./gradlew clean build

Windows: Link errors

Ensure you’re building for x64 (not x86)
Verify all .lib files are in linker dependencies
Check include paths point to the include folder
Use Visual Studio 2019 or later

Linux: CMake fails

# Install build dependencies
sudo apt-get update
sudo apt-get install build-essential cmake

# Check CMake version
cmake --version  # Should be 3.15+

Raspberry Pi: Permission denied

# Audio device permissions
sudo usermod -a -G audio $USER

# Reboot
sudo reboot

Next Steps

Quickstart Guide

Start transcribing in under 2 minutes

Python API Guide

Complete API reference and examples

Examples

Platform-specific code examples

Model Selection

Choose the right model for your needs

Support

Need help with installation?

Discord Community

Get live support from the team

GitHub Issues

Report installation problems

Get Started

Core Concepts

Platform Guides

Guides

Models

​Overview

Python

iOS/macOS

Android

Windows

Linux

Raspberry Pi

​Python

​Installation

​Requirements

​Quick Test

​Import in Code

​iOS and macOS

​Swift Package Manager

​Requirements

​Example Projects

​Package.swift (for Libraries)

​Android

​Gradle Setup

​Requirements

​Example Project

​Maven Central

​Windows

​Download Library Files

​Visual Studio Project Setup

​Requirements

​Linux

​Build from Source

​Python Installation (Easier)

​Requirements

​Build Script

​Raspberry Pi

​Installation

​Using Virtual Environment (Recommended)

​Performance

​Example Projects

​Video Tutorial

​Model Installation

​Download Models

​Supported Languages

​Model Cache Location

​Available Model Architectures

​Verification

​Building from Source

​Prerequisites

​Complete Build

​Build All Platform Packages

​Language Bindings

​Troubleshooting

​Next Steps

Quickstart Guide

Python API Guide

Examples

Model Selection

​Support

Discord Community

GitHub Issues

Build docs developers (and LLMs) love

Overview

Python

Installation

Requirements

Quick Test

Import in Code

iOS and macOS

Swift Package Manager

Requirements

Example Projects

Package.swift (for Libraries)

Android

Gradle Setup

Requirements

Example Project

Maven Central

Windows

Download Library Files

Visual Studio Project Setup

Requirements

Linux

Build from Source

Python Installation (Easier)

Requirements

Build Script

Raspberry Pi

Installation

Using Virtual Environment (Recommended)

Performance

Example Projects

Video Tutorial

Model Installation

Download Models

Supported Languages

Model Cache Location

Available Model Architectures

Verification

Building from Source

Prerequisites

Complete Build

Build All Platform Packages

Language Bindings

Troubleshooting

Next Steps

Support