Repolode
Submit
ggerganov

ggerganov/ggwave

A tiny C++ library that sends small amounts of data between devices using sound, usable from Python, JavaScript, and microcontrollers.

View on GitHubWebsite
Stars
7,906
Forks
479
Open issues
65
Last commit
6 months ago

What is it?

ggwave lets devices exchange small pieces of data over sound, which is useful when they cannot use a network connection. It uses a multi-frequency FSK modulation scheme with Reed-Solomon error correction, and it can transmit both audible and ultrasonic signals. The stated bandwidth is roughly 8 to 16 bytes per second, depending on protocol parameters.

The library only generates and analyzes raw waveforms. Your own audio backend, such as PulseAudio, ALSA, or Web Audio, handles playback and capture through callbacks for queuing and dequeuing samples. Bindings and packages are available for Python, Node.js, and Swift, and the examples include code for ESP32, Arduino, and Raspberry Pi Pico.

The project also includes the Waver app for iOS, Android, Linux, and macOS, plus browser demos for testing transmissions.

Key features

  • 01Transmits small data payloads over audible or ultrasonic sound.
  • 02Uses FSK modulation with Reed-Solomon error correction.
  • 03Works with any audio backend through sample queue callbacks.
  • 04Provides bindings for Python, Node.js, and Swift.
  • 05Includes examples for ESP32, Arduino, and Raspberry Pi Pico.

Use cases

  • Sharing a short message or pairing code between nearby devices without a network.
  • Sending commands from a PC or phone to microcontrollers that have a microphone or speaker.
  • Building offline device pairing or contact exchange features.
  • Prototyping data-over-sound protocols for IoT projects.

Quick start

  1. 1

    Install the Python package

    pip install ggwave
  2. 2

    Or build the C++ library and CLI with CMake

    git clone https://github.com/ggerganov/ggwave --recursive && cd ggwave && mkdir build && cd build && cmake .. && make
  3. 3

    Run the command line tool

    ./bin/ggwave-cli

Things to know

  • Throughput is very low, roughly 8-16 bytes per second.
  • Building the SDL-based examples requires installing SDL2 separately.

Topics

#data-over-sound#audio#fsk#iot#error-correction#cpp#python#embedded#arduino#ecc

FAQ

What is ggwave?
A tiny C++ library that sends small amounts of data between devices using sound, usable from Python, JavaScript, and microcontrollers. ggwave lets devices exchange small pieces of data over sound, which is useful when they cannot use a network connection. It uses a multi-frequency FSK modulation scheme with Reed-Solomon error correction, and it can transmit both audible and ultrasonic signals. The stated bandwidth is roughly 8 to 16 bytes per second, depending on protocol parameters.
Is ggwave free to use? What license does it have?
ggwave is open source under the MIT license. Check the license terms before using it in commercial products.
Is ggwave still maintained?
No commits for 6+ months. The last commit to ggwave was on Apr 16, 2026.
What can I use ggwave for?
Sharing a short message or pairing code between nearby devices without a network. Sending commands from a PC or phone to microcontrollers that have a microphone or speaker. Building offline device pairing or contact exchange features. Prototyping data-over-sound protocols for IoT projects.
How do I install ggwave?
Install the Python package: pip install ggwave Or build the C++ library and CLI with CMake: git clone https://github.com/ggerganov/ggwave --recursive && cd ggwave && mkdir build && cd build && cmake .. && make Run the command line tool: ./bin/ggwave-cli
Where can I get ggwave?
The source code and installation instructions are on GitHub: https://github.com/ggerganov/ggwave

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects