GitHub C++ Monthly Trending Repositories

hyprwm/Hyprland

Hyprland is an independent, highly customizable, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.

Hyprland is a 100% independent, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.

It provides the latest Wayland features, is highly customizable, has all the eyecandy, the most powerful plugins, easy IPC, much more QoL stuff than other compositors and more...

Install Quick Start Configure Contribute

Features

All of the eyecandy: gradient borders, blur, animations, shadows and much more
A lot of customization
100% independent, no wlroots, no libweston, no kwin, no mutter.
Custom bezier curves for the best animations
Powerful plugin support
Built-in plugin manager
Tearing support for better gaming performance
Easily expandable and readable codebase
Fast and active development
Not afraid to provide bleeding-edge features
Config reloaded instantly upon saving
Fully dynamic workspaces
Two built-in layouts and more available as plugins
Global keybinds passed to your apps of choice
Tiling/pseudotiling/floating/fullscreen windows
Special workspaces (scratchpads)
Window groups (tabbed mode)
Powerful window/monitor/layer rules
Socket-based IPC
Native IME and Input Panels Support
and much more...

Gallery

Special Thanks

wlroots - For powering Hyprland in the past

tinywl - For showing how 2 do stuff

Sway - For showing how 2 do stuff the overkill way

Vivarium - For showing how 2 do stuff the simple way

dwl - For showing how 2 do stuff the hacky way

Wayfire - For showing how 2 do some graphics stuff

microsoft/terminal

The new Windows Terminal and the original Windows console host, all in the same place!

Welcome to the Windows Terminal, Console and Command-Line repo

Table of Contents

This repository contains the source code for:

Windows Terminal
Windows Terminal Preview
The Windows console host (conhost.exe)
Components shared between the two projects
ColorTool
Sample projects that show how to consume the Windows Console APIs

Related repositories include:

Installing and running Windows Terminal

Note

Windows Terminal requires Windows 10 2004 (build 19041) or later

Microsoft Store [Recommended]

Install the Windows Terminal from the Microsoft Store. This allows you to always be on the latest version when we release new builds with automatic upgrades.

This is our preferred method.

Other install methods

Via GitHub

For users who are unable to install Windows Terminal from the Microsoft Store, released builds can be manually downloaded from this repository's Releases page.

Download the Microsoft.WindowsTerminal_<versionNumber>.msixbundle file from the Assets section. To install the app, you can simply double-click on the .msixbundle file, and the app installer should automatically run. If that fails for any reason, you can try the following command at a PowerShell prompt:

# NOTE: If you are using PowerShell 7+, please run
# Import-Module Appx -UseWindowsPowerShell
# before using Add-AppxPackage.

Add-AppxPackage Microsoft.WindowsTerminal_<versionNumber>.msixbundle

Note

If you install Terminal manually:

You may need to install the VC++ v14 Desktop Framework Package. This should only be necessary on older builds of Windows 10 and only if you get an error about missing framework packages.
Terminal will not auto-update when new builds are released so you will need to regularly install the latest Terminal release to receive all the latest fixes and improvements!

Via Windows Package Manager CLI (aka winget)

winget users can download and install the latest Terminal release by installing the Microsoft.WindowsTerminal package:

winget install --id Microsoft.WindowsTerminal -e

Note

Dependency support is available in WinGet version 1.6.2631 or later. To install the Terminal stable release 1.18 or later, please make sure you have the updated version of the WinGet client.

Via Chocolatey (unofficial)

Chocolatey users can download and install the latest Terminal release by installing the microsoft-windows-terminal package:

choco install microsoft-windows-terminal

To upgrade Windows Terminal using Chocolatey, run the following:

choco upgrade microsoft-windows-terminal

If you have any issues when installing/upgrading the package please go to the Windows Terminal package page and follow the Chocolatey triage process

Via Scoop (unofficial)

Scoop users can download and install the latest Terminal release by installing the windows-terminal package:

scoop bucket add extras
scoop install windows-terminal

To update Windows Terminal using Scoop, run the following:

scoop update windows-terminal

If you have any issues when installing/updating the package, please search for or report the same on the issues page of Scoop Extras bucket repository.

Installing Windows Terminal Canary

Windows Terminal Canary is a nightly build of Windows Terminal. This build has the latest code from our main branch, giving you an opportunity to try features before they make it to Windows Terminal Preview.

Windows Terminal Canary is our least stable offering, so you may discover bugs before we have had a chance to find them.

Windows Terminal Canary is available as an App Installer distribution and a Portable ZIP distribution.

The App Installer distribution supports automatic updates. Due to platform limitations, this installer only works on Windows 11.

The Portable ZIP distribution is a portable application. It will not automatically update and will not automatically check for updates. This portable ZIP distribution works on Windows 10 (19041+) and Windows 11.

Distribution	Architecture	Link
App Installer	x64, arm64, x86	Download
Portable ZIP	x64	Download
Portable ZIP	ARM64	Download
Portable ZIP	x86	Download

Learn more about the types of Windows Terminal distributions.

Terminal & Console Overview

Please take a few minutes to review the overview below before diving into the code:

Windows Terminal

Windows Terminal is a new, modern, feature-rich, productive terminal application for command-line users. It includes many of the features most frequently requested by the Windows command-line community including support for tabs, rich text, globalization, configurability, theming & styling, and more.

The Terminal will also need to meet our goals and measures to ensure it remains fast and efficient, and doesn't consume vast amounts of memory or power.

The Windows Console Host

The Windows Console host, conhost.exe, is Windows' original command-line user experience. It also hosts Windows' command-line infrastructure and the Windows Console API server, input engine, rendering engine, user preferences, etc. The console host code in this repository is the actual source from which the conhost.exe in Windows itself is built.

Since taking ownership of the Windows command-line in 2014, the team added several new features to the Console, including background transparency, line-based selection, support for ANSI / Virtual Terminal sequences, 24-bit color, a Pseudoconsole ("ConPTY"), and more.

However, because Windows Console's primary goal is to maintain backward compatibility, we have been unable to add many of the features the community (and the team) have been wanting for the last several years including tabs, unicode text, and emoji.

These limitations led us to create the new Windows Terminal.

You can read more about the evolution of the command-line in general, and the Windows command-line specifically in this accompanying series of blog posts on the Command-Line team's blog.

Shared Components

While overhauling Windows Console, we modernized its codebase considerably, cleanly separating logical entities into modules and classes, introduced some key extensibility points, replaced several old, home-grown collections and containers with safer, more efficient STL containers, and made the code simpler and safer by using Microsoft's Windows Implementation Libraries - WIL.

This overhaul resulted in several of Console's key components being available for re-use in any terminal implementation on Windows. These components include a new DirectWrite-based text layout and rendering engine, a text buffer capable of storing both UTF-16 and UTF-8, a VT parser/emitter, and more.

Creating the new Windows Terminal

When we started planning the new Windows Terminal application, we explored and evaluated several approaches and technology stacks. We ultimately decided that our goals would be best met by continuing our investment in our C++ codebase, which would allow us to reuse several of the aforementioned modernized components in both the existing Console and the new Terminal. Further, we realized that this would allow us to build much of the Terminal's core itself as a reusable UI control that others can incorporate into their own applications.

The result of this work is contained within this repo and delivered as the Windows Terminal application you can download from the Microsoft Store, or directly from this repo's releases.

Resources

For more information about Windows Terminal, you may find some of these resources useful and interesting:

Command-Line Blog
Command-Line Backgrounder Blog Series
Windows Terminal Launch: Terminal "Sizzle Video"
Windows Terminal Launch: Build 2019 Session
Run As Radio: Show 645 - Windows Terminal with Richard Turner
Azure DevOps Podcast: Episode 54 - Kayla Cinnamon and Rich Turner on DevOps on the Windows Terminal
Microsoft Ignite 2019 Session: The Modern Windows Command Line: Windows Terminal - BRK3321

FAQ

I built and ran the new Terminal, but it looks just like the old console

Cause: You're launching the incorrect solution in Visual Studio.

Solution: Make sure you're building & deploying the CascadiaPackage project in Visual Studio.

Note

OpenConsole.exe is just a locally-built conhost.exe, the classic Windows Console that hosts Windows' command-line infrastructure. OpenConsole is used by Windows Terminal to connect to and communicate with command-line applications (via ConPty).

Documentation

All project documentation is located at aka.ms/terminal-docs. If you would like to contribute to the documentation, please submit a pull request on the Windows Terminal Documentation repo.

Contributing

We are excited to work alongside you, our amazing community, to build and enhance Windows Terminal!

BEFORE you start work on a feature/fix, please read & follow our Contributor's Guide to help avoid any wasted or duplicate effort.

Communicating with the Team

The easiest way to communicate with the team is via GitHub issues.

Please file new issues, feature requests and suggestions, but DO search for similar open/closed preexisting issues before creating a new issue.

If you would like to ask a question that you feel doesn't warrant an issue (yet), please reach out to us via Twitter:

Christopher Nguyen, Product Manager: @nguyen_dows
Dustin Howett, Engineering Lead: @dhowett
Mike Griese, Senior Developer: @zadjii@mastodon.social
Carlos Zamora, Developer: @cazamor_msft
Pankaj Bhojwani, Developer
Leonard Hecker, Developer: @LeonardHecker

Developer Guidance

Prerequisites

You can configure your environment to build Terminal in one of two ways:

Using WinGet configuration file

After cloning the repository, you can use a WinGet configuration file to set up your environment. The default configuration file installs Visual Studio 2026 Community & rest of the required tools. There are two other variants of the configuration file available in the .config directory for Enterprise & Professional editions of Visual Studio 2026. To run the default configuration file, you can either double-click the file from explorer or run the following command:

winget configure .config\configuration.winget

Manual configuration

You must be running Windows 10 2004 (build >= 10.0.19041.0) or later to run Windows Terminal
You must enable Developer Mode in the Windows Settings app to locally install and run Windows Terminal
You must have PowerShell 7 or later installed
You must have the Windows 11 (10.0.26100) SDK installed at version 10.0.26100.8249 or greater.
You must have at least VS 2026 version 18.6 installed
You must install the following Workloads via the VS Installer. Note: Opening the solution will prompt you to install missing components automatically:
- Desktop Development with C++
- WinUI application development
You must install the .NET Framework 4.7.2 Targeting Pack to build test projects

Building the Code

OpenConsole.slnx may be built from within Visual Studio or from the command-line using a set of convenience scripts & tools in the /tools directory:

Building in PowerShell

Import-Module .\tools\OpenConsole.psm1
Set-MsBuildDevEnvironment
Invoke-OpenConsoleBuild

Building in Cmd

.\tools\razzle.cmd
bcz

Running & Debugging

To debug the Windows Terminal in VS, right click on CascadiaPackage (in the Solution Explorer) and go to properties. In the Debug menu, change "Application process" and "Background task process" to "Native Only".

You should then be able to build & debug the Terminal project by hitting F5. Make sure to select either the "x64" or the "x86" platform - the Terminal doesn't build for "Any Cpu" (because the Terminal is a C++ application, not a C# one).

👉 You will not be able to launch the Terminal directly by running the WindowsTerminal.exe. For more details on why, see #926, #4043

Coding Guidance

Please review these brief docs below about our coding practices.

👉 If you find something missing from these docs, feel free to contribute to any of our documentation files anywhere in the repository (or write some new ones!)

This is a work in progress as we learn what we'll need to provide people in order to be effective contributors to our project.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

moonshine-ai/moonshine

Very low latency speech to text, intent recognition, and text to speech, for building voice agents and interfaces

Moonshine Voice

Voice Interfaces for Everyone

Moonshine Voice is an open source AI toolkit for developers building real-time voice agents and applications.

Everything runs on-device, so it's fast, private, and you don't need an account, credit card, or API keys.
The framework and models are optimized for live streaming applications, offering low latency responses by doing a lot of the work while the user is still talking.
All speech to text models are based on our cutting edge research and trained from scratch, so we can offer higher accuracy than Whisper Large V3 at the top end, down to tiny 1MB models for constrained deployments.
It's easy to integrate across platforms, with the same library running on Python, iOS, Android, MacOS, Linux, Windows, Raspberry Pis, IoT devices, microcontrollers, DSPs, and wearables.
Batteries are included. Its high-level APIs offer complete solutions for common tasks like transcription, text to speech, voice cloning, speaker identification (diarization), command recognition, and conversational agents, so you can build your voice application with a single library.
It supports multiple languages, including English, Spanish, Mandarin, Japanese, Korean, Vietnamese, Ukrainian, and Arabic for STT, and English, Spanish, Arabic, German, French, Hindi, Italian, Japanese, Korean, Dutch, Portuguese, Russian, Turkish, Ukrainian, Vietnamese, and Mandarin for TTS.

Quickstart

Join our community on Discord to get live support.

Javascript

In node run npm install @moonshine-ai/moonshine-wasm, or for the web import directly from the 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();

You can see live examples running at moonshine.ai, or download the speech to text, text to speech, voice agent, dictation, or meeting note taker projects. To serve them run node serve.mjs and navigate to http://localhost:8080/.

Python

pip install moonshine-voice
moonshine-voice mic --language en

Listens to the microphone and prints updates to the transcript as they come in.

moonshine-voice agent

Runs a spoken wifi-setup conversation: it listens for a trigger phrase, asks questions, and confirms the answers. Matching is semantic, so natural language variations are recognized. For more, check out our "Getting Started" Colab notebook and video.

moonshine-voice tts --language en_us --text "Hello world"

Synthesizes and speaks the text.

iOS

First add https://github.com/moonshine-ai/moonshine-swift/ as a package dependency to your project in Xcode.

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()

Download github.com/moonshine-ai/moonshine/releases/latest/download/ios-Transcriber.tar.gz, extract it, and then open the Transcriber/Transcriber.xcodeproj project in Xcode.

Android

Add ai.moonshine:moonshine-voice:0.1.1 to your project's build.gradle.kts (or equivalent).

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();
});

Download github.com/moonshine-ai/moonshine/releases/latest/download/android-Transcriber.tar.gz, extract it, and then open the Transcriber folder in Android Studio.

Linux

Moonshine Voice ships prebuilt shared libraries for both x86_64 and arm64 Linux. The quickest way to try it is with the portable C++ example, which downloads the library, an English speech to text model, and a sample recording, then builds and runs a transcriber:

curl -O -L https://github.com/moonshine-ai/moonshine/releases/download/v0.1.1/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

MacOS

First add https://github.com/moonshine-ai/moonshine-swift/ as a package dependency to your project in Xcode.

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()

This code is identical to the iOS version.

Download github.com/moonshine-ai/moonshine/releases/latest/download/macos-MicTranscription.tar.gz, extract it, and then open the MicTranscription/MicTranscription.xcodeproj project in Xcode.

Windows

Download github.com/moonshine-ai/moonshine/releases/latest/download/windows-cli-transcriber.tar.gz, extract it, and then open the cli-transcriber\cli-transcriber.vcxproj project in Visual Studio.

It's a self-contained archive that includes the library and model, so Ctrl+Shift+B or F7 will build the executable.

Raspberry Pi

You'll need a USB microphone plugged in to get audio input, but the Python pip package has been optimized for the Pi, so you can run:

 sudo pip install --break-system-packages moonshine-voice
 moonshine-voice mic --language en

I've recorded a screencast on YouTube to help you get started, and you can also download github.com/moonshine-ai/moonshine/releases/latest/download/raspberry-pi-my-dalek.tar.gz for some fun, Pi-specific examples. The README has information about using a virtual environment for the Python install if you don't want to use --break-system-packages.

You can look at github.com/moonshine-ai/pi-help-bot for a more advanced example.

More examples

Example apps for the web, iOS, Android, macOS, Windows, and Raspberry Pi are published on GitHub Releases as separate archives (mostly {platform}-{Project}.tar.gz, matching folder names under examples/; Windows also ships moonshine-voice-windows-x86_64.tar.gz for the C++ sample). See the Examples section for the full list of release downloads.

When should you choose Moonshine over Whisper?

TL;DR - When you're working with live speech.

Model	WER	# Parameters	MacBook Pro	Linux x86	R. Pi 5	Pixel 10a	iPad (A16)
Moonshine Medium Streaming	6.65%	245 million	74ms	269ms	802ms	916ms	181ms
Whisper Large v3	7.44%	1.5 billion	11,286ms	16,919ms	N/A	—	—
Moonshine Small Streaming	7.84%	123 million	49ms	165ms	527ms	394ms	99ms
Whisper Small	8.59%	244 million	1940ms	3,425ms	10,397ms	—	—
Moonshine Tiny Streaming	12.00%	34 million	32ms	69ms	237ms	114ms	39ms
Whisper Tiny	12.81%	39 million	277ms	1,141ms	5,863ms	—	—

See benchmarks for how these numbers were measured.

OpenAI's release of their Whisper family of models was a massive step forward for open-source speech to text. They offered a range of sizes, allowing developers to trade off compute and storage space against accuracy to fit their applications. Their biggest models, like Large v3, also gave accuracy scores that were higher than anything available outside of large tech companies like Google or Apple. At Moonshine we were early and enthusiastic adopters of Whisper, and we still remain big fans of the models and the great frameworks like FasterWhisper and others that have been built around them.

However, as we built applications that needed a live voice interface we found we needed features that weren't available through Whisper:

Whisper always operates on a 30-second input window. This isn't an issue when you're processing audio in large batches, you can usually just look ahead in the file and find a 30-second-ish chunk of speech to apply it to. Voice interfaces can't look ahead to create larger chunks from their input stream, and phrases are seldom longer than five to ten seconds. This means there's a lot of wasted computation encoding zero padding in the encoder and decoder, which means longer latency in returning results. Since one of the most important requirements for any interface is responsiveness, usually defined as latency below 200ms, this hurts the user experience even on platforms that have compute to spare, and makes it unusable on more constrained devices.
Whisper doesn't cache anything. Another common requirement for voice interfaces is that they display feedback as the user is talking, so that they know the app is listening and understanding them. This means calling the speech to text model repeatedly over time as a sentence is spoken. Most of the audio input is the same, with only a short addition to the end. Even though a lot of the input is constant, Whisper starts from scratch every time, doing a lot of redundant work on audio that it has seen before. Like the fixed input window, this unnecessary latency impairs the user experience.
Whisper supports a lot of languages poorly. Whisper's multilingual support is an incredible feat of engineering, and demonstrated a single model could handle many languages, and even offer translations. This chart from OpenAI (raw data in Appendix D-2.4) shows the drop-off in Word Error Rate (WER) with the very largest 1.5 billion parameter model.

82 languages are listed, but only 33 have sub-20% WER (what we consider usable). For the Base model size commonly used on edge devices, only 5 languages are under 20% WER. Asian languages like Korean and Japanese stand out as the native tongue of large markets with a lot of tech innovation, but Whisper doesn't offer good enough accuracy to use in most applications The proprietary in-house versions of Whisper that are available through OpenAI's cloud API seem to offer better accuracy, but aren't available as open models.

Fragmented edge support. A fantastic ecosystem has grown up around Whisper, there are a lot of mature frameworks you can use to deploy the models. However these often tend to be focused on desktop-class machines and operating systems. There are projects you can use across edge platforms like iOS, Android, or Raspberry Pi OS, but they tend to have different interfaces, capabilities, and levels of optimization. This made building applications that need to run on a variety of devices unnecessarily difficult.

All these limitations drove us to create our own family of models that better meet the needs of live voice interfaces. It took us some time since the combined size of the open speech datasets available is tiny compared to the amount of web-derived text data, but after extensive data-gathering work, we were able to release the first generation of Moonshine models. These removed the fixed-input window limitation along with some other architectural improvements, and gave significantly lower latency than Whisper in live speech applications, often running 5x faster or more.

However we kept encountering applications that needed even lower latencies on even more constrained platforms. We also wanted to offer higher accuracy than the Base-equivalent that was the top end of the initial models. That led us to this second generation of Moonshine models, which offer:

Flexible input windows. You can supply any length of audio (though we recommend staying below around 30 seconds) and the model will only spend compute on that input, no zero-padding required. This gives us a significant latency boost.
Caching for streaming. Our models now support incremental addition of audio over time, and they cache the input encoding and part of the decoder's state so that we're able to skip even more of the compute, driving latency down dramatically.
Language-specific models. We have gathered data and trained models for multiple languages, including Arabic, Japanese, Korean, Spanish, Ukrainian, Vietnamese, and Chinese. As we discuss in our Flavors of Moonshine paper, we've found that we can get much higher accuracy for the same size and compute if we restrict a model to focus on just one language, compared to training one model across many.
Cross-platform library support. We're building applications ourselves, and needed to be able to deploy these models across Linux, MacOS, Windows, iOS, and Android, as well as use them from languages like Python, Swift, Java, and C++. To support this we architected a portable C++ core library that handles all of the processing, uses OnnxRuntime for good performance across systems, and then built native interfaces for all the required high-level languages. This allows developers to learn one API, and then deploy it almost anywhere they want to run.
Better accuracy than Whisper V3 Large. On HuggingFace's OpenASR leaderboard, our newest streaming model for English, Medium Streaming, achieves a lower word-error rate than the most-accurate Whisper model from OpenAI. This is despite Moonshine's version using 250 million parameters, versus Large v3's 1.5 billion, making it much easier to deploy on the edge.

Hopefully this gives you a good idea of how Moonshine compares to Whisper. If you're working with GPUs in the cloud on data in bulk where throughput is most important then Whisper (or Nvidia alternatives like Parakeet) offer advantages like batch processing, but we believe we can't be beat for live speech. We've built the framework and models we wished we'd had when we first started building applications with voice interfaces, so if you're working with live voice inputs, give Moonshine a try.

Using the Library

The Moonshine API is designed to take care of the details around capturing and transcribing live speech, giving application developers a high-level API focused on actionable events. I'll use Python to illustrate how it works, but the API is consistent across all the supported languages.

Architecture

Our goal is to build a framework that any developer can pick up and use, even with no previous experience of speech technologies. We've abstracted away a lot of the unnecessary details and provide a simple interface that lets you focus on building your application, and that's reflected in our system architecture.

The basic flow is:

Create a Transcriber object if you want the text that's spoken, or an AgentFlow if you only need to know that a user has requested an action.
Attach an EventListener that gets called when important things occur, like the end of a phrase or an action being triggered, so your application can respond.
Use a TextToSpeech object to make it a two-way conversation.

Traditionally, adding a voice interface to an application or product required integrating a lot of different libraries to handle all the processing that's needed to capture audio and turn it into something actionable. The main steps involved are microphone capture, voice activity detection (to break a continuous stream of audio into sections of speech), speech to text, speaker identification, and phrase matching. Each of these steps typically involved a different framework, which greatly increased the complexity of integrating, optimizing, and maintaining these dependencies.

Moonshine Voice includes all of these stages in a single library, and abstracts away everything but the essential information your application needs to respond to user speech, whether you want to transcribe it or trigger actions.

Most developers should be able to treat the library as a black box that tells them when something interesting has happened, using our event-based classes to implement application logic. Of course the framework is fully open source, so speech experts can dive as deep under the hood as they'd like, but it's not necessary to use it.

Concepts

A Transcriber takes in audio input and turns any speech into text. This is the first object you'll need to create to use Moonshine, and you'll give it a path to the models you've downloaded.

A MicTranscriber is a helper class based on the general transcriber that takes care of connecting to a microphone using your platform's built-in support (for example sounddevice in Python) and then feeding the audio in as it's captured.

A Stream is a handler for audio input. The reason streams exist is because you may want to process multiple audio inputs at once, and a transcriber can support those through multiple streams, without duplicating the model resources. If you only have one input, the transcriber class includes the same methods (start/stop/add_audio) as a stream, and you can use that interface instead and forget about streams.

A TranscriptLine is a data structure holding information about one line in the transcript. When someone is speaking, the library waits for short pauses (where punctuation might go in written language) and starts a new line. These aren't exactly sentences, since a speech pause isn't a sure sign of the end of a sentence, but this does break the spoken audio into segments that can be considered phrases. A line includes state such as whether the line has just started, is still being spoken, or is complete, along with its start time and duration.

A Transcript is a list of lines in time order holding information about what text has already been recognized, along with other state like when it was captured.

A TranscriptEvent contains information about changes to the transcript. Events include a new line being started, the text in a line being updated, and a line being completed. The event object includes the transcript line it's referring to as a member, holding the latest state of that line.

A TranscriptEventListener is a protocol that allows app-defined functions to be called when transcript events happen. This is the main way that most applications interact with the results of the transcription. When live speech is happening, applications usually need to respond or display results as new speech is recognized, and this approach allows you to handle those changes in a similar way to events from traditional user interfaces like touch screen gestures or mouse clicks on buttons.

A TextToSpeech object synthesizes audio for playback to the user.

An AgentFlow object manages conversations between the user and an agent. It opens the transcriber, microphone, and speech synthesizer it needs itself, and invokes a callback whenever someone says something close in meaning to a phrase you registered — the basis of voice command recognition.

A Dialog object is created for each conversational exchange, and allows the agent to hold a multi-step discussion with the user.

Getting Started with Transcription

We have examples for most platforms so as a first step I recommend checking out what we have for the systems you're targeting.

Next, you'll need to add the library to your project. We aim to provide pre-built binaries for all major platforms using their native package managers. On Python this means a pip install, for Android it's a Maven package, and for MacOS and iOS we provide a Swift package through SPM.

The transcriber needs access to the files for the model you're using, so after downloading them you'll need to place them somewhere the application can find them, and make a note of the path. This usually means adding them as resources in your IDE if you're planning to distribute the app, or you can use hard-wired paths if you're just experimenting. The download script gives you the location of the models and their architecture type on your drive after it completes.

Now you can try creating a transcriber. Here's what that looks like in Python:

transcriber = Transcriber(model_path=model_path, model_arch=model_arch)

If the model isn't found, or if there's any other error, this will throw an exception with information about the problem. You can also check the console for logs from the core library, these are printed to stderr or your system's equivalent.

Now we'll create a listener that contains the app logic that you want triggered when the transcript updates, and attach it to your transcriber:

class TestListener(TranscriptEventListener):
    def on_line_started(self, event):
        print(f"Line started: {event.line.text}")

    def on_line_text_changed(self, event):
        print(f"Line text changed: {event.line.text}")

    def on_line_completed(self, event):
        print(f"Line completed: {event.line.text}")

listener = TestListener()
transcriber.add_listener(listener)

The transcriber needs some audio data to work with. If you want to try it with the microphone you can update your transcriber creation line to use a MicTranscriber instead, but if you want to start with a .wav file for testing purposes here's how you feed that in:

    audio_data, sample_rate = load_wav_file(wav_path)

    transcriber.start()

    # Loop through the audio data in chunks to simulate live streaming
    # from a microphone or other source.
    chunk_duration = 0.1
    chunk_size = int(chunk_duration * sample_rate)
    for i in range(0, len(audio_data), chunk_size):
        chunk = audio_data[i: i + chunk_size]
        transcriber.add_audio(chunk, sample_rate)

    transcriber.stop()

The important things to notice here are:

We create an array of mono audio data from a wav file, using the convenience load_wav_file() function that's part of the Moonshine library.
We start the transcriber to activate its processing code.
The loop adds audio in chunks. These chunks can be any length and any sample rate, the library takes care of all the housekeeping.
As audio is added, the event listener you added will be called, giving information about the latest speech.

In a real application you'd be calling add_audio() from an audio handler that's receiving it from your source. Since the library can handle arbitrary durations and sample rates, just make sure it's mono and otherwise feed it in as-is.

The transcriber analyses the speech at a default interval of every 500ms of input. You can change this with the update_interval argument to the transcriber constructor. For streaming models most of the work is done as the audio is being added, and it's automatically done at the end of a phrase, so changing this won't usually affect the workload or latency massively.

The interval is a floor rather than a fixed cadence. A pass has to cover at least as much audio as the last one took to make, up to ten intervals' worth, so a machine that cannot keep up transcribes in larger batches instead of falling further behind with every pass. Where there is processing time to spare this makes no difference and the interval governs as before.

The key takeaway is that you usually don't need to worry about the transcript data structure itself, the event system tells you when something important happens. You can manually trigger a transcript update by calling update_transcription() which returns a transcript object with all of the information about the current session if you do need to examine the state.

By calling start() and stop() on a transcriber (or stream) we're beginning and ending a session. Each session has one transcript document associated with it, and it is started fresh on every start() call, so you should make copies of any data you need from the transcript object before that.

The transcriber class also offers a simpler transcribe_without_streaming() method, for when you have an array of data from the past that you just want to analyse, such as a file or recording.

We also offer a specialization of the base Transcriber class called MicTranscriber. How this is implemented will depend on the language and platform, but it should provide a transcriber that's automatically attached to the main microphone on the system. This makes it straightforward to start transcribing speech from that common source, since it supports all of the same listener callbacks as the base class.

Transcription Event Flow

The main communication channel between the library and your application is through events that are passed to any listener functions you have registered. There are five major event types:

LineStarted. This is sent to listeners when the beginning of a new speech segment is detected. It may or may not contain any text, but since it's dispatched near the start of an utterance, that text is likely to change over time.
LineUpdated. Called whenever any of the information about a line changes, including the duration, audio data, and text.
LineTextChanged. Called only when the text associated with a line is updated. This is a subset of LineUpdated that focuses on the common need to refresh the text shown to users as often as possible to keep the experience interactive.
LineSpeakersChanged. Only fired when the opt-in identify_speakers option is enabled. Called when the speaker spans attached to a line change. Unlike the other line events, this can fire for lines that are already complete, because the diarization algorithm keeps refining its speaker assignments as more audio arrives.
LineCompleted. Sent when we detect that someone has paused speaking, and we've ended the current segment. The line data structure has the final values for the text and duration.

We offer some guarantees about these events:

LineStarted is always called exactly once for any segment.
LineCompleted is always called exactly once after LineStarted for any segment.
LineUpdated and LineTextChanged will only ever be called after the LineStarted and before the LineCompleted events for a segment.
Those update events are not guaranteed to be called (and in practice can be disabled by setting update_interval to a very large value).
There will only be one line active at any one time for any given stream.
Once LineCompleted has been called, the library will never alter that line's text, timing, or audio data again. The one exception is the line's speaker spans: when identify_speakers is enabled, those can be revised for recent audio (signaled by LineSpeakersChanged), since diarization re-clusters a sliding window of recent speech. Assignments for audio older than diarization_cluster_window_sec are frozen.
If stop() is called on a transcriber or stream, any active lines will have LineCompleted called.
Each line has a 64-bit lineId that is designed to be unique enough to avoid collisions.
This lineId remains the same for the line over time, from the first LineStarted event onwards.

Getting Started with a Conversational Agent

Many applications need a voice agent that can understand what users are saying and respond appropriately. To make this as straightforward as possible, we let you define different conversational flows. A flow can be as simple as responding to a query, or be a multi-step, branching conversation that takes actions.

To define these flows, you use an AgentFlow object, with callbacks that take Dialog arguments. Here's an example of a simple flow, taken from the github.com/moonshine-ai/pi-help-bot sample code:

    def report_ip_address(d: Dialog):
        ip = _find_local_ip()
        if ip is None:
            yield d.say("Sorry, I couldn't find a local IP address.")
            return
        speech_ip = re.sub(r"(\d)", r"\1 ", ip.replace(".", " dot "))
        yield d.say([
            f"Okay. Your local IP address is {speech_ip}. ",
            f"To repeat, that's {speech_ip}."
        ])

    agent_flow.listen_for("What is my IP address?", report_ip_address)

This registers the report_ip_address() function to be called whenever the user says anything similar to "What is my IP address?". The matching is done semantically, so alternative phrasings like "Tell me your IP address" or "Can you tell me the local IP address?" should trigger it too. You can register as many top-level conversation starters as you'd like, the system will listen out and route to the closest in meaning.

The function itself receives a Dialog argument that represents the current conversational exchange. In this simple case we don't need any additional input from the user so we just use it to say() the information that was requested. We break the IP address into separate words for each digit for clarity, and replace the connecting periods with explicit "dot"s, so that 192.178.4.72 becomes "1 9 2 dot 1 7 8 dot 4 dot 72", since that's the conventional way to articulate them in speech.

For more complex conversations, like setting up a new wifi network, you can define multiple steps and branch points directly in Python:

    def connect_to_wifi(d: Dialog):
        input_ssid = yield d.ask("What's the name of your Wi-Fi network? Say list if you want to pick from a list or spell if you want to spell out the start of the name")
        input_ssid = input_ssid.strip()

        networks = _scan_wifi_networks()

        if input_ssid.lower().strip(string.punctuation) == "list":
            yield d.say("Say yes to the network you want to connect to.")
            for network in networks:
                if (yield d.confirm(f"{network}?")):
                    input_ssid = network
                    break
        elif input_ssid.lower().strip(string.punctuation) == "spell":
            input_ssid = yield d.ask("Spell out the start of the network name.", mode=SPELLED)

        found_ssid = fuzzy_match_network(input_ssid, networks)
        if found_ssid is None:
            yield d.say(f"Sorry, I couldn't find a matching network for {input_ssid}.")
            return

        password = yield d.ask(
            f"Please spell the Wi-Fi password for {found_ssid} one character at a time, and say done when finished.",
            mode=SPELLED,
        )

        yield d.say(f"Connecting to {found_ssid}.")

        try:
            result = subprocess.run(
                ["sudo", "nmcli", "device", "wifi",
                    "connect", found_ssid, "password", password],
                capture_output=True, text=True, timeout=30,
            )
        except FileNotFoundError:
            yield d.say("Sorry, network manager was not found on this system.")
            return
        except subprocess.TimeoutExpired:
            yield d.say("Sorry, the connection attempt timed out.")
            return

        if result.returncode == 0:
            yield d.say(f"Connected to {found_ssid}.")
        else:
            print(f"[ERROR] nmcli stderr: {result.stderr}", file=sys.stderr)
            yield d.say(
                f"Sorry, I wasn't able to connect to {found_ssid}. "
                "Please check the network name and password and try again."
            )

    agent_flow.listen_for("Connect to Wi-Fi", connect_to_wifi)

The first thing the function does is ask the user to give them the name of the network they want to join, through the call:

input_ssid = yield d.ask("What's the name of your Wi-Fi network?...")

The Dialog class lets you ask users questions and will return the string containing the what they said in response. The only unusual feature here, compared to regular Python code, is the yield keyword. Because it may take some time for the user to respond, we call yield to hand back control to the main script until their response has been received. This is a general pattern for AgentFlow and you'll see it wherever we're waiting for the user to say something, to avoid blocking.

        if input_ssid.lower().strip(string.punctuation) == "list":
            yield d.say("Say yes to the network you want to connect to.")
            for network in networks:
                if (yield d.confirm(f"{network}?")):
                    input_ssid = network
                    break

Our example application supports a few different input methods - running through a list of networks, spelling out the first few letters, or saying the name. Here we implement the list approach by looping through all the available networks and asking the user whether each is the one they want. Here you can see that regular loops and conditional statements work as you'd expect in Python.

For each network, we call confirm(), which asks a question and then waits for a positive or negative result. Like all matching in the system this is done semantically, so "okay", "affirmative", and "go ahead" will work as well as a straightforward "yes".

        password = yield d.ask(
            f"Please spell the Wi-Fi password for {found_ssid} one character at a time, and say done when finished.",
            mode=SPELLED,
        )

Password input is tricky, because they consist of arbitrary letters, digits, and symbols, and so they have to be spelled out by the user. Moonshine supports this through the mode=SPELLED argument. This asks the user to spell out each character, and uses a fine-tuned model to recognise what the user is saying for each. As well as supporting regular utterances like "aitch" or "capital zee", it also supports the NATO alphabet ("alpha", "bravo", etc) and even short descriptive phrases like "E as in elephant". It repeats back what it heard, and lets you delete mistakes.

        try:
            result = subprocess.run(
                ["sudo", "nmcli", "device", "wifi",
                    "connect", found_ssid, "password", password],
                capture_output=True, text=True, timeout=30,
            )
        except FileNotFoundError:
            yield d.say("Sorry, network manager was not found on this system.")
            return
        except subprocess.TimeoutExpired:
            yield d.say("Sorry, the connection attempt timed out.")
            return

The flow also works with other control structures like exception handlers, so you can specify your conversations using idiomatic code, even for error recovery.

Agent Setup

Once your flows are written, the only setup left is to register them and go live. AgentFlow opens everything it needs itself — the speech recognition model, the microphone, and the speech synthesizer — so there's nothing to wire together:

    agent_flow = (
        AgentFlow()
        .language("en")
        .listen_for("What is my IP address?", report_ip_address)
        .listen_for("Connect to Wi-Fi", connect_to_wifi)
    )

    agent_flow.start_listening()

Every configuration method returns the runner, so a whole voice interface can be built in a single expression, and each one has a working default. listen_for() registers the conversation starters. "Cancel" and "start over" need no registration: they work at any point inside a flow, and outside one they're treated as ordinary speech so a dictation interface doesn't lose them. Use always() to register a phrase of your own that stays live at every moment, whether or not a flow is running.

start_listening() opens and downloads whatever is missing on first use (the embedding model used for matching, the speech to text model for your language, and a synthesizer), then returns as soon as the microphone is live. Speech arrives on the audio thread and drives your flows from there, so your own code is free to sleep, run a UI, or do anything else. If you want the loading to happen at a moment of your choosing rather than on the first start_listening() call, call load() yourself beforehand and pass on_progress() a callback to report download progress. Call close() when you're finished to release everything the runner opened.

To give this a try for yourself, run this built-in example:

python -m moonshine_voice.agent_flow

Getting Started with Text to Speech

Voice interfaces often need to talk back, and Moonshine's TextToSpeech is designed to make that easy, across multiple languages. It's also self-contained, so you can use it independently from the transcription and agent modules.

You configure a synthesizer with chainable setters, call load() to fetch and open the voice, and then pass text into say() to speak it on the default audio device:

from moonshine_voice import TextToSpeech

tts = TextToSpeech().language("fr")
tts.load()
tts.say("Bonjour, mon ami")
tts.wait()  # block until playback finishes

load() blocks, since the first call may have to download a voice. Pass on_progress() a handler to drive a progress bar:

tts = TextToSpeech().language("fr").on_progress(lambda fraction, file: print(f"{fraction:.0%}"))
tts.load()

say() returns immediately and queues the text for background synthesis and playback. Calling say() multiple times queues each utterance in order, and the next utterance is pre-synthesized while the current one plays. You can also pass a list of strings, cancel everything with stop(), or poll with is_talking():

tts.say(["One.", "Two.", "Three."])
tts.stop()  # cancel remaining utterances and halt playback

If you're on a machine without an audio output, or want to do further processing, you can retrieve the audio samples using the synthesize() method:

from moonshine_voice import TextToSpeech

tts = TextToSpeech().language("en-us")
tts.load()
audio_data, sample_rate = tts.synthesize("Howdy, partner")

As you can see, text to speech supports multiple languages. To see which are available, run the list_tts_languages() function:

from moonshine_voice import list_tts_languages
list_tts_languages()

['ar-msa', 'de-de', 'en-gb', 'en-us', 'es-ar', 'es-es', 'es-mx', 'fr-fr', 'hi-in', 'it-it', 'ja-jp', 'ko-kr', 'nl-nl', 'pt-br', 'pt-pt', 'ru-ru', 'tr-tr', 'uk-ua', 'vi-vn', 'zh-hans']

For each language, you can list which voices are available:

from moonshine_voice import list_tts_voices

list_tts_voices("ru")

{'present': [], 'downloadable': ['piper_ru_RU-denis-medium', 'piper_ru_RU-dmitri-medium', 'piper_ru_RU-irina-medium', 'piper_ru_RU-ruslan-medium']}

If a voice is marked as downloadable that means if you pass it to voice() then Moonshine will download it to a cache automatically, and it will be available on your machine with no internet access required for subsequent calls.

Voice Cloning

The integrated ZipVoice model can imitate someone's voice, given a short audio clip. Pass the clip to clone_from(), either as a path to a .wav file or as a (pcm, sample_rate) pair of mono float samples. You can also pass transcript, the text spoken in the clip; when omitted, Moonshine auto-transcribes the clip with its ASR model before cloning (this takes a few extra seconds on first use):

from moonshine_voice import TextToSpeech
import importlib.resources;

clone_path = importlib.resources.files("moonshine_voice.assets").joinpath("clone-test.wav")
clone_transcript = "Ever tried. Ever failed. No matter. Try Again. Fail again. Fail better."

tts = TextToSpeech().language("en-us").cloning()
tts.load()
tts.clone_from(clone_path, transcript=clone_transcript)
tts.say("Ask not what your country can do for you, but what you can do for your country")
tts.wait()

cloning() tells load() to fetch ZipVoice and its clone-ASR assets up front, so clone_from() only swaps the reference clip. Call cloning() before load() — without it, clone_from() / start_cloning() raise a clear error. Catalog voices and cloning are mutually exclusive: voice() clears cloning, and cloning() clears the catalog voice.

To clone from someone speaking into the microphone rather than from a file, start_cloning() hands back a VoiceClone that listens until it has heard enough usable speech:

clone = tts.start_cloning()
clone.on_ready(lambda: print("Got it, you can stop talking."))
clone.from_microphone()
tts.clone_from(clone)

Picking the clip out of the recording runs Moonshine's built-in voice-activity detector, which is compiled into the library, so nothing is downloaded for this step. from_microphone() blocks until the clip is ready or 20 seconds have passed; on_progress() reports how long it has been recording and how much speech it has found so far.

You can also try cloning from the command line. Since you won't always have easy access to a clean transcript of the speech you want to clone from, you can leave it out and have Moonshine automatically generate one, in both the API and command line.

curl -O -L 'https://github.com/moonshine-ai/moonshine/raw/refs/heads/main/language-bindings/python/src/moonshine_voice/assets/clone-test.wav'

python3 -m moonshine_voice.tts \
  --clone clone-test.wav \
  --text "I am so excited about Moonshine Voice's text to speech"

Voice Samples

To help you choose a voice, here are sample clips of each one saying "Welcome to Moonshine Voice text to speech". Each entry is the voice name you can pass to voice(); click the ▶ next to it to hear it.

ZipVoice

These voices were created using the zero-shot voice cloning capabilities of ZipVoice, a high-quality flow-matching TTS model from the k2-fsa team. It takes significantly longer to generate than Kokoro or PiperTTS, but offers voice cloning and more realistic speech.


`zipvoice_american_female` ▶	`zipvoice_american_male` ▶	`zipvoice_australian_male` ▶
`zipvoice_canadian_female` ▶	`zipvoice_canadian_male` ▶	`zipvoice_english_female` ▶
`zipvoice_english_male` ▶	`zipvoice_indian_female` ▶	`zipvoice_indian_male` ▶
`zipvoice_irish_female` ▶	`zipvoice_irish_male` ▶	`zipvoice_new_zealand_female` ▶
`zipvoice_northern_irish_female` ▶	`zipvoice_south_african_female` ▶	`zipvoice_south_african_male` ▶

Kokoro

These voices come from the excellent Kokoro project, an 82-million-parameter open-weight TTS model that delivers quality comparable to much larger models.

American Female	American Male	British Female	British Male
`kokoro_af_alloy` ▶	`kokoro_am_adam` ▶	`kokoro_bf_alice` ▶	`kokoro_bm_daniel` ▶
`kokoro_af_aoede` ▶	`kokoro_am_echo` ▶	`kokoro_bf_emma` ▶	`kokoro_bm_fable` ▶
`kokoro_af_bella` ▶	`kokoro_am_eric` ▶	`kokoro_bf_isabella` ▶	`kokoro_bm_george` ▶
`kokoro_af_heart` ▶	`kokoro_am_fenrir` ▶	`kokoro_bf_lily` ▶	`kokoro_bm_lewis` ▶
`kokoro_af_jessica` ▶	`kokoro_am_liam` ▶
`kokoro_af_kore` ▶	`kokoro_am_michael` ▶
`kokoro_af_nicole` ▶	`kokoro_am_onyx` ▶
`kokoro_af_nova` ▶	`kokoro_am_puck` ▶
`kokoro_af_river` ▶	`kokoro_am_santa` ▶
`kokoro_af_sarah` ▶
`kokoro_af_sky` ▶

Piper TTS

The Piper project provides over a hundred lightweight voices across all of the languages Moonshine supports, from many contributors — too many to sample here. You can listen to every Piper voice on the Piper voice samples page, and use any of them with Moonshine through the piper_ voice names returned by list_tts_voices().

Converting Graphemes to Phonemes

As you may notice from the voice names, Moonshine Voice uses models from the fantastic Kokoro and PiperTTS projects. You can find full details on all the model and data sources we use for text to speech at core/moonshine-tts/data/README.md.

Given that there are other great TTS projects out there, why does the world need yet another implementation? Moonshine tries to run on as many platforms as possible and supports commercial applications, and both Kokoro and Piper use espeak-ng to convert text strings into phonemes, representations of the noises associated with the sentence, in the International Pronunciation Alphabet. Espeak-ng is licensed under the GPL, and while I am a fan of free software, the terms do make it hard to incorporate into applications that don't also release their source code under a similar license.

In the cloud this isn't as much of an issue, as many uses of espeak-ng can be implemented by calling out to an external executable, so the dependency isn't as problematic. This isn't an option on many edge operating systems unfortunately, as the only way to include code on iOS or Android is to link it into the application, which requires open sourcing the calling code.

To allow wider usage, we developed our own "grapheme to phoneme" module that performs a similar role, but has been written from scratch. You'll find the implementation in core/moonshine-tts and it's released under the same MIT License as the rest of this code base.

Every language requires a different process to convert its written form into speech, and often it varies by dialect too. This is why espeak-ng is so widely used, it has had years of work put into it to encode linguistic knowledge into a complex set of rules, many of which are heuristics that require a lot of testing to get right. The Moonshine Voice G2P engine is still new, and will need similar tuning to handle all of the variations across languages, but I'm hoping the initial implementation is a good start and will benefit from community feedback and contributions over time. Here are the current results for intelligibility across languages, using scripts/tts_g2p_intelligibility.py:

Language	Moonshine CER	Reference CER
ar_msa	20.8%	15.3%
de_de	18.3%	9.2%
en_us	12.6%	9.8%
es_ar	7.9%	10.6%
es_es	4.2%	4.5%
es_mx	3.2%	2.6%
fr_fr	14.8%	9.4%
hi_in	26.5%	15.9%
it_it	24.2%	11.4%
ja_jp	38.1%	16.8%
ko_kr	25.0%	18.6%
nl_nl	15.9%	3.3%
pt_br	19.7%	4.9%
pt_pt	43.8%	24.6%
ru_ru	16.9%	5.0%
tr_tr	8.9%	7.9%
uk_ua	27.7%	15.6%
vi_vn	79.0%	36.5%
zh_hans	37.8%	32.6%

If you want access to just the grapheme to phoneme capability, without the speech synthesis, you can all it directly:

from moonshine_voice import GraphemeToPhonemizer

g2p = GraphemeToPhonemizer("en-us")
g2p.to_ipa("Hello world")

'həlˈoʊ wˈɝld'

Examples

The examples folder has code samples organized by platform. We use the usual tooling per stack (Android Studio and Gradle, Xcode and Swift on Apple platforms, Visual Studio on Windows). GitHub Releases currently ship the downloadable assets below (example trees are mostly named {platform}-{Project}.tar.gz; Windows and C++ also include prebuilt native library bundles).

Android
Portable C++
- cpp-examples.tar.gz (sources plus the download-library.sh helper)
- transcriber.cpp
- text-to-speech.cpp
iOS
MacOS
Windows
- cli-transcriber
Python
Raspberry Pi
- my-dalek
- Pi Help Bot
Web (self-contained archives: node serve.mjs, then open the demo path)
- stt
- tts
- agent-flow
- dictation
- meeting-notes

The examples usually include one minimal project that just creates a transcriber and then feeds it data from a WAV file, and another that's pulling audio from a microphone using the platform's default framework for accessing audio devices. Each one is a self-contained project you can copy out of the tree: the Android samples depend on ai.moonshine:moonshine-voice:0.1.1 from Maven Central, and the Apple ones pull MoonshineVoice from the Swift package.

None of them bundle model weights. Every engine downloads what it needs on first use — the speech model for Transcriber, the voice and G2P assets for TextToSpeech, all three plus the embedding model for AgentFlow — from https://download.moonshine.ai/, reporting progress through the onProgress callback the examples wire up to a label. Downloads are cached (under filesDir on Android, Caches/MoonshineModels on Apple platforms), so later launches run offline. Switching to a different voice triggers the same on-demand download for whatever that voice needs.

If you want a fully offline build with no first-run download, fetch the assets ahead of time and point the engine at them with modelsFrom(path); see docs/design/api-comparison.md for the tradeoff.

Adding the Library to your own App

We distribute the library through the most widely-used package managers for each platform. Here's how you can use these to add the framework to an existing project on different systems.

Python

The Python package is hosted on PyPi, so all you should need to do to install it is pip install moonshine-voice, and then import moonshine_voice in your project.

Command-line tools

Installing the pip package adds a moonshine-voice command (with a shorter moonshine alias) that groups the built-in tools as subcommands. These are designed for one-off use cases, if you need multiple Moonshine calls for the same task then loading the models once from Python will be more efficient.

moonshine-voice --help

Command	Description
`moonshine-voice mic`	Transcribe live microphone input to the terminal.
`moonshine-voice transcribe`	Transcribe a WAV file (optionally with speaker IDs / word timestamps).
`moonshine-voice tts`	Synthesize speech from text to a WAV file or audio device.
`moonshine-voice agent`	Run a spoken agent flow (wifi setup) from the microphone.
`moonshine-voice download`	Download STT, TTS, G2P, or embedding model assets.
`moonshine-voice g2p`	Convert text to phonemes (IPA).

Run moonshine-voice <command> --help for the options each one accepts. Every subcommand is equivalent to running the underlying module directly, so moonshine-voice mic --language en and python -m moonshine_voice.mic_transcriber --language en do exactly the same thing.

iOS or MacOS

For iOS we use the Swift Package Manager, with an auto-updated GitHub repository holding each version. To use this right-click on the file view sidebar in Xcode and choose "Add Package Dependencies..." from the menu. A dialog should open up, paste https://github.com/moonshine-ai/moonshine-swift/ into the top search box and you should see moonshine-swift. Select it and choose "Add Package", and it should be added to your project. You should now be able to import MoonshineVoice and use the library. You will need to add any model files you use to your app bundle and ensure they're copied during the deployment phase, so they can be accessed on-device.

For reference purposes you can find Xcode projects with these changes applied in examples/ios/Transcriber and examples/macos/BasicTranscription.

Android

On Android we publish the package to Maven. To include it in your project using Android Studio and Gradle, first add the version number you want to the gradle/libs.versions.toml file by inserting a line in the [versions] section, for example moonshineVoice = "0.1.1". Then in the [libraries] part, add a reference to the package: moonshine-voice = { group = "ai.moonshine", name = "moonshine-voice", version.ref = "moonshineVoice" }.

Finally, in your app/build.gradle.kts add the library to the dependencies list: implementation(libs.moonshine.voice). The examples/android/Transcriber and examples/android/TextToSpeech samples use the same coordinates (moonshineVoice = "0.1.1" in their catalogs).

Windows/C++

We couldn't find a single package manager that is used by most Windows developers, so instead we've made the raw library and headers available as a download. The script in examples/windows/cli-transcriber/download-lib.bat will fetch these for you. You'll see an include folder that you should add to the include search paths in your project settings, and a lib directory that you should add to the include search paths. Then add all of the library files in the lib folder to your project's linker dependencies.

The recommended interface to use on Windows is the C++ language binding. This is a header-only library that offers a higher-level API than the underlying C version. You can #include "moonshine-cpp.h" to access Moonshine from your C++ code. If you want to see an example of all these changes together, take a look at examples/windows/cli-transcriber.

Debugging

Console Logs

The library is designed to help you understand what's going wrong when you hit an issue. If something isn't working as expected, the first place to look is the console for log messages. Whenever there's a failure point or an exception within the core library, you should see a message that adds more information about what went wrong. Your language bindings should also recognize when the core library has returned an error and raise an appropriate exception, but sometimes the logs can be helpful because they contain more details.

Input Saving

If no errors are being reported but the quality of the transcription isn't what you expect, it's worth ruling out an issue with the audio data that the transcriber is receiving. To make this easier, you can pass in the save_input_wav_path option when you create a transcriber. That will save any audio received into .wav files in the folder you specify. Here's a Python example:

moonshine-voice transcribe --options='save_input_wav_path=.'

This will run test audio through a transcriber, and write out the audio it has received into an input_1.wav file in the current directory. If you're running multiple streams, you'll see input_2.wav, etc for each additional one. These wavs only contain the audio data from the latest session, and are overwritten after each one is started. Listening to these files should help you confirm that the input you're providing is as you expect it, and not distorted or corrupted.

API Call Logging

If you're running into errors it can be hard to keep track of the timeline of your interactions with the library. The log_api_calls option will print out the underlying API calls that have been triggered to the console, so you can investigate any ordering or timing issues.

moonshine-voice transcribe --options='log_api_calls=true'

Building from Source

If you want to debug into the library internals, or add instrumentation to help understand its operation, or add improvements or customizations, all of the source is available for you to build it for yourself.

Tip

Large model and TTS binaries are not stored in git. Before running scripts/test-core.sh or offline TTS work, fetch them from the CDN (or the Hugging Face mirror):

scripts/fetch-voice-assets.sh all

A few compile-time embeds and ONNX Runtime prebuilts still use Git LFS. If you clone without LFS set up, you may see errors like 'version' does not name a type when compiling embedded sources such as community1_cpp_annote_embedded.cpp (LFS pointers left as text). Install git-lfs and run git lfs install before cloning, or git lfs pull in an existing clone.

Cmake

The core engine of the library is contained in the core folder of this repo. It's written in C++ with a C interface for easy integration with other languages. We use cmake to build on all our platforms, and so the easiest way to get started is something like this:

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

After that completes you should have a set of binary executables you can run on your own system. These executables are all unit tests, and expect to be run from the test-assets folder. You can run the build and test process in one step using the scripts/test-core.sh, or scripts/test-core.bat for Windows. All tests should compile and run without any errors.

Language Bindings

There are various scripts for building for different platforms and languages, but to see examples of how to build for all of the supported systems you should look at scripts/build-all-platforms.sh. This is the script we call for every release, and it builds all of the artifacts we upload to the various package manager systems. docs/release-process.md describes how releases are branched and versioned: main always matches the most recently published binaries, and development happens on a dev-v<version> candidate branch.

The different platforms and languages have a layer on top of the C interfaces to enable idiomatic use of the library within the different environments. The major systems each have their own folder under language-bindings/, for example: language-bindings/python, language-bindings/android, and language-bindings/swift for iOS and MacOS. This is where you'll find the code that calls the underlying core library routines, and handles the event system for each platform.

Porting

If you have a device that isn't supported, you can try building using cmake on your system. The only major dependency that the C++ core library has is the Onnx Runtime. We include pre-built binary library files for all our supported systems, but you'll need to find or build your own version if the libraries we offer don't cover your use case.

If you want to call this library from a language we don't support, then you should take a look at the C interface bindings. Most languages have some way to call into C functions, so you can use these and the binding examples for other languages to guide your implementation.

Downloading Models

Speech to Text Models

The easiest way to get the model files required for transcription is by using the Python download module. After installing it run the downloader like this:

moonshine-voice download --stt --language en

You can use either the two-letter code or the English name for the language argument. If you want to see which languages are supported by your current version they're listed below, or you can supply a bogus language as the argument to this command:

moonshine-voice download --stt --language foo

You can also optionally request a specific model architecture using the model-arch flag, chosen from the numbers in moonshine-c-api.h. If no architecture is set, the script will load the highest-quality model available.

The download script will log the location of the downloaded model files and the model architecture, for example:

adapter.ort: 100%|██████████████████████████████████████████████████████████████| 3.48M/3.48M [00:00<00:00, 18.6MB/s]
cross_kv.ort: 100%|█████████████████████████████████████████████████████████████| 11.0M/11.0M [00:00<00:00, 39.4MB/s]
decoder_kv.ort: 100%|███████████████████████████████████████████████████████████████| 139M/139M [00:01<00:00, 100MB/s]
encoder.ort: 100%|██████████████████████████████████████████████████████████████| 89.8M/89.8M [00:01<00:00, 83.1MB/s]
frontend.ort: 100%|█████████████████████████████████████████████████████████████| 45.3M/45.3M [00:00<00:00, 65.7MB/s]
streaming_config.json: 100%|██████████████████████████████████████████████████████| 513/513 [00:00<00:00, 1.88MB/s]
tokenizer.bin: 100%|█████████████████████████████████████████████████████████████| 244k/244k [00:00<00:00, 3.06MB/s]
spelling_cnn.ort: 100%|█████████████████████████████████████████████████████████| 1.59M/1.59M [00:00<00:00, 10.2MB/s]
spelling_cnn_meta.json: 100%|█████████████████████████████████████████████████████| 622/622 [00:00<00:00, 1.72MB/s]
Model download url: https://download.moonshine.ai/model/medium-streaming-en/quantized_26_07_30
Model components: ['adapter.ort', 'cross_kv.ort', 'decoder_kv.ort', 'encoder.ort', 'frontend.ort', 'streaming_config.json', 'tokenizer.bin']
Model arch: 5
Downloaded model path: /Users/petewarden/Library/Caches/moonshine_voice/download.moonshine.ai/model/medium-streaming-en/quantized_26_07_30

Since no architecture was requested here, this downloaded Medium Streaming (architecture 5), the highest-quality English model. The two spelling_cnn files at the end are the alphanumeric spelling model, which the downloader fetches alongside the main model when one is published for the language.

The last two lines tell you which model architecture is being used, and where the model files are on disk. By default it uses your user cache directory, which is ~/Library/Caches/moonshine_voice on MacOS, but you can use a different location by setting the MOONSHINE_VOICE_CACHE environment variable before running the script.

Embedding Models

The download module also helps you obtain the assets needed to match spoken phrases, primarily a sentence embedding model. AgentFlow fetches this for you on first use, so you only need this command to warm the cache ahead of time — before shipping a device that will be offline, for example.

moonshine-voice download --embedding

model_q4.ort: 100%|████████████████████████████████████████████████| 189M/189M [00:02<00:00, 90.1MB/s]
tokenizer.bin: 100%|███████████████████████████████████████████████| 2.46M/2.46M [00:00<00:00, 13.9MB/s]
Embedding model path: /Users/petewarden/Library/Caches/moonshine_voice/download.moonshine.ai/model/embeddinggemma-300m
/Users/petewarden/Library/Caches/moonshine_voice/download.moonshine.ai/model/embeddinggemma-300m

Text to Speech Models

A large variety of models, dictionaries and other files are needed for TTS, and these vary widely by language. You can use the download module to pull down exactly what you need for a particular language, and optionally a voice:

moonshine-voice download --tts --root /tmp/tts-files/

dict_filtered_heteronyms.tsv: 100%|██████████████████████████████| 2.77M/2.77M [00:00<00:00, 15.5MB/s]
g2p-config.json: 100%|██████████████████████████████████████████████| 60.0/60.0 [00:00<00:00, 160kB/s]
model.ort: 100%|█████████████████████████████████████████████████| 21.1M/21.1M [00:00<00:00, 37.7MB/s]
onnx-config.json: 100%|██████████████████████████████████████████| 4.53k/4.53k [00:00<00:00, 11.7MB/s]
model.ort: 100%|█████████████████████████████████████████████████| 88.3M/88.3M [00:01<00:00, 85.6MB/s]
config.json: 100%|███████████████████████████████████████████████| 2.30k/2.30k [00:00<00:00, 6.88MB/s]
af_heart.kokorovoice: 100%|████████████████████████████████████████| 510k/510k [00:00<00:00, 3.82MB/s]
TTS assets root (use as g2p_root): /private/tmp/tts-files
/private/tmp/tts-files

The downloaded models are placed in child folders underneath the root folder, and by default the text to speech module expects the files to have the same relative paths so it can find them automatically given only the parent's path. If you do need to move them to different locations, you can supply new paths for each file using the options argument to TextToSpeech's constructor, with the usual relative path as the key, and the actual path to the file as the key.

If you have an application that may be stored in an arbitrary location after installation, you can also pass in a tts_root value as an option to set the path to the actual root folder of the TTS data at runtime.

On-Device Auto-Download (iOS / macOS / Android)

The Python download module is the right tool for build-time and desktop workflows, but mobile apps often want to fetch models on first run instead of shipping every model inside the app bundle. Both the Swift (iOS/macOS) and Android bindings include an opt-in downloader for this.

This is strictly opt-in: apps that bundle their models and load them with the usual from files / from assets / from memory paths behave exactly as before and never touch the network. The downloader only resolves the file list from the native dependency catalog (the same catalog the Python module uses), so you never hardcode filenames, and it writes each file atomically (through a .part file), resumes interrupted transfers with HTTP Range, checks free space before large writes, and reports per-file progress.

Swift (iOS 15+ / macOS 12+)

AssetDownloader.ensureModelPresent downloads whatever is missing under a directory you choose and returns that directory, ready to hand to Transcriber, MicTranscriber, or TextToSpeech. Call it off the main actor (it is async).

import MoonshineVoice

let modelDir = URL.cachesDirectory.appending(path: "moonshine/tiny-en")

// Speech-to-text: download the default English model (add includeSpelling: true for the
// alphanumeric spelling model, or pass modelArch: to pick a specific architecture).
let downloader = AssetDownloader(allowsCellularAccess: false)  // Wi-Fi only
try await downloader.ensureModelPresent(root: modelDir, spec: .stt(language: "en")) { progress in
    print("\(progress.relativePath): \(progress.bytesDownloaded)/\(progress.bytesTotal)")
}
let transcriber = try Transcriber(modelPath: modelDir.path, modelArch: .tiny)

// Text embeddings (the embeddinggemma-300m model is large — a few hundred MB even at q4):
try await downloader.ensureModelPresent(root: embeddingDir, spec: .embedding(variant: "q4"))

// Text to speech (files land under the directory you pass as g2p_root):
try await downloader.ensureModelPresent(root: ttsRoot, spec: .tts(language: "en_us", voice: "kokoro_af_heart"))

isModelPresent(root:spec:) is a cheap synchronous check you can use to skip the download UI entirely when everything is already on disk. Download failures throw AssetDownloadError (HTTP status, insufficient space, cancellation, …) so you can distinguish "couldn't fetch" from a later load failure. No extra Info.plist entries or permissions are required for HTTPS downloads.

Android

The Android AssetDownloader mirrors the Swift API and performs blocking network I/O, so run it off the main thread. For reliable background downloads that survive process death, honor a network constraint, and retry with backoff, use MoonshineDownloadWorker (WorkManager).

File modelDir = new File(context.getFilesDir(), "moonshine/tiny-en");

// Direct (call from a background thread / coroutine):
File root = new AssetDownloader().ensureModelPresent(
        modelDir, ModelSpec.stt("en"),
        (path, index, total, done, size) -> Log.i("dl", path + " " + done + "/" + size));
Transcriber transcriber = new Transcriber();
transcriber.loadFromFiles(root.getAbsolutePath(), JNI.MOONSHINE_MODEL_ARCH_TINY);

// Or via WorkManager, downloading only over unmetered (e.g. Wi-Fi) connections:
OneTimeWorkRequest request =
        MoonshineDownloadWorker.buildRequest(modelDir, ModelSpec.stt("en"), /*requireUnmetered=*/ true);
WorkManager.getInstance(context).enqueue(request);

ModelSpec also has tts(language, voice), embedding(modelName, variant), and g2p(language) factories, matching the Swift specs. The library manifest declares the INTERNET and ACCESS_NETWORK_STATE permissions, which merge into your app automatically; observe MoonshineDownloadWorker progress via WorkInfo.getProgress() using the worker's PROGRESS_* data keys. Using the downloader pulls in OkHttp and WorkManager transitively; apps that bundle their models still ship these but never invoke the network path.

Where files go

You pick the destination directory, so choose one appropriate for your platform's cache/storage policy (for example URL.cachesDirectory on Apple platforms, or context.getFilesDir() / context.getCacheDir() on Android). Files are laid out under that directory exactly as the loaders expect: STT and embedding files use their bare filenames, while TTS/G2P assets keep their canonical relative paths (e.g. en_us/dict.tsv) so the engine can find them from the root alone.

Testing the download path

Both frameworks ship download tests that hit the real CDN, download a model into an empty directory, and then load and run the matching engine. They pull tens to hundreds of MB, so they are opt-in and skip on a normal test run:

Swift (AssetDownloaderNetworkTests): MOONSHINE_DOWNLOAD_TESTS=1 swift test --filter AssetDownloaderNetworkTests.
Android (AssetDownloaderTest): ./gradlew connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=ai.moonshine.voice.AssetDownloaderTest -Pandroid.testInstrumentationRunnerArguments.moonshineDownloadTests=1 (needs a connected device/emulator).

scripts/test-model-downloads.sh runs the native catalog samples and then drives both of these automatically (skipping a platform when its toolchain or a device is unavailable). The mocked, offline AssetDownloaderTests still run as part of the default swift test and cover manifest parsing, resume, and error handling without a network.

Benchmarks

The core library includes a benchmarking tool that simulates processing live audio by loading a .wav audio file and feeding it in chunks to the model. To run it:

cd core
mkdir -p build
cd build
cmake ..
cmake --build . --config Release
./benchmark

This will report the absolute time taken to process the audio, what percentage of the audio file's duration that is, and the average latency for a response.

The percentage is helpful because it approximates how much of a compute load the model will be on your hardware. For example, if it shows 20% then that means the speech processing will take a fifth of the compute time when running in your application, leaving 80% for the rest of your code.

The latency metric needs a bit of explanation. What most applications care about is how soon they are notified about a phrase after the user has finished talking, since this determines how fast the product can respond. As with any user interface, the time between speech ending and the app doing something determines how responsive the voice interface feels, with a goal of keeping it below 200ms. The latency figure logged here is the average time between when the library determines the user has stopped talking and the delivery of the final transcript of that phrase to the client. This is where streaming models have the most impact, since they do a lot of their work upfront, while speech is still happening, so they can usually finish very quickly.

By default the benchmark binary uses the Tiny English model and the two_cities.wav recording from this repository's test-assets folder, which is why it's run from the build directory, but you can pass in the --model-path, --model-arch, and --wav-path parameters to choose a model you've downloaded or a different recording.

You can also choose how often the transcript should be updated using the --transcription-interval argument. This defaults to 0.5 seconds, but the right value will depend on how fast your application needs updates. Longer intervals reduce the compute required a bit, at the cost of slower updates.

The MacBook Pro, Pixel 10a, and iPad (A16) Tiny / Small / Medium Streaming cells in the comparison table use the same latency metric, measured by scripts/test-mobile-latency.sh (also run from scripts/build-all-platforms.sh). That script downloads the models from the CDN, feeds two_cities.wav in small chunks as fast as the device can process, and averages lastTranscriptionLatencyMs over completed lines. Re-measure and refresh the README with the command below; a cell is rewritten only when the new average differs from the published value by more than 5%:

./scripts/test-mobile-latency.sh --update-readme

Whisper Comparisons

For platforms that support Python, you can run the scripts/run-benchmarks.py script which will evaluate similar metrics, with the advantage that it can also download the models so you don't need to worry about path handling.

It also evaluates equivalent Whisper models. This is a pretty opinionated benchmark that looks at the latency and total compute cost of the two families of models in a situation that is representative of many common real-time voice applications' requirements:

Speech needs to be responded to as quickly as possible once a user completes a phrase.
The phrases are of durations between a range of one to ten seconds.

These are very different requirements from bulk offline processing scenarios, where the overall throughput of the system is more important, and so the latency on a single segment of speech is less important than the overall throughput of the system. This allows optimizations like batch processing.

We are not claiming that Whisper is not a great model for offline processing, but we do want to highlight the advantages we that Moonshine offers for live speech applications with real-time latency requirements.

The experimental setup is as follows:

We use the two_cities.wav audio file as a test case, since it has a mix of short and long phrases. You can vary this by passing in your own audio file with the --wav_path argument.
We use the Moonshine Tiny, Base, Tiny Streaming, Small Streaming, and Medium Streaming models.
We compare these to the Whisper Tiny, Base, Small, and Large v3 models. Since the Moonshine Medium Streaming model achieves lower WER than Whisper Large v3 we compare those two, otherwise we compare each with their namesake.
We use the Moonshine VAD segmenter to split the audio into phrases, and feed each phrase to Whisper for transcription.
Response latency for both models is measured as the time between a phrase being identified as complete by the VAD segmenter and the transcribed text being returned. For Whisper this means the full transcription time, but since the Moonshine models are streaming we can do a lot of the work while speech is still happening, so the latency is much lower.
We measure the total compute cost of the models by totalling the duration of the audio processing times for each model, and then expressing that as a percentage of the total audio duration. This is the inverse of the commonly used real-time factor (RTF) metric, but it reflects the compute load required for a real-time application.
We're using faster-whisper for Whisper, since that seems to provide the best cross-platform performance. We're also sticking with the CPU, since most applications can't rely on GPU or NPU acceleration being present on all the platforms they target. We know there are a lot of great GPU/NPU-accelerated Whisper implementations out there, but these aren't portable enough to be useful for the applications we care about.

Models

Moonshine Voice is based on a family of speech to text models created by the team at Moonshine AI. If you want to download models to use with the framework, you can use the Python package to access them. This section contains more information about the history and characteristics of the models we offer.

Papers

These research papers are a good resource for understanding the architectures and performance strategies behind the models:

Moonshine: Speech Recognition for Live Transcription and Voice Commands: Describes the first-generation model architecture, which enabled flexible-duration input windows, improving on Whisper's fixed 30 second requirement.
Flavors of Moonshine: Tiny Specialized ASR Models for Edge Devices: How we improved accuracy for non-English languages by training mono-lingual models.
Moonshine v2: Ergodic Streaming Encoder ASR for Latency-Critical Speech Applications: Introduces our approach to streaming, and the advantages it offers for live voice applications.

Available Models

Here are the models currently available. See Downloading Models for how to obtain them. This library uses the Onnx model format, converted to the memory-mappable OnnxRuntime (.ort) flatbuffer encoding. For safetensor versions, see the HuggingFace section.

Language	Architecture	# Parameters	WER/CER
English	Tiny	26 million	12.66%
English	Tiny Streaming	34 million	12.00%
English	Base	58 million	10.07%
English	Small Streaming	123 million	7.84%
English	Medium Streaming	245 million	6.65%
Arabic	Base	58 million	5.63%
Japanese	Base	58 million	13.62%
Korean	Tiny	26 million	6.46%
Mandarin	Base	58 million	25.76%
Spanish	Base	58 million	4.33%
Ukrainian	Base	58 million	14.55%
Vietnamese	Base	58 million	8.82%

The English evaluations were done using the HuggingFace OpenASR Leaderboard datasets and methodology. The other languages were evaluated using the FLEURS dataset and the scripts/eval-model-accuracy script, with the character or word error rate chosen per language.

Note that the English WER figures above are the Open ASR Leaderboard average across eight datasets, measured on the floating-point reference models. The quantized models this library actually ships score a little higher, especially at the Tiny size. See Accuracy (Word Error Rate) below for a float-vs-quantized comparison and instructions on reproducing the numbers.

One common issue to watch out for if you're using models that don't use the Latin alphabet (so any languages except English and Spanish) is that you'll need to set the max_tokens_per_second option to 13.0 when you create the transcriber. This is because the most common pattern for hallucinations is endlessly repeating the last few words, and our heuristic to detect this is to check if there's an unusually high number of tokens for the duration of a segment. Unfortunately the base number of tokens per second for non-Latin languages is much higher than for English, thanks to how we're tokenizing, so you have to manually set the threshold higher to avoid cutting off valid outputs.

Accuracy (Word Error Rate)

Beyond knowing which models are available, you'll often want to understand how accurate they are and how to reproduce the numbers yourself. The scripts/eval-librispeech.py script measures Word Error Rate (WER) on the LibriSpeech test-clean set using the same dataset and Open ASR Leaderboard methodology (corpus-level WER with the Whisper English text normalizer) reported in our Moonshine v2 paper.

There's an important subtlety here that can be confusing: the WER numbers in the paper were measured with the floating-point models running in the Hugging Face Transformers library, not the quantized models this framework ships. As the paper notes in section 4.1.2, we use the Transformers implementation to measure accuracy and our own C++/ONNX library to measure latency. The models you download here are 8-bit quantized .ort files chosen for on-device speed and size.

The table below shows LibriSpeech test-clean WER for all three streaming models, comparing the paper's floating-point reference against the quantized models this library ships. All numbers use whole-utterance (non-streaming) transcription with the VAD disabled, so they're a like-for-like comparison of raw model accuracy.

Model	Paper (float)	Reproduced float (HF Transformers)	Shipped quantized model (this library)
Tiny Streaming	4.49%	4.52%	4.83%
Small Streaming	2.49%	2.55%	2.61%
Medium Streaming	2.08%	2.16%	2.17%

Every shipped model is now within 0.31% WER of its floating-point reference. That was not always true: models published before 2026-07-30 quantized each weight tensor with a single scale factor, which cost Tiny Streaming 7.57% instead of 4.83%. Switching to per-channel weight scales fixed it, for 0.5% more model size. See Quantization for the details.

Reproducing these numbers

The evaluation script downloads the dataset and models for you. Install the dependencies and run it:

# Core dependencies for evaluating the shipped (quantized) models.
pip install moonshine-voice datasets soundfile scipy jiwer openai-whisper

# Evaluate a shipped quantized model on LibriSpeech test-clean (VAD disabled).
python scripts/eval-librispeech.py --backend moonshine_c --model-arch tiny_streaming
python scripts/eval-librispeech.py --backend moonshine_c --model-arch small_streaming
python scripts/eval-librispeech.py --backend moonshine_c --model-arch medium_streaming

To reproduce the paper's floating-point reference numbers you also need a recent version of Transformers (the streaming models were added in Transformers 5.x) and PyTorch, then pass --backend hf:

pip install "transformers>=5.13" torch
python scripts/eval-librispeech.py --backend hf --model-arch tiny_streaming

The script disables the VAD by default (vad_threshold=0 plus a very large vad_max_segment_duration) because the LibriSpeech clips are already single utterances, so any VAD segmentation only adds errors. Pass --enable-vad to see the effect of the segmenter, or --backend moonshine_c_streaming to measure the chunked, real-time streaming path instead of whole-utterance transcription. Use --limit N for a quick smoke test on the first N clips.

Takeaways

8-bit quantization now costs very little accuracy at any size. The penalty against the floating-point reference is +0.31% WER on Tiny, +0.06% on Small and +0.01% on Medium. There is no longer much reason to run the floating-point checkpoint in Transformers just for accuracy, even on Tiny.
Disable the VAD when evaluating pre-segmented data. On already-segmented clips like LibriSpeech, leaving the default VAD enabled adds roughly +1.5–2% WER on Tiny (mostly extra insertions at segment boundaries). The VAD is there to chop up continuous live audio, not clean single utterances.
Watch which number you're comparing against. The per-model WER in the Available Models table is the Open ASR Leaderboard average across eight datasets (12.00% for Tiny Streaming, 7.84% for Small Streaming, and 6.65% for Medium Streaming), which is much higher than the LibriSpeech-clean-only numbers above. Make sure you're comparing the same benchmark.

Domain Customization

It's often useful to be able to calibrate a speech to text model towards certain words that you're expecting to hear in your application, whether it's technical terms, slang, or a particular dialect or accent. Moonshine AI offers full retraining using our internal dataset for customization as a commercial service and we do hope to support free lighter-weight approaches in the future. You can find a community project working on this at github.com/pierre-cheneau/finetune-moonshine-asr.

Quantization

We typically quantize our models to eight-bit weights across the board, and eight-bit calculations for heavy operations like MatMul. This is all post-training quantization, using a combination of OnnxRuntime's tools and my Onnx Shrink Ray utility. The only anomaly in the process is the treatment of the frontend, which uses convolution layers to generate features, which produces results similar to the more traditional MEL spectrogram preprocessing, but in a learned way with standard ML operations. The inputs to this initial stage correspond to 16-bit signed integers from the raw audio data (though they're encoded as floats) so we've found it necessary to leave the convolution operations in at least B16 float precision.

We give each output channel of a weight its own scale factor rather than sharing one across the whole tensor. This matters far more than it sounds like it should. Our frontend convolutions are trained with weight normalization, which by construction learns a separate magnitude per output channel — on Tiny Streaming the largest channel is 17x the smallest. A single scale for the whole tensor has to cover the largest channel, so the smallest ones get only a handful of the 256 available levels. Measured on LibriSpeech test-clean, moving to per-channel scales took Tiny Streaming from 7.57% to 4.83% WER, Small from 3.03% to 2.61%, and Medium from 2.37% to 2.17%, while adding 0.5% to the download. Roughly 90% of that gain came from the frontend alone.

If you quantize your own Moonshine-style model, this is the first thing to check. It is also why we do not fold the weight-normalization out of the exported graph even though doing so would save a little work at runtime: folding makes the per-channel magnitudes more extreme, not less, so it must be paired with per-channel scales rather than done on its own.

You can see the options we use for the conversions in scripts/quantize-streaming-model.sh.

Re-quantized models are published to a new dated directory on our CDN (currently quantized_26_07_30) instead of overwriting the previous files. That way a given version of this library always resolves the exact weights it was tested against, and your local model cache never mixes old and new files.

HuggingFace

We have safetensors versions of the models linked from our organization on HF, huggingface.co/UsefulSensors/models. The organization name is from an earlier incarnation of the company, when we were focused on supplying complete voice interface solutions integrated onto a low-cost chip with a built-in microphone. These are all floating-point checkpoints exported from our training pipeline

Separately, every asset this library can download is mirrored in a single repository at huggingface.co/moonshine-ai/moonshine-voice-assets, under our current organization name. It holds exactly the files the download manifests reference (currently 438 files, 7.3GB) — the .ort speech to text and embedding models, the TTS voices, and the grapheme to phoneme data — laid out in the same folder hierarchy as the CDN, so a path in that repo is the path under download.moonshine.ai. The list is enumerated from the compiled model catalog rather than by listing the bucket, because the bucket also holds unconverted .onnx sources, older copies of models that manifests no longer point at, and platform artifacts like the Raspberry Pi disk image. If you need to know which files a given release actually uses, that repo is the authoritative answer, and its FILES.tsv records the size and checksum of each one. Note that the library still downloads from the CDN at runtime; the mirror is there for archival and verification, not for serving. For local tests and offline TTS work, populate the gitignored trees with scripts/fetch-voice-assets.sh. Reclaiming GitHub LFS storage after removing historical binaries is documented in docs/lfs-purge.md.

API Reference

This documentation covers the Python API, but the same functions and classes are present in all the other supported languages, just with native adaptations (for example CamelCase). You should be able to use this as a reference for all platforms the library runs on.

Data Structures

TranscriptLine

Represents a single "line" or speech segment in a transcript. It includes information about the timing, speaker, and text content of the utterance, as well as state such as whether the speech is ongoing or done. If you're building an application that involves transcription, this data structure has all of the information available about each line of speech. Be aware that each line can be updated multiple times with new text and other information as the user keeps speaking.

text: A string containing the UTF-8 encoded text that has been extracted from the audio of this segment.
start_time: A float value representing the time in seconds since the start of the current session that the current utterance was first detected.
duration: A float that represents the duration in seconds of the current utterance.
line_id: An unsigned 64-bit integer that represents a line in a collision-resistant way, for use in storage and ensuring the application can keep track of lines as they change over time. See Transcription Event Flow for more details.
is_complete: A boolean that is false until the segment has been completed, and true for the remainder of the line's lifetime.
is_updated: A boolean that's true if any information about the line has changed since the last time the transcript was updated. Since the transcript will be periodically updated internally by the library as you add audio chunks, you can't rely on polling this to detect changes. You should rely on the event/listener flow to catch modifications instead. This applies to all of the booleans below too.
is_new: A boolean indicating whether the line has been added to the transcript by the last update call.
has_text_changed: A boolean that's set if the contents of the line's text was modified by the last transcript update. If this is set, is_updated will always be set too, but if other properties of the line (for example the duration or the audio data) have changed but the text remains the same, then is_updated can be true while has_text_changed is false.
have_speakers_changed: A boolean that's set if the line's speaker spans were revised by the last transcript update. Unlike the other change flags, this can be set for lines that are already complete, since the diarization algorithm keeps refining speaker assignments for recent audio. Only relevant when the identify_speakers option is enabled.
speaker_spans: An array of speaker spans describing who was talking during which parts of the line, ordered by start time and clipped to the line's time range. Empty unless the opt-in identify_speakers option is enabled (which also turns on word timestamps automatically, since they are needed to map spans onto the line text). Each span has:
- start_time: A float giving the time offset in seconds from the start of the stream.
- duration: A float giving the length of the span in seconds.
- speaker_id: A unique-ish unsigned 64-bit integer that is stable for a given speaker within a stream, designed for storage or keeping track of speakers over time.
- speaker_index: An integer that represents the order in which the speaker first appeared in the transcript, to make it easy to give speakers default names like "Speaker 1:", etc.
- start_char: A UTF-8 byte offset into the line's text where this span begins (inclusive). Zero when unknown.
- end_char: A UTF-8 byte offset into the line's text where this span ends (exclusive). Slice with text[start_char:end_char] in Python. Both zero when the span could not be aligned to words yet.
Be aware that speaker spans are mutable: the diarization algorithm re-clusters the entire audio history on a cadence, so the spans of any line - including completed ones - can move, merge, split, or change speaker on any transcription call. Watch the have_speakers_changed flag (or the LineSpeakersChanged event) to catch revisions.
words: An array of per-word timings, empty unless the word_timestamps option is enabled (which identify_speakers turns on for you). Each entry has the word itself, its start and end times in seconds, and a confidence value.
audio_data: An array of 32-bit floats representing the raw audio data that the line is based on, as 16KHz mono PCM data between 0.0 and 1.0. This can be useful for further processing (for example to drive a visual indicator or to feed into a specialized speech to text model after the line is complete).

Transcript

A Transcript contains a list of TranscriptLines, arranged in descending time order. The transcript is reset at every Transcriber.start() call, so if you need to retain information from it, you should make explicit copies. Most applications won't work with this structure, since all of the same information is available through event callbacks.

TranscriptEvent

Contains information about a change to the transcript. It has five subclasses — LineStarted, LineUpdated, LineTextChanged, LineSpeakersChanged, and LineCompleted — which are explained in more detail in the transcription event flow section. Most of the information is contained in the line member, but there's also a stream_handle that your application can use to tell the source of a line if you're running multiple streams.

TtsVoiceEntry

A single voice row from the native TTS catalog (as returned inside the map from get_tts_voice_catalog()).

id: The voice identifier string (often with a kokoro_ or piper_ prefix to pin the vocoder).
state: Either "found" (assets present under the resolved asset root) or "missing" (listed in the catalog but not on disk yet).

TtsVoicesByAvailability

The dictionary shape returned by list_tts_voices().

present: Sorted list of voice ids that are already available under the asset root used for the query.
downloadable: Sorted list of catalog voice ids that are not on disk yet but can be fetched (for example when constructing TextToSpeech with download=True).

Classes

Transcriber

Handles the speech to text pipeline.

__init__(): Loads and initializes the transcriber.
- model_path: The path to the directory holding the component model files needed for the complete flow. Note that this is a path to the folder, not an individual file. You can download and get a path to a cached version of the standard models using the download_model() function.
- model_arch: The architecture of the model to load, from the selection defined in ModelArch.
- update_interval: By default the transcriber will periodically run text transcription as new audio data is fed, so that update events can be triggered. This value is how often the speech to text model should be run. You can set this to a large duration to suppress updates between a line starting and ending, but because the streaming models do a lot of their work before the final speech to text stage, this may not reduce overall latency by much.
- options: These are flags that affect how the transcription process works inside the library, often enabling performance optimizations or debug logging. They are passed as a dictionary mapping strings to strings, even if the values are to be interpreted as numbers - for example {"max_tokens_per_second", "15"}.
  - skip_transcription: If you only want the voice-activity detection and segmentation, but want to do further processing in your app, you can set this to "true" and then use the audioData array in each line.
  - max_tokens_per_second: The models occassionally get caught in an infinite decoder loop, where the same words are repeated over and over again. As a heuristic to catch this we compare the number of tokens in the current run to the duration of the audio, and if there seem to be too many tokens we truncate the decoding. By default this is set to 6.5, but for non-English languages where the models produce a lot more raw tokens per second, you may want to bump this to 13.0.
  - use_speculative_decoding: A boolean (default true) that speeds up streaming re-decodes by verifying the previous hypothesis and continuing from the first mismatch instead of greedily redecoding from BOS. Set to false to disable.
  - transcription_interval: How often to run transcription, in seconds.
  - vad_threshold: Controls the sensitivity of the initial voice-activity detection stage that decides how to break raw audio into segments. This defaults to 0.5, with lower values creating longer segments, potentially with more background noise sections, and higher values breaking up speech into smaller chunks, at the risk of losing some actual speech by clipping. If you set it to zero, it disables the VAD entirely, though speech will still be broken up into vad_max_segment_duration sized chunks.
  - save_input_wav_path: One of the most common causes of poor transcription quality is incorrect conversion or corruption of the audio that's fed into the pipeline. If you set this option to a folder path, the transcriber will save out exactly what it has received as 16KHz mono WAV files, so you can ensure that your input audio is as you expect.
  - log_api_calls: Another debugging option, turning this on causes all calls to the C API entry points in the library to write out information on their arguments to stderr or the console each time they're run.
  - log_ort_run: Prints information about the ONNXRuntime inference runs and how long they take.
  - ort_providers: A comma-separated, ordered list of the ONNX Runtime execution providers the models should try to use, for example "CoreML,CPU" on macOS. The names are case-insensitive and accept either the short form (CPU, CoreML, NNAPI) or the full ONNX Runtime name (CPUExecutionProvider, CoreMLExecutionProvider, NNAPIExecutionProvider). Providers are appended in the order given, and ONNX Runtime falls back to later entries for any operations an earlier provider can't handle, so it's good practice to always list CPU last as a catch-all. If you leave this unset the library runs CPU-only, which is what we recommend and what every mobile build supports: the iOS and Android libraries ship without CoreML and NNAPI because neither could run our models in large enough pieces to be worth its size, and asking for one there is an error that says so. docs/execution-providers.md has the measurements. Requesting a provider that isn't available on the current platform (such as CoreML off Apple hardware, or NNAPI off Android) is likewise an error. The alias ort_provider is also accepted.
  - coreml_cache_dir: A directory path where the CoreML execution provider caches its compiled models on macOS. Compiling a model for CoreML is expensive, so pointing this at a persistent, writable folder lets subsequent runs reuse the cached artifacts and start up much faster. This only has an effect when CoreML is included in ort_providers, so it does nothing on iOS, whose library has no CoreML in it.
  - vad_window_duration: The VAD runs every 30ms, but to get higher-confidence values we average the results over time. This value is the time in seconds to average over. The default is 0.5s, shorter durations will spot speech faster at the cost of lower accuracy, higher values may increase accuracy, but at the cost of missing shorter utterances.
  - vad_look_behind_sample_count: Because we're averaging over time, the mean VAD signal will lag behind the initial speech detection. To compensate for that, when speech is detected we pull in some of the audio immediately before the average passed the threshold. This value is the number of samples to prepend, and defaults to 8192 (all at 16KHz).
  - vad_max_segment_duration: It can be hard to find gaps in rapid-fire speech, but a lot of applications want their text in chunks that aren't endless. This option sets the longest duration a line can be before it's marked as complete and a new segment is started. The default is 15 seconds, and to increase the chance that a natural break is found, the vad_threshold is linearly decreased over time from two thirds of the maximum duration until the maximum is reached.
  - word_timestamps: A boolean (default false) that fills in each line's words array with per-word timings. This needs the optional attention decoder that sits alongside the main model files (decoder_kv_with_attention.ort for streaming architectures, decoder_with_attention.ort otherwise), so ask the downloader for it when you fetch the model. Turning on identify_speakers enables this automatically, since speaker spans are mapped onto the line text using word timings.
  - identify_speakers: A boolean (default false) that controls whether to run the speaker diarization stage of the pipeline. When enabled, each line carries a speaker_spans array describing who spoke when, including UTF-8 character ranges into the line text. Word timestamps are enabled automatically in this mode. This runs a C++ port of the pyannote community-1 pipeline inline inside transcription calls, which adds significant compute. Streaming sessions bound VBx re-clustering to a sliding window (see diarization_cluster_window_sec); batch/one-shot transcription still uses full-history clustering. This needs the two diarization models, which are an 8.2 MB download rather than part of the library; the high-level loaders fetch them for you when this option is set, and everything else takes diarization_model_dir. See The diarization models are a download. For tests, test-assets/endgame_nagg_nell.wav is a ~28 second synthetic two-speaker clip (ZipVoice TTS, Beckett's Endgame dialogue); regenerate it with python3 scripts/generate-diarization-test-audio.py.
  - diarization_model_dir: The directory holding segmentation.ort and embedding.ort, required whenever identify_speakers is set and you are constructing a transcriber directly rather than through one of the loaders that downloads for you. Get the directory from moonshine_voice.get_diarization_model() in Python, ModelSpec.diarization in Swift, or ModelSpec.diarization() on Android; in the browser, pass the two files to the in-memory loader instead.
  - diarization_cluster_cadence: A float (default 2.0) giving the minimum number of seconds of new audio between diarization re-clustering passes. Raising this reduces compute on long sessions, at the cost of slower refinement of speaker assignments.
  - diarization_analyze_cadence: A float (default 0, meaning the model default of 1.0) giving the number of seconds between diarization segmentation/embedding model runs.
  - diarization_cluster_window_sec: A float (default 120.0) giving the maximum seconds of recent audio history fed to VBx on each streaming refresh. Older chunks are evicted from the cache and their speaker turns are frozen (no longer revised). Set to 0 for unlimited full-history re-clustering (higher quality on long sessions, but compute and memory grow with session length). Batch/one-shot diarization always uses full history regardless of this setting.
  - return_audio_data: By default the transcriber returns the segment of audio data corresponding to a line of text along with the transcription. You can disable this if you want to reduce memory overhead.
  - log_output_text: If this is enabled then the results of the speech to text model will be logged to the console.
transcribe_without_streaming(): A convenience function to extract text from a non-live audio source, such as a file. We optimize for streaming use cases, so you're probably better off using libraries that specialize in bulk, batched transcription if you use this a lot and have performance constraints. This will still call any registered event listeners as it processes the lines, so this can be useful to test your application using pre-recorded files, or to easily integrate offline audio sources.
- audio_data: An array of 32-bit float values, representing mono PCM audio between -1.0 and 1.0, to be analyzed for speech.
- sample_rate: The number of samples per second. The library uses this to convert to its working rate (16KHz) internally.
- flags: Integer, currently unused.
start(): Begins a new transcription session. You need to call this after you've created the Transcriber and before you add any audio.
stop(): Ends a transcription session. If a speech segment was still active, it's marked as complete and the appropriate event handlers are called.
add_audio(): Call this every time you have a new chunk of audio from your input, to begin processing. The size and sample rate of the audio should be whatever's natural for your source, since the library will handle all conversions.
- audio_data: Array of 32-bit floats representing a mono PCM chunk of audio.
- sample_rate: How many samples per second are present in the input audio. The library uses this to convert the data to its preferred rate.
update_transcription: The transcript is usually updated periodically as audio data is added, but if you need to trigger one yourself, for example when a user presses refresh, or want access to the complete transcript, you can call this manually.
- flags: Integer holding flags that are combined using bitwise or (|).
  - MOONSHINE_FLAG_FORCE_UPDATE: By default the transcriber returns a cached version of the transcript if less than 200ms of new audio has come in since the last transcription, but by setting this you can ensure that a transcription happens regardless.
create_stream(): If your application is taking audio input from multiple sources, for example a microphone and system audio, then you'll want to create multiple streams on a single transcriber to avoid loading multiple copies of the models. Each stream has its own transcript, and line events are tagged with the stream handle they came from. You don't need to worry about this if you only need to deal with a single input though, just use the Transcriber class's start(), stop(), etc. This function returns Stream class object.
- flags: Integer, reserved for future expansion.
- update_interval: Period in seconds between transcription updates.
add_listener(): Registers a callable object with the transcriber. This object will be called back as audio is fed in and text is extracted.
- listener: This is often a subclass of TranscriptEventListener, but can be a plain function. It defines what code is called when a speech event happens.
remove_listener(): Deletes a listener so that it no longer receives events.
- listener: An object you previously passed into add_listener().
remove_all_listeners(): Deletes all registered listeners so than none of them receive events anymore.

MicTranscriber

Transcribes speech straight from the system's microphone, so you never call add_audio() yourself. In Python this uses the sounddevice library, but in other languages the class uses the native audio API under the hood.

Construct one, configure it with chainable setters, call load() to fetch and open the model, then start() to begin listening.

mic = (
    MicTranscriber()
    .on_text(lambda text: show_in_progress(text))
    .on_line(lambda line: append_line(line.text))
)
mic.load()
mic.start()

__init__(): Constructs an unconfigured transcriber. Takes no arguments and cannot fail, so nothing is downloaded or opened until load().

Every setter returns the transcriber, so one can be built in a single expression, and every one has a working default. Call them before load().

language(): Sets the speech-to-text language. Defaults to "en".
model_arch(): Picks a specific model size. By default the catalog's recommended model for the language is used, which is medium streaming for English. Most languages publish only one model.
models_from(): Loads the model from a directory you supply rather than downloading it.
use_transcriber(): Reuses a Transcriber you already have instead of opening another. It stays yours to close.
update_interval(): Seconds between automatic streaming updates. Defaults to 0.5.
options(): Passes a dictionary of advanced transcriber options straight through, for anything the setters don't cover.
spelling_model(): Uses a specific alphanumeric spelling model. load() finds the published one for the language by itself, so this is only for when you keep your own copy. Pass None to go without one.
transcribe_flags(): Sets the flags applied to every streaming update. Pass MOONSHINE_FLAG_SPELLING_MODE to turn on the spelling-CNN fusion that makes dictated codes and passwords accurate. Takes effect immediately when already loaded.
device(): Captures from a specific input device, by index or name. Defaults to the system default.
samplerate(): Asks the capture device for a sample rate. Defaults to 16000, and start() falls back to the device's own rate if it refuses, so this rarely needs setting.
channels(): Number of channels to capture. Defaults to 1.
blocksize(): Frames per capture callback. Defaults to 1024.

The callbacks below cover almost everything. For line ids, speaker spans, word timings, or the moment a line starts, attach a TranscriptEventListener with add_listener() instead; listeners registered before load() are held and applied once the stream exists.

on_text(): Called with the in-progress text of the line currently being spoken, each time it changes.
on_line(): Called once per finished line, with the TranscriptLine.
on_error(): Called when the audio or transcription pipeline raises.
on_progress(): Reports model download progress as a 0..1 fraction and the file being fetched. Attaching a handler also silences the default terminal progress bars.
load(): Downloads the model if needed, opens it, and returns the transcriber. Blocking, since the first call may have to fetch several hundred megabytes; report progress with on_progress(). Safe to call twice.
start(): Opens the microphone and begins transcribing. Raises if you haven't called load().
mute(): Drops incoming audio without closing the microphone, so an assistant doesn't transcribe its own synthesized speech.
stop(): Stops listening and flushes any audio still in flight, so the final line is complete.
close(): Releases the microphone, the stream, and the model. Also available as a context manager.

Stream

The access point for when you need to feed multiple audio inputs into a single transcriber. Supports start(), stop(), add_audio(), update_transcription(), add_listener(), remove_listener(), and remove_all_listeners() as documented in the Transcriber class.

TranscriptEventListener

A convenience class to derive from to create your own listener code. Override any or all of on_line_started(), on_line_updated(), on_line_text_changed(), on_line_speakers_changed(), on_line_completed(), and on_error(), and they'll be called back when the corresponding event occurs. Every method has a no-op default, so you only need to write the ones you care about.

AgentFlow

A runner that drives generator-based conversational flows, and the entry point for voice interfaces. You register flow functions against trigger phrases, and the runner routes completed transcript lines either to trigger matching (when no flow is active) or to the currently suspended generator (when one is). Matching is semantic, using an embedding model that the runner downloads and loads the first time it needs one. load() opens the microphone transcriber and speech synthesizer for you, so there's no listener to wire up by hand; pass use_mic_transcriber() if you'd rather it listened to a transcriber you already have. See Getting Started with a Conversational Agent for usage examples.

A flow is an ordinary Python generator function that takes a Dialog as its argument and yields prompt objects back to the runner. The runner carries out each prompt (speaking text, waiting for the user's response) and resumes the generator with the answer via .send(). This lets you write multi-step, branching conversations using regular Python control flow, including loops and exception handlers, without any async machinery. Trigger matching, confirmation, and option selection are all done semantically through the embedding model, so alternative phrasings will work without you needing to enumerate them.

__init__(): Constructs an unconfigured runner. Takes no arguments — configure it with the chainable setters below, then call load().

Every setter returns the runner, so a whole voice interface can be built in one expression, and every one of them has a working default. Call them before load().

language(): Sets the language used for both recognition and speech. Defaults to "en".
model_arch(): Picks a specific speech recognition model size instead of the default for the language.
voice(): Chooses the synthesis voice used to speak prompts.
speech_options(): Passes a dictionary of advanced options straight through to the TextToSpeech synthesizer.
models_from(): Reads and caches model files under the given directory instead of the default cache location.
microphone(): Whether load() should open a microphone. Defaults to True. Turn it off to drive the runner from text with handle_utterance().
speech(): Whether load() should open a speech synthesizer. Defaults to True. Turn it off for a silent runner: prompts are still logged and flows still advance, they just aren't spoken.
output_device(): Pins playback to a specific audio output device, for machines where the host default isn't the speaker you want.
trigger_threshold(): The similarity a phrase must reach to fire, between 0 and 1. Defaults to 0.7. Raise it when triggers fire on unrelated speech, lower it when they don't fire on genuine attempts.
use_embeddings(): Whether to match phrases by meaning. Defaults to True, which downloads a small language model so "set up wifi" also fires on "I need to get online". Turn it off to fall back to case-insensitive substring matching and load no model, which is what offline tests usually want.
beeps(): Whether to play the recognition cue tones. Defaults to True, which plays a short "got it" tone when an utterance matches and a distinct "didn't get that" tone when nothing does, so a misrecognition never ends in silence.
spell_feedback(): Whether to echo each character during spelled input. Defaults to True, speaking back "haitch" for "h" and "deleting <character>" for an undo, so the user hears that the right letter came off the end.
barge_in(): Whether the user can interrupt the assistant mid-prompt. Off by default, because an utterance arriving while the assistant is talking is usually the microphone hearing the speakers. Enable it only when you have reliable echo cancellation.
log_io(): Logs the dialogue to stderr as user: ... / assistant: ... lines. Off by default. This is the user-facing transcript; use debug() for the verbose internal trace.
debug(): Traces every internal stage transition, with timings, to stderr.
on_progress(): Reports model download and load progress as (fraction, name).
on_heard(): Reports every utterance the runner receives from the microphone, including trigger phrases and answers to prompts. Use otherwise() instead for just the lines that didn't match anything.
on_said(): Reports every prompt the runner speaks.
on_error(): Reports errors raised by a flow or by the audio pipeline. Without a handler the runner prints them to stderr and carries on; a flow that raises is torn down either way, so one bad turn can't wedge the runner.
speak_with(): Speaks prompts with your own callable instead of the built-in synthesizer. It must block until playback finishes, since the runner resumes the flow as soon as it returns. Setting this stops load() creating a synthesizer.
use_text_to_speech(): Speaks with an existing TextToSpeech instead of creating one.
use_mic_transcriber(): Listens to an existing MicTranscriber, or any object with the same add_listener / start / stop shape — a plain Transcriber fed from a file works, which is handy for testing a flow against recorded audio.

The runner won't close a synthesizer or transcriber it didn't create.

listen_for(): Starts a flow whenever the user says something like the trigger phrase.
- trigger_phrase: A canonical phrase that is embedded once at registration time and compared against utterances via cosine similarity, so alternative phrasings of the same meaning will all start the flow.
- flow: A callable that takes a Dialog and returns a generator yielding prompts. Typically a generator function.
unregister_flow(): Removes a flow registered with listen_for(). Returns True if a flow was removed, False otherwise.
- trigger_phrase: The trigger phrase used when the flow was registered.
always(): Registers a phrase that stays live at every moment, whether or not a flow is running. "Cancel" and "start over" are built in and need no registration, but they apply only to a flow in progress, so an interface that dictates whatever it hears keeps those words when nothing is active. Registering either here opts it into being live all the time.
- trigger_phrase: The canonical phrase to match, in the same way as listen_for().
- handler: A callable that takes the current Dialog and returns an optional prompt to speak (or None). The handler can also call d.cancel() or d.restart() to abandon or reset the active flow.
otherwise(): Handles speech that matched no trigger and no waiting prompt. This is what a dictation interface hangs its text off: on_heard() reports every line including commands and answers, while this one reports only the lines nothing else claimed, so "delete the last sentence" starts your flow instead of being typed into the document. Registering a handler also silences the "didn't get that" cue, since unmatched speech is no longer a dead end. Nothing arrives here while a flow is running, because a flow's prompts take every line until it finishes.
- handler: A callable that takes the utterance as a string.
load(): Downloads and opens everything the runner needs — the phrase-matching model, a speech synthesizer, and a microphone transcriber — skipping any you've supplied or turned off. Blocking, since the first call may have to download models; report progress with on_progress(). Returns the runner.
start_listening(): Starts listening on the microphone, calling load() first if you haven't. Returns as soon as the microphone is live: transcript lines arrive on the audio thread and drive your flows from there, so the caller is free to sleep, run a UI, or do anything else.
stop_listening(): Stops listening. Safe to call when already stopped.
handle_utterance(): Routes an utterance manually, without going through transcript events. Returns True if the utterance was consumed by a flow or a global handler, False otherwise. Useful for unit tests, or for driving the runner from input sources other than a Transcriber.
- utterance: The string to route.
cancel(): Abandons the currently running flow, if any. Returns True if a flow was canceled.
say(): Speaks text outside any flow. Useful for welcome messages, status announcements, and error notifications that don't need a full flow registration. Blocks until playback finishes, and shares the same playback path as in-flow prompts, so mic muting and self-capture suppression still apply.
- text: The string to speak.
close(): Stops listening and releases everything the runner opened. Only closes what it created itself: a synthesizer or transcriber you passed in stays yours to close. Safe to call more than once, and safe on a runner that never loaded anything.
is_active: A read-only boolean property that's True when a flow is currently in progress.
active_trigger: A read-only property returning the trigger phrase of the active flow, or None if no flow is running.
registered_flows: A read-only list of all registered flow trigger phrases.

Dialog

The context object passed as the first argument to every flow function. Each method returns a prompt object that the flow yields back to the runner; the runner then carries out the prompt (speaking text, waiting for input) and sends the result, if any, back into the generator via .send(). Dialog itself performs no I/O, so flows can be unit-tested by constructing a Dialog, calling the flow function, and driving the resulting generator manually without any audio, TTS, or event loop.

trigger_phrase: The phrase that started the flow, available to the flow function as d.trigger_phrase.
state: A dict for the flow's own per-conversation state, initially empty.
say(): Returns a prompt that, when yielded, speaks text and resumes the flow once playback has finished. The flow receives None from the yield.
- text: The string for the assistant to speak.
- barge_in: Reserved for future use; when supported, will allow the user to interrupt playback by speaking.
ask(): Returns a prompt that speaks a question and resumes the flow with the user's next utterance as a string.
- prompt: The string for the assistant to speak before listening.
- mode: One of FREE (free-form natural-language input, the default), SPELLED (the user dictates one character at a time, terminated by "done"/"stop"/"finish", with each character spoken back as feedback and support for NATO-alphabet style words and "delete"/"undo" commands), DIGITS (digits-only spelled input), or PHRASE (a single phrase). These constants are exported from the moonshine_voice package.
- bias_terms: Optional list of strings the recognizer should bias toward when interpreting the response.
- timeout: Seconds to wait for a response before reprompting. Defaults to 8 seconds.
- no_input_reprompt: Template used to reprompt the user when no input arrives within the timeout. {prompt} is substituted with the original prompt text. Pass None to skip the reprompt.
- max_retries: Number of times to reprompt before raising NoInputError into the flow. Defaults to 2.
confirm(): Returns a prompt that asks a yes/no question and resumes the flow with a bool. Matching is semantic, so "okay", "affirmative", and "go ahead" all count as yes, and "no", "cancel", and "stop" count as no.
- prompt: The yes/no question for the assistant to speak.
- timeout: Seconds to wait for a response. Defaults to 6 seconds.
- max_retries: Number of reprompts before raising NoMatchError into the flow. Defaults to 1.
choose(): Returns a prompt that asks the user to pick from a set of named options and resumes the flow with the key of the matched option as a string. Each option key has a list of associated phrases; matching is done against the union of the key and its phrases using the embedding model.
- prompt: The string for the assistant to speak.
- options: A mapping of option keys to lists of associated phrases the user might say.
- timeout: Seconds to wait for a response. Defaults to 8 seconds.
- max_retries: Number of reprompts before raising NoMatchError. Defaults to 2.
cancel(): Raises DialogCancelled into the generator to abandon the active flow entirely. Typically called from a global handler registered with AgentFlow.always().
restart(): Raises DialogRestart into the generator to restart the active flow from the beginning. Typically called from a global handler.
replay_last_prompt(): Returns a Say prompt that re-speaks the most recent question. Intended for global "repeat" / "say that again" handlers; returns None if nothing has been spoken yet.

TextToSpeech

On-device text-to-speech using the Moonshine native stack (Kokoro and Piper vocoders plus per-language G2P assets). Required files are resolved from the CDN unless you pass download=False and supply a populated tree. Invalid language tags raise MoonshineTtsLanguageError; missing or unknown voices raise MoonshineTtsVoiceError. Playback failures from say() raise MoonshineAudioOutputError with a list of output devices when enumeration succeeds.

say() is non-blocking and queued: each call returns immediately and utterances are played back in order by a background pipeline. A dedicated synthesis thread pre-synthesizes the next utterance while the current one is playing, minimizing the gap between consecutive utterances. Use stop() to cancel all pending speech, wait() to block until everything has been played, and is_talking() to poll playback state. The same API shape is available across Python, Swift, and Android (Java).

Use list_tts_languages(), list_tts_voices(), and get_tts_voice_catalog() to discover supported tags and voices. Asset layout and licenses are summarized in core/moonshine-tts/data/README.md; see also Downloading Models.

__init__(): Creates a synthesizer and optionally downloads dependencies into the package cache (or a custom root).
- language: BCP-47-style tag for the speaking locale (for example en_us, de, fr). Aliases such as en-us are normalized by the library.
- voice: Optional voice id. Prefix with kokoro_ or piper_ to choose the vocoder (for example kokoro_af_heart). When download is true, a catalogued voice that is not yet on disk is downloaded automatically.
- options: Optional mapping of string keys to strings, numbers, or booleans, passed through to the native option parser (see below). The Python binding always sets g2p_root to the resolved asset directory; do not rely on overriding that key for a different layout—use asset_root / tts_root-style options instead.
- asset_root: Optional directory to use as the TTS cache or as the on-disk asset tree. When download is true, downloads go under this root when set; when false, this path must already contain the expected g2p_root layout.
- download: When true (default), missing TTS assets are downloaded from https://download.moonshine.ai/tts/. When false, asset_root is required and must already contain the files the native layer expects.
- clone: Optional reference clip for ZipVoice voice cloning; either a path to a .wav file or a (pcm, sample_rate) pair of mono float PCM. When set, the ZipVoice engine is used automatically; passing voice together with clone raises an error.
- clone_transcript: Optional transcript of the clone clip (recommended for better cloning quality; requires clone).
language: Read-only property returning the normalized language tag in use.
asset_root: Read-only property returning the pathlib.Path directory passed to the native layer as g2p_root.
synthesize(): Converts text to mono PCM audio.
- text: UTF-8 string to speak.
- options: Optional extra native options for this call only (merged with the constructor’s options semantics on the C side as documented there).
- Returns a tuple (samples, sample_rate) where samples is a list of 32-bit floats in roughly the −1.0…1.0 range and sample_rate is the output sample rate in Hz.
say(): Queues text for synthesis and playback, returning immediately. A background synthesis thread converts text to audio, then hands it to a playback thread that plays it on the selected output device. Synthesis of the next utterance overlaps with playback of the current one. Requires pip install numpy sounddevice on Python.
- text: A string or a list of strings to speak. A list is equivalent to calling say() once per element in order.
- device: (Python/Swift-macOS) None for the host default output, an integer PortAudio output device index, a decimal string index, or a case-insensitive substring of a device name. On Android, pass a Context (required) and optionally an AudioDeviceInfo.
- options: Optional per-call native options, passed through to synthesis unchanged.
stop(): Clears the utterance queue and stops any audio currently playing. Returns once all pending utterances are discarded and active playback has been halted. It is safe to call say() again afterwards.
wait(): Blocks the calling thread until every queued utterance has been synthesized and played to completion. Named waitUntilDone() on Android.
is_talking(): Returns True if utterances are still queued, being synthesized, or currently playing. Named isTalking() on Swift and Android.
close(): Stops any in-progress playback, discards pending utterances, and releases the native synthesizer handle. Called automatically when using a with TextToSpeech(...) as tts: block or on garbage collection.

Common options keys (TTS): These mirror MoonshineTTSOptions in the C++ layer. Values are strings in the underlying API; the Python binding accepts bools and numbers where noted.

tts_root, path_root, model_root: Aliases for the asset root directory when you need to override layout discovery (same role as g2p_root in the native parser).
voice: Default voice id if not passed to the constructor (constructor argument wins when both are set in typical use).
speed: Speaking rate multiplier (floating-point).
kokoro_dir, kokoro_model / kokoro_model_onnx, kokoro_config / kokoro_config_json: Override paths for Kokoro ONNX and config within the asset tree.
piper_onnx / piper_model_onnx, piper_onnx_json, piper_voices_dir / voices_dir, piper_voices_json_dir / voices_json_dir: Override paths for Piper model, JSON sidecar, and voice directories.
normalize_audio / piper_normalize_audio (legacy alias), output_volume / piper_output_volume (legacy alias): Shared post-synthesis effects applied to both Kokoro and Piper output (peak-normalize, apply gain, then clip to [-1, 1]).
piper_noise_scale / piper_noise_scale_override, piper_noise_w / piper_noise_w_override: Piper inference tuning (see native option parsing for types).
zipvoice_clone_sample_rate / clone_sample_rate, zipvoice_clone_transcript / clone_transcript: Sample rate and transcript for a caller-supplied ZipVoice reference clip (memory key zipvoice/clone_audio); the Python clone / clone_transcript constructor arguments set these for you.

Additional keys are forwarded to the G2P option parser (language-specific ONNX overrides, feature flags, and so on).

GraphemeToPhonemizer

IPA string generation without speech synthesis. Dependencies are the same CDN lexicon and ONNX bundles as TTS, but restricted to what moonshine_get_g2p_dependencies reports for the language. When download is true, assets are placed under the package cache or asset_root; when false, asset_root must already contain those files.

__init__(): Creates a native G2P handle.
- language: Locale tag (for example en_us, ja). Normalized the same way as for TTS.
- options: Optional mapping passed to the native layer (G2P keys only; the binding sets g2p_root automatically).
- asset_root: Optional cache or pre-populated directory, same semantics as for TextToSpeech.
- download: When true (default), missing G2P assets are downloaded. When false, asset_root is required.
language: Read-only normalized tag.
asset_root: Read-only pathlib.Path to the directory used as g2p_root.
to_ipa(): Returns a single IPA string for the input text.
- text: UTF-8 surface string.
- options: Optional per-call native G2P options.
close(): Frees the native handle; also invoked by context manager exit and __del__.

Support

Our primary support channel is the Moonshine Discord. We make our best efforts to respond to questions there, and other channels like GitHub issues. We also offer paid support for commercial customers who need porting or acceleration on other platforms, model customization, more languages, or any other services, please get in touch.

Roadmap

This library is in active development, and we aim to implement:

Binary size reduction for mobile deployment.
More languages.
More streaming models.
Improved speaker identification.
Lightweight domain customization.

Acknowledgements

We're grateful to:

Lambda and Stephen Balaban for supporting our model training through their foundational model grants.
The ONNX Runtime community for building a fast, cross-platform inference engine.
Alexander Veysov for the great Silero Voice Activity Detector.
Viktor Kirilov for his fantastic DocTest C++ testing framework.
Nemanja Trifunovic for his very helpful UTF8 CPP library.
The Pyannote team for making available their speaker embedding model.
The espeak-ng community, for all of their inspiring work tackling the endless complexities of translating the written word into speech.
The CMU Pronouncing Dictionary and eSpeak NG for English G2P lexicon and pronunciation filtering (core/moonshine-tts/data/en_us).
open-dict-data/ipa-dict for multilingual IPA lexicon data used across many locales (core/moonshine-tts/data).
WikiPron (CUNY-CL) for Italian, Russian, and European Portuguese pronunciations.
Koichi Yasuoka for the Hugging Face models chinese-roberta-base-upos, roberta-small-japanese-char-luw-upos, and roberta-base-korean-morph-upos.
hexgrad/Kokoro-82M and onnx-community/Kokoro-82M-ONNX for Kokoro TTS weights and ONNX (core/moonshine-tts/data/kokoro).
PiperTTS for their excellent lightweight TTS models.
MeloTTS from MyShell as reference for Korean Piper voice training (core/moonshine-tts/data/ko).
English Wiktionary and hermitdave/FrequencyWords for Hindi lexicon material (core/moonshine-tts/data/hi).
hbenbel/French-Dictionary for related French liaison lexicon work (core/moonshine-tts/data/fr).
AbderrahmanSkiredj1/arabertv02_tashkeel_fadel for Arabic diacritization and CAMeL Tools for optional Arabic MSA lexicon builds (core/moonshine-tts/data/ar_msa).
ZipVoice for their high-quality text to speech and voice cloning.
The team behind the VCTK dataset at the University of Edinburgh for generously providing a rich source of voice styles.

License

This code, apart from the source in core/third-party, is licensed under the MIT License, see LICENSE in this repository.

The English-language models are also released under the MIT License. Models for other languages are released under the Moonshine Community License, which is a non-commercial license.

The code in core/third-party is licensed according to the terms of the open source projects it originates from, with details in a LICENSE file in each subfolder.

The Eigen library is compiled with only the MPL-2.0 subset, all files with other licenses are removed.

The text to speech and grapheme to phoneme models and data files are licensed under the terms listed in their readmes and their source repositories. Per-language details and regeneration notes live under core/moonshine-tts/data/.

tensorflow/tensorflow

An Open Source Machine Learning Framework for Everyone

`Documentation`

TensorFlow is an end-to-end open source platform for machine learning. It has a comprehensive, flexible ecosystem of tools, libraries, and community resources that lets researchers push the state-of-the-art in ML and developers easily build and deploy ML-powered applications.

TensorFlow was originally developed by researchers and engineers working within the Machine Intelligence team at Google Brain to conduct research in machine learning and neural networks. However, the framework is versatile enough to be used in other areas as well.

TensorFlow provides stable Python and C++ APIs, as well as a non-guaranteed backward compatible API for other languages.

Keep up-to-date with release announcements and security updates by subscribing to announce@tensorflow.org. See all the mailing lists.

Install

See the TensorFlow install guide for the pip package, to enable GPU support, use a Docker container, and build from source.

To install the current release, which includes support for CUDA-enabled GPU cards (Ubuntu and Windows):

 pip install tensorflow

Other devices (DirectX and MacOS-metal) are supported using Device Plugins.

A smaller CPU-only TensorFlow package is also available:

 pip install tensorflow-cpu

To update TensorFlow to the latest version, add the --upgrade flag to the commands above.

Nightly binaries are available for testing using the tf-nightly and tf-nightly-cpu packages on PyPI.

Try your first TensorFlow program

$ python

>>> import tensorflow as tf
>>> tf.add(1, 2).numpy()
3
>>> hello = tf.constant('Hello, TensorFlow!')
>>> hello.numpy()
b'Hello, TensorFlow!'

For more examples, see the TensorFlow Tutorials.

Contribution guidelines

If you want to contribute to TensorFlow, be sure to review the Contribution Guidelines. This project adheres to TensorFlow's Code of Conduct. By participating, you are expected to uphold this code.

We use GitHub Issues for tracking requests and bugs, please see TensorFlow Forum for general questions and discussion, and please direct specific questions to Stack Overflow.

The TensorFlow project strives to abide by generally accepted best practices in open-source software development.

Patching guidelines

Follow these steps to patch a specific version of TensorFlow, for example, to apply fixes to bugs or security vulnerabilities:

Clone the TensorFlow repository and switch to the appropriate branch for your desired version—for example, r2.8 for version 2.8.
Apply the desired changes (i.e., cherry-pick them) and resolve any code conflicts.
Run TensorFlow tests and ensure they pass.
Build the TensorFlow pip package from source.

Continuous build status

You can find more community-supported platforms and configurations in the TensorFlow SIG Build Community Builds Table.

Official Builds

Build Type	Status	Artifacts
Linux CPU		PyPI
Linux GPU		PyPI
Linux XLA		TBA
macOS		PyPI
Windows CPU		PyPI
Windows GPU		PyPI
Android		Download
Raspberry Pi 0 and 1		Py3
Raspberry Pi 2 and 3		Py3

Resources

Learn more about the TensorFlow Community and how to Contribute.

Courses

License

Apache License 2.0

amnezia-vpn/amnezia-client

Amnezia VPN Client (Desktop+Mobile)

Amnezia VPN

The best client for self-hosted VPN

English | Русский

Amnezia is an open-source VPN client, with a key feature that enables you to deploy your own VPN server on your server.

Website | Alt website link | Documentation | Troubleshooting

Tip

If the Amnezia website is blocked in your region, you can use an Alternative website link.

All releases

Features

Very easy to use - enter your IP address, SSH login, password and Amnezia will automatically install VPN docker containers to your server and connect to the VPN.
Classic VPN-protocols: OpenVPN, WireGuard and IKEv2 protocols.
Protocols with traffic Masking (Obfuscation): OpenVPN over Cloak plugin, Shadowsocks (OpenVPN over Shadowsocks), AmneziaWG and XRay.
Split tunneling support - add any sites to the client to enable VPN only for them or add Apps (only for Android and Desktop).
Windows, MacOS, Linux, Android, iOS releases.
Support for AmneziaWG protocol configuration on Keenetic beta firmware.

Tech

AmneziaVPN uses several open-source projects to work:

Help us with translations

Download the most actual translation files.

Go to "Actions" tab, click on the first line. Then scroll down to the "Artifacts" section and download "AmneziaVPN_translations".

Unzip this file. Each *.ts file contains strings for one corresponding language.

Translate or correct some strings in one or multiple *.ts files and commit them back to this repository into the client/translations folder. You can do it via a web-interface or any other method you're familiar with.

Checking out the source code

Make sure to pull all submodules after checking out the repo.

git submodule update --init --recursive

Hacking guide

Want to contribute? Welcome!

Build requirements

CMake
Compiler and underlying build system, depending on the target:
- [Linux] Any of make and gcc
- [Apple] Xcode or Xcode command line tools
- [Windows] Visual Studio 2022 or VS 2022 Build Tools
- [Android] Android SDK and Ninja
Qt 6.10+ with the following modules:
- Core module for targeting platform (Desktop/Android/iOS)
- Qt 5 Compatibility module
- Qt Remote Objects
Conan package manager
- On MacOS is enough just to use homebrew or install it in .venv in project root
- Other systems must have it in PATH
(Optional) Installer dependencies:
- [Windows/Linux] Qt Installer Framework
- [Windows] WIX toolset

Building the project using scripts

Run scripts located in deploy directory
Basically, if dependencies are located in default installation paths, the scripts will find them automatically.
If they differ, specify them using the following variables:
- QT_INSTALL_DIR - Qt root installation folder
- QT_ROOT_PATH - Qt framework root directory
- QIF_ROOT_PATH - Qt Installer Framework root path
- ANDROID_HOME - Path to Android SDK root folder
- and others. Check scripts for more

Unix-like:

# Build executables for the host platform
deploy/build.sh

# Or just
deploy/build.sh

# Build executables and installers for the host platform
deploy/build.sh --installer all

# Build Android APK and AAB
deploy/build.sh -t android --aab

# Call for help
deploy/build.sh -h

Windows:

:: Build executables for Windows
deploy/build.bat

:: Build executables with IFW installer for Windows
deploy/build.bat --installer ifw

:: Build executables with IFW and WIX installer for Windows
deploy/build.bat --installer ifw --installer wix

:: Or just
deploy/build.bat --installer all

Developing the project in IDEs

Basically, you can use any IDE that handles CMake and Qt kits properly to run configure and build steps, and to navigate through the code nicely. For example:
- Qt Creator
- Visual Studio Code with Qt Extension Pack
- and so on
To use Xcode, you have to configure project first by using cmake. The easiest way to do it is to use Qt Creator for configuration. Then open AmneziaVPN.xcodeproj file from the build folder by using Xcode. Note that none of the files changed are saved - the files actually getting changed in build directory. Copy them manually if necessary
Android studio could be used in the same way - just configure the project by using cmake manually or by using Qt Creator. Open <build-dir>/client/android-build in Android studio then. Do not forget to copy the changes - everything you do is saved under the build directory actually.

Installing Android SDK

Android SDK could be installed using the following methods:
- Using Qt Creator. Use Preferences->SDKs
- Using Android studio. By default it installs necessary SDKs automatically during the installation
- Manually by using sdk-manager. Check this page for details

License

This project is licensed under the GNU General Public License v3.0 (see LICENSE) and also includes third-party components distributed under their own terms (see THIRD_PARTY_LICENSES.md).

Donate

Patreon: https://www.patreon.com/amneziavpn

Bitcoin: bc1qmhtgcf9637rl3kqyy22r2a8wa8laka4t9rx2mf
USDT BEP20: 0x6abD576765a826f87D1D95183438f9408C901bE4
USDT TRC20: TELAitazF1MZGmiNjTcnxDjEiH5oe7LC9d
XMR: 48spms39jt1L2L5vyw2RQW6CXD6odUd4jFu19GZcDyKKQV9U88wsJVjSbL4CfRys37jVMdoaWVPSvezCQPhHXUW5UKLqUp3
TON: UQDpU1CyKRmg7L8mNScKk9FRc2SlESuI7N-Hby4nX-CcVmns

Acknowledgments

This project is tested with BrowserStack. We express our gratitude to BrowserStack for supporting our project.

protocolbuffers/protobuf

Protocol Buffers - Google's data interchange format

Overview

Protocol Buffers (a.k.a., protobuf) are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. You can learn more about it in protobuf's documentation.

This README file contains protobuf installation instructions. To install protobuf, you need to install the protocol compiler (used to compile .proto files) and the protobuf runtime for your chosen programming language.

Working With Protobuf Source Code

Most users will find working from supported releases to be the easiest path.

If you choose to work from the head revision of the main branch your build will occasionally be broken by source-incompatible changes and insufficiently-tested (and therefore broken) behavior.

If you are using C++ or otherwise need to build protobuf from source as a part of your project, you should pin to a release commit on a release branch.

This is because even release branches can experience some instability in between release commits.

Bazel with Bzlmod

Protobuf supports Bzlmod with Bazel 8 +. Users should specify a dependency on protobuf in their MODULE.bazel file as follows.

bazel_dep(name = "protobuf", version = <VERSION>)

Users can optionally override the repo name, such as for compatibility with WORKSPACE.

bazel_dep(name = "protobuf", version = <VERSION>, repo_name = "com_google_protobuf")

Bazel with WORKSPACE

Users can also add the following to their legacy WORKSPACE file.

Note that with the release of 30.x there are a few more load statements to properly set up rules_java and rules_python.

http_archive(
    name = "com_google_protobuf",
    strip_prefix = "protobuf-VERSION",
    sha256 = ...,
    url = ...,
)

load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")

protobuf_deps()

load("@rules_java//java:rules_java_deps.bzl", "rules_java_dependencies")

rules_java_dependencies()

load("@rules_java//java:repositories.bzl", "rules_java_toolchains")

rules_java_toolchains()

load("@rules_python//python:repositories.bzl", "py_repositories")

py_repositories()

Protobuf Compiler Installation

The protobuf compiler is written in C++. If you are using C++, please follow the C++ Installation Instructions to install protoc along with the C++ runtime.

For non-C++ users, the simplest way to install the protocol compiler is to download a pre-built binary from our GitHub release page.

In the downloads section of each release, you can find pre-built binaries in zip packages: protoc-$VERSION-$PLATFORM.zip. It contains the protoc binary as well as a set of standard .proto files distributed along with protobuf.

If you are looking for an old version that is not available in the release page, check out the Maven repository.

These pre-built binaries are only provided for released versions. If you want to use the github main version at HEAD, or you need to modify protobuf code, or you are using C++, it's recommended to build your own protoc binary from source.

If you would like to build protoc binary from source, see the C++ Installation Instructions.

Protobuf Runtime Installation

Protobuf supports several different programming languages. For each programming language, you can find instructions in the corresponding source directory about how to install protobuf runtime for that specific language:

Language	Source
C++ (include C++ runtime and protoc)	src
Java	java
Python	python
Objective-C	objectivec
C#	csharp
Ruby	ruby
Go	protocolbuffers/protobuf-go
PHP	php
Dart	dart-lang/protobuf
JavaScript	protocolbuffers/protobuf-javascript

Quick Start

The best way to learn how to use protobuf is to follow the tutorials in our developer guide.

If you want to learn from code examples, take a look at the examples in the examples directory.

Documentation

The complete documentation is available at the Protocol Buffers doc site.

Support Policy

Read about our version support policy to stay current on support timeframes for the language libraries.

Developer Community

To be alerted to upcoming changes in Protocol Buffers and connect with protobuf developers and users, join the Google Group.

aseprite/aseprite

Animated sprite editor & pixel art tool (Windows, macOS, Linux)

Aseprite

Introduction

Aseprite is a program to create animated sprites. Its main features are:

Sprites are composed of layers & frames as separated concepts.
Support for color profiles and different color modes: RGBA, Indexed (palettes up to 256 colors), Grayscale.
Animation facilities, with real-time preview and onion skinning.
Export/import animations to/from sprite sheets, GIF files, or sequence of PNG files (and FLC, FLI, JPG, BMP, PCX, TGA).
Multiple editors support.
Layer groups for organizing your work, and reference layers for rotoscoping.
Pixel-art specific tools like Pixel Perfect freehand mode, Shading ink, Custom Brushes, Outlines, Wide Pixels, etc.
Other special drawing tools like Pressure sensitivity, Symmetry Tool, Stroke and Fill selection, Gradients.
Tiled mode useful to draw patterns and textures.
Transform multiple frames/layers at the same time.
Lua scripting capabilities.
CLI - Command Line Interface to automatize tasks.
Quick Reference / Cheat Sheet keyboard shortcuts (customizable keys and mouse wheel).
Reopen closed files and recover data in case of crash.
Undo/Redo for every operation and support for non-linear undo.
More features & tips

Issues

There is a list of Known Issues (things to be fixed or that aren't yet implemented).

If you found a bug or have a new idea/feature for the program, you can report them.

Support

You can ask for help in:

Aseprite Community
Aseprite Discord Server
Official support: support@aseprite.org
Social networks and community-driven places: Twitter, Facebook, YouTube, Instagram.

Credits

Aseprite was originally created by David Capello and is now being developed and maintained by Igara Studio and contributors.

Check the AUTHORS file for details about the active team of developers working on Aseprite.

License

This program is distributed under three different licenses:

Source code and official releases/binaries are distributed under our End-User License Agreement for Aseprite (EULA). Please check that there are modules/libraries in the source code that are distributed under the MIT license (e.g. laf, clip, undo, observable, ui, etc.).
You can request a special educational license in case you are a teacher in an educational institution and want to use Aseprite in your classroom (in-situ).
Steam releases are distributed under the terms of the Steam Subscriber Agreement.

You can get more information about Aseprite license in the FAQ.

vllm-project/vllm-ascend

Community maintained hardware plugin for vLLM on Ascend

vLLM Ascend Plugin

English | 中文

Latest News 🔥

[2026/07] We released the first release candidate v0.23.0rc1! Please follow the official guide to start using vLLM Ascend Plugin on Ascend.
[2026/05] We released the new official version v0.18.0! Please follow the official guide to start using vLLM Ascend Plugin on Ascend.
[2026/02] We released the new official version v0.13.0! Please follow the official guide to start using vLLM Ascend Plugin on Ascend.

[2025/12] We released the new official version v0.11.0! Please follow the official guide to start using vLLM Ascend Plugin on Ascend.
[2025/09] We released the new official version v0.9.1! Please follow the official guide to start deploying large-scale Expert Parallelism (EP) on Ascend.
[2025/08] We hosted the vLLM Beijing Meetup with vLLM and Tencent! Please find the meetup slides.
[2025/06] User stories page is now live! It kicks off with LLaMA-Factory/verl/TRL/GPUStack to demonstrate how vLLM Ascend assists Ascend users in enhancing their experience across fine-tuning, evaluation, reinforcement learning (RL), and deployment scenarios.
[2025/06] Contributors page is now live! All contributions deserve to be recorded, thanks for all contributors.
[2025/05] We've released the first official version v0.7.3! We collaborated with the vLLM community to publish a blog post sharing our practice: Introducing vLLM Hardware Plugin, Best Practice from Ascend NPU.
[2025/03] We hosted the vLLM Beijing Meetup with vLLM team! Please find the meetup slides.
[2025/02] vLLM community officially created vllm-project/vllm-ascend repo for running vLLM seamlessly on the Ascend NPU.
[2024/12] We are working with the vLLM community to support [RFC]: Hardware pluggable.

Overview

vLLM Ascend (vllm-ascend) is a community maintained hardware plugin for running vLLM seamlessly on the Ascend NPU.

It is the recommended approach for supporting the Ascend backend within the vLLM community. It adheres to the principles outlined in the [RFC]: Hardware pluggable, providing a hardware-pluggable interface that decouples the integration of the Ascend NPU with vLLM.

By using vLLM Ascend plugin, popular open-source models, including Transformer-like, Mixture-of-Experts (MoE), Embedding, Multi-modal LLMs can run seamlessly on the Ascend NPU.

For detailed information on supported models and features, please refer to the support matrix.

Prerequisites

Hardware: Atlas 800I A2 Inference series, Atlas A2 Training series, Atlas 800I A3 Inference series, Atlas A3 Training series, Atlas 300I Duo (Experimental)
OS: Linux
Software:
- Python >= 3.10, < 3.13
- CANN == 9.1.0 (For Ascend HDK version, please refer to the Release Notes)
- PyTorch == 2.10.0, TorchNPU == 2.10.0.post4
- vLLM (the same version as vllm-ascend)

Accessing Ascend NPU

If you need to access Ascend NPU computing resources for development or testing, please visit the HiDevLab - Online Development page on the Huawei HiDevLab platform to apply for and use them.

Getting Started

Please use the following recommended versions to get started quickly:

Version	Release type	Doc
v0.23.0rc1	Latest release candidate	See QuickStart and Installation for more details
v0.18.0	Latest stable version	See QuickStart and Installation for more details

Branch

vllm-ascend has a main branch and a dev branch.

main: main branch, corresponds to the vLLM main branch, and is continuously monitored for quality through Ascend CI.
releases/vX.Y.Z: development branch, created alongside new releases of vLLM. For example, releases/v0.13.0 is the dev branch for vLLM v0.13.0 version.

Below are the maintained branches:

Branch	Status	Note
main	Maintained	CI commitment for vLLM main branch and vLLM v0.26.0 tag
releases/v0.13.0	Maintained	Only bug fixes are allowed, and no new release tags anymore.
releases/v0.18.0	Maintained	CI commitment for vLLM 0.18.0 version
releases/v0.23.0	Maintained	CI commitment for vLLM 0.23.0 version
rfc/	Maintained	Feature branches for collaboration

Please refer to Versioning policy for more details.

Contributing

See CONTRIBUTING for more details, which is a step-by-step guide to help you set up the development environment, build and test.

We welcome and value any contributions and collaborations:

Please let us know if you encounter a bug by filing an issue
Please use User forum for usage questions and help.

Weekly Meeting

vLLM Ascend Weekly Meeting: https://tinyurl.com/vllm-ascend-meeting
Wednesday, 15:00 - 16:00 (UTC+8, Convert to your timezone)

License

Apache License 2.0, as found in the LICENSE file.

ClickHouse/ClickHouse

ClickHouse® is a real-time analytics database management system

ClickHouse® is an open-source column-oriented database management system that allows generating analytical data reports in real-time.

How To Install (Linux, macOS, FreeBSD)

curl https://clickhouse.com/ | sh

Useful Links

Official website has a quick high-level overview of ClickHouse on the main page.
ClickHouse Cloud ClickHouse as a service, built by the creators and maintainers.
Tutorial shows how to set up and query a small ClickHouse cluster.
Documentation provides more in-depth information.
YouTube channel has a lot of content about ClickHouse in video format.
ClickHouse Theater contains presentations and videos about ClickHouse.
Slack and Telegram allow chatting with ClickHouse users in real-time.
Blog contains various ClickHouse-related articles, as well as announcements and reports about events.
Bluesky and X for short news.
Code Browser (github.dev) with syntax highlighting, powered by github.dev.
Contacts can help to get your questions answered if there are any.

Monthly Release & Community Call

The ClickHouse 26.7 Release Call took place on July 23, 2026 — watch the recording and the slides.

The ClickHouse 26.6 special "10 Year Anniversary" Release Call — recording and slides.

Watch all release presentations and videos at ClickHouse Theater and YouTube Playlist.

Upcoming Events

Keep an eye out for upcoming meetups and events around the world. Want to speak? Apply here You can also peruse ClickHouse Events for a list of all upcoming trainings, meetups, speaking engagements, etc.

Upcoming meetups

AI Builders Night SF - July 14th, 2026
Data Engineering Things Seattle Meetup - July 16th, 2026
Bangkok OSS & Data Evening: Queries, Code & Community - July 23rd, 2026
Happy Hour warm-up: AWS Summit Bogotá - July 30th, 2026
ClickHouse Singapore August 2026 Edition - August 4th, 2026
ClickHouse Jakarta Meetup - August 5th, 2026
AI Demo Night - August 6th, 2026
Data Engineering Meetup - August 11th, 2026
AI Demo Night - August 18th, 2026
NYC Apache Iceberg™ Community Meetup - August 20th, 2026
Bangalore Iceberg Community Meetup - August 22nd, 2026
Vancouver Meetup - August 25th, 2026
The Agentic Data Stack: Berlin - September 2nd, 2026
Amsterdam Meetup - September 15th, 2026
Cape Town Meetup - September 15th, 2026
Rows And Columns Summit - September 22nd, 2026
Paris Meetup - September 29th, 2026

Recent meetups

Happy Hour Open Source de Montréal - July 9th, 2026
AI Builders Night NY - July 8th, 2026
AI Builders Offstage: Docker & ClickHouse - July 7th, 2026
AI Demo Night SF - July 1st, 2026
KL Meetup - June 26th, 2026
Seattle Iceberg Meetup - June 25th, 2026

Recent Recordings

Recent Meetup Videos: Meetup Playlist Whenever possible recordings of the ClickHouse Community Meetups are edited and presented as individual talks.

Interested in joining ClickHouse and making it your full-time job?

ClickHouse is a nice DBMS, and it's a good place to work.

Check out our current openings here: https://clickhouse.com/company/careers

Email: careers@clickhouse.com!

godotengine/godot

Godot Engine – Multi-platform 2D and 3D game engine

Godot Engine

2D and 3D cross-platform game engine

Godot Engine is a feature-packed, cross-platform game engine to create 2D and 3D games from a unified interface. It provides a comprehensive set of common tools, so that users can focus on making games without having to reinvent the wheel. Games can be exported with one click to a number of platforms, including the major desktop platforms (Linux, macOS, Windows), mobile platforms (Android, iOS), as well as Web-based platforms and consoles.

Free, open source and community-driven

Godot is completely free and open source under the very permissive MIT license. No strings attached, no royalties, nothing. The users' games are theirs, down to the last line of engine code. Godot's development is fully independent and community-driven, empowering users to help shape their engine to match their expectations. It is supported by the Godot Foundation not-for-profit.

Before being open sourced in February 2014, Godot had been developed by Juan Linietsky and Ariel Manzur for several years as an in-house engine, used to publish several work-for-hire titles.

Getting the engine

Binary downloads

Official binaries for the Godot editor and the export templates can be found on the Godot website.

Compiling from source

See the official docs for compilation instructions for every supported platform.

Community and contributing

Godot is not only an engine but an ever-growing community of users and engine developers. The main community channels are listed on the homepage.

The best way to get in touch with the core engine developers is to join the Godot Contributors Chat.

To get started contributing to the project, see the contributing guide. This document also includes guidelines for reporting bugs.

Documentation and demos

The official documentation is hosted on Read the Docs. It is maintained by the Godot community in its own GitHub repository.

The class reference is also accessible from the Godot editor.

We also maintain official demos in their own GitHub repository as well as a list of awesome Godot community resources.

There are also a number of other learning resources provided by the community, such as text and video tutorials, demos, etc. Consult the community channels for more information.

YimMenu/YimMenuV2

Experimental menu for GTA 5: Enhanced

YimMenuV2

Experimental menu for GTA 5: Enhanced

How to use

Download the latest version of FSL from here and place WINMM.dll in your GTA V directory. Using FSL is now optional but highly recommended for account safety
Download YimMenuV2 from GitHub Releases
Download an injector, such as Xenos
Open Rockstar Launcher, select Grand Theft Auto V Enhanced, go to settings, and disable BattlEye. If you are using Steam or Epic Games, you may have to pass the -nobattleye command line parameter as well
Launch GTA V, then use your injector to inject YimMenuV2.dll at the main menu

How to open the menu?

Press the INSERT key or Ctrl+\ to open the menu

Common issues

I keep getting desynced from public sessions every five minutes

We currently do not have a BattlEye bypass, and legitimate hosts will eventually remove you due to a heartbeat failure. There is currently no way to stop this other than using an actual (private) bypass

I removed FSL and all my progress disappeared!

FSL reroutes account save data to disk, so any progress made with FSL will only show up if you have FSL enabled. If you don't want this, you can also use YimMenuV2 without FSL, but this is not recommended

I removed FSL and the game doesn't start up anymore

This is a known issue; delete "Documents/GTAV Enhanced/Profiles" to fix

nlohmann/json

JSON for Modern C++

Design goals

There are myriads of JSON libraries out there, and each may even have its reason to exist. Our class had these design goals:

Intuitive syntax. In languages such as Python, JSON feels like a first-class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the examples below and you'll know what I mean.
Trivial integration. Our whole code consists of a single header file json.hpp. That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings. The library is also included in all popular package managers.
Serious testing. Our code is heavily unit-tested and covers 100% of the code, including all exceptional behavior. Furthermore, we checked with Valgrind and the Clang Sanitizers that there are no memory leaks. Google OSS-Fuzz additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the Core Infrastructure Initiative (CII) best practices. See the quality assurance overview documentation.

Other aspects were not so important to us:

Memory efficiency. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). The default generalization uses the following C++ data types: std::string for strings, int64_t, uint64_t or double for numbers, std::map for objects, std::vector for arrays, and bool for Booleans. However, you can template the generalized class basic_json to your needs.
Speed. There are certainly faster JSON libraries out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a std::vector or std::map, you are already set.

See the contribution guidelines for more information.

Support

❓ If you have a question, please check if it is already answered in the FAQ or the Q&A section. If not, please ask a new question there.

📚 If you want to learn more about how to use the library, check out the rest of the README, have a look at code examples, or browse through the help pages.

🚧 If you want to understand the API better, check out the API Reference or have a look at the quick reference below.

🐛 If you found a bug, please check the FAQ if it is a known issue or the result of a design decision. Please also have a look at the issue list before you create a new issue. Please provide as much information as possible to help us understand and reproduce your issue.

There is also a docset for the documentation browsers Dash, Velocity, and Zeal that contains the full documentation as an offline resource.

Quick reference

Constructors basic_json, array, binary, object
Object inspection: type, operator value_t, type_name, is_primitive, is_structured, is_null, is_boolean, is_number, is_number_integer, is_number_unsigned, is_number_float, is_object, is_array, is_string, is_binary, is_discarded
Value access; get, get_to, get_ptr, get_ref, operator ValueType, get_binary
Element access: at, operator[], value, front, back
Lookup: find, count, contains
Iterators: begin, cbegin, end, cend, rbegin, rend, crbegin, crend, items
Capacity: empty, size, max_size
Modifiers: clear, push_back, operator+=, emplace_back, emplace, erase, insert, update, swap
Lexicographical comparison operators: operator==, operator!=, operator<, operator>, operator<=, operator>=, operator<=>
Serialization / Dumping: dump
Deserialization / Parsing: parse, accept, sax_parse
JSON Pointer functions: flatten, unflatten
JSON Patch functions: patch, patch_inplace, diff, merge_patch
Static functions: meta, get_allocator
Binary formats: from_bjdata, from_bson, from_cbor, from_msgpack, from_ubjson, to_bjdata, to_bson, to_cbor, to_msgpack, to_ubjson
Non-member functions: operator<<, operator>>, to_string
Literals: operator""_json
Helper classes: std::hash<basic_json>, std::swap<basic_json>

Full API documentation

Examples

Here are some examples to give you an idea how to use the class.

Besides the examples below, you may want to:

→ Check the documentation
→ Browse the standalone example files
→ Read the full API Documentation with self-contained examples for every function

Read JSON from a file

The json class provides an API for manipulating a JSON value. To create a json object by reading a JSON file:

#include <fstream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

If using modules (enabled with NLOHMANN_JSON_BUILD_MODULES), this example becomes:

import std;
import nlohmann.json;

using json = nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

Creating `json` objects from JSON literals

Assume you want to hard-code this literal JSON value as a json object:

{
  "pi": 3.141,
  "happy": true
}

There are various options:

// Using (raw) string literals and json::parse
json ex1 = json::parse(R"(
  {
    "pi": 3.141,
    "happy": true
  }
)");

// Using user-defined (raw) string literals
using namespace nlohmann::literals;
json ex2 = R"(
  {
    "pi": 3.141,
    "happy": true
  }
)"_json;

// Using initializer lists
json ex3 = {
  {"happy", true},
  {"pi", 3.141},
};

JSON as a first-class data type

Here are some examples to give you an idea how to use the class.

Assume you want to create the JSON object

{
  "pi": 3.141,
  "happy": true,
  "name": "Niels",
  "nothing": null,
  "answer": {
    "everything": 42
  },
  "list": [1, 0, 2],
  "object": {
    "currency": "USD",
    "value": 42.99
  }
}

With this library, you could write:

// create an empty structure (null)
json j;

// add a number stored as double (note the implicit conversion of j to an object)
j["pi"] = 3.141;

// add a Boolean stored as bool
j["happy"] = true;

// add a string stored as std::string
j["name"] = "Niels";

// add another null object by passing nullptr
j["nothing"] = nullptr;

// add an object inside the object
j["answer"]["everything"] = 42;

// add an array stored as std::vector (using an initializer list)
j["list"] = { 1, 0, 2 };

// add another object (using an initializer list of pairs)
j["object"] = { {"currency", "USD"}, {"value", 42.99} };

// instead, you could also write (which looks very similar to the JSON above)
json j2 = {
  {"pi", 3.141},
  {"happy", true},
  {"name", "Niels"},
  {"nothing", nullptr},
  {"answer", {
    {"everything", 42}
  }},
  {"list", {1, 0, 2}},
  {"object", {
    {"currency", "USD"},
    {"value", 42.99}
  }}
};

Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions json::array() and json::object() will help:

// a way to express the empty array []
json empty_array_explicit = json::array();

// ways to express the empty object {}
json empty_object_implicit = json({});
json empty_object_explicit = json::object();

// a way to express an _array_ of key/value pairs [["currency", "USD"], ["value", 42.99]]
json array_not_object = json::array({ {"currency", "USD"}, {"value", 42.99} });

Serialization / Deserialization

To/from strings

You can create a JSON value (deserialization) by appending _json to a string literal:

// create object from string literal
json j = "{ \"happy\": true, \"pi\": 3.141 }"_json;

// or even nicer with a raw string literal
auto j2 = R"(
  {
    "happy": true,
    "pi": 3.141
  }
)"_json;

Note that without appending the _json suffix, the passed string literal is not parsed, but just used as JSON string value. That is, json j = "{ \"happy\": true, \"pi\": 3.141 }" would just store the string "{ "happy": true, "pi": 3.141 }" rather than parsing the actual object.

The string literal should be brought into scope with using namespace nlohmann::literals; (see json::parse()).

The above example can also be expressed explicitly using json::parse():

// parse explicitly
auto j3 = json::parse(R"({"happy": true, "pi": 3.141})");

You can also get a string representation of a JSON value (serialize):

// explicit conversion to string
std::string s = j.dump();    // {"happy":true,"pi":3.141}

// serialization with pretty printing
// pass in the amount of spaces to indent
std::cout << j.dump(4) << std::endl;
// {
//     "happy": true,
//     "pi": 3.141
// }

Note the difference between serialization and assignment:

// store a string in a JSON value
json j_string = "this is a string";

// retrieve the string value
auto cpp_string = j_string.get<std::string>();
// retrieve the string value (alternative when a variable already exists)
std::string cpp_string2;
j_string.get_to(cpp_string2);

// retrieve the serialized value (explicit JSON serialization)
std::string serialized_string = j_string.dump();

// output of original string
std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::string>() << '\n';
// output of serialized value
std::cout << j_string << " == " << serialized_string << std::endl;

.dump() returns the originally stored string value.

Note the library only supports UTF-8. When you store strings with different encodings in the library, calling dump() may throw an exception unless json::error_handler_t::replace or json::error_handler_t::ignore are used as error handlers.

To/from streams (e.g., files, string streams)

You can also use streams to serialize and deserialize:

// deserialize from standard input
json j;
std::cin >> j;

// serialize to standard output
std::cout << j;

// the setw manipulator was overloaded to set the indentation for pretty printing
std::cout << std::setw(4) << j << std::endl;

These operators work for any subclasses of std::istream or std::ostream. Here is the same example with files:

// read a JSON file
std::ifstream i("file.json");
json j;
i >> j;

// write prettified JSON to another file
std::ofstream o("pretty.json");
o << std::setw(4) << j << std::endl;

Please note that setting the exception bit for failbit is inappropriate for this use case. It will result in program termination due to the noexcept specifier in use.

Read from iterator range

You can also parse JSON from an iterator range; that is, from any container accessible by iterators whose value_type is an integral type of 1, 2, or 4 bytes, which will be interpreted as UTF-8, UTF-16, and UTF-32 respectively. For instance, a std::vector<std::uint8_t>, or a std::list<std::uint16_t>:

std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'};
json j = json::parse(v.begin(), v.end());

You may leave the iterators for the range [begin, end):

std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'};
json j = json::parse(v);

Custom data source

Since the parse function accepts arbitrary iterator ranges, you can provide your own data sources by implementing the LegacyInputIterator concept.

struct MyContainer {
  void advance();
  const char& get_current();
};

struct MyIterator {
    using difference_type = std::ptrdiff_t;
    using value_type = char;
    using pointer = const char*;
    using reference = const char&;
    using iterator_category = std::input_iterator_tag;

    explicit MyIterator(MyContainer* tgt = nullptr) : target(tgt) {}

    MyIterator& operator++() {
        target->advance();
        return *this;
    }

    bool operator!=(const MyIterator& rhs) const {
        return rhs.target != target;
    }

    reference operator*() const {
        return target->get_current();
    }

    MyContainer* target = nullptr;
};

MyIterator begin(MyContainer& tgt) {
    return MyIterator{&tgt};
}

MyIterator end(const MyContainer&) {
    return MyIterator{};
}

void foo() {
    MyContainer c;
    json j = json::parse(begin(c), end(c));
}

SAX interface

The library uses a SAX-like interface with the following functions:

// called when null is parsed
bool null();

// called when a boolean is parsed; value is passed
bool boolean(bool val);

// called when a signed or unsigned integer number is parsed; value is passed
bool number_integer(number_integer_t val);
bool number_unsigned(number_unsigned_t val);

// called when a floating-point number is parsed; value and original string is passed
bool number_float(number_float_t val, const string_t& s);

// called when a string is parsed; value is passed and can be safely moved away
bool string(string_t& val);
// called when a binary value is parsed; value is passed and can be safely moved away
bool binary(binary_t& val);

// called when an object or array begins or ends, resp. The number of elements is passed (or -1 if not known)
bool start_object(std::size_t elements);
bool end_object();
bool start_array(std::size_t elements);
bool end_array();
// called when an object key is parsed; value is passed and can be safely moved away
bool key(string_t& val);

// called when a parse error occurs; byte position, the last token, and an exception is passed
bool parse_error(std::size_t position, const std::string& last_token, const detail::exception& ex);

The return value of each function determines whether parsing should proceed.

To implement your own SAX handler, proceed as follows:

Implement the SAX interface in a class. You can use class nlohmann::json_sax<json> as base class, but you can also use any class where the functions described above are implemented and public.
Create an object of your SAX interface class, e.g. my_sax.
Call bool json::sax_parse(input, &my_sax); where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.

Note the sax_parse function only returns a bool indicating the result of the last executed SAX event. It does not return a json value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error -- it is up to you what to do with the exception object passed to your parse_error implementation. Internally, the SAX interface is used for the DOM parser (class json_sax_dom_parser) as well as the acceptor (json_sax_acceptor), see file json_sax.hpp.

STL-like access

We designed the JSON class to behave just like an STL container. In fact, it satisfies the ReversibleContainer requirement.

// create an array using push_back
json j;
j.push_back("foo");
j.push_back(1);
j.push_back(true);

// also use emplace_back
j.emplace_back(1.78);

// iterate the array
for (json::iterator it = j.begin(); it != j.end(); ++it) {
  std::cout << *it << '\n';
}

// range-based for
for (auto& element : j) {
  std::cout << element << '\n';
}

// getter/setter
const auto tmp = j[0].get<std::string>();
j[1] = 42;
bool foo = j.at(2);

// comparison
j == R"(["foo", 1, true, 1.78])"_json;  // true

// other stuff
j.size();     // 4 entries
j.empty();    // false
j.type();     // json::value_t::array
j.clear();    // the array is empty again

// convenience type checkers
j.is_null();
j.is_boolean();
j.is_number();
j.is_object();
j.is_array();
j.is_string();

// create an object
json o;
o["foo"] = 23;
o["bar"] = false;
o["baz"] = 3.141;

// also use emplace
o.emplace("weather", "sunny");

// special iterator member functions for objects
for (json::iterator it = o.begin(); it != o.end(); ++it) {
  std::cout << it.key() << " : " << it.value() << "\n";
}

// the same code as range for
for (auto& el : o.items()) {
  std::cout << el.key() << " : " << el.value() << "\n";
}

// even easier with structured bindings (C++17)
for (auto& [key, value] : o.items()) {
  std::cout << key << " : " << value << "\n";
}

// find an entry
if (o.contains("foo")) {
  // there is an entry with key "foo"
}

// or via find and an iterator
if (o.find("foo") != o.end()) {
  // there is an entry with key "foo"
}

// or simpler using count()
int foo_present = o.count("foo"); // 1
int fob_present = o.count("fob"); // 0

// delete an entry
o.erase("foo");

Conversion from STL containers

Any sequence container (std::array, std::vector, std::deque, std::forward_list, std::list) whose values can be used to construct JSON values (e.g., integers, floating point numbers, Booleans, string types, or again STL containers described in this section) can be used to create a JSON array. The same holds for similar associative containers (std::set, std::multiset, std::unordered_set, std::unordered_multiset), but in these cases the order of the elements of the array depends on how the elements are ordered in the respective STL container.

std::vector<int> c_vector {1, 2, 3, 4};
json j_vec(c_vector);
// [1, 2, 3, 4]

std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
json j_deque(c_deque);
// [1.2, 2.3, 3.4, 5.6]

std::list<bool> c_list {true, true, false, true};
json j_list(c_list);
// [true, true, false, true]

std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
json j_flist(c_flist);
// [12345678909876, 23456789098765, 34567890987654, 45678909876543]

std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
json j_array(c_array);
// [1, 2, 3, 4]

std::set<std::string> c_set {"one", "two", "three", "four", "one"};
json j_set(c_set); // only one entry for "one" is used
// ["four", "one", "three", "two"]

std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
json j_uset(c_uset); // only one entry for "one" is used
// maybe ["two", "three", "four", "one"]

std::multiset<std::string> c_mset {"one", "two", "one", "four"};
json j_mset(c_mset); // both entries for "one" are used
// maybe ["one", "two", "one", "four"]

std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
json j_umset(c_umset); // both entries for "one" are used
// maybe ["one", "two", "one", "four"]

Likewise, any associative key-value containers (std::map, std::multimap, std::unordered_map, std::unordered_multimap) whose keys can construct an std::string and whose values can be used to construct JSON values (see examples above) can be used to create a JSON object. Note that in case of multimaps, only one key is used in the JSON object and the value depends on the internal order of the STL container.

std::map<std::string, int> c_map { {"one", 1}, {"two", 2}, {"three", 3} };
json j_map(c_map);
// {"one": 1, "three": 3, "two": 2 }

std::unordered_map<const char*, double> c_umap { {"one", 1.2}, {"two", 2.3}, {"three", 3.4} };
json j_umap(c_umap);
// {"one": 1.2, "two": 2.3, "three": 3.4}

std::multimap<std::string, bool> c_mmap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_mmap(c_mmap); // only one entry for key "three" is used
// maybe {"one": true, "two": true, "three": true}

std::unordered_multimap<std::string, bool> c_ummap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_ummap(c_ummap); // only one entry for key "three" is used
// maybe {"one": true, "two": true, "three": true}

JSON Pointer and JSON Patch

The library supports JSON Pointer (RFC 6901) as an alternative means to address structured values. On top of this, JSON Patch (RFC 6902) allows describing differences between two JSON values -- effectively allowing patch and diff operations known from Unix.

// a JSON value
json j_original = R"({
  "baz": ["one", "two", "three"],
  "foo": "bar"
})"_json;

// access members with a JSON pointer (RFC 6901)
j_original["/baz/1"_json_pointer];
// "two"

// a JSON patch (RFC 6902)
json j_patch = R"([
  { "op": "replace", "path": "/baz", "value": "boo" },
  { "op": "add", "path": "/hello", "value": ["world"] },
  { "op": "remove", "path": "/foo"}
])"_json;

// apply the patch
json j_result = j_original.patch(j_patch);
// {
//    "baz": "boo",
//    "hello": ["world"]
// }

// calculate a JSON patch from two JSON values
json::diff(j_result, j_original);
// [
//   { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
//   { "op": "remove","path": "/hello" },
//   { "op": "add", "path": "/foo", "value": "bar" }
// ]

JSON Merge Patch

The library supports JSON Merge Patch (RFC 7386) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.

// a JSON value
json j_document = R"({
  "a": "b",
  "c": {
    "d": "e",
    "f": "g"
  }
})"_json;

// a patch
json j_patch = R"({
  "a":"z",
  "c": {
    "f": null
  }
})"_json;

// apply the patch
j_document.merge_patch(j_patch);
// {
//  "a": "z",
//  "c": {
//    "d": "e"
//  }
// }

Implicit conversions

Supported types can be implicitly converted to JSON values.

It is recommended to NOT USE implicit conversions FROM a JSON value. You can find more details about this recommendation here. You can switch off implicit conversions by defining JSON_USE_IMPLICIT_CONVERSIONS to 0 before including the json.hpp header. When using CMake, you can also achieve this by setting the option JSON_ImplicitConversions to OFF.

// strings
std::string s1 = "Hello, world!";
json js = s1;
auto s2 = js.get<std::string>();
// NOT RECOMMENDED
std::string s3 = js;
std::string s4;
s4 = js;

// Booleans
bool b1 = true;
json jb = b1;
auto b2 = jb.get<bool>();
// NOT RECOMMENDED
bool b3 = jb;
bool b4;
b4 = jb;

// numbers
int i = 42;
json jn = i;
auto f = jn.get<double>();
// NOT RECOMMENDED
double f2 = jn;
double f3;
f3 = jn;

// etc.

Note that char types are not automatically converted to JSON strings, but to integer numbers. A conversion to a string must be specified explicitly:

char ch = 'A';                       // ASCII value 65
json j_default = ch;                 // stores integer number 65
json j_string = std::string(1, ch);  // stores string "A"

Arbitrary types conversions

Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:

namespace ns {
    // a simple struct to model a person
    struct person {
        std::string name;
        std::string address;
        int age;
    };
}

ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};

// convert to JSON: copy each value into the JSON object
json j;
j["name"] = p.name;
j["address"] = p.address;
j["age"] = p.age;

// ...

// convert from JSON: copy each value from the JSON object
ns::person p {
    j["name"].get<std::string>(),
    j["address"].get<std::string>(),
    j["age"].get<int>()
};

It works, but that's quite a lot of boilerplate... Fortunately, there's a better way:

// create a person
ns::person p {"Ned Flanders", "744 Evergreen Terrace", 60};

// conversion: person -> json
json j = p;

std::cout << j << std::endl;
// {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}

// conversion: json -> person
auto p2 = j.get<ns::person>();

// that's it
assert(p == p2);

Basic usage

To make this work with one of your types, you only need to provide two functions:

using json = nlohmann::json;

namespace ns {
    void to_json(json& j, const person& p) {
        j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}};
    }

    void from_json(const json& j, person& p) {
        j.at("name").get_to(p.name);
        j.at("address").get_to(p.address);
        j.at("age").get_to(p.age);
    }
} // namespace ns

That's all! When calling the json constructor with your type, your custom to_json method will be automatically called. Likewise, when calling get<your_type>() or get_to(your_type&), the from_json method will be called.

Some important things:

Those methods MUST be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace ns, where person is defined).
Those methods MUST be available (e.g., proper headers must be included) everywhere you use these conversions. Look at issue 1108 for errors that may occur otherwise.
When using get<your_type>(), your_type MUST be DefaultConstructible. (There is a way to bypass this requirement described later.)
In function from_json, use function at() to access the object values rather than operator[]. In case a key does not exist, at throws an exception that you can handle, whereas operator[] exhibits undefined behavior.
You do not need to add serializers or deserializers for STL types like std::vector: the library already implements these.

Simplify your life with macros

If you just want to serialize/deserialize some structs, the to_json/from_json functions can be a lot of boilerplate. There are several macros to make your life easier as long as you want to use a JSON object as serialization.

Which macro to choose depends on whether private member variables need to be accessed, a deserialization is needed, missing values should yield an error or should be replaced by default values, and if derived classes are used. See this overview to choose the right one for your use case.

Example usage of macros

The to_json/from_json functions for the person struct above can be created with NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE. In all macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.

namespace ns {
    NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(person, name, address, age)
}

If you want to inherit the person struct and add a field to it, it can be done with:

namespace ns {
    struct person_derived : person {
        std::string email;
    };
    
    NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(person_derived, person, email)
}

Here is another example with private members, where NLOHMANN_DEFINE_TYPE_INTRUSIVE is needed:

namespace ns {
    class address {
      private:
        std::string street;
        int housenumber;
        int postcode;
  
      public:
        NLOHMANN_DEFINE_TYPE_INTRUSIVE(address, street, housenumber, postcode)
    };
}

Or in case if you use some naming convention that you do not want to expose to JSON:

namespace ns {
    class address {
      private:
        std::string m_street;
        int m_housenumber;
        int m_postcode;

      public:
        NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES(address, "street", m_street,
                                                           "housenumber", m_housenumber,
                                                           "postcode", m_postcode)
    };
}

How do I convert third-party types?

This requires a bit more advanced technique. But first, let's see how this conversion mechanism works:

The library uses JSON Serializers to convert types to JSON. The default serializer for nlohmann::json is nlohmann::adl_serializer (ADL means Argument-Dependent Lookup).

It is implemented like this (simplified):

template <typename T>
struct adl_serializer {
    static void to_json(json& j, const T& value) {
        // calls the "to_json" method in T's namespace
    }

    static void from_json(const json& j, T& value) {
        // same thing, but with the "from_json" method
    }
};

This serializer works fine when you have control over the type's namespace. However, what about boost::optional or std::filesystem::path (C++17)? Hijacking the boost namespace is pretty bad, and it's illegal to add something other than template specializations to std...

To solve this, you need to add a specialization of adl_serializer to the nlohmann namespace, here's an example:

// partial specialization (full specialization works too)
namespace nlohmann {
    template <typename T>
    struct adl_serializer<boost::optional<T>> {
        static void to_json(json& j, const boost::optional<T>& opt) {
            if (opt == boost::none) {
                j = nullptr;
            } else {
              j = *opt; // this will call adl_serializer<T>::to_json which will
                        // find the free function to_json in T's namespace!
            }
        }

        static void from_json(const json& j, boost::optional<T>& opt) {
            if (j.is_null()) {
                opt = boost::none;
            } else {
                opt = j.get<T>(); // same as above, but with
                                  // adl_serializer<T>::from_json
            }
        }
    };
}

How can I use `get()` for non-default constructible/non-copyable types?

There is a way if your type is MoveConstructible. You will need to specialize the adl_serializer as well, but with a special from_json overload:

struct move_only_type {
    move_only_type() = delete;
    move_only_type(int ii): i(ii) {}
    move_only_type(const move_only_type&) = delete;
    move_only_type(move_only_type&&) = default;

    int i;
};

namespace nlohmann {
    template <>
    struct adl_serializer<move_only_type> {
        // note: the return type is no longer 'void', and the method only takes
        // one argument
        static move_only_type from_json(const json& j) {
            return {j.get<int>()};
        }

        // Here's the catch! You must provide a to_json method! Otherwise, you
        // will not be able to convert move_only_type to json, since you fully
        // specialized adl_serializer on that type
        static void to_json(json& j, move_only_type t) {
            j = t.i;
        }
    };
}

Can I write my own serializer? (Advanced use)

Yes. You might want to take a look at unit-udt.cpp in the test suite, to see a few examples.

If you write your own serializer, you'll need to do a few things:

use a different basic_json alias than nlohmann::json (the last template parameter of basic_json is the JSONSerializer)
use your basic_json alias (or a template parameter) in all your to_json/from_json methods
use nlohmann::to_json and nlohmann::from_json when you need ADL

Here is an example, without simplifications, that only accepts types with a size <= 32, and uses ADL.

// You should use void as a second template argument
// if you don't need compile-time checks on T
template<typename T, typename SFINAE = typename std::enable_if<sizeof(T) <= 32>::type>
struct less_than_32_serializer {
    template <typename BasicJsonType>
    static void to_json(BasicJsonType& j, T value) {
        // we want to use ADL, and call the correct to_json overload
        using nlohmann::to_json; // this method is called by adl_serializer,
                                 // this is where the magic happens
        to_json(j, value);
    }

    template <typename BasicJsonType>
    static void from_json(const BasicJsonType& j, T& value) {
        // same thing here
        using nlohmann::from_json;
        from_json(j, value);
    }
};

Be very careful when reimplementing your serializer, you can stack overflow if you don't pay attention:

template <typename T, void>
struct bad_serializer
{
    template <typename BasicJsonType>
    static void to_json(BasicJsonType& j, const T& value) {
      // this calls BasicJsonType::json_serializer<T>::to_json(j, value)
      // if BasicJsonType::json_serializer == bad_serializer ... oops!
      j = value;
    }

    template <typename BasicJsonType>
    static void to_json(const BasicJsonType& j, T& value) {
      // this calls BasicJsonType::json_serializer<T>::from_json(j, value)
      // if BasicJsonType::json_serializer == bad_serializer ... oops!
      value = j.get<T>(); // oops!
    }
};

Specializing enum conversion

By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later deserialized JSON data may be undefined or a different enum value than was originally intended.

It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:

// example enum type declaration
enum TaskState {
    TS_STOPPED,
    TS_RUNNING,
    TS_COMPLETED,
    TS_INVALID=-1,
};

// map TaskState values to JSON as strings
NLOHMANN_JSON_SERIALIZE_ENUM( TaskState, {
    {TS_INVALID, nullptr},
    {TS_STOPPED, "stopped"},
    {TS_RUNNING, "running"},
    {TS_COMPLETED, "completed"},
})

The NLOHMANN_JSON_SERIALIZE_ENUM() macro declares a set of to_json() / from_json() functions for type TaskState while avoiding repetition and boilerplate serialization code.

Usage:

// enum to JSON as string
json j = TS_STOPPED;
assert(j == "stopped");

// json string to enum
json j3 = "running";
assert(j3.get<TaskState>() == TS_RUNNING);

// undefined json value to enum (where the first map entry above is the default)
json jPi = 3.14;
assert(jPi.get<TaskState>() == TS_INVALID);

Just as in Arbitrary Type Conversions above,

NLOHMANN_JSON_SERIALIZE_ENUM() MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it, and it will default to integer serialization.
It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.

Other Important points:

When using get<ENUM_TYPE>(), undefined JSON values will default to the first pair specified in your map. Select this default pair carefully. If you desire an exception in this circumstance use NLOHMANN_JSON_SERIALIZE_ENUM_STRICT() which behaves identically except for throwing an exception on unrecognized values.
If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.

Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)

Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports BSON (Binary JSON), CBOR (Concise Binary Object Representation), MessagePack, UBJSON (Universal Binary JSON Specification) and BJData (Binary JData) to efficiently encode JSON values to byte vectors and to decode such vectors.

// create a JSON value
json j = R"({"compact": true, "schema": 0})"_json;

// serialize to BSON
std::vector<std::uint8_t> v_bson = json::to_bson(j);

// 0x1B, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00

// roundtrip
json j_from_bson = json::from_bson(v_bson);

// serialize to CBOR
std::vector<std::uint8_t> v_cbor = json::to_cbor(j);

// 0xA2, 0x67, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xF5, 0x66, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00

// roundtrip
json j_from_cbor = json::from_cbor(v_cbor);

// serialize to MessagePack
std::vector<std::uint8_t> v_msgpack = json::to_msgpack(j);

// 0x82, 0xA7, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xC3, 0xA6, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00

// roundtrip
json j_from_msgpack = json::from_msgpack(v_msgpack);

// serialize to UBJSON
std::vector<std::uint8_t> v_ubjson = json::to_ubjson(j);

// 0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D

// roundtrip
json j_from_ubjson = json::from_ubjson(v_ubjson);

The library also supports binary types from BSON, CBOR (byte strings), and MessagePack (bin, ext, fixext). They are stored by default as std::vector<std::uint8_t> to be processed outside the library.

// CBOR byte string with payload 0xCAFE
std::vector<std::uint8_t> v = {0x42, 0xCA, 0xFE};

// read value
json j = json::from_cbor(v);

// the JSON value has type binary
j.is_binary(); // true

// get reference to stored binary value
auto& binary = j.get_binary();

// the binary value has no subtype (CBOR has no binary subtypes)
binary.has_subtype(); // false

// access std::vector<std::uint8_t> member functions
binary.size(); // 2
binary[0]; // 0xCA
binary[1]; // 0xFE

// set subtype to 0x10
binary.set_subtype(0x10);

// serialize to MessagePack
auto cbor = json::to_msgpack(j); // 0xD5 (fixext2), 0x10, 0xCA, 0xFE

Customers

The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know, see contact.

Ecosystem

Beyond projects that use the library, there are third-party projects that build on top of it - schema validators, language bindings, format converters, and the like. See the curated Ecosystem page.

Supported compilers

Though it's 2026 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:

GCC 4.8 - 14.2 (and possibly later)
Clang 3.4 - 21.0 (and possibly later)
Apple Clang 9.1 - 16.0 (and possibly later)
Intel C++ Compiler 17.0.2 (and possibly later)
Nvidia CUDA Compiler 11.0.221 (and possibly later)
Microsoft Visual C++ 2015 / Build Tools 14.0.25123.0 (and possibly later)
Microsoft Visual C++ 2017 / Build Tools 15.5.180.51428 (and possibly later)
Microsoft Visual C++ 2019 / Build Tools 16.3.1+1def00d3d (and possibly later)
Microsoft Visual C++ 2022 / Build Tools 19.30.30709.0 (and possibly later)

I would be happy to learn about other compilers/versions.

Please note:

GCC 4.8 has a bug 57824: multiline raw strings cannot be the arguments to macros. Don't use multiline raw strings directly in macros with this compiler.
Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your Application.mk. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
```
APP_STL := c++_shared
NDK_TOOLCHAIN_VERSION := clang3.6
APP_CPPFLAGS += -frtti -fexceptions
```
The code compiles successfully with Android NDK, Revision 9 - 11 (and possibly later) and CrystaX's Android NDK version 10.
For GCC running on MinGW or Android SDK, the error 'to_string' is not a member of 'std' (or similarly, for strtod or strtof) may occur. Note this is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to this site and this discussion for information on how to fix this bug. For Android NDK using APP_STL := gnustl_static, please refer to this discussion.
Unsupported versions of GCC and Clang are rejected by #error directives. This can be switched off by defining JSON_SKIP_UNSUPPORTED_COMPILER_CHECK. Note that you can expect no support in this case.

See the page quality assurance on the compilers used to check the library in the CI.

Integration

json.hpp is the single required file in single_include/nlohmann or released here. You need to add

#include <nlohmann/json.hpp>

// for convenience
using json = nlohmann::json;

to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., -std=c++11 for GCC and Clang).

You can further use file include/nlohmann/json_fwd.hpp for forward-declarations. The installation of json_fwd.hpp (as part of cmake's install step) can be achieved by setting -DJSON_MultipleHeaders=ON.

CMake

You can also use the nlohmann_json::nlohmann_json interface target in CMake. This target populates the appropriate usage requirements for INTERFACE_INCLUDE_DIRECTORIES to point to the appropriate include directories and INTERFACE_COMPILE_FEATURES for the necessary C++11 flags.

External

To use this library from a CMake project, you can locate it directly with find_package() and use the namespaced imported target from the generated package configuration:

# CMakeLists.txt
find_package(nlohmann_json 3.12.0 REQUIRED)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

The package configuration file, nlohmann_jsonConfig.cmake, can be used either from an install tree or directly out of the build tree.

Embedded

To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call add_subdirectory() in your CMakeLists.txt file:

# Typically you don't care so much for a third party library's tests to be
# run from your own project's code.
set(JSON_BuildTests OFF CACHE INTERNAL "")

# If you only include this third party in PRIVATE source files, you do not
# need to install it when your main project gets installed.
# set(JSON_Install OFF CACHE INTERNAL "")

# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
# unintended consequences that will break the build.  It's generally
# discouraged (although not necessarily well documented as such) to use
# include(...) for pulling in other CMake projects anyways.
add_subdirectory(nlohmann_json)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

Embedded (FetchContent)

Since CMake v3.11, FetchContent can be used to automatically download a release as a dependency at configure time.

Example:

include(FetchContent)

FetchContent_Declare(json URL https://github.com/nlohmann/json/releases/download/v3.12.0/json.tar.xz)
FetchContent_MakeAvailable(json)

target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

Note: It is recommended to use the URL approach described above, which is supported as of version 3.10.0. See https://json.nlohmann.me/integration/cmake/#fetchcontent for more information.

Supporting Both

To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:

# Top level CMakeLists.txt
project(FOO)
...
option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
...
add_subdirectory(thirdparty)
...
add_library(foo ...)
...
# Note that the namespaced target will always be available regardless of the
# import method
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

# thirdparty/CMakeLists.txt
...
if(FOO_USE_EXTERNAL_JSON)
  find_package(nlohmann_json 3.12.0 REQUIRED)
else()
  set(JSON_BuildTests OFF CACHE INTERNAL "")
  add_subdirectory(nlohmann_json)
endif()
...

thirdparty/nlohmann_json is then a complete copy of this source tree.

Package Managers

Use your favorite package manager to use the library.

Homebrew nlohmann-json
Meson nlohmann_json
Bazel nlohmann_json
Conan nlohmann_json
Spack nlohmann-json
Hunter nlohmann_json
vcpkg nlohmann-json
cget nlohmann/json
Swift Package Manager nlohmann/json
Nuget nlohmann.json
Conda nlohmann_json
MacPorts nlohmann-json
cpm.cmake gh:nlohmann/json
xmake nlohmann_json

The library is part of many package managers. See the documentation for detailed descriptions and examples.

Pkg-config

If you are using bare Makefiles, you can use pkg-config to generate the include flags that point to where the library is installed:

pkg-config nlohmann_json --cflags

License

The class is licensed under the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed under the MIT License (see above). Copyright © 2008-2009 Björn Hoehrmann bjoern@hoehrmann.de
The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the MIT License (see above). Copyright © 2009 Florian Loitsch
The class contains a copy of Hedley from Evan Nemerson which is licensed as CC0-1.0.
The class contains parts of Google Abseil which is licensed under the Apache 2.0 License.

The library is compliant to version 3.3 of the REUSE specification:

Every source file contains an SPDX copyright header.
The full text of all licenses used in the repository can be found in the LICENSES folder.
File .reuse/dep5 contains an overview of all files' copyrights and licenses.
Run pipx run reuse lint to verify the project's REUSE compliance and pipx run reuse spdx to generate a SPDX SBOM.

Contact

If you have questions regarding the library, I would like to invite you to open an issue at GitHub. Please describe your request, problem, or question as detailed as possible, and also mention the version of the library you are using as well as the version of your compiler and operating system. Opening an issue at GitHub allows other users and contributors to this library to collaborate. For instance, I have little experience with MSVC, and most issues in this regard have been solved by a growing community. If you have a look at the closed issues, you will see that we react quite timely in most cases.

Only if your request would contain confidential information, please send me an email. For encrypted messages, please use this key.

Security

Commits by Niels Lohmann and releases are signed with this PGP Key.

Thanks

I deeply appreciate the help of the following people.

Teemperor implemented CMake support and lcov integration, realized escape and Unicode handling in the string parser, and fixed the JSON serialization.
elliotgoodrich fixed an issue with double deletion in the iterator classes.
kirkshoop made the iterators of the class composable to other libraries.
wancw fixed a bug that hindered the class to compile with Clang.
Tomas Åblad found a bug in the iterator implementation.
Joshua C. Randall fixed a bug in the floating-point serialization.
Aaron Burghardt implemented code to parse streams incrementally. Furthermore, he greatly improved the parser class by allowing the definition of a filter function to discard undesired elements while parsing.
Daniel Kopeček fixed a bug in the compilation with GCC 5.0.
Florian Weber fixed a bug in and improved the performance of the comparison operators.
Eric Cornelius pointed out a bug in the handling with NaN and infinity values. He also improved the performance of the string escaping.
易思龙 implemented a conversion from anonymous enums.
kepkin patiently pushed forward the support for Microsoft Visual Studio.
gregmarr simplified the implementation of reverse iterators and helped with numerous hints and improvements. In particular, he pushed forward the implementation of user-defined types.
Caio Luppi fixed a bug in the Unicode handling.
dariomt fixed some typos in the examples.
Daniel Frey cleaned up some pointers and implemented exception-safe memory allocation.
Colin Hirsch took care of a small namespace issue.
Huu Nguyen corrected a variable name in the documentation.
Silverweed overloaded parse() to accept an rvalue reference.
dariomt fixed a subtlety in MSVC type support and implemented the get_ref() function to get a reference to stored values.
ZahlGraf added a workaround that allows compilation using Android NDK.
whackashoe replaced a function that was marked as unsafe by Visual Studio.
406345 fixed two small warnings.
Glen Fernandes noted a potential portability problem in the has_mapped_type function.
Corbin Hughes fixed some typos in the contribution guidelines.
twelsby fixed the array subscript operator, an issue that failed the MSVC build, and floating-point parsing/dumping. He further added support for unsigned integer numbers and implemented better roundtrip support for parsed numbers.
Volker Diels-Grabsch fixed a link in the README file.
msm- added support for American Fuzzy Lop.
Annihil fixed an example in the README file.
Themercee noted a wrong URL in the README file.
Lv Zheng fixed a namespace issue with int64_t and uint64_t.
abc100m analyzed the issues with GCC 4.8 and proposed a partial solution.
zewt added useful notes to the README file about Android.
Róbert Márki added a fix to use move iterators and improved the integration via CMake.
Chris Kitching cleaned up the CMake files.
Tom Needham fixed a subtle bug with MSVC 2015 which was also proposed by Michael K..
Mário Feroldi fixed a small typo.
duncanwerner found a really embarrassing performance regression in the 2.0.0 release.
Damien fixed one of the last conversion warnings.
Thomas Braun fixed a warning in a test case and adjusted MSVC calls in the CI.
Théo DELRIEU patiently and constructively oversaw the long way toward iterator-range parsing. He also implemented the magic behind the serialization/deserialization of user-defined types and split the single header file into smaller chunks.
Stefan fixed a minor issue in the documentation.
Vasil Dimov fixed the documentation regarding conversions from std::multiset.
ChristophJud overworked the CMake files to ease project inclusion.
Vladimir Petrigo made a SFINAE hack more readable and added Visual Studio 17 to the build matrix.
Denis Andrejew fixed a grammar issue in the README file.
Pierre-Antoine Lacaze found a subtle bug in the dump() function.
TurpentineDistillery pointed to std::locale::classic() to avoid too much locale joggling, found some nice performance improvements in the parser, improved the benchmarking code, and realized locale-independent number parsing and printing.
cgzones had an idea how to fix the Coverity scan.
Jared Grubb silenced a nasty documentation warning.
Yixin Zhang fixed an integer overflow check.
Bosswestfalen merged two iterator classes into a smaller one.
Daniel599 helped to get Travis to execute the tests with Clang's sanitizers.
Jonathan Lee fixed an example in the README file.
gnzlbg supported the implementation of user-defined types.
Alexej Harm helped to get the user-defined types working with Visual Studio.
Jared Grubb supported the implementation of user-defined types.
EnricoBilla noted a typo in an example.
Martin Hořeňovský found a way for a 2x speedup for the compilation time of the test suite.
ukhegg proposed an improvement for the examples section.
rswanson-ihi noted a typo in the README.
Mihai Stan fixed a bug in the comparison with nullptrs.
Tushar Maheshwari added cotire support to speed up the compilation.
TedLyngmo noted a typo in the README, removed unnecessary bit arithmetic, and fixed some -Weffc++ warnings.
Krzysztof Woś made exceptions more visible.
ftillier fixed a compiler warning.
tinloaf made sure all pushed warnings are properly popped.
Fytch found a bug in the documentation.
Jay Sistar implemented a Meson build description.
Henry Lee fixed a warning in ICC and improved the iterator implementation.
Vincent Thiery maintains a package for the Conan package manager.
Steffen fixed a potential issue with MSVC and std::min.
Mike Tzou fixed some typos.
amrcode noted misleading documentation about comparison of floats.
Oleg Endo reduced the memory consumption by replacing <iostream> with <iosfwd>.
dan-42 cleaned up the CMake files to simplify including/reusing of the library.
Nikita Ofitserov allowed for moving values from initializer lists.
Greg Hurrell fixed a typo.
Dmitry Kukovinets fixed a typo.
kbthomp1 fixed an issue related to the Intel OSX compiler.
Markus Werle fixed a typo.
WebProdPP fixed a subtle error in a precondition check.
Alex noted an error in a code sample.
Tom de Geus reported some warnings with ICC and helped to fix them.
Perry Kundert simplified reading from input streams.
Sonu Lohani fixed a small compilation error.
Jamie Seward fixed all MSVC warnings.
Nate Vargas added a Doxygen tag file.
pvleuven helped to fix a warning in ICC.
Pavel helped to fix some warnings in MSVC.
Jamie Seward avoided unnecessary string copies in find() and count().
Mitja fixed some typos.
Jorrit Wronski updated the Hunter package links.
Matthias Möller added a .natvis for the MSVC debug view.
bogemic fixed some C++17 deprecation warnings.
Eren Okka fixed some MSVC warnings.
abolz integrated the Grisu2 algorithm for proper floating-point formatting, allowing more roundtrip checks to succeed.
Vadim Evard fixed a Markdown issue in the README.
zerodefect fixed a compiler warning.
Kert allowed to template the string type in the serialization and added the possibility to override the exceptional behavior.
mark-99 helped fix an ICC error.
Patrik Huber fixed links in the README file.
johnfb found a bug in the implementation of CBOR's indefinite length strings.
Paul Fultz II added a note on the cget package manager.
Wilson Lin made the integration section of the README more concise.
RalfBielig detected and fixed a memory leak in the parser callback.
agrianius allowed dumping JSON to an alternative string type.
Kevin Tonon overworked the C++11 compiler checks in CMake.
Axel Huebl simplified a CMake check and added support for the Spack package manager.
Carlos O'Ryan fixed a typo.
James Upjohn fixed a version number in the compilers section.
Chuck Atkins adjusted the CMake files to the CMake packaging guidelines and provided documentation for the CMake integration.
Jan Schöppach fixed a typo.
martin-mfg fixed a typo.
Matthias Möller removed the dependency from std::stringstream.
agrianius added code to use alternative string implementations.
Daniel599 allowed to use more algorithms with the items() function.
Julius Rakow fixed the Meson include directory and fixed the links to cppreference.com.
Sonu Lohani fixed the compilation with MSVC 2015 in debug mode.
grembo fixed the test suite and re-enabled several test cases.
Hyeon Kim introduced the macro JSON_INTERNAL_CATCH to control the exception handling inside the library.
thyu fixed a compiler warning.
David Guthrie fixed a subtle compilation error with Clang 3.4.2.
Dennis Fischer allowed to call find_package without installing the library.
Hyeon Kim fixed an issue with a double macro definition.
Ben Berman made some error messages more understandable.
zakalibit fixed a compilation problem with the Intel C++ compiler.
mandreyel fixed a compilation problem.
Kostiantyn Ponomarenko added version and license information to the Meson build file.
Henry Schreiner added support for GCC 4.8.
knilch made sure the test suite does not stall when run in the wrong directory.
Antonio Borondo fixed an MSVC 2017 warning.
Dan Gendreau implemented the NLOHMANN_JSON_SERIALIZE_ENUM macro to quickly define an enum/JSON mapping.
efp added line and column information to parse errors.
julian-becker added BSON support.
Pratik Chowdhury added support for structured bindings.
David Avedissian added support for Clang 5.0.1 (PS4 version).
Jonathan Dumaresq implemented an input adapter to read from FILE*.
kjpus fixed a link in the documentation.
Manvendra Singh fixed a typo in the documentation.
ziggurat29 fixed an MSVC warning.
Sylvain Corlay added code to avoid an issue with MSVC.
mefyl fixed a bug when JSON was parsed from an input stream.
Millian Poquet allowed to install the library via Meson.
Michael Behrns-Miller found an issue with a missing namespace.
Nasztanovics Ferenc fixed a compilation issue with libc 2.12.
Andreas Schwab fixed the endian conversion.
Mark-Dunning fixed a warning in MSVC.
Gareth Sylvester-Bradley added operator/ for JSON Pointers.
John-Mark noted a missing header.
Vitaly Zaitsev fixed compilation with GCC 9.0.
Laurent Stacul fixed compilation with GCC 9.0.
Ivor Wanders helped to reduce the CMake requirement to version 3.1.
njlr updated the Buckaroo instructions.
Lion fixed a compilation issue with GCC 7 on CentOS.
Isaac Nickaein improved the integer serialization performance and implemented the contains() function.
past-due suppressed an unfixable warning.
Elvis Oric improved Meson support.
Matěj Plch fixed an example in the README.
Mark Beckwith fixed a typo.
scinart fixed a bug in the serializer.
Patrick Boettcher implemented push_back() and pop_back() for JSON Pointers.
Bruno Oliveira added support for Conda.
Michele Caini fixed links in the README.
Hani documented how to install the library with NuGet.
Mark Beckwith fixed a typo.
yann-morin-1998 helped to reduce the CMake requirement to version 3.1.
Konstantin Podsvirov maintains a package for the MSYS2 software distro.
remyabel added GNUInstallDirs to the CMake files.
Taylor Howard fixed a unit test.
Gabe Ron implemented the to_string method.
Watal M. Iwasaki fixed a Clang warning.
Viktor Kirilov switched the unit tests from Catch to doctest
Juncheng E fixed a typo.
tete17 fixed a bug in the contains function.
Xav83 fixed some cppcheck warnings.
0xflotus fixed some typos.
Christian Deneke added a const version of json_pointer::back.
Julien Hamaide made the items() function work with custom string types.
Evan Nemerson updated fixed a bug in Hedley and updated this library accordingly.
Florian Pigorsch fixed a lot of typos.
Camille Bégué fixed an issue in the conversion from std::pair and std::tuple to json.
Anthony VH fixed a compile error in an enum deserialization.
Yuriy Vountesmery noted a subtle bug in a preprocessor check.
Chen fixed numerous issues in the library.
Antony Kellermann added a CI step for GCC 10.1.
Alex fixed an MSVC warning.
Rainer proposed an improvement in the floating-point serialization in CBOR.
Francois Chabot made performance improvements in the input adapters.
Arthur Sonzogni documented how the library can be included via FetchContent.
Rimas Misevičius fixed an error message.
Alexander Myasnikov fixed some examples and a link in the README.
Hubert Chathi made CMake's version config file architecture-independent.
OmnipotentEntity implemented the binary values for CBOR, MessagePack, BSON, and UBJSON.
ArtemSarmini fixed a compilation issue with GCC 10 and fixed a leak.
Evgenii Sopov integrated the library to the wsjcpp package manager.
Sergey Linev fixed a compiler warning.
Miguel Magalhães fixed the year in the copyright.
Gareth Sylvester-Bradley fixed a compilation issue with MSVC.
Alexander “weej” Jones fixed an example in the README.
Antoine Cœur fixed some typos in the documentation.
jothepro updated links to the Hunter package.
Dave Lee fixed a link in the README.
Joël Lamotte added instruction for using Build2's package manager.
Paul Jurczak fixed an example in the README.
Sonu Lohani fixed a warning.
Carlos Gomes Martinho updated the Conan package source.
Konstantin Podsvirov fixed the MSYS2 package documentation.
Tridacnid improved the CMake tests.
Michael fixed MSVC warnings.
Quentin Barbarat fixed an example in the documentation.
XyFreak fixed a compiler warning.
TotalCaesar659 fixed links in the README.
Tanuj Garg improved the fuzzer coverage for UBSAN input.
AODQ fixed a compiler warning.
jwittbrodt made NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE inline.
pfeatherstone improved the upper bound of arguments of the NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE/NLOHMANN_DEFINE_TYPE_INTRUSIVE macros.
Jan Procházka fixed a bug in the CBOR parser for binary and string values.
T0b1-iOS fixed a bug in the new hash implementation.
Matthew Bauer adjusted the CBOR writer to create tags for binary subtypes.
gatopeich implemented an ordered map container for nlohmann::ordered_json.
Érico Nogueira Rolim added support for pkg-config.
KonanM proposed an implementation for the NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE/NLOHMANN_DEFINE_TYPE_INTRUSIVE macros.
Guillaume Racicot implemented string_view support and allowed C++20 support.
Alex Reinking improved CMake support for FetchContent.
Hannes Domani provided a GDB pretty printer.
Lars Wirzenius reviewed the README file.
Jun Jie fixed a compiler path in the CMake scripts.
Ronak Buch fixed typos in the documentation.
Alexander Karzhenkov fixed a move constructor and the Travis builds.
Leonardo Lima added CPM.Cmake support.
Joseph Blackman fixed a warning.
Yaroslav updated doctest and implemented unit tests.
Martin Stump fixed a bug in the CMake files.
Jaakko Moisio fixed a bug in the input adapters.
bl-ue fixed some Markdown issues in the README file.
William A. Wieselquist fixed an example from the README.
abbaswasim fixed an example from the README.
Remy Jette fixed a warning.
Fraser fixed the documentation.
Ben Beasley updated doctest.
Doron Behar fixed pkg-config.pc.
raduteo fixed a warning.
David Pfahler added the possibility to compile the library without I/O support.
Morten Fyhn Amundsen fixed a typo.
jpl-mac allowed treating the library as a system header in CMake.
Jason Dsouza fixed the indentation of the CMake file.
offa added a link to Conan Center to the documentation.
TotalCaesar659 updated the links in the documentation to use HTTPS.
Rafail Giavrimis fixed the Google Benchmark default branch.
Louis Dionne fixed a conversion operator.
justanotheranonymoususer made the examples in the README more consistent.
Finkman suppressed some -Wfloat-equal warnings.
Ferry Huberts fixed -Wswitch-enum warnings.
Arseniy Terekhin made the GDB pretty-printer robust against unset variable names.
Amir Masoud Abdol updated the Homebrew command as nlohmann/json is now in homebrew-core.
Hallot fixed some -Wextra-semi-stmt warnings.
Giovanni Cerretani fixed -Wunused warnings on JSON_DIAGNOSTICS.
Bogdan Popescu hosts the docset for offline documentation viewers.
Carl Smedstad fixed an assertion error when using JSON_DIAGNOSTICS.
miikka75 provided an important fix to compile C++17 code with Clang 9.
Maarten Becker fixed a warning for shadowed variables.
Cristi Vîjdea fixed typos in the operator[] documentation.
Alex Beregszaszi fixed spelling mistakes in comments.
Dirk Stolle fixed typos in documentation.
Daniel Albuschat corrected the parameter name in the parse documentation.
Prince Mendiratta fixed a link to the FAQ.
Florian Albrechtskirchinger implemented std::string_view support for object keys and made dozens of other improvements.
Qianqian Fang implemented the Binary JData (BJData) format.
pketelsen added macros NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT and NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT.
DarkZeros adjusted to code to not clash with Arduino defines.
flagarde fixed the output of meta() for MSVC.
Giovanni Cerretani fixed a check for std::filesystem.
Dimitris Apostolou fixed a typo.
Ferry Huberts fixed a typo.
Michael Nosthoff fixed a typo.
JungHoon Lee fixed a typo.
Faruk D. fixed the CITATION.CFF file.
Andrea Cocito added a clarification on macro usage to the documentation.
Krzysiek Karbowiak refactored the tests to use CHECK_THROWS_WITH_AS.
Chaoqi Zhang fixed a typo.
ivanovmp fixed a whitespace error.
KsaNL fixed a build error when including <windows.h>.
Andrea Pappacoda moved .pc and .cmake files to share directory.
Wolf Vollprecht added the patch_inplace function.
Jake Zimmerman highlighted common usage patterns in the README file.
NN added the Visual Studio output directory to .gitignore.
Romain Reignier improved the performance of the vector output adapter.
Mike fixed the std::iterator_traits.
Richard Hozák added macro JSON_NO_ENUM to disable default enum conversions.
vakokako fixed tests when compiling with C++20.
Alexander “weej” Jones fixed an example in the README.
Eli Schwartz added more files to the include.zip archive.
Kevin Lu fixed a compilation issue when typedefs with certain names were present.
Trevor Hickey improved the description of an example.
Jef LeCompte updated the year in the README file.
Alexandre Hamez fixed a warning.
Maninderpal Badhan fixed a typo.
kevin-- added a note to an example in the README file.
I fixed a typo.
Gregorio Litenstein fixed the Clang detection.
Andreas Smas added a Doozer badge.
WanCW fixed the string conversion with Clang.
zhaohuaxishi fixed a Doxygen error.
emvivre removed an invalid parameter from CMake.
Tobias Hermann fixed a link in the README file.
Michael fixed a warning.
Ryan Mulder added ensure_ascii to the dump function.
Muri Nicanor fixed the sed discovery in the Makefile.
David Avedissian implemented SFINAE-friendly iterator_traits.
AQNOUCH Mohammed fixed a typo in the README.
Gareth Sylvester-Bradley added operator/= and operator/ to construct JSON pointers.
Michael Macnair added support for afl-fuzz testing.
Berkus Decker fixed a typo in the README.
Illia Polishchuk improved the CMake testing.
Ikko Ashimine fixed a typo.
Raphael Grimm added the possibility to define a custom base class.
tocic fixed typos in the documentation.
Vertexwahn added Bazel build support.
Dirk Stolle fixed typos in the documentation.
DavidKorczynski added a CIFuzz CI GitHub action.
Finkman fixed the debug pretty-printer.
Florian Segginger bumped the years in the README.
haadfida cleaned up the badges of used services.
Arsen Arsenović fixed a build error.
theevilone45 fixed a typo in a CMake file.
Sergei Trofimovich fixed the custom allocator support.
Joyce fixed some security issues in the GitHub workflows.
Nicolas Jakob add vcpkg version badge.
Tomerkm added tests.
No. fixed the use of get<> calls.
taro fixed a typo in the CODEOWNERS file.
Ikko Eltociear Ashimine fixed a typo.
Felix Yan fixed a typo in the README.
HO-COOH fixed a parenthesis in the documentation.
Ivor Wanders fixed the examples to catch exception by const&.
miny1233 fixed a parenthesis in the documentation.
tomalakgeretkal fixed a compilation error.
alferov fixed a compilation error.
Craig Scott fixed a deprecation warning in CMake.
Vyacheslav Zhdanovskiy added macros for serialization-only types.
Mathieu Westphal fixed typos.
scribam fixed the MinGW workflow.
Aleksei Sapitskii added support for Apple's Swift Package Manager.
Benjamin Buch fixed the installation path in CMake.
Colby Haskell clarified the parse error message in case a file cannot be opened.
Juan Carlos Arevalo Baeza fixed the enum conversion.
alferov fixed a version in the documentation.
ss fixed the amalgamation call.
AniketDhemare fixed a version in the documentation.
Philip Müller fixed an example.
Leila Shcheglova fixed a warning in a test.
Alex Prabhat Bara fixed a function name in the documentation.
laterlaugh fixed some typos.
Yuanhao Jia fixed the GDB pretty printer.
Fallen_Breath fixed an example for JSON Pointer.
Nikhil Idiculla fixed some typos.
Griffin Myers updated the Natvis file.
thetimr fixed a typo in the documentation.
Balazs Erseki fixed a URL in the contribution guidelines.
Niccolò Iardella added NLOHMANN_DEFINE_DERIVED_TYPE_* macros.
Borislav Stanimirov allowed overriding the CMake target name.
Captain Crutches made iterator_proxy_value a std::forward_iterator.
Fredrik Sandhei added type conversion support for std::optional.
jh96 added exceptions when nullptr is passed to parse.
Stuart Gorman fixed number parsing when EINTR set in errno.
Dylan Baker generated a pkg-config file that follows the pkg-config conventions.
Tianyi Chen optimized the binary get_number implementation.
peng-wang-cn added type conversion support for multidimensional arrays.
Einars Netlis-Galejs added ONLY_SERIALIZE for NLOHMANN_DEFINE_DERIVED_TYPE_* macros.
Marcel removed alwayslink=True Bazel flag.
Harinath Nampally added diagnostic positions to exceptions.
Nissim Armand Ben Danan fixed NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT with an empty JSON instance.
Michael Valladolid added support for BSON uint64 serialization/deserialization.
Nikhil updated the documentation.
Nebojša Cvetković added support for BJDATA optimized binary array type.
Sushrut Shringarputale added support for diagnostic positions.
kimci86 templated to NLOHMANN_DEFINE_TYPE macros to also support ordered_json.
Richard Topchii added support for VisionOS in the Swift Package Manager.
Robert Chisholm fixed a typo.
zjyhjqs added CPack support.
bitFiedler made GDB pretty printer work with Python 3.8.
Gianfranco Costamagna fixed a compiler warning.
risa2000 made std::filesystem::path conversion to/from UTF-8 encoded string explicit.

Thanks a lot for helping out! Please let me know if I forgot someone.

Used third-party tools

The library itself consists of a single header file licensed under the MIT license. However, it is built, tested, documented, and whatnot using a lot of third-party tools and services. Thanks a lot!

amalgamate.py - Amalgamate C source and header files to create a single header file
American fuzzy lop for fuzz testing
AppVeyor for continuous integration on Windows
Artistic Style for automatic source code indentation
Clang for compilation with code sanitizers
CMake for build automation
Codacy for further code analysis
Coveralls to measure code coverage
Coverity Scan for static analysis
cppcheck for static analysis
doctest for the unit tests
GitHub Changelog Generator to generate the ChangeLog
Google Benchmark to implement the benchmarks
Hedley to avoid re-inventing several compiler-agnostic feature macros
lcov to process coverage information and create an HTML view
libFuzzer to implement fuzz testing for OSS-Fuzz
Material for MkDocs for the style of the documentation site
MkDocs for the documentation site
OSS-Fuzz for continuous fuzz testing of the library (project repository)
Probot for automating maintainer tasks such as closing stale issues, requesting missing information, or detecting toxic comments.
Valgrind to check for correct memory management

Notes

Standards compliance

The library targets strict conformance with RFC 8259. Both the original JSONTestSuite and its updated revision are exercised in CI; their test data is downloaded from nlohmann/json_test_data at configure time rather than committed to this repository (see tests/src/unit-testsuites.cpp):

The updated revision runs all mandatory y_ (must-accept) and n_ (must-reject) cases through the strict parse() entry point; the original suite runs its n_ cases through parse() and its y_ cases through operator>>.
The i_ (implementation-defined) cases are, by RFC 8259, free to be accepted or rejected, so "passing all i_ cases" is not a meaningful conformance metric. The library makes deliberate, documented choices there: nesting depth is not artificially limited, a leading UTF-8 byte order mark is silently ignored, Unicode noncharacters are forwarded unchanged, invalid UTF-8 and lone/unpaired UTF-16 surrogates are rejected (stricter than required), and a number that cannot be stored without becoming NaN/INF raises out_of_range.406.

One behavioral nuance is worth calling out, because a superficial test often misreads it as non-compliance: parse() is strict and rejects trailing data after a value, whereas operator>> follows relaxed iostream semantics — it parses a single value and leaves the stream positioned right after it. Feeding "a valid document followed by trailing bytes" through operator>> reports success; the same input through parse() is rejected. This is a documented two-API design, not a conformance gap. See parsing for details.

Character encoding

The library supports Unicode input as follows:

Only UTF-8 encoded input is supported, which is the default encoding for JSON according to RFC 8259.
std::u16string and std::u32string can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
Other encodings such as Latin-1 or ISO 8859-1 are not supported and will yield parse or serialization errors.
Unicode noncharacters will not be replaced by the library.
Invalid surrogates (e.g., incomplete pairs such as \uDEAD) will yield parse errors.
The strings stored in the library are UTF-8 encoded. When using the default string type (std::string), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
When you store strings with different encodings in the library, calling dump() may throw an exception unless json::error_handler_t::replace or json::error_handler_t::ignore are used as error handlers.
To store wide strings (e.g., std::wstring), you need to convert them to a UTF-8 encoded std::string before, see an example.

Comments in JSON

This library does not support comments by default. It does so for three reasons:

Comments are not part of the JSON specification. You may argue that // or /* */ are allowed in JavaScript, but JSON is not JavaScript.
This was not an oversight: Douglas Crockford wrote on this in May 2012:

I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.

Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
It is dangerous for interoperability if some libraries would add comment support while others don't. Please check The Harmful Consequences of the Robustness Principle on this.

However, you can set parameter ignore_comments to true in the parse function to ignore // or /* */ comments. Comments will then be treated as whitespace.

Trailing commas

The JSON specification does not allow trailing commas in arrays and objects, and hence this library is treating them as parsing errors by default.

Like comments, you can set parameter ignore_trailing_commas to true in the parse function to ignore trailing commas in arrays and objects. Note that a single comma as the only content of the array or object ([,] or {,}) is not allowed, and multiple trailing commas ([1,,]) are not allowed either.

This library does not add trailing commas when serializing JSON data.

For more information, see JSON With Commas and Comments (JWCC).

Order of object keys

By default, the library does not preserve the insertion order of object elements. This is standards-compliant, as the JSON standard defines objects as "an unordered collection of zero or more name/value pairs".

If you do want to preserve the insertion order, you can try the type nlohmann::ordered_json. Alternatively, you can use a more sophisticated ordered map like tsl::ordered_map (integration) or nlohmann::fifo_map (integration).

See the documentation on object order for more information.

Memory Release

We checked with Valgrind and the Address Sanitizer (ASAN) that there are no memory leaks.

If you find that a parsing program with this library does not release memory, please consider the following case, and it may be unrelated to this library.

Your program is compiled with glibc. There is a tunable threshold that glibc uses to decide whether to actually return memory to the system or whether to cache it for later reuse. If in your program you make lots of small allocations and those small allocations are not a contiguous block and are presumably below the threshold, then they will not get returned to the OS. Here is a related issue #1924.

Further notes

The code contains numerous debug assertions which can be switched off by defining the preprocessor macro NDEBUG, see the documentation of assert. In particular, note operator[] implements unchecked access for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an assertion failure if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the at() function. Furthermore, you can define JSON_ASSERT(x) to replace calls to assert(x). See the documentation on runtime assertions for more information.
As the exact number type is not defined in the JSON specification, this library tries to choose the best fitting C++ number type automatically. As a result, the type double may be used to store numbers which may yield floating-point exceptions in certain rare situations if floating-point exceptions have been unmasked in the calling code. These exceptions are not caused by the library and need to be fixed in the calling code, such as by re-masking the exceptions prior to calling library functions.
The code can be compiled without C++ runtime type identification features; that is, you can use the -fno-rtti compiler flag.
Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag -fno-exceptions or by defining the symbol JSON_NOEXCEPTION. In this case, exceptions are replaced by abort() calls. You can further control this behavior by defining JSON_THROW_USER (overriding throw), JSON_TRY_USER (overriding try), and JSON_CATCH_USER (overriding catch). Note that JSON_THROW_USER should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. Note the explanatory what() string of exceptions is not available for MSVC if exceptions are disabled, see #2824. See the documentation of exceptions for more information.

Execute unit tests

To compile and run the tests, you need to execute

mkdir build
cd build
cmake .. -DJSON_BuildTests=On
cmake --build .
ctest --output-on-failure

Note that during the ctest stage, several JSON test files are downloaded from an external repository. If policies forbid downloading artifacts during testing, you can download the files yourself and pass the directory with the test files via -DJSON_TestDataDirectory=path to CMake. Then, no Internet connectivity is required. See issue #2189 for more information.

If the testdata is not found, several test suites will fail like this:

===============================================================================
json/tests/src/make_test_data_available.hpp:21:
TEST CASE:  check test suite is downloaded

json/tests/src/make_test_data_available.hpp:23: FATAL ERROR: REQUIRE( utils::check_testsuite_downloaded() ) is NOT correct!
  values: REQUIRE( false )
  logged: Test data not found in 'json/cmake-build-debug/json_test_data'.
          Please execute target 'download_test_data' before running this test suite.
          See <https://github.com/nlohmann/json#execute-unit-tests> for more information.

===============================================================================

In case you have downloaded the library rather than checked out the code via Git, test cmake_fetch_content_configure will fail. Please execute ctest -LE git_required to skip these tests. See issue #2189 for more information.

Some tests are requiring network to be properly execute. They are labeled as git_required. Please execute ctest -LE git_required to skip these tests. See issue #4851 for more information.

Some tests change the installed files and hence make the whole process not reproducible. Please execute ctest -LE not_reproducible to skip these tests. See issue #2324 for more information. Furthermore, assertions must be switched off to ensure reproducible builds (see discussion 4494).

Note you need to call cmake -LE "not_reproducible|git_required" to exclude both labels. See issue #2596 for more information.

As Intel compilers use unsafe floating point optimization by default, the unit tests may fail. Use flag /fp:precise then.

duckdb/duckdb

DuckDB is an analytical in-process SQL database management system

DuckDB

DuckDB is a high-performance analytical database system. It is designed to be fast, reliable, portable, and easy to use. DuckDB provides a rich SQL dialect with support far beyond basic SQL. DuckDB supports arbitrary and nested correlated subqueries, window functions, collations, complex types (arrays, structs, maps), and several extensions designed to make SQL easier to use.

DuckDB is available as a standalone CLI application and has clients for Python, R, Java, Wasm, etc., with deep integrations with packages such as pandas and dplyr.

For more information on using DuckDB, please refer to the DuckDB documentation.

Installation

If you want to install DuckDB, please see our installation page for instructions.

Data Import

For CSV files and Parquet files, data import is as simple as referencing the file in the FROM clause:

SELECT * FROM 'myfile.csv';
SELECT * FROM 'myfile.parquet';

Refer to our Data Import section for more information.

SQL Reference

The documentation contains a SQL introduction and reference.

Development

For development, DuckDB requires CMake, Python 3 and a C++17 compliant compiler. In the root directory, run make to compile the sources. For development, use make debug to build a non-optimized debug version. You should run make unit and make allunit to verify that your version works properly after making changes. To test performance, you can run BUILD_BENCHMARK=1 BUILD_TPCH=1 make and then perform several standard benchmarks from the root directory by executing ./build/release/benchmark/benchmark_runner. The details of benchmarks are in our Benchmark Guide.

Please also refer to our Build Guide and Contribution Guide.

Support

See the Support Options page and the dedicated endoflife.date page.

wazuh/wazuh

Wazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.

Wazuh

Wazuh is a free and open source platform used for threat prevention, detection, and response. It is capable of protecting workloads across on-premises, virtualized, containerized, and cloud-based environments.

Wazuh solution consists of an endpoint security agent, deployed to the monitored systems, and a management server, which collects and analyzes data gathered by the agents. Besides, Wazuh has been fully integrated with the Elastic Stack, providing a search engine and data visualization tool that allows users to navigate through their security alerts.

Wazuh capabilities

A brief presentation of some of the more common use cases of the Wazuh solution.

Intrusion detection

Wazuh agents scan the monitored systems looking for malware, rootkits and suspicious anomalies. They can detect hidden files, cloaked processes or unregistered network listeners, as well as inconsistencies in system call responses.

In addition to agent capabilities, the server component uses a signature-based approach to intrusion detection, using its regular expression engine to analyze collected log data and look for indicators of compromise.

Log data analysis

Wazuh agents read operating system and application logs, and securely forward them to a central manager for rule-based analysis and storage. When no agent is deployed, the server can also receive data via syslog from network devices or applications.

The Wazuh rules help make you aware of application or system errors, misconfigurations, attempted and/or successful malicious activities, policy violations and a variety of other security and operational issues.

File integrity monitoring

Wazuh monitors the file system, identifying changes in content, permissions, ownership, and attributes of files that you need to keep an eye on. In addition, it natively identifies users and applications used to create or modify files.

File integrity monitoring capabilities can be used in combination with threat intelligence to identify threats or compromised hosts. In addition, several regulatory compliance standards, such as PCI DSS, require it.

Vulnerability detection

Wazuh agents pull software inventory data and send this information to the server, where it is correlated with continuously updated CVE (Common Vulnerabilities and Exposure) databases, in order to identify well-known vulnerable software.

Automated vulnerability assessment helps you find the weak spots in your critical assets and take corrective action before attackers exploit them to sabotage your business or steal confidential data.

Configuration assessment

Wazuh monitors system and application configuration settings to ensure they are compliant with your security policies, standards and/or hardening guides. Agents perform periodic scans to detect applications that are known to be vulnerable, unpatched, or insecurely configured.

Additionally, configuration checks can be customized, tailoring them to properly align with your organization. Alerts include recommendations for better configuration, references and mapping with regulatory compliance.

Incident response

Wazuh agents provide out-of-the-box active responses to perform various countermeasures to address active threats, such as blocking access to a system from the threat source when certain criteria are met.

In addition, Wazuh can be used to remotely run commands or system queries on agents, identifying indicators of compromise (IOCs) and helping perform other live forensics or incident response tasks.

Regulatory compliance

Wazuh provides some of the necessary security controls to become compliant with industry standards and regulations. These features, combined with its scalability and multi-platform support help organizations meet technical compliance requirements.

Wazuh is widely used by payment processing companies and financial institutions to meet PCI DSS (Payment Card Industry Data Security Standard) requirements. Its web user interface provides reports and dashboards that can help with this and other regulations (e.g. GPG13 or GDPR).

Cloud security

Wazuh helps monitoring cloud infrastructure at an API level, using integration modules that are able to pull security data from well known cloud providers, such as Amazon AWS, Azure or Google Cloud. In addition, Wazuh provides rules to assess the configuration of your cloud environment, easily spotting weaknesses.

In addition, Wazuh light-weight and multi-platform agents are commonly used to monitor cloud environments at the instance level.

Containers security

Wazuh provides security visibility into your Docker hosts and containers, monitoring their behavior and detecting threats, vulnerabilities and anomalies. The Wazuh agent has native integration with the Docker engine allowing users to monitor images, volumes, network settings, and running containers.

Wazuh continuously collects and analyzes detailed runtime information. For example, alerting for containers running in privileged mode, vulnerable applications, a shell running in a container, changes to persistent volumes or images, and other possible threats.

WUI

The Wazuh WUI provides a powerful user interface for data visualization and analysis. This interface can also be used to manage Wazuh configuration and to monitor its status.

Modules overview

Security events

Integrity monitoring

Vulnerability detection

Regulatory compliance

Agents overview

Agent summary

Orchestration

Here you can find all the automation tools maintained by the Wazuh team.

Branches

main branch contains the latest code, be aware of possible bugs on this branch.

Software and libraries used

Software	Version	Author	License
bpftool	7.7.0	libbpf	GNU Public License version 2
bzip2	1.0.8	Julian Seward	BSD License
cJSON	1.7.18	Dave Gamble	MIT License
cpp-httplib	0.25.0	yhirose	MIT License
cPython	3.12.13	Guido van Rossum	Python Software Foundation License version 2
cURL	8.20.0	Daniel Stenberg	MIT License
dbus	1.14.10	freedesktop.org	GNU Public License version 2
Flatbuffers	23.5.26	Google Inc.	Apache 2.0 License
Google Benchmark	1.6.1	Google Inc.	Apache 2.0 License
GoogleTest	1.11.0	Google Inc.	3-Clause "New" BSD License
jemalloc	5.2.1	Jason Evans	2-Clause "Simplified" BSD License
libarchive	3.8.7	Tim Kientzle	3-Clause "New" BSD License
libbpf	1.7.0	libbpf	GNU Lesser General Public License version 2.1
libdb	18.1.40	Oracle Corporation	Affero GPL v3
libffi	3.2.1	Anthony Green	MIT License
libpcre2	10.42.0	Philip Hazel	BSD License
libplist	2.2.0	Aaron Burghardt et al.	GNU Lesser General Public License version 2.1
libYAML	0.1.7	Kirill Simonov	MIT License
liblzma	5.8.3	Lasse Collin, Jia Tan et al.	GNU Public License version 3
Linux Audit userspace	2.8.4	Rik Faith	GNU Lesser General Public License
Lua	5.4.8	PUC-Rio	MIT License
nlohmann	3.11.2	Niels Lohmann	MIT License
OpenSSL	3.6.2	OpenSSL Software Foundation	Apache 2.0 License
popt	1.16	Jeff Johnson & Erik Troan	MIT License
procps	2.8.3	Brian Edmonds et al.	GNU Lesser General Public License
RocksDB	8.3.2	Facebook Inc.	Apache 2.0 License
rpm	4.20.1	Marc Ewing & Erik Troan	GNU Public License version 2
simdjson	3.13.0	Daniel Lemire	Apache License 2.0
sqlite	3.53.1	D. Richard Hipp	Public Domain (no restrictions)
zlib	1.3.1	Jean-loup Gailly & Mark Adler	zlib/libpng License

PyPi packages

Documentation

Get involved

Become part of the Wazuh's community to learn from other users, participate in discussions, talk to our developers and contribute to the project.

If you want to contribute to our project please don’t hesitate to make pull-requests, submit issues or send commits, we will review all your questions.

You can also join our Slack community channel and mailing list by sending an email to wazuh+subscribe@googlegroups.com, to ask questions and participate in discussions.

Stay up to date on news, releases, engineering articles and more.

Authors

Based on the OSSEC project started by Daniel Cid.

deskflow/deskflow

Share a single keyboard and mouse between multiple computers.

Deskflow is a free and open source keyboard and mouse sharing app. Use the keyboard, mouse, or trackpad of one computer to control nearby computers, and work seamlessly between them. It's like a software KVM (but without the video). TLS encryption is enabled by default. Wayland is supported. Clipboard sharing is supported.

Tip

Chat with us

Main discussion on Matrix: #deskflow:matrix.org (Matrix clients)
Discussion also happens on IRC: #deskflow or #deskflow-dev on Libera Chat
Start a new discussion on our GitHub project.

Download

Note

On Windows, you will need to install the Microsoft Visual C++ Redistributable.
Download latest: vc_redist.x64.exe vc_redist.arm64.exe

Tip

For macOS users, the easiest way to install and stay up to date is to use Homebrew with our homebrew-tap. macOS reports unsigned apps as damaged. This occurs because we do not use an Apple certificate for notarization. Clear the quarantine attribute to run the app: xattr -c Deskflow.app

To use Deskflow, download one of our packages, install deskflow (from your package repository), or build it from source.

Stats

Contribute

There are many ways to contribute to the Deskflow project.

We're a friendly, active, and welcoming community focused on building a great app.

Read our Contributing page to get started.

For instructions on building Deskflow, use the wiki page: Building

Operating Systems

We support all major operating systems, including Windows, macOS, Linux, and Unix-like BSD-derived.

Windows 10 v1809 or higher is required.

macOS 13 or higher is required to use our CI builds for Apple Silicon machines. macOS 12 or higher is required for Intel macs or local builds.

Linux requires libei 1.3+ and libportal 0.8+ for the server/client. Additionally, Qt 6.7+ is required for the GUI. Linux users with systems not meeting these requirements should use flatpak in place of a native package.

We officially support FreeBSD, and would also like to support: OpenBSD, NetBSD, DragonFly, Solaris.

Repology

Repology monitors a huge number of package repositories and other sources comparing package versions across them and gathering other information.

Installing on macOS

When you install Deskflow on macOS, you need to allow accessibility access (Privacy & Security) to both the Deskflow app and the deskflow process.

If using Sequoia, you may also need to allow Deskflow under Local Network‍ settings (Privacy & Security). When prompted by the OS, go to the settings and enable the access.

If you are upgrading and you already have Deskflow or deskflow on the allowed list you will need to manually remove them before accessibility access can be granted to the new version.

macOS users who download directly from releases may need to run xattr -c /Applications/Deskflow.app after copying the app to the Applications dir.

It is recommended to install Deskflow using Homebrew from our homebrew-tap

To add our tap, run:

brew tap deskflow/tap

Then install either:

Stable: brew install deskflow
Continuous: brew install deskflow-dev

Similar Projects

In the open source developer community, similar projects collaborate for the improvement of all mouse and keyboard sharing tools. We aim for idea sharing and interoperability.

Lan Mouse - Rust implementation with the goal of having native front-ends and interoperability with Deskflow/Synergy.
Synergy - Downstream commercial fork. Synergy sponsors Deskflow with financial support and contributes code (learn more).
Input Leap - Inactive Deskflow/Synergy-derivative with the goal continuing Barrier development (now a dead fork).

FAQ

Is Deskflow compatible with Synergy, Input Leap, or Barrier?

Yes, Deskflow has network compatibility with all forks:

Requires Deskflow >= v1.17.0.96
Deskflow will just work with Input Leap and Barrier (server or client).
Connecting a Deskflow client to a Synergy 1 server will also just work.
To connect a Synergy 1 client, you need to select the Synergy protocol in the Deskflow server settings.

Note: Only Synergy 1 is compatible with Deskflow (Synergy 3 is not yet compatible).

Is Deskflow compatible with Lan Mouse?

We would love to see compatibility with Lan Mouse. This may be quite an effort as currently the way they handle the generated input is very different.

If I want to solve issues in Deskflow do I need to contribute to a fork?

We welcome PRs (pull requests) from the community. If you'd like to make a change, please feel free to start a discussion or open a PR.

Is clipboard sharing supported?

Absolutely. The clipboard-sharing feature is a cornerstone feature of the product and we are committed to maintaining and improving that feature.

Is Wayland for Linux supported?

Yes! Wayland (the Linux display server protocol aimed to become the successor of the X Window System) is an important platform for us. The libei and libportal libraries enable Wayland support for Deskflow. We would like to give special thanks to Peter Hutterer, who is the author of libei, a major contributor to libportal, and the author of the Wayland implementation in Deskflow. Others such as Olivier Fourdan and Povilas Kanapickas helped with the Wayland implementation.

Some features may be unavailable or broken on Wayland. Please see the known Wayland issues.

Where did it all start?

Deskflow was first created as Synergy in 2001 by Chris Schoeneman. Read about the history of the project on our wiki.

Meow'Dib (our mascot)

Deskflow Contributors

Synergy sponsors the Deskflow project by contributing code and providing financial support (learn more).

Deskflow is made by possible by these contributors.

License

This project is licensed under GPL-2.0 with an OpenSSL exception.

kvcache-ai/Mooncake

Mooncake is the serving platform for Kimi, a leading LLM service provided by Moonshot AI.

A KVCache-centric Disaggregated Architecture for LLM Serving

Mooncake is the serving platform for Kimi, a leading LLM service provided by Moonshot AI. Under real workloads, Mooncake’s innovative architecture enables Kimi to handle 75% more requests while adhering to SLOs.

🔄 Updates

Jul 2, 2026: DSpark scales fully online training on a GB300 NVL72 system with Speculators and Mooncake: 9 vLLM nodes serve the GLM 5.2 FP8 verifier through Mooncake RDMA Store to 6 FSDP training nodes (DP=24), achieving 125k prefill tokens/s and 1.5 steps/s.
May 7, 2026: 🚀 vLLM officially features Mooncake Store — a deep dive into how Mooncake's distributed KVCache engine supercharges vLLM inference with high-throughput, memory-efficient, cross-instance KV cache sharing!
Apr 29, 2026: SGLang introduces RDMA-based P2P weight transfer for large-scale distributed RL using Mooncake TransferEngine, achieving 7x faster weight updates for the 1T-parameter Kimi-K2 model (53s → 7.2s) with zero-copy RDMA transfer across thousands of GPUs.
Mar 19, 2026: TorchSpec: Speculative Decoding Training at Scale is open sourced, using Mooncake to decouple inference and training via efficient hidden states management.
Mar 5, 2026: LightX2V now supports disaggregated deployment based on Mooncake, enabling encoder/transformer service decoupling with Mooncake Transfer Engine for high-performance cross-device and cross-machine data transfer. Details in blog.
Feb 25, 2026: SGLang merged Encoder Global Cache Manager, introducing a Mooncake-powered global multimodal embedding cache that enables cross-instance sharing of ViT embeddings to avoid redundant GPU computation.

Feb 24, 2026: vLLM-Omni introduces disaggregated inference connectors with support for both MooncakeStoreConnector and MooncakeTransferEngineConnector for multi-node omni-modality pipelines.
Feb 12, 2026: Mooncake Joins PyTorch Ecosystem We are thrilled to announce that Mooncake has officially joined the PyTorch Ecosystem!
Jan 28, 2026: FlexKV, a distributed KV store and cache system from Tencent and NVIDIA in collaboration with the community, now supports distributed KVCache reuse with the Mooncake Transfer Engine.
Dec 27, 2025: Collaboration with ROLL! Check out the paper here.
Dec 23, 2025: SGLang introduces Encode-Prefill-Decode (EPD) Disaggregation with Mooncake as a transfer backend. This integration allows decoupling compute-intensive multimodal encoders (e.g., Vision Transformers) from language model nodes, utilizing Mooncake's RDMA engine for zero-copy transfer of large multimodal embeddings.
Dec 19, 2025: Mooncake Transfer Engine has been integrated into TensorRT LLM for KVCache transfer in PD-disaggregated inference.
Dec 19, 2025: Mooncake Transfer Engine has been directly integrated into vLLM v1 as a KV Connector in PD-disaggregated setups.
Nov 07, 2025: RBG + SGLang HiCache + Mooncake, a role-based out-of-the-box solution for cloud native deployment, which is elastic, scalable, and high-performance.
Sept 18, 2025: Mooncake Store empowers vLLM Ascend by serving as the distributed KV cache pool backend.
Sept 10, 2025: SGLang officially supports Mooncake Store as a hierarchical KV caching storage backend. The integration extends RadixAttention with multi-tier KV cache storage across device, host, and remote storage layers.
Sept 10, 2025: The official & high-performance version of Mooncake P2P Store is open-sourced as checkpoint-engine. It has been successfully applied in K1.5 and K2 production training, updating Kimi-K2 model (1T parameters) across thousands of GPUs in ~20s.
Aug 23, 2025: xLLM high-performance inference engine builds hybrid KV cache management based on Mooncake, supporting global KV cache management with intelligent offloading and prefetching.
Aug 18, 2025: vLLM-Ascend integrates Mooncake Transfer Engine for KV cache register and disaggregate prefill, enabling efficient distributed inference on Ascend NPUs.
Jul 20, 2025: Mooncake powers the deployment of Kimi K2 on 128 H200 GPUs with PD disaggregation and large-scale expert parallelism, achieving 224k tokens/sec prefill throughput and 288k tokens/sec decode throughput.
Jun 20, 2025: Mooncake becomes a PD disaggregation backend for LMDeploy.
May 9, 2025: NIXL officially supports Mooncake Transfer Engine as a backend plugin.
May 8, 2025: Mooncake x LMCache unite to pioneer KVCache-centric LLM serving system.
May 5, 2025: Supported by Mooncake Team, SGLang release guidance to deploy DeepSeek with PD Disaggregation on 96 H100 GPUs.
Apr 22, 2025: LMCache officially supports Mooncake Store as a remote connector.
Apr 10, 2025: SGLang officially supports Mooncake Transfer Engine for disaggregated prefilling and KV cache transfer.
Mar 7, 2025: We open-sourced the Mooncake Store, a distributed KVCache based on Transfer Engine. vLLM's xPyD disaggregated prefilling & decoding based on Mooncake Store will be released soon.
Feb 25, 2025: Mooncake receives the Best Paper Award at FAST 2025!
Feb 21, 2025: The updated traces used in our FAST'25 paper have been released.
Dec 16, 2024: vLLM officially supports Mooncake Transfer Engine for disaggregated prefilling and KV cache transfer.
Nov 28, 2024: We open-sourced the Transfer Engine, the central component of Mooncake. We also provide two demonstrations of Transfer Engine: a P2P Store and vLLM integration.
July 9, 2024: We open-sourced the trace as a JSONL file.
June 27, 2024: We present a series of Chinese blogs with more discussions on zhihu 1, 2, 3, 4, 5, 6, 7.
June 26, 2024: Initial technical report release.

🎉 Overview

Mooncake is an infrastructure project for large-scale LLM inference and training. It features a KV cache-centric disaggregated architecture that separates prefill and decode clusters, while leveraging otherwise underutilized CPU, DRAM, and SSD resources in GPU clusters to build a disaggregated KV cache pool.

Mooncake includes a high-performance Transfer Engine for low-latency data movement across heterogeneous networks and accelerators; Mooncake Store for distributed KV cache and model-weight management; and Mooncake EP & PG for elastic MoE serving. Deeply integrated with ecosystems such as SGLang and vLLM, Mooncake helps LLM systems improve cache reuse, reduce serving latency, and scale efficiently across multi-node clusters.

🔥 Show Cases

Transfer Engine (TE)

The core of Mooncake is the Transfer Engine (TE), a high-performance data transfer framework. TE offers a unified interface for batched data movement across diverse storage, network, and accelerator environments. By supporting multiple transport protocols, topology-aware routing, multi-NIC bandwidth aggregation, and automatic failover, TE delivers low-latency, scalable, and robust data transmission for distributed AI workloads. See the Transfer Engine guide for details.

Highlights

Efficient use of multiple RDMA NIC devices. Transfer Engine supports the use of multiple RDMA NIC devices to achieve the aggregation of transfer bandwidth.
Topology-aware path selection. Transfer Engine can select optimal devices based on the location (NUMA affinity, etc.) of both source and destination.
Robust against temporary network errors. Once transmission fails, Transfer Engine will try to use alternative paths for data delivery automatically.
Superior performance at scale. With 40 GB of data (equivalent to the size of the KVCache generated by 128k tokens in the LLaMA3-70B model), Mooncake Transfer Engine delivers up to 87 GB/s and 190 GB/s of bandwidth in 4×200 Gbps and 8×400 Gbps RoCE networks respectively, which are about 2.4x and 4.6x faster than the TCP protocol.

Broad support for heterogeneous transports and accelerators. Transfer Engine provides unified data transfer across diverse protocols, including TCP, RDMA, AWS EFA, NVMe-oF, NVLink, HIP, Barex, CXL, and Ascend-family transports. When built with the corresponding runtime, Transfer Engine can detect accelerator memory and select suitable transport paths for efficient data movement across CUDA, MUSA, HIP, MACA, Cambricon MLU, and Ascend-enabled environments. For a complete list of supported protocols and configuration guide, see the Supported Protocols Documentation.
Widely adopted across the LLM ecosystem. TE is used in production inference stacks such as SGLang, vLLM, TensorRT-LLM, vLLM-Ascend, checkpoint-engine, and NIXL, among others, to efficiently transfer KV cache, embeddings, model weights, and other data.

Mooncake Store

Mooncake Store is a high-performance distributed key-value cache storage engine designed for LLM inference. Built on the Transfer Engine, it stores and manages reusable KV caches and model weights across inference clusters, with support for efficient object storage, replication, eviction, and high-bandwidth data transfer. See the Mooncake Store guide for details.

Highlights

High bandwidth utilization. Mooncake Store supports large-object striping, parallel I/O, and end-to-end zero-copy data transfer, fully utilizing aggregated bandwidth across multiple NICs.
Multi-tier cache hierarchy. Mooncake Store supports a multi-level cache design across DRAM and SSD/NVMe, enabling larger cache capacity.
Elastic and disaggregated storage. Mooncake Store decouples KVCache storage from inference engines, allowing storage nodes to be dynamically added or removed while keeping cached data independent from engine restarts, upgrades, and scheduling decisions.
Programmatic object management. Mooncake Store allows applications to control object placement and lifecycle through per-object policies, including replica counts, preferred segments, soft pin, and hard pin. These controls help inference systems protect important KV caches and model weights while guiding replication, placement, and eviction behavior.
Broad ecosystem adoption. Mooncake Store is used across the LLM systems ecosystem as a high-performance distributed storage backend for KV caches, hidden states, and model weights. It supports integrations with SGLang's Hierarchical KV Caching, vLLM's prefill serving, and LMCache, and has been adopted by systems such as TorchSpec and TransferQueue to decouple inference, training, and reinforcement-learning workloads through efficient state management and asynchronous data movement.

Mooncake EP and Process Group (PG)

Mooncake EP and Mooncake PG extend Mooncake from high-performance data movement to fault-tolerant distributed execution for large-scale MoE inference. Mooncake EP adapts DeepEP-style expert-parallel dispatch and combine operations with rank activeness awareness, while Mooncake PG provides a PyTorch distributed process-group backend with collective communication primitives that can detect failed ranks, report failures to upper layers, and recover ranks without restarting the entire inference service. See the Mooncake EP & Backend guide for details.

Highlights

Fault-tolerant expert parallelism. Mooncake EP adds active_ranks awareness to expert-parallel dispatch and combine APIs, allowing MoE inference systems to route around failed ranks and continue serving with healthy experts.
DeepEP-compatible programming model. Mooncake EP keeps the API largely consistent with DeepEP's low-latency mode, making it easier for inference engines to adopt fault-tolerant expert parallelism without rewriting their MoE communication stack.
PyTorch ProcessGroup integration. Mooncake PG can be registered as a torch.distributed backend, enabling standard collective APIs such as all_gather while using Mooncake's communication and failure-reporting mechanisms underneath.
Elastic rank recovery. Mooncake PG exposes recovery-oriented primitives such as peer-state polling and rank recovery, allowing replacement processes to rejoin existing process groups and helping inference services recover from partial failures.
SGLang integration for production MoE serving. Mooncake's collective backend and expert-parallel kernels are integrated into SGLang to support fault-tolerant expert-parallel inference for large MoE models, including Elastic Expert Parallel serving scenarios.

Tensor-Centric Ecosystem

Mooncake establishes a full-stack, Tensor-oriented AI infrastructure where Tensors serve as the fundamental data carrier. The ecosystem spans from the Transfer Engine, which accelerates Tensor data movement across heterogeneous storage (DRAM/VRAM/NVMe), to Mooncake Store for distributed management of Tensor objects (e.g., KVCache and model weight), up to the Mooncake Backend enabling Tensor-based elastic distributed computing. This architecture is designed to maximize Tensor processing efficiency for large-scale model inference and training.

SGLang Integration (Guide)

Mooncake is deeply integrated into SGLang as a high-performance communication and storage backend. These integrations enable efficient KV cache transfer in PD-disaggregated serving, scalable multi-level KV caching through HiCache, fault-tolerant expert-parallel inference, high-performance multimodal pipeline data movement, and fast RDMA-based weight synchronization for large-scale RL training. Together, Mooncake and SGLang provide a production-oriented foundation for building elastic, high-throughput, and resource-efficient LLM and multimodal serving systems.

Details

PD Disaggregated Serving: SGLang officially supports Mooncake Transfer Engine as a backend for disaggregated serving and KV cache transfer, enabling prefill and decode workers to exchange KV cache data efficiently across devices and machines.
Hierarchical KV Caching: Mooncake Store serves as an external storage backend in SGLang's HiCache system, extending RadixAttention with multi-level KV cache storage across device, host, and remote storage layers.
Elastic Expert Parallel: Mooncake's collective communication backend and expert parallel kernels are integrated into SGLang to enable fault-tolerant expert parallel inference (Elastic EP).
Cloud-Native SGLang HiCache Deployment with RBG: The RBG + SGLang HiCache + Mooncake integration provides a role-based, out-of-the-box cloud-native deployment solution that is elastic, scalable, and optimized for high-performance inference workloads.
Encode-Prefill-Decode Disaggregation for Multimodal Serving: SGLang introduces Encode-Prefill-Decode disaggregation with Mooncake as a transfer backend. This enables compute-intensive multimodal encoders, such as Vision Transformers, to be decoupled from language model workers while transferring large embeddings efficiently through Mooncake’s RDMA-based engine.
SGLang-Omni Multi-Stage Pipeline Data Transfer: SGLang-Omni integrates Mooncake as a relay backend for efficient cross-stage tensor and blob transfer in multimodal serving pipelines. This enables high-performance data movement between heterogeneous components such as thinker, talker, codec, and vocoder stages.
RDMA-Based P2P Weight Transfer for Distributed RL: SGLang adopts Mooncake TransferEngine for RDMA-based peer-to-peer weight transfer in large-scale distributed reinforcement learning. This enables zero-copy weight updates across thousands of GPUs and significantly accelerates synchronization for trillion-parameter models.

vLLM Integration (Guide)

Mooncake integrates with vLLM to accelerate large language model serving through high-performance KV cache transfer and distributed KV cache storage. The integration supports both disaggregated prefill-decode serving and cross-instance KV cache sharing, helping vLLM deployments reduce TTFT, improve cache reuse, and scale more efficiently across multi-node inference clusters.

Details

Disaggregated prefill-decode serving: Mooncake enables vLLM to split prefill and decode workloads across different nodes. Through MooncakeConnector, vLLM transfers KV cache blocks from prefill workers to decode workers using Mooncake’s high-performance transfer engine, allowing prefill and decode resources to scale independently while keeping cross-node KV transfer overhead low.
Distributed KV cache pooling and sharing: Mooncake Store extends vLLM from isolated per-instance KV caches to a shared, cluster-level KV cache pool. Through MooncakeStoreConnector, multiple vLLM instances can store, retrieve, and reuse KV cache blocks based on hash-based prefix caching, reducing redundant prefill computation and improving cache efficiency for workloads with repeated prefixes, especially agentic and multi-turn serving scenarios.
vLLM-Omni stage communication: Mooncake also integrates with vLLM-Omni through MooncakeTransferEngineConnector and MooncakeStoreConnector, enabling efficient cross-node data exchange between vLLM-Omni stages.

🖥️ Supported Hardware

Mooncake supports hardware backends across accelerator vendors, cloud fabrics, and standard datacenter interconnects, as listed below. See the supported protocols and Transfer Engine design docs for details.

🚀 Getting Started

Install Mooncake using pip. The mooncake-transfer-engine package includes Mooncake Transfer Engine, Mooncake Store, Mooncake EP and PG:

CUDA < 13.0

pip install mooncake-transfer-engine

CUDA >= 13.0

pip install mooncake-transfer-engine-cuda13

In addition to CUDA, Mooncake also supports other accelerator backends, along with flexible installation and deployment options. See the guides below for details:

Skills for AI Assistants

Mooncake ships a set of built-in skills under .claude/skills — reusable, task-focused playbooks that an AI coding assistant (such as Claude Code) invokes automatically when your request matches, or that you can run as a slash command.

Details

Skill	Description
`/mooncake-troubleshoot`	Diagnose Mooncake deployment and runtime issues (services, RDMA, env vars, logs).
`/mooncake-ci-local`	Run pre-PR local validation via `scripts/run_ci_test.sh`.
`/mooncake-api`	Work with the Mooncake Store, Transfer Engine, and EP/Backend Python APIs.

Install them without cloning the repository via the Claude Code plugin marketplace:

/plugin marketplace add kvcache-ai/Mooncake --sparse .claude-plugin
/plugin install mooncake-troubleshoot@mooncake
/plugin install mooncake-ci-local@mooncake
/plugin install mooncake-api@mooncake

The --sparse .claude-plugin flag fetches only the marketplace catalog, and each plugin is published as a git-subdir source, so installing one fetches only that single skill directory — never the whole repo. If you are already working inside a Mooncake checkout, the skills under .claude/skills/ load automatically with no setup.

📦 Open Source Traces and Tools

We open-source anonymized request traces containing request arrival times, input and output token counts, and remapped block hashes. These traces are designed to support reproducible simulation and evaluation of caching behavior while preserving user privacy. The released traces and related details are available in FAST25-release.

Together with the released traces, we also provide two KV cache analysis tools: a KV Cache Size Calculator for calculating cache capacity across popular LLM model families, and a KV Cache Hit Rate Simulator for analyzing KV cache hit rates and planning cache capacity under different workloads and models. These tools help users better understand KV cache storage costs and caching effectiveness when analyzing or reproducing serving workloads. The tools are open-sourced here.

📑 Citation

Please kindly cite our papers if you find the papers or the traces are useful:

@inproceedings{qin2025mooncake,
  author    = {Ruoyu Qin and Zheming Li and Weiran He and Jialei Cui and Feng Ren and Mingxing Zhang and Yongwei Wu and Weimin Zheng and Xinran Xu},
  title     = {Mooncake: Trading More Storage for Less Computation {\textemdash} A {KVCache-centric} Architecture for Serving {LLM} Chatbot},
  booktitle = {23rd USENIX Conference on File and Storage Technologies (FAST 25)},
  year      = {2025},
  isbn      = {978-1-939133-45-8},
  address   = {Santa Clara, CA},
  pages     = {155--170},
  url       = {https://www.usenix.org/conference/fast25/presentation/qin},
  publisher = {USENIX Association},
  month     = {feb},
}

@misc{ren2026tentdeclarativeslicespraying,
  title     = {TENT: A Declarative Slice Spraying Engine for Performant and Resilient Data Movement in Disaggregated LLM Serving},
  author    = {Feng Ren and Ruoyu Qin and Teng Ma and Shangming Cai and Zheng Liu and Chao Lei and Dejiang Zhu and Ke Yang and Zheming Li and Jialei Cui and Weixiao Huang and Yikai Zhao and Yineng Zhang and Hao Wu and Xiang Gao and Yuhao Fu and Jinlei Jiang and Yongwei Wu and Mingxing Zhang},
  year      = {2026},
  eprint    = {2604.00368},
  archivePrefix = {arXiv},
  primaryClass  = {cs.DC},
  url       = {https://arxiv.org/abs/2604.00368},
}

@article{sun2026survivingpartialrankfailures,
  title     = {Surviving Partial Rank Failures in Wide Expert-Parallel MoE Inference},
  author    = {Xun Sun and Shaoyuan Chen and Pingchuan Ma and Yue Chen and Ziwei Yuan and Zhanhao Cao and Han Han and Shangming Cai and Teng Ma and Xuchun Shang and Xinpeng Zhao and Ke Yang and Junlin Wei and Lianzhi Lin and Yuji Liu and Feng Ren and Haoran Hu and Cheng Wan and Yingdi Shan and Yongwei Wu and Mingxing Zhang},
  year      = {2026},
  url       = {https://arxiv.org/abs/2605.10670},
}

@article{qin2025mooncake_tos,
  author    = {Qin Ruoyu and Li Zheming and He Weiran and Cui Jialei and Tang Heyi and Ren Feng and Ma Teng and Cai Shangming and Zhang Yineng and Zhang Mingxing and Wu Yongwei and Zheng Weimin and Xu Xinran},
  title     = {Mooncake: A KVCache-centric Disaggregated Architecture for LLM Serving},
  year      = {2025},
  publisher = {Association for Computing Machinery},
  address   = {New York, NY, USA},
  issn      = {1553-3077},
  url       = {https://doi.org/10.1145/3773772},
  doi       = {10.1145/3773772},
  journal   = {ACM Trans. Storage},
  month     = {nov},
  keywords  = {Machine learning system, LLM serving, KVCache},
}

@article{qin2024mooncake_arxiv,
  title  = {Mooncake: A KVCache-centric Disaggregated Architecture for LLM Serving},
  author = {Ruoyu Qin and Zheming Li and Weiran He and Mingxing Zhang and Yongwei Wu and Weimin Zheng and Xinran Xu},
  year   = {2024},
  url    = {https://arxiv.org/abs/2407.00079},
}

shadps4-emu/shadPS4

PlayStation 4 emulator for Windows, Linux, macOS and FreeBSD written in C++

shadPS4

Bloodborne by From Software	Hatsune Miku Project DIVA Future Tone by SEGA

Yakuza 0 by SEGA	DRIVECLUB™ by Evolution Studios

General information

shadPS4 is an early PlayStation 4 emulator for Windows, Linux and macOS written in C++.

Important

This is the emulator core, which does not include a GUI. If you just want to use the emulator as an end user, download the QtLauncher instead.

If you encounter problems or have doubts, do not hesitate to look at the Quickstart.
To verify that a game works, you can look at shadPS4 Game Compatibility.
To discuss shadPS4 development, suggest ideas or to ask for help, join our Discord server.
To get the latest news, go to our X (Twitter) or our website.
You can donate to the project via our Kofi page.

Status

Important

shadPS4 is early in development, don't expect a flawless experience.

Currently, the emulator can successfully run games like Bloodborne, Dark Souls Remastered, Red Dead Redemption, and many other games.

Why

This project began for fun. Given our limited free time, it may take some time before shadPS4 can run more complex games, but we're committed to making small, regular updates.

Building

Docker

For building shadPS4 in a containerized environment using Docker and VSCode, check the instructions here:
Docker Build Instructions

Windows

Check the build instructions for Windows.

Linux

Check the build instructions for Linux.

macOS

Check the build instructions for macOS.

Important

macOS users need at least macOS 26.0 to run shadPS4. Intel Macs are not supported.

Usage examples

Important

For a user-friendly GUI, download the QtLauncher.

To get the list of all available commands and also a more detailed description of what each command does, please refer to the --help flag's output.

Below is a list of commonly used command patterns:

shadPS4 CUSA00001 # Searches for a game folder called CUSA00001 in the list of game install folders, and boots it.
shadPS4 --fullscreen true --config-clean CUSA00001    # the game argument is always the last one,
shadPS4 -g CUSA00001 --fullscreen true --config-clean # ...unless manually specified otherwise.
shadPS4 /path/to/game.elf # Boots a PS4 ELF file directly. Useful if you want to boot an executable that is not named eboot.bin.
shadPS4 CUSA00001 -- -flag1 -flag2 # Passes '-flag1' and '-flag2' to the game executable in argv.

Debugging and reporting issues

For more information on how to test, debug and report issues with the emulator or games, read the Debugging documentation.

Keyboard and Mouse Mappings

Note

Some keyboards may also require you to hold the Fn key to use the F* keys. Mac users should use the Command key instead of Control, and need to use Command+F11 for full screen to avoid conflicting with system key bindings.

Button	Function
F10	FPS Counter
Ctrl+F10	Video Debug Info
F11	Fullscreen
F12	Trigger RenderDoc Capture (or game-only screenshot if RenderDoc is unavailable)
Alt+F12	Capture screenshot including HUD/dialog overlays

Note

Xbox and DualShock controllers work out of the box.

Controller button	Keyboard equivalent
LEFT AXIS UP	W
LEFT AXIS DOWN	S
LEFT AXIS LEFT	A
LEFT AXIS RIGHT	D
RIGHT AXIS UP	I
RIGHT AXIS DOWN	K
RIGHT AXIS LEFT	J
RIGHT AXIS RIGHT	L
TRIANGLE	Numpad 8 or C
CIRCLE	Numpad 6 or B
CROSS	Numpad 2 or N
SQUARE	Numpad 4 or V
PAD UP	UP
PAD DOWN	DOWN
PAD LEFT	LEFT
PAD RIGHT	RIGHT
OPTIONS	RETURN
BACK BUTTON / TOUCH PAD	SPACE
L1	Q
R1	U
L2	E
R2	O
L3	X
R3	M

Keyboard and mouse inputs can be customized in the settings menu by clicking the Controller button, and further details and help on controls are also found there. Custom bindings are saved per-game. Inputs support up to three keys per binding, mouse buttons, mouse movement mapped to joystick input, and more.

Firmware files

shadPS4 can load some PlayStation 4 firmware files. The following firmware modules are supported and must be placed in shadPS4's sys_modules folder.

Modules	Modules	Modules	Modules
libSceAudiodec.sprx	libSceAudiodecCpu.sprx	libSceAudiodecCpuDdp.sprx	libSceAudiodecCpuDtsHdLbr.sprx
libSceAudiodecCpuHevag.sprx	libSceAudiodecCpuM4aac.sprx	libSceCesCs.sprx	libSceFont.sprx
libSceFontFt.sprx	libSceFreeTypeOl.sprx	libSceFreeTypeOptOl.sprx	libSceFreeTypeOt.sprx
libSceJpegDec.sprx	libSceJpegEnc.sprx	libSceJson.sprx	libSceJson2.sprx
libSceLibcInternal.sprx	libSceNgs2.sprx	libScePngEnc.sprx	libSceRtc.sprx
libSceRudp.sprx	libSceSystemGesture.sprx	libSceUlt.sprx	libSceWkFontConfig.sprx
libSceXml.sprx	libSceAt9Enc.sprx

Caution

The above modules are required to run the games properly and must be dumped from your legally owned PlayStation 4 console.

Main team

Logo is done by Xphalnos

Contributing

If you want to contribute, please read the CONTRIBUTING.md file.
Open a PR and we'll check it 😃

Special Thanks

A few noteworthy teams/projects who've helped us along the way are:

Panda3DS: A multiplatform 3DS emulator from our co-author wheremyfoodat. They have been incredibly helpful in understanding and solving problems that came up from natively executing the x64 code of PS4 binaries
fpPS4: The fpPS4 team has assisted massively with understanding some of the more complex parts of the PS4 operating system and libraries, by helping with reverse engineering work and research.
yuzu: Our shader compiler has been designed with yuzu's Hades compiler as a blueprint. This allowed us to focus on the challenges of emulating a modern AMD GPU while having a high-quality optimizing shader compiler implementation as a base.
felix86: A new x86-64 → RISC-V Linux userspace emulator
emudev.org: A network of people interested in the documentation, emulation, simulation and re-implementation of hardware near extinction . Belongs to my friend skmp and me (shadow) also a member of it

License

GPL-2.0 license

FreeCAD/FreeCAD

Official source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.

Your own 3D Parametric Modeler

Website • Documentation • Forum • Bug tracker • Git repository • Blog

Overview

Freedom to build what you want FreeCAD is an open-source parametric 3D modeler made primarily to design real-life objects of any size. Parametric modeling allows you to easily modify your design by going back into your model history to change its parameters.
Create 3D from 2D and back FreeCAD lets you sketch geometry-constrained 2D shapes and use them as a base to build other objects. It contains many components to adjust dimensions or extract design details from 3D models to create high quality production-ready drawings.
Designed for your needs FreeCAD is designed to fit a wide range of uses including product design, mechanical engineering and architecture, whether you are a hobbyist, programmer, experienced CAD user, student or teacher.
Cross platform FreeCAD runs on Windows, macOS and Linux operating systems.
Underlying technology
- OpenCASCADE A powerful geometry kernel, the most important component of FreeCAD
- Coin3D library Open Inventor-compliant 3D scene representation model
- Python FreeCAD offers a broad Python API
- Qt Graphical user interface built with Qt

Installing

Precompiled packages for stable releases are available for Windows, macOS and Linux on the latest releases page.

On most Linux distributions, FreeCAD is also directly installable from the software center application.

For weekly development releases visit the releases page.

Other options are described on the wiki Download page.

Compiling

See the Developers Handbook – Getting Started for build instructions.

Reporting Issues

To report an issue please:

Consider posting to the Forum, Discord channel, or Reddit to verify the issue;
Search the existing issues for potential duplicates;
Use the most updated stable or development versions of FreeCAD;
Post version info from Help > About FreeCAD > Copy to clipboard;
Restart FreeCAD in safe mode Help > Restart in safe mode and try to reproduce the issue again. If the issue is resolved it can be fixed by deleting the FreeCAD config files.
Start recording a macro Macro > Macro recording... and repeat all steps. Stop recording after the issue occurs and upload the saved macro or copy the macro code in the issue;
Post a Step-By-Step explanation on how to recreate the issue;
Upload an example file (FCStd as ZIP file) to demonstrate the problem;

For more details see:

Note

The FPA offers developers the opportunity to apply for a grant to work on projects of their choosing. Check jobs and funding to know more.

Usage & Getting Help

The FreeCAD wiki contains documentation on general FreeCAD usage, Python scripting, and development. View these pages for more information:

The FreeCAD forum is a great place to find help and solve specific problems when learning to use FreeCAD.

This project receives generous infrastructure support from and KiCad Services Corp.

ggml-org/whisper.cpp

Port of OpenAI's Whisper model in C/C++

whisper.cpp

Stable: v1.9.2 / Roadmap

High-performance inference of OpenAI's Whisper automatic speech recognition (ASR) model:

Plain C/C++ implementation without dependencies
Apple Silicon first-class citizen - optimized via ARM NEON, Accelerate framework, Metal and Core ML
AVX intrinsics support for x86 architectures
VSX intrinsics support for POWER architectures
Mixed F16 / F32 precision
Integer quantization support
Zero memory allocations at runtime
Vulkan support
Support for CPU-only inference
Efficient GPU support for NVIDIA
AMD ROCm GPU support
OpenVINO Support
Ascend NPU Support
Moore Threads GPU Support
C-style API
Voice Activity Detection (VAD)

Supported platforms:

The entire high-level implementation of the model is contained in whisper.h and whisper.cpp. The rest of the code is part of the ggml machine learning library.

Having such a lightweight implementation of the model allows to easily integrate it in different platforms and applications. As an example, here is a video of running the model on an iPhone 13 device - fully offline, on-device: whisper.objc

https://user-images.githubusercontent.com/1991296/197385372-962a6dea-bca1-4d50-bf96-1d8c27b98c81.mp4

You can also easily make your own offline voice assistant application: command

https://user-images.githubusercontent.com/1991296/204038393-2f846eae-c255-4099-a76d-5735c25c49da.mp4

On Apple Silicon, the inference runs fully on the GPU via Metal:

https://github.com/ggml-org/whisper.cpp/assets/1991296/c82e8f86-60dc-49f2-b048-d2fdbd6b5225

Quick start

First clone the repository:

git clone https://github.com/ggml-org/whisper.cpp.git

Navigate into the directory:

cd whisper.cpp

Then, download one of the Whisper models converted in ggml format. For example:

sh ./models/download-ggml-model.sh base.en

Now build the whisper-cli example and transcribe an audio file like this:

# build the project
cmake -B build
cmake --build build -j --config Release

# transcribe an audio file
./build/bin/whisper-cli -f samples/jfk.wav

For a quick demo, simply run make base.en.

The command downloads the base.en model converted to custom ggml format and runs the inference on all .wav samples in the folder samples.

For detailed usage instructions, run: ./build/bin/whisper-cli -h

Note that the whisper-cli example currently runs only with 16-bit WAV files, so make sure to convert your input before running the tool. For example, you can use ffmpeg like this:

ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav

More audio samples

If you want some extra audio samples to play with, simply run:

make -j samples

This will download a few more audio files from Wikipedia and convert them to 16-bit WAV format via ffmpeg.

You can download and run the other models as follows:

make -j tiny.en
make -j tiny
make -j base.en
make -j base
make -j small.en
make -j small
make -j medium.en
make -j medium
make -j large-v1
make -j large-v2
make -j large-v3
make -j large-v3-turbo

Memory usage

Model	Disk	Mem
tiny	75 MiB	~273 MB
base	142 MiB	~388 MB
small	466 MiB	~852 MB
medium	1.5 GiB	~2.1 GB
large	2.9 GiB	~3.9 GB

POWER VSX Intrinsics

whisper.cpp supports POWER architectures and includes code which significantly speeds operation on Linux running on POWER9/10, making it capable of faster-than-realtime transcription on underclocked Raptor Talos II. Ensure you have a BLAS package installed, and replace the standard cmake setup with:

# build with GGML_BLAS defined
cmake -B build -DGGML_BLAS=1
cmake --build build -j --config Release
./build/bin/whisper-cli [ .. etc .. ]

Quantization

whisper.cpp supports integer quantization of the Whisper ggml models. Quantized models require less memory and disk space and depending on the hardware can be processed more efficiently.

Here are the steps for creating and using a quantized model:

# quantize a model with Q5_0 method
cmake -B build
cmake --build build -j --config Release
./build/bin/quantize models/ggml-base.en.bin models/ggml-base.en-q5_0.bin q5_0

# run the examples as usual, specifying the quantized model file
./build/bin/whisper-cli -m models/ggml-base.en-q5_0.bin ./samples/gb0.wav

Core ML support

On Apple Silicon devices, the Encoder inference can be executed on the Apple Neural Engine (ANE) via Core ML. This can result in significant speed-up - more than x3 faster compared with CPU-only execution. Here are the instructions for generating a Core ML model and using it with whisper.cpp:

Install Python dependencies needed for the creation of the Core ML model:
```
pip install ane_transformers
pip install openai-whisper
pip install coremltools
```
- To ensure coremltools operates correctly, please confirm that Xcode is installed and execute xcode-select --install to install the command-line tools.
- Python 3.11 is recommended.
- MacOS Sonoma (version 14) or newer is recommended, as older versions of MacOS might experience issues with transcription hallucination.
- [OPTIONAL] It is recommended to utilize a Python version management system, such as Miniconda for this step:
  - To create an environment, use: conda create -n py311-whisper python=3.11 -y
  - To activate the environment, use: conda activate py311-whisper
Generate a Core ML model. For example, to generate a base.en model, use:
```
./models/generate-coreml-model.sh base.en
```
This will generate the folder models/ggml-base.en-encoder.mlmodelc

Build whisper.cpp with Core ML support:

# using CMake
cmake -B build -DWHISPER_COREML=1
cmake --build build -j --config Release

Run the examples as usual. For example:

$ ./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/jfk.wav

...

whisper_init_state: loading Core ML model from 'models/ggml-base.en-encoder.mlmodelc'
whisper_init_state: first run on a device may take a while ...
whisper_init_state: Core ML model loaded

system_info: n_threads = 4 / 10 | AVX = 0 | AVX2 = 0 | AVX512 = 0 | FMA = 0 | NEON = 1 | ARM_FMA = 1 | F16C = 0 | FP16_VA = 1 | WASM_SIMD = 0 | BLAS = 1 | SSE3 = 0 | VSX = 0 | COREML = 1 |

...

The first run on a device is slow, since the ANE service compiles the Core ML model to some device-specific format. Next runs are faster.

For more information about the Core ML implementation please refer to PR #566.

OpenVINO support

On platforms that support OpenVINO, the Encoder inference can be executed on OpenVINO-supported devices including x86 CPUs and Intel GPUs (integrated & discrete).

This can result in significant speedup in encoder performance. Here are the instructions for generating the OpenVINO model and using it with whisper.cpp:

First, setup python virtual env. and install python dependencies. Python 3.10 is recommended.

Windows:

cd models
python -m venv openvino_conv_env
openvino_conv_env\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements-openvino.txt

Linux and macOS:

cd models
python3 -m venv openvino_conv_env
source openvino_conv_env/bin/activate
python -m pip install --upgrade pip
pip install -r requirements-openvino.txt

Generate an OpenVINO encoder model. For example, to generate a base.en model, use:
```
python convert-whisper-to-openvino.py --model base.en
```
This will produce ggml-base.en-encoder-openvino.xml/.bin IR model files. It's recommended to relocate these to the same folder as ggml models, as that is the default location that the OpenVINO extension will search at runtime.
Build whisper.cpp with OpenVINO support:

Download OpenVINO package from release page. The recommended version to use is 2024.6.0. Ready to use Binaries of the required libraries can be found in the OpenVino Archives

After downloading & extracting package onto your development system, set up required environment by sourcing setupvars script. For example:

Linux:
```
source /path/to/l_openvino_toolkit_ubuntu22_2023.0.0.10926.b4452d56304_x86_64/setupvars.sh
```
Windows (cmd):
```
C:\Path\To\w_openvino_toolkit_windows_2023.0.0.10926.b4452d56304_x86_64\setupvars.bat
```
And then build the project using cmake:
```
cmake -B build -DWHISPER_OPENVINO=1
cmake --build build -j --config Release
```

Run the examples as usual. For example:

$ ./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/jfk.wav

...

whisper_ctx_init_openvino_encoder: loading OpenVINO model from 'models/ggml-base.en-encoder-openvino.xml'
whisper_ctx_init_openvino_encoder: first run on a device may take a while ...
whisper_openvino_init: path_model = models/ggml-base.en-encoder-openvino.xml, device = GPU, cache_dir = models/ggml-base.en-encoder-openvino-cache
whisper_ctx_init_openvino_encoder: OpenVINO model loaded

system_info: n_threads = 4 / 8 | AVX = 1 | AVX2 = 1 | AVX512 = 0 | FMA = 1 | NEON = 0 | ARM_FMA = 0 | F16C = 1 | FP16_VA = 0 | WASM_SIMD = 0 | BLAS = 0 | SSE3 = 1 | VSX = 0 | COREML = 0 | OPENVINO = 1 |

...

The first time run on an OpenVINO device is slow, since the OpenVINO framework will compile the IR (Intermediate Representation) model to a device-specific 'blob'. This device-specific blob will get cached for the next run.

For more information about the OpenVINO implementation please refer to PR #1037.

NVIDIA GPU support

With NVIDIA cards the processing of the models is done efficiently on the GPU via cuBLAS and custom CUDA kernels. First, make sure you have installed cuda: https://developer.nvidia.com/cuda-downloads

Now build whisper.cpp with CUDA support:

cmake -B build -DGGML_CUDA=1
cmake --build build -j --config Release

or for newer NVIDIA GPU's (RTX 5000 series):

cmake -B build -DGGML_CUDA=1 -DCMAKE_CUDA_ARCHITECTURES="86"
cmake --build build -j --config Release

Vulkan GPU support

Cross-vendor solution which allows you to accelerate workload on your GPU. First, make sure your graphics card driver provides support for Vulkan API.

Now build whisper.cpp with Vulkan support:

cmake -B build -DGGML_VULKAN=1
cmake --build build -j --config Release

AMD ROCm GPU support

With AMD GPUs the processing can be accelerated via HIP/ROCm. First, make sure you have installed ROCm.

Now build whisper.cpp with HIP support:

cmake -B build -DGGML_HIP=1 -DAMDGPU_TARGETS="gfx1201"
cmake --build build -j --config Release

Replace gfx1201 with your GPU architecture. You can find it with:

rocminfo | grep "gfx"

Common architectures: gfx1100 (RX 7900 XTX), gfx1101 (RX 7800 XT), gfx1201 (RX 9070 XT). For multiple GPUs with different architectures: -DAMDGPU_TARGETS="gfx1100;gfx1201".

BLAS CPU support via OpenBLAS

Encoder processing can be accelerated on the CPU via OpenBLAS. First, make sure you have installed openblas: https://www.openblas.net/

Now build whisper.cpp with OpenBLAS support:

cmake -B build -DGGML_BLAS=1
cmake --build build -j --config Release

Ascend NPU support

Ascend NPU provides inference acceleration via CANN and AI cores.

First, check if your Ascend NPU device is supported:

Verified devices

Ascend NPU	Status
Atlas 300T A2	Support
Atlas 300I Duo	Support

Then, make sure you have installed CANN toolkit . The lasted version of CANN is recommanded.

Now build whisper.cpp with CANN support:

cmake -B build -DGGML_CANN=1
cmake --build build -j --config Release

Run the inference examples as usual, for example:

./build/bin/whisper-cli -f samples/jfk.wav -m models/ggml-base.en.bin -t 8

Notes:

If you have trouble with Ascend NPU device, please create a issue with [CANN] prefix/tag.
If you run successfully with your Ascend NPU device, please help update the table Verified devices.

Moore Threads GPU support

With Moore Threads cards the processing of the models is done efficiently on the GPU via muBLAS and custom MUSA kernels. First, make sure you have installed MUSA SDK rc4.2.0: https://developer.mthreads.com/sdk/download/musa?equipment=&os=&driverVersion=&version=4.2.0

Now build whisper.cpp with MUSA support:

cmake -B build -DGGML_MUSA=1
cmake --build build -j --config Release

or specify the architecture for your Moore Threads GPU. For example, if you have a MTT S80 GPU, you can specify the architecture as follows:

cmake -B build -DGGML_MUSA=1 -DMUSA_ARCHITECTURES="21"
cmake --build build -j --config Release

FFmpeg support (examples only)

By default, the examples in this repo use the miniaudio library to decode audio files. Some of the examples also can use FFmpeg for decoding and broader format support. To enable that, build with WHISPER_COMMON_FFMPEG.

First, you need to install required libraries:

# Debian/Ubuntu
sudo apt install libavcodec-dev libavformat-dev libavutil-dev

# RHEL/Fedora
sudo dnf install libavcodec-free-devel libavformat-free-devel libavutil-free-devel

Then you can build the project as follows:

cmake -B build -D WHISPER_COMMON_FFMPEG=yes
cmake --build build

Run the following example to confirm it's working:

# Convert an audio file to Opus format
ffmpeg -i samples/jfk.wav jfk.opus

# Transcribe the audio file
./build/bin/whisper-cli --model models/ggml-base.en.bin --file jfk.opus

Docker

Prerequisites

Docker must be installed and running on your system.
Create a folder to store big models & intermediate files (ex. /whisper/models)

Images

We have multiple Docker images available for this project:

ghcr.io/ggml-org/whisper.cpp:main: This image includes the main executable file as well as curl and ffmpeg. (platforms: linux/amd64, linux/arm64)
ghcr.io/ggml-org/whisper.cpp:main-cuda: Same as main but compiled with CUDA support. (platforms: linux/amd64)
ghcr.io/ggml-org/whisper.cpp:main-musa: Same as main but compiled with MUSA support. (platforms: linux/amd64)
ghcr.io/ggml-org/whisper.cpp:main-vulkan: Same as main but compiled with Vulkan support. (platforms: linux/amd64)

Usage

# download model and persist it in a local folder
docker run -it --rm \
  -v path/to/models:/models \
  whisper.cpp:main "./models/download-ggml-model.sh base /models"

# transcribe an audio file
docker run -it --rm \
  -v path/to/models:/models \
  -v path/to/audios:/audios \
  whisper.cpp:main "whisper-cli -m /models/ggml-base.bin -f /audios/jfk.wav"

# transcribe an audio file in samples folder
docker run -it --rm \
  -v path/to/models:/models \
  whisper.cpp:main "whisper-cli -m /models/ggml-base.bin -f ./samples/jfk.wav"

# run the web server
docker run -it --rm -p "8080:8080" \
  -v path/to/models:/models \
  whisper.cpp:main "whisper-server --host 127.0.0.1 -m /models/ggml-base.bin"
  
# run the bench too on the small.en model using 4 threads
docker run -it --rm \
  -v path/to/models:/models \
  whisper.cpp:main "whisper-bench -m /models/ggml-small.en.bin -t 4"

Installing with Conan

You can install pre-built binaries for whisper.cpp or build it from source using Conan. Use the following command:

conan install --requires="whisper-cpp/[*]" --build=missing

For detailed instructions on how to use Conan, please refer to the Conan documentation.

Limitations

Inference only

Real-time audio input example

This is a naive example of performing real-time inference on audio from your microphone. The stream tool samples the audio every half a second and runs the transcription continuously. More info is available in issue #10. You will need to have sdl2 installed for it to work properly.

cmake -B build -DWHISPER_SDL2=ON
cmake --build build -j --config Release
./build/bin/whisper-stream -m ./models/ggml-base.en.bin -t 8 --step 500 --length 5000

https://user-images.githubusercontent.com/1991296/194935793-76afede7-cfa8-48d8-a80f-28ba83be7d09.mp4

Confidence color-coding

Adding the --print-colors argument will print the transcribed text using an experimental color coding strategy to highlight words with high or low confidence:

./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/gb0.wav --print-colors

Controlling the length of the generated text segments (experimental)

For example, to limit the line length to a maximum of 16 characters, simply add -ml 16:

$ ./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/jfk.wav -ml 16

whisper_model_load: loading model from './models/ggml-base.en.bin'
...
system_info: n_threads = 4 / 10 | AVX2 = 0 | AVX512 = 0 | NEON = 1 | FP16_VA = 1 | WASM_SIMD = 0 | BLAS = 1 |

main: processing './samples/jfk.wav' (176000 samples, 11.0 sec), 4 threads, 1 processors, lang = en, task = transcribe, timestamps = 1 ...

[00:00:00.000 --> 00:00:00.850]   And so my
[00:00:00.850 --> 00:00:01.590]   fellow
[00:00:01.590 --> 00:00:04.140]   Americans, ask
[00:00:04.140 --> 00:00:05.660]   not what your
[00:00:05.660 --> 00:00:06.840]   country can do
[00:00:06.840 --> 00:00:08.430]   for you, ask
[00:00:08.430 --> 00:00:09.440]   what you can do
[00:00:09.440 --> 00:00:10.020]   for your
[00:00:10.020 --> 00:00:11.000]   country.

Word-level timestamp (experimental)

The --max-len argument can be used to obtain word-level timestamps. Simply use -ml 1:

$ ./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/jfk.wav -ml 1

whisper_model_load: loading model from './models/ggml-base.en.bin'
...
system_info: n_threads = 4 / 10 | AVX2 = 0 | AVX512 = 0 | NEON = 1 | FP16_VA = 1 | WASM_SIMD = 0 | BLAS = 1 |

main: processing './samples/jfk.wav' (176000 samples, 11.0 sec), 4 threads, 1 processors, lang = en, task = transcribe, timestamps = 1 ...

[00:00:00.000 --> 00:00:00.320]
[00:00:00.320 --> 00:00:00.370]   And
[00:00:00.370 --> 00:00:00.690]   so
[00:00:00.690 --> 00:00:00.850]   my
[00:00:00.850 --> 00:00:01.590]   fellow
[00:00:01.590 --> 00:00:02.850]   Americans
[00:00:02.850 --> 00:00:03.300]  ,
[00:00:03.300 --> 00:00:04.140]   ask
[00:00:04.140 --> 00:00:04.990]   not
[00:00:04.990 --> 00:00:05.410]   what
[00:00:05.410 --> 00:00:05.660]   your
[00:00:05.660 --> 00:00:06.260]   country
[00:00:06.260 --> 00:00:06.600]   can
[00:00:06.600 --> 00:00:06.840]   do
[00:00:06.840 --> 00:00:07.010]   for
[00:00:07.010 --> 00:00:08.170]   you
[00:00:08.170 --> 00:00:08.190]  ,
[00:00:08.190 --> 00:00:08.430]   ask
[00:00:08.430 --> 00:00:08.910]   what
[00:00:08.910 --> 00:00:09.040]   you
[00:00:09.040 --> 00:00:09.320]   can
[00:00:09.320 --> 00:00:09.440]   do
[00:00:09.440 --> 00:00:09.760]   for
[00:00:09.760 --> 00:00:10.020]   your
[00:00:10.020 --> 00:00:10.510]   country
[00:00:10.510 --> 00:00:11.000]  .

Speaker segmentation via tinydiarize (experimental)

More information about this approach is available here: https://github.com/ggml-org/whisper.cpp/pull/1058

Sample usage:

# download a tinydiarize compatible model
./models/download-ggml-model.sh small.en-tdrz

# run as usual, adding the "-tdrz" command-line argument
./build/bin/whisper-cli -f ./samples/a13.wav -m ./models/ggml-small.en-tdrz.bin -tdrz
...
main: processing './samples/a13.wav' (480000 samples, 30.0 sec), 4 threads, 1 processors, lang = en, task = transcribe, tdrz = 1, timestamps = 1 ...
...
[00:00:00.000 --> 00:00:03.800]   Okay Houston, we've had a problem here. [SPEAKER_TURN]
[00:00:03.800 --> 00:00:06.200]   This is Houston. Say again please. [SPEAKER_TURN]
[00:00:06.200 --> 00:00:08.260]   Uh Houston we've had a problem.
[00:00:08.260 --> 00:00:11.320]   We've had a main beam up on a volt. [SPEAKER_TURN]
[00:00:11.320 --> 00:00:13.820]   Roger main beam interval. [SPEAKER_TURN]
[00:00:13.820 --> 00:00:15.100]   Uh uh [SPEAKER_TURN]
[00:00:15.100 --> 00:00:18.020]   So okay stand, by thirteen we're looking at it. [SPEAKER_TURN]
[00:00:18.020 --> 00:00:25.740]   Okay uh right now uh Houston the uh voltage is uh is looking good um.
[00:00:27.620 --> 00:00:29.940]   And we had a a pretty large bank or so.

Karaoke-style movie generation (experimental)

The whisper-cli example provides support for output of karaoke-style movies, where the currently pronounced word is highlighted. Use the -owts argument and run the generated bash script. This requires to have ffmpeg installed.

Here are a few "typical" examples:

./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/jfk.wav -owts
source ./samples/jfk.wav.wts
ffplay ./samples/jfk.wav.mp4

https://user-images.githubusercontent.com/1991296/199337465-dbee4b5e-9aeb-48a3-b1c6-323ac4db5b2c.mp4

./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/mm0.wav -owts
source ./samples/mm0.wav.wts
ffplay ./samples/mm0.wav.mp4

https://user-images.githubusercontent.com/1991296/199337504-cc8fd233-0cb7-4920-95f9-4227de3570aa.mp4

./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/gb0.wav -owts
source ./samples/gb0.wav.wts
ffplay ./samples/gb0.wav.mp4

https://user-images.githubusercontent.com/1991296/199337538-b7b0c7a3-2753-4a88-a0cd-f28a317987ba.mp4

Video comparison of different models

Use the scripts/bench-wts.sh script to generate a video in the following format:

./scripts/bench-wts.sh samples/jfk.wav
ffplay ./samples/jfk.wav.all.mp4

https://user-images.githubusercontent.com/1991296/223206245-2d36d903-cf8e-4f09-8c3b-eb9f9c39d6fc.mp4

Benchmarks

In order to have an objective comparison of the performance of the inference across different system configurations, use the whisper-bench tool. The tool simply runs the Encoder part of the model and prints how much time it took to execute it. The results are summarized in the following Github issue:

Benchmark results

Additionally a script to run whisper.cpp with different models and audio files is provided bench.py.

You can run it with the following command, by default it will run against any standard model in the models folder.

python3 scripts/bench.py -f samples/jfk.wav -t 2,4,8 -p 1,2

It is written in python with the intention of being easy to modify and extend for your benchmarking use case.

It outputs a csv file with the results of the benchmarking.

`ggml` format

The original models are converted to a custom binary format. This allows to pack everything needed into a single file:

model parameters
mel filters
vocabulary
weights

You can download the converted models using the models/download-ggml-model.sh script or manually from here:

https://huggingface.co/ggerganov/whisper.cpp

For more details, see the conversion script models/convert-pt-to-ggml.py or models/README.md.

Bindings

XCFramework

The XCFramework is a precompiled version of the library for iOS, visionOS, tvOS, and macOS. It can be used in Swift projects without the need to compile the library from source. For example, the v1.7.5 version of the XCFramework can be used as follows:

// swift-tools-version: 5.10
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "Whisper",
    targets: [
        .executableTarget(
            name: "Whisper",
            dependencies: [
                "WhisperFramework"
            ]),
        .binaryTarget(
            name: "WhisperFramework",
            url: "https://github.com/ggml-org/whisper.cpp/releases/download/v1.7.5/whisper-v1.7.5-xcframework.zip",
            checksum: "c7faeb328620d6012e130f3d705c51a6ea6c995605f2df50f6e1ad68c59c6c4a"
        )
    ]
)

Voice Activity Detection (VAD)

Support for Voice Activity Detection (VAD) can be enabled using the --vad argument to whisper-cli. In addition to this option a VAD model is also required.

The way this works is that first the audio samples are passed through the VAD model which will detect speech segments. Using this information, only the speech segments that are detected are extracted from the original audio input and passed to whisper for processing. This reduces the amount of audio data that needs to be processed by whisper and can significantly speed up the transcription process.

The following VAD models are currently supported:

Silero-VAD

Silero-vad is a lightweight VAD model written in Python that is fast and accurate.

Models can be downloaded by running the following command on Linux or MacOS:

$ ./models/download-vad-model.sh silero-v6.2.0
Downloading ggml model silero-v6.2.0 from 'https://huggingface.co/ggml-org/whisper-vad' ...
ggml-silero-v6.2.0.bin        100%[==============================================>] 864.35K  --.-KB/s    in 0.04s
Done! Model 'silero-v6.2.0' saved in '/path/models/ggml-silero-v6.2.0.bin'
You can now use it like this:

  $ ./build/bin/whisper-cli -vm /path/models/ggml-silero-v6.2.0.bin --vad -f samples/jfk.wav -m models/ggml-base.en.bin

And the following command on Windows:

> .\models\download-vad-model.cmd silero-v6.2.0
Downloading vad model silero-v6.2.0...
Done! Model silero-v6.2.0 saved in C:\Users\danie\work\ai\whisper.cpp\ggml-silero-v6.2.0.bin
You can now use it like this:

C:\path\build\bin\Release\whisper-cli.exe -vm C:\path\ggml-silero-v6.2.0.bin --vad -m models/ggml-base.en.bin -f samples\jfk.wav

To see a list of all available models, run the above commands without any arguments.

This model can be also be converted manually to ggml using the following command:

$ python3 -m venv venv && source venv/bin/activate
$ (venv) pip install silero-vad
$ (venv) $ python models/convert-silero-vad-to-ggml.py --output models/silero.bin
Saving GGML Silero-VAD model to models/silero-v6.2.0-ggml.bin

And it can then be used with whisper as follows:

$ ./build/bin/whisper-cli \
   --file ./samples/jfk.wav \
   --model ./models/ggml-base.en.bin \
   --vad \
   --vad-model ./models/silero-v6.2.0-ggml.bin

VAD Options

--vad-threshold: Threshold probability for speech detection. A probability for a speech segment/frame above this threshold will be considered as speech.
--vad-min-speech-duration-ms: Minimum speech duration in milliseconds. Speech segments shorter than this value will be discarded to filter out brief noise or false positives.
--vad-min-silence-duration-ms: Minimum silence duration in milliseconds. Silence periods must be at least this long to end a speech segment. Shorter silence periods will be ignored and included as part of the speech.
--vad-max-speech-duration-s: Maximum speech duration in seconds. Speech segments longer than this will be automatically split into multiple segments at silence points exceeding 98ms to prevent excessively long segments.
--vad-speech-pad-ms: Speech padding in milliseconds. Adds this amount of padding before and after each detected speech segment to avoid cutting off speech edges.
--vad-samples-overlap: Amount of audio to extend from each speech segment into the next one, in seconds (e.g., 0.10 = 100ms overlap). This ensures speech isn't cut off abruptly between segments when they're concatenated together.

Examples

There are various examples of using the library for different projects in the examples folder. Some of the examples are even ported to run in the browser using WebAssembly. Check them out!

Example	Web	Description
whisper-cli	whisper.wasm	Tool for translating and transcribing audio using Whisper
whisper-bench	bench.wasm	Benchmark the performance of Whisper on your machine
whisper-stream	stream.wasm	Real-time transcription of raw microphone capture
whisper-command	command.wasm	Basic voice assistant example for receiving voice commands from the mic
whisper-server		HTTP transcription server with OAI-like API
whisper-talk-llama		Talk with a LLaMA bot
whisper.objc		iOS mobile application using whisper.cpp
whisper.swiftui		SwiftUI iOS / macOS application using whisper.cpp
whisper.android		Android mobile application using whisper.cpp
whisper.nvim		Speech-to-text plugin for Neovim
generate-karaoke.sh		Helper script to easily generate a karaoke video of raw audio capture
livestream.sh		Livestream audio transcription
yt-wsp.sh		Download + transcribe and/or translate any VOD (original)
wchess	wchess.wasm	Voice-controlled chess

Discussions

If you have any kind of feedback about this project feel free to use the Discussions section and open a new topic. You can use the Show and tell category to share your own projects that use whisper.cpp. If you have a question, make sure to check the Frequently asked questions (#126) discussion.

barry-ran/QtScrcpy

Android real-time display control software

QtScrcpy

中文用户？点我查看中文介绍

QtScrcpy supports displaying and controlling Android devices via USB or over network. It does NOT require root privileges.

It supports three major platforms: GNU/Linux, Windows and macOS.

It focuses on:

lightness (displays only the device screen)
performance (30~60 fps)
quality (1920×1080 or above)
low latency (35~70ms)
low startup time (only about 1 second to display the first frame)
non-intrusiveness (nothing will be installed on the device)

The author has developed a more professional screen casting software called `QuickMirror`

QuickMirror function&features:

Equipment screen casting&control: batch screen casting, individual control, batch control
Group management
WiFi screen mirroring/OTG screen mirroring
Adb shell shortcut command
File transfer, apk installation
Multiple screen mirroring: In OTG mirroring mode, with low resolution and smoothness settings, a single computer can manage 500+phones simultaneously
Low latency: USB screen mirroring 1080p latency is within 30ms, which is lower than all screen mirroring software on the market in terms of latency at the same resolution and smoothness
Low CPU usage: pure C++development, high-performance GPU video rendering
High resolution: adjustable, maximum support for native resolution of Android terminals
Perfect Chinese input: Supports Xianyu app, supports Samsung phones
The free version can cast up to 10 screens, with unlimited functionality (except for automatic screen mirroring)
QuickMirror tutorial: https://lrbnfell4p.feishu.cn/docx/EMkvdfIvDowy3UxsXUCcpPV8nDh
QuickMirror Telegram communication group: https://t.me/+EnQNmb47C_liYmRl
Preview of QuickMirror Interface:

Mapping Keys

You can write your script to map keyboard and mouse actions to touches and clicks of the mobile phone according to your needs. Here are the script writing rules.

Script for TikTok and some other games are provided by default. Once enabled, you can play the game with your keyboard and mouse. The default key mapping for PUBG Mobile is as follows:

Instruction for adding new customized mapping files.

Write a customized script and put it in the keymap directory
Click refresh script to show it
Select your script
Connect to your phone, start service and click apply
Press ~ key (the SwitchKey in the key map script) to switch to custom mapping mode
Press the ~ key again to switch back to normal mode
(For games such as PUBG Mobile) If you want to move vehicles with the STEER_WHEEL keys, you need to set the move mode to single rocker mode.

If you don't know how to manually write mapping rules, you can also use the QuickAssistant developed by the author QuickAssistant Features&Functions:

Play Android mobile games smoothly through keyboard and mouse
Interface based editing of key mapping script
Support pausing the computer screen and using only keyboard and mouse operations
Screenshot&Recording of Mobile Screen
Simple batch control
Android 11+supports playing mobile audio on computers (under development...)
Mobile app installation free
Fast and instant connection
Low latency: USB screen mirroring 1080p latency is within 30ms, which is lower than all screen mirroring software on the market in terms of latency at the same resolution and smoothness
Low CPU usage: pure C++development, high-performance GPU video rendering
High resolution: adjustable, maximum support for native resolution of Android terminals
Telegram Group：https://t.me/+Ylf_5V_rDCMyODQ1
QuickAssistant

Group control

You can control all your phones at the same time.

Star History

Thanks

QtScrcpy is based on Genymobile's scrcpy project. Thanks a lot!

The difference between QtScrcpy and the original scrcpy is as follows:

key points	scrcpy	QtScrcpy
ui	sdl	qt
video encode	ffmpeg	ffmpeg
video render	sdl	opengl
cross-platform	self implemented	provided by Qt
language	C	C++
style	sync	async
keymap	no custom keymap	support custom keymap
build	meson+gradle	qmake or CMake

It's very easy to customize your GUI with Qt
Asynchronous programming of Qt-based signal slot mechanism improves performance
Easy to learn
Add support for multi-touch

Learn

If you are interested in it and want to learn how it works but do not know how to get started, you can choose to purchase my recorded video lessons. It details the development architecture and the development process of the entire software and helps you develop QtScrcpy from scratch.

Course introduction：https://blog.csdn.net/rankun1/article/details/87970523

You can join Telegram Group for QtScrcpy and exchange ideas with like-minded friends.：

Telegram Group：https://t.me/+EnQNmb47C_liYmRl

Requirements

Android API >= 21 (Android 5.0).

Make sure you have enabled ADB debugging on your device(s).

Download

Windows

On Windows, for simplicity, prebuilt archives with all the dependencies (including ADB) are available at Releases:

QtScrcpy

or you can build it yourself

Mac OS

On Mac OS, for simplicity, prebuilt archives with all the dependencies (including ADB) are available at Releases:

QtScrcpy

or you can build it yourself

Linux

For Arch Linux Users, you can use AUR to install: yay -Syu qtscrcpy (may be outdated; maintainer: yochananmarqos)

For users in other distros, you can use the prebuilt archives from Releases:

QtScrcpy

or you can get it at GitHub Actions, in branch dev and download the latest artifact.

or you can build it yourself (not recommended, get it in Actions if you can)

Run

Connect to your Android device on your computer, then run the program and click USB connect or WiFi connect

Wireless connection steps (ensure that the mobile phone and PC are on the same LAN):

Enable USB debugging in developer options on the Android device
Connect the Android device to the computer via USB
Click update device, and you will see that the device number is updated
Click get device IP
Click start adbd
Click wireless connect
Click update device again, and another device with an IP address will be found. Select this device.
Click start service

Note: it is not necessary to keep your Android device connected via USB after you start adbd.

Interface button introduction：

Start config: function parameter settings before starting the service

You can set the bit rate, resolution, recording format, and video save path of the locally recorded video.
- Background record: the Android device screen is not displayed after starting the service. It is recorded in the background.
- Always on top: the video window for Android devices will be kept on the top
- Close screen: automatically turn off the Android device screen to save power after starting the service
- Reverse connection: service startup mode. You can uncheck it if you experience connection failure with a message more than one device
Refresh devices: Refresh the currently connected device
Start service: connect to the Android device
Stop service: disconnect from the Android device
Stop all services: disconnect all connected Android devices
Get device IP: Get the IP address of the Android device and update it to the "Wireless" area for the ease of wireless connection setting.
Start adbd: Start the adbd service of the Android device. You must start it before the wireless connection.
Wireless connect: Connect to Android devices wirelessly
Wireless disconnect: Disconnect wirelessly connected Android devices
adb command: execute customized ADB commands (blocking commands are not supported now, such as a shell)

The main function

Display Android device screens in real-time
Real-time mouse and keyboard control of Android devices
Screen recording
Screenshot to png
Wireless connection
Supports multiple device connections
Full-screen display
Display on the top
Install apk: drag and drop apk to the video window to install
Transfer files: Drag files to the video window to send files to Android devices
Background recording: record only, no display interface
Copy-paste

It is possible to synchronize clipboards between the computer and the device, in both directions:
- Ctrl + c copies the device clipboard to the computer clipboard;
- Ctrl + Shift + v copies the computer clipboard to the device clipboard;
- Ctrl + v pastes the computer clipboard as a sequence of text events (non-ASCII characters does not yet work).
Group control
Sync device speaker sound to the computer (based on sndcpy, Android 10+ only)

Shortcuts

Action	Shortcut (Windows)	Shortcut (macOS)
Switch fullscreen mode	`Ctrl`+`f`	`Cmd`+`f`
Resize window to 1:1 (pixel-perfect)	`Ctrl`+`g`	`Cmd`+`g`
Resize window to remove black borders	`Ctrl`+`w` \| Double-click¹	`Cmd`+`w` \| Double-click¹
Click on `HOME`	`Ctrl`+`h` \| Middle-click	`Ctrl`+`h` \| Middle-click
Click on `BACK`	`Ctrl`+`b` \| Right-click²	`Cmd`+`b` \| Right-click²
Click on `APP_SWITCH`	`Ctrl`+`s`	`Cmd`+`s`
Click on `MENU`	`Ctrl`+`m`	`Ctrl`+`m`
Click on `VOLUME_UP`	`Ctrl`+`↑` (up)	`Cmd`+`↑` (up)
Click on `VOLUME_DOWN`	`Ctrl`+`↓` (down)	`Cmd`+`↓` (down)
Click on `POWER`	`Ctrl`+`p`	`Cmd`+`p`
Power on	Right-click²	Right-click²
Turn device screen off (keep mirroring)	`Ctrl`+`o`	`Cmd`+`o`
Expand notification panel	`Ctrl`+`n`	`Cmd`+`n`
Collapse notification panel	`Ctrl`+`Shift`+`n`	`Cmd`+`Shift`+`n`
Copy to clipboard³	`Ctrl`+`c`	`Cmd`+`c`
Cut to clipboard³	`Ctrl`+`x`	`Cmd`+`x`
Synchronize clipboards and paste³	`Ctrl`+`v`	`Cmd`+`v`
Inject computer clipboard text	`Ctrl`+`Shift`+`v`	`Cmd`+`Shift`+`v`

¹Double-click on black borders to remove them.

²Right-click turns the screen on if it was off, presses BACK otherwise.

³Only on Android >= 7.

TODO

FAQ

DEVELOP

Everyone is welcome to maintain this project and contribute your own code, but please follow these requirements:

Please open PRs to the dev branch instead of the master branch
Please rebase the original project before opening PRs
Please submit PRs on the principle of "small amounts, many times" (one PR for a change is recommended)
Please keep the code style consistent with the existing style.

Why develop QtScrcpy?

There are several reasons listed below according to importance (high to low).

In the process of learning Qt, I need a real project to try.
I have some background skills in audio and video and I am interested in them.
I have some Android development skills. But I have used it for a long time. I want to consolidate it.
I found scrcpy and decided to re-make it with the new technology stack (C++ + Qt + Opengl + FFmpeg).

Build

All the dependencies are provided and it is easy to compile.

QtScrcpy

Non-Arch Linux Users

Set up the Qt development environment with the official Qt installer or third-party tools such as aqt on the target platform. Qt version bigger than 5.12 is required. (use MSVC 2019 on Windows)
Clone the project with git clone --recurse-submodules git@github.com:barry-ran/QtScrcpy.git
For Windows, open CMakeLists.txt with QtCreator and compile Release
For Linux, directly run ./ci/linux/build_for_linux.sh "Release" Note: compiled artifacts are located at output/x64/Release

Arch Linux Users

Install packages: base-devel cmake qt5-base qt5-multimedia qt5-x11extras (qtcreator is recommended)
Clone the project with git clone --recurse-submodules git@github.com:barry-ran/QtScrcpy.git
Run ./ci/linux/build_for_linux.sh "Release"

Scrcpy-Server

Set up Android development environment on the target platform
Open server project in project root with Android Studio
The first time you open it, if you do not have the corresponding version of Gradle, you will be prompted to find Gradle, whether to upgrade Gradle or create it. Select Cancel. After cancelling, you will be prompted to select the location of existing Gradle. Cancel it too and it will download automatically.
After compiling the apk, rename it to scrcpy-server and replace QtScrcpy/QtScrcpyCore/src/third_party/scrcpy-server.

Licence

Since it is based on scrcpy, it uses the same license as scrcpy

Copyright (C) 2025 Rankun

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

About the author

Barry CSDN

An ordinary programmer, working mainly in C++ for desktop client development, graduated from Shandong for more than a year of steel simulation education software, and later moved to Shanghai to work in security, online education-related fields, familiar with audio and video. I have an understanding of audio and video fields such as voice calls, live education, video conferencing and other related solutions. I also have experience in Android, Linux servers and other kinds of development.

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

ArduPilot/ardupilot

ArduPlane, ArduCopter, ArduRover, ArduSub source

ArduPilot Project

ArduPilot is the most advanced, full-featured, and reliable open source autopilot software available. It has been under development since 2010 by a diverse team of professional engineers, computer scientists, and community contributors. Our autopilot software is capable of controlling almost any vehicle system imaginable, from conventional airplanes, quad planes, multi-rotors, and helicopters to rovers, boats, balance bots, and even submarines. It is continually being expanded to provide support for new emerging vehicle types.

The ArduPilot project is made up of

ArduCopter: code, wiki
ArduPlane: code, wiki
Rover: code, wiki
ArduSub : code, wiki
Antenna Tracker : code, wiki

User Support & Discussion Forums

Support Forum: https://discuss.ardupilot.org/
Community Site: https://ardupilot.org

Developer Information

Github repository: https://github.com/ArduPilot/ardupilot
Main developer wiki: https://ardupilot.org/dev/
Developer discussion: https://discuss.ardupilot.org
Developer chat: https://discord.com/channels/ardupilot

Top Contributors

How To Get Involved

The ArduPilot project is open source and we encourage participation and code contributions: guidelines for contributors to the ardupilot codebase
We have an active group of Beta Testers to help us improve our code: release procedures
Desired Enhancements and Bugs can be posted to the issues list.
Help other users with log analysis in the support forums
Improve the wiki and chat with other wiki editors on Discord #documentation
Contact the developers on one of the communication channels

License

The ArduPilot project is licensed under the GNU General Public License, version 3.

Maintainers

ArduPilot is comprised of several parts, vehicles and boards. The list below contains the people that regularly contribute to the project and are responsible for reviewing patches on their specific area.

Andrew Tridgell:
- Vehicle: Plane, AntennaTracker
- Board: Pixhawk, Pixhawk2, PixRacer
Francisco Ferreira:
- Bug Master
Grant Morphett:
- Vehicle: Rover
Willian Galvani:
- Vehicle: Sub
- Board: Navigator
Michael du Breuil:
- Subsystem: Batteries
- Subsystem: GPS
- Subsystem: Scripting
Peter Barker:
- Subsystem: DataFlash, Tools
Randy Mackay:
- Vehicle: Copter, Rover, AntennaTracker
Siddharth Purohit:
- Subsystem: CAN, Compass
- Board: Cube*
Tom Pittenger:
- Vehicle: Plane
Bill Geyer:
- Vehicle: TradHeli
Emile Castelnuovo:
- Board: VRBrain
Georgii Staroselskii:
- Board: NavIO
Gustavo José de Sousa:
- Subsystem: Build system
Julien Beraud:
- Board: Bebop & Bebop 2
Leonard Hall:
- Subsystem: Copter attitude control and navigation
Matt Lawrence:
- Vehicle: 3DR Solo & Solo based vehicles
Matthias Badaire:
- Subsystem: FRSky
Mirko Denecke:
- Board: BBBmini, BeagleBone Blue, PocketPilot
Paul Riseborough:
- Subsystem: AP_NavEKF2
- Subsystem: AP_NavEKF3
Víctor Mayoral Vilches:
- Board: PXF, Erle-Brain 2, PXFmini
Amilcar Lucas:
- Subsystem: Marvelmind
Samuel Tabor:
- Subsystem: Soaring/Gliding
Henry Wurzburg:
- Subsystem: OSD
- Site: Wiki
Peter Hall:
- Vehicle: Tailsitters
- Vehicle: Sailboat
- Subsystem: Scripting
Andy Piper:
- Subsystem: Crossfire
- Subsystem: ESC
- Subsystem: OSD
- Subsystem: SmartAudio
Alessandro Apostoli:
- Subsystem: Telemetry
- Subsystem: OSD
Rishabh Singh:
- Subsystem: Avoidance/Proximity
David Bussenschutt:
- Subsystem: ESP32,AP_HAL_ESP32
Charles Villard:
- Subsystem: ESP32,AP_HAL_ESP32

jrouwe/JoltPhysics

A multi core friendly rigid body physics and collision detection library. Written in C++. Suitable for games and VR applications. Used by Horizon Forbidden West and Death Stranding 2.

Jolt Physics

A multi core friendly rigid body physics and collision detection library. Suitable for games and VR applications. Used by Horizon Forbidden West and Death Stranding 2: On the Beach.


A YouTube video showing a ragdoll pile simulated with Jolt Physics.

For more demos and videos go to the Samples section.

Design considerations

Why create yet another physics engine? Firstly, it has been a personal learning project. Secondly, I wanted to address some issues that I had with existing physics engines:

Games do more than simulating physics. These things happen across multiple threads. We emphasize on concurrently accessing physics data outside of the main simulation update:
- Sections of the simulation can be loaded / unloaded in the background. We prepare a batch of physics bodies on a background thread without locking or affecting the simulation. We insert the batch into the simulation with a minimal impact on performance.
- Collision queries can run parallel to adding / removing or updating a body. If a change to a body happened on the same thread, the change will be immediately visible. If the change happened on another thread, the query will see a consistent before or after state. An alternative would be to have a read and write version of the world. This prevents changes from being visible immediately, so we avoid this.
- Collision queries can run parallel to the main physics simulation. We do a coarse check (broad phase query) before the simulation step and do fine checks (narrow phase query) in the background. This way, long running processes (like navigation mesh generation) can be spread out across multiple frames.
Accidental wake up of bodies cause performance problems when loading / unloading content. Therefore, bodies will not automatically wake up when created. Neighboring bodies will not be woken up when bodies are removed. This can be triggered manually if desired.
The simulation runs deterministically. You can replicate a simulation to a remote client by merely replicating the inputs to the simulation. Read the Deterministic Simulation section to understand the limits.
We try to simulate behavior of rigid bodies in the real world but make approximations. Therefore, this library should mainly be used for games or VR simulations.

Features

Simulation of rigid bodies of various shapes using continuous collision detection:
- Sphere
- Box
- Capsule
- Tapered-capsule
- Cylinder
- Tapered-cylinder
- Convex hull
- Plane
- Compound
- Mesh (triangle)
- Terrain (height field)
Simulation of constraints between bodies:
- Fixed
- Point
- Distance (including springs)
- Hinge
- Slider (also called prismatic)
- Cone
- Rack and pinion
- Gear
- Pulley
- Smooth spline paths
- Swing-twist (for humanoid shoulders)
- 6 DOF
Motors to drive the constraints.
Collision detection:
- Casting rays.
- Testing shapes vs shapes.
- Casting a shape vs another shape.
- Broadphase only tests to quickly determine which objects may intersect.
Sensors (trigger volumes).
Animated ragdolls:
- Hard keying (kinematic only rigid bodies).
- Soft keying (setting velocities on dynamic rigid bodies).
- Driving constraint motors to an animated pose.
- Mapping a high detail (animation) skeleton onto a low detail (ragdoll) skeleton and vice versa.
Game character simulation (capsule)
- Rigid body character. Moves during the physics simulation. Cheapest option and most accurate collision response between character and dynamic bodies.
- Virtual character. Does not have a rigid body in the simulation but simulates one using collision checks. Updated outside of the physics update for more control. Less accurate interaction with dynamic bodies.
Vehicles
- Wheeled vehicles.
- Tracked vehicles.
- Motorcycles.
Soft body simulation (e.g. a soft ball or piece of cloth).
- Edge constraints.
- Dihedral bend constraints.
- Cosserat rod constraints (an edge with an orientation that can be used to orient geometry, e.g. a plant leaf).
- Tetrahedron volume constraints.
- Long range attachment constraints (also called tethers).
- Limiting the simulation to stay within a certain range of a skinned vertex.
- Internal pressure.
- Collision with simulated rigid bodies.
- Collision tests against soft bodies.
A strand based hair simulation running on GPU
- System is based on Cosserad rods.
- Can use long range attachment constraints to limit the stretch of hairs.
- Supports simulation (guide) and render (follow) hairs.
- Hair vs hair collision is handled by accumulating the average velocity in a grid and using those velocities to drive hairs.
- Supports collision with the environment, although it only supports ConvexHull and CompoundShapes at the moment.
- The roots of the hairs can be skinned to the scalp mesh.
Water buoyancy calculations.
An optional double precision mode that allows large worlds.

Supported platforms

Windows x86/x64/ARM64
Linux (tested on Ubuntu) x86/x64/ARM32/ARM64/RISC-V64/LoongArch64/PowerPC64LE
FreeBSD
Android x86/x64/ARM32/ARM64
Platform Blue (a popular game console) x64
macOS x64/ARM64
iOS x64/ARM64
MSYS2 MinGW64
WebAssembly, see this separate project.

Required CPU features

On x86/x64 the minimal requirements are SSE2. The library can be compiled using SSE4.1, SSE4.2, AVX, AVX2, or AVX512.
On ARM64 (AArch64) the library uses NEON and is compatible with Armv8-A. On ARM32 (AArch32) it doesn't use any special CPU instructions.

Documentation

To get started, look at the HelloWorld example. A HelloWorld example using CMake FetchContent is also available to show how you can integrate Jolt Physics in a CMake project.

Every feature in Jolt has its own sample. Running the Samples application and browsing through the code is a great way to learn about the library!

To learn more about Jolt go to the latest Architecture and API documentation. Documentation for a specific release is also available.

Some algorithms used by Jolt are described in detail in my GDC 2022 talk: Architecting Jolt Physics for 'Horizon Forbidden West' (slides, slides with speaker notes, video).

Compiling

Compiles with Visual Studio 2022+, Clang 16+ or GCC 12+.
Uses C++ 17.
Depends only on the standard template library.
Doesn't use RTTI.
Doesn't use exceptions.

If you want to run on Platform Blue you'll need to provide your own build environment and PlatformBlue.h due to NDA requirements. This file is available on the Platform Blue developer forum.

For build instructions go to the Build section. When upgrading from an older version of the library go to the Release Notes or API Changes sections.

Performance

If you're interested in how Jolt scales with multiple CPUs and compares to other physics engines, take a look at this document.

Folder structure

Assets - This folder contains assets used by the TestFramework, Samples and JoltViewer.
Build - Contains everything needed to build the library, see the Build section.
Docs - Contains documentation for the library.
HelloWorld - A simple application demonstrating how to use the Jolt Physics library.
Jolt - All source code for the library is in this folder.
JoltViewer - It is possible to record the output of the physics engine using the DebugRendererRecorder class (a .jor file), this folder contains the source code to an application that can visualize a recording. This is useful for e.g. visualizing the output of the PerformanceTest from different platforms. Currently available on Windows, macOS and Linux.
PerformanceTest - Contains a simple application that runs a performance test and collects timing information.
Samples - This contains the sample application, see the Samples section. Currently available on Windows, macOS and Linux.
TestFramework - A rendering framework to visualize the results of the physics engine. Used by Samples and JoltViewer. Currently available on Windows, macOS and Linux.
UnitTests - A set of unit tests to validate the behavior of the physics engine.

Bindings for other languages

C here, here, here and here
C#
Java or Kotlin here and here
JavaScript
Rust
Python
Zig
Jai, based on this bindings generator

Integrations in other engines

Godot
Source Engine
Unreal Plugin here and here

See a list of projects that use Jolt Physics here.

License

The project is distributed under the MIT license.

Contributions

All contributions are welcome! If you intend to make larger changes, please discuss first in the GitHub Discussion section. For non-trivial changes, we require that you agree to a Contributor Agreement. When you create a PR, CLA assistant will prompt you to sign it.

Note that all PRs will be squashed before merging, so there's no need to force-push to git to keep the history clean.

meshtastic/firmware

The official firmware for Meshtastic, an open-source, off-grid mesh communication system.

Meshtastic Firmware

Website - Documentation

Overview

This repository contains the official device firmware for Meshtastic, an open-source LoRa mesh networking project designed for long-range, low-power communication without relying on internet or cellular infrastructure. The firmware supports various hardware platforms, including ESP32, nRF52, RP2040/RP2350, and Linux-based devices.

Meshtastic enables text messaging, location sharing, and telemetry over a decentralized mesh network, making it ideal for outdoor adventures, emergency preparedness, and remote operations.

Get Started

🔧 Building Instructions - Learn how to compile the firmware from source.
⚡ Flashing Instructions - Install or update the firmware on your device.

Join our community and help improve Meshtastic! 🚀

Stats

electron/electron

Build cross-platform desktop apps with JavaScript, HTML, and CSS

📝 Available Translations: 🇨🇳 🇧🇷 🇪🇸 🇯🇵 🇷🇺 🇫🇷 🇺🇸 🇩🇪. View these docs in other languages on our Crowdin project.

The Electron framework lets you write cross-platform desktop applications using JavaScript, HTML and CSS. It is based on Node.js and Chromium and is used by the Visual Studio Code and many other apps.

Follow @electronjs on Twitter for important announcements.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to coc@electronjs.org.

Installation

To install prebuilt Electron binaries, use npm. The preferred method is to install Electron as a development dependency in your app:

npm install electron --save-dev

For more installation options and troubleshooting tips, see installation. For info on how to manage Electron versions in your apps, see Electron versioning.

Platform support

Each Electron release provides binaries for macOS, Windows, and Linux.

macOS (Ventura and up): Electron provides 64-bit Intel and Apple Silicon / ARM binaries for macOS.
Windows (Windows 10 and up): Electron provides x64 (amd64) and arm64 binaries for Windows.
Linux: Electron provides x64 (amd64) and arm64 binaries for Linux. Electron supports major Linux distributions (e.g., Ubuntu, Fedora, Debian) in versions that are still supported by both Chromium and the distro maker (without requiring a paid subscription). The prebuilt binaries are built on Ubuntu.

In general, Electron tries to align with Chromium on platform support.

Electron Fiddle

Use Electron Fiddle to build, run, and package small Electron experiments, to see code examples for all of Electron's APIs, and to try out different versions of Electron. It's designed to make the start of your journey with Electron easier.

Resources for learning Electron

electronjs.org/docs - All of Electron's documentation
electron/fiddle - A tool to build, run, and package small Electron experiments
electronjs.org/community#boilerplates - Sample starter apps created by the community

Programmatic usage

Most people use Electron from the command line, but if you require electron inside your Node app (not your Electron app) it will return the file path to the binary. Use this to spawn Electron from Node scripts:

const electron = require('electron')
const proc = require('node:child_process')

// will print something similar to /Users/maf/.../Electron
console.log(electron)

// spawn Electron
const child = proc.spawn(electron)

Mirrors

China

See the Advanced Installation Instructions to learn how to use a custom mirror.

Documentation translations

We crowdsource translations for our documentation via Crowdin. We currently accept translations for Chinese (Simplified), French, German, Japanese, Portuguese, Russian, and Spanish.

Contributing

If you are interested in reporting/fixing issues and contributing directly to the code base, please see CONTRIBUTING.md for more information on what we're looking for and how to get started.

Community

Info on reporting bugs, getting help, finding third-party tools and sample apps, and more can be found on the Community page.

License

MIT

When using Electron logos, make sure to follow OpenJS Foundation Trademark Policy.

lemonade-sdk/lemonade

Lemonade helps users discover and run local AI apps by serving optimized LLMs right from their own GPUs and NPUs. Join our discord: https://discord.gg/5xXzkMu8Zk

🍋 Lemonade: Refreshingly fast local AI

Download | Documentation | Discord

Lemonade is the local AI server that gives you the same capabilities as cloud APIs, except 100% free and private. Use the latest models for chat, coding, speech, and image generation on your own NPU and GPU.

Lemonade comes in two flavors:

Lemonade Server installs a service you can connect to hundreds of great apps using standard OpenAI, Anthropic, and Ollama APIs.
Embeddable Lemonade is a portable binary you can package into your own application to give it multi-modal local AI that auto-optimizes for your user’s PC.

This project is built by the community for every PC, with optimizations by AMD engineers to get the most from Ryzen AI, Radeon, and Strix Halo PCs.

Getting Started

Install: Windows · Linux · macOS · Docker · Source
Get Models: Browse and download with the Model Manager
Generate: Try models with the built-in interfaces for chat, image gen, speech gen, and more
Mobile: Take your lemonade to go: iOS · Android · Source
Connect: Use Lemonade with your favorite apps:

Want your app featured here? Just submit a marketplace PR!

Supported Platforms

Platform	Build

Using the CLI

To run and chat with Gemma:

lemonade run Gemma-4-E2B-it-GGUF

To code with Lemonade models:

lemonade launch claude

Multi-modality:

# image gen
lemonade run SDXL-Turbo

# speech gen
lemonade run kokoro-v1

# transcription
lemonade run Whisper-Large-v3-Turbo

To see available models and download them:

lemonade list

lemonade pull Gemma-4-E2B-it-GGUF

To manage model aliases for environment-independent naming and active-standby failover:

lemonade alias add production-llm Gemma-4-E2B-it-GGUF
lemonade alias list

# Instant active-standby failover to a different model target
lemonade alias add production-llm Qwen3-0.6B-GGUF
lemonade alias remove production-llm

To see the backends available on your PC:

lemonade backends

For hybrid setups, Lemonade can also route to any OpenAI-compatible cloud provider (Fireworks, OpenAI, OpenRouter, Together, …) alongside local models — see Cloud Offload. (Experimental.)

Model Library

Lemonade supports a wide variety of LLMs (GGUF, FLM, and ONNX), whisper, stable diffusion, etc. models across CPU, GPU, and NPU.

Use lemonade pull or the built-in Model Manager to download models. Custom GGUF/ONNX models can be pulled from Hugging Face or ModelScope, with their source retained for future updates.

Browse all built-in models →

Supported Configurations

Lemonade supports multiple inference engines for LLM, speech, TTS, and image generation, and each has its own backend and hardware requirements.

Modality	Engine	Backend	Device	OS
Text generation	`llamacpp`	`system`	`x86_64`/ARM64 CPU, GPU	Linux
		`metal`	Apple Silicon GPU	macOS
		`cuda`	NVIDIA GPUs (Turing or newer)**	Windows, Linux
		`vulkan`	`x86_64` CPU, AMD iGPU, AMD dGPU; ARM64 CPU/GPU (Linux)	Windows, Linux
		`rocm`	AMD GPUs supported by ROCm	Windows, Linux
		`cpu`	`x86_64` CPU; ARM64 CPU (Linux)	Windows, Linux
	`flm`	`npu`	XDNA2 NPU	Windows, Linux
	`ryzenai-llm`	`npu`	XDNA2 NPU	Windows
	`vllm` (experimental)	`rocm`	Strix Halo iGPU (gfx1151)	Linux
Speech-to-text	`whispercpp`	`npu`	XDNA2 NPU	Windows
		`metal`	Apple Silicon GPU	macOS
		`vulkan`	`x86_64` CPU	Windows, Linux
		`rocm`	Supported AMD ROCm iGPU/dGPU families*	Windows, Linux
		`cpu`	`x86_64` CPU	Windows, Linux
	`moonshine`	`cpu`	`x86_64`/`arm64` CPU	Windows, Linux, macOS
Text-to-speech	`kokoro`	`metal`	Apple Silicon GPU	macOS
	`kokoro`	`cpu`	`x86_64` CPU	Windows, Linux
	`openmoss` (experimental)	`cuda`	NVIDIA GPUs	Windows, Linux
		`vulkan`	Vulkan-capable GPUs	Windows, Linux
		`rocm`	AMD GPUs (ROCm via TheRock)	Windows, Linux
Audio generation	`thinksound` (experimental)	`cuda`	NVIDIA GPUs	Windows, Linux
		`vulkan`	Vulkan-capable GPUs	Windows, Linux
		`rocm`	Supported AMD ROCm iGPU/dGPU families (ROCm via TheRock)	Windows, Linux
	`acestep` (experimental)	`cuda`	NVIDIA GPUs	Windows, Linux
		`vulkan`	Vulkan-capable GPUs	Windows, Linux
		`rocm`	Supported AMD ROCm iGPU/dGPU families (ROCm via TheRock)	Windows, Linux
Image generation	`sd-cpp`	`metal`	Apple Silicon GPU	macOS
		`cuda`	NVIDIA GPUs (Turing or newer)**	Windows, Linux
		`vulkan`	Vulkan-capable GPUs	Windows, Linux
		`rocm`	Supported AMD ROCm iGPU/dGPU families*	Windows, Linux
		`cpu`	`x86_64` CPU	Windows, Linux
	`thenoise` (experimental)	`rocm`	Supported AMD ROCm iGPU families	Linux
3D generation	`trellis` (experimental)	`cuda`	NVIDIA GPUs	Windows, Linux
		`vulkan`	Vulkan-capable GPUs	Windows, Linux
		`rocm`	Supported AMD ROCm iGPU/dGPU families (ROCm via TheRock)	Windows, Linux
Text classification	`onnxruntime` (experimental)	`cpu`	`x86_64` CPU	Windows
		`cpu`	`x86_64`/`arm64` CPU	Linux
		`cpu`	`arm64` CPU	macOS

To check exactly which recipes/backends are supported on your own machine, run:

lemonade backends

* See supported AMD ROCm platforms

Architecture	Platform Support	GPU Models
gfx1151 (STX Halo)	Windows, Ubuntu	Ryzen AI MAX+ Pro 395
gfx120X (RDNA4)	Windows, Ubuntu	Radeon AI PRO R9700, RX 9070 XT/GRE/9070, RX 9060 XT
gfx110X (RDNA3)	Windows, Ubuntu	Radeon PRO W7900/W7800/W7700/V710, RX 7900 XTX/XT/GRE, RX 7800 XT, RX 7700 XT

** See supported NVIDIA CUDA platforms

Compute Capability	Architecture	GPU Models
sm_75	Turing	RTX 20-series, GTX 16-series, T4
sm_80 / sm_86	Ampere	RTX 30-series, A100, A40
sm_89	Ada Lovelace	RTX 40-series, L40, L4
sm_90	Hopper	H100, H200
sm_100 / sm_120	Blackwell	RTX 50-series, B100, B200

Project Roadmap

Lemonade's roadmap is defined by a set of working groups. Visit the landing page here to learn each group's goal and roadmap.

Integrate Embeddable Lemonade in Your Application

Embeddable Lemonade is a binary version of Lemonade that you can bundle into your own app to give it a portable, auto-optimizing, multi-modal local AI stack. This lets users focus on your app, with zero Lemonade installers, branding, or telemetry.

Check out the Embeddable Lemonade guide.

Connect Lemonade Server to Your Application

You can use any OpenAI-compatible client library by configuring it to use http://localhost:13305/v1 as the base URL. A table containing official and popular OpenAI clients on different languages is shown below.

Feel free to pick and choose your preferred language.

Python	C++	Java	C#	Node.js	Go	Ruby	Rust	PHP
openai-python	openai-cpp	openai-java	openai-dotnet	openai-node	go-openai	ruby-openai	async-openai	openai-php

Python Client Example

from openai import OpenAI

# Initialize the client to use Lemonade Server
client = OpenAI(
    base_url="http://localhost:13305/api/v1",
    api_key="lemonade"  # required but unused
)

# Create a chat completion
completion = client.chat.completions.create(
    model="Gemma-4-E2B-it-GGUF",  # or any other available model
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

# Print the response
print(completion.choices[0].message.content)

Click to learn more about the available APIs and how to embed Lemonade in your own application.

FAQ

To read our frequently asked questions, see our FAQ Guide

Contributing

Lemonade is built by the local AI community! If you would like to contribute to this project, please check out our contribution guide.

Maintainers

This is a community project maintained by @amd-pworfolk @bitgamma @danielholanda @jeremyfowers @kenvandine @Geramy @ramkrishna2910 @sawansri @siavashhub @sofiageo @superm1 @vgodsoe, and sponsored by AMD. You can reach us by filing an issue, emailing lemonade@amd.com, or joining our Discord.

Code Signing Policy

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

Committers and reviewers: Maintainers of this repo
Approvers: Owners

Privacy policy: This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. When the user requests a model download or registry lookup, Lemonade may contact Hugging Face Hub (see their privacy policy) or ModelScope, according to the model source selected by the user or packager.

License and Attribution

This project is:

Built with C++ (server) and React (app) with ❤️ for the open source community,
Standing on the shoulders of great tools from:
- ggml/llama.cpp
- ggml/whisper.cpp
- ggml/stable-diffusion.cpp
- kokoros
- OnnxRuntime GenAI
- Hugging Face Hub
- ModelScope
- OpenAI API
- IRON/MLIR-AIE
- and more...
Licensed under the Apache 2.0 License.
- Portions of the project are licensed as described in LICENSE.