DOCSEARCHbyAlgolia
Submit Docs

ggwave Documentation

repository·master·Indexed 27 days ago

https://github.com/ggerganov/ggwave

A lightweight data-over-sound library for transmitting small amounts of data between air-gapped devices using FSK modulation. It provides raw waveform generation and analysis with a bandwidth rate of 8-16 bytes/sec. ggwave supports multiple platforms including C++, Python, Node.js, and WebAssembly, allowing developers to integrate audio hardware interfacing via their own backends.

Tokens
2.7K
Snippets
14
Records
22
Agent score
92%

What's inside ggwave

  1. Overview of ggwave

    master
    ggwave is a tiny data-over-sound library that enables communication between air-gapped devices using sound. It implements an FSK-based (Frequency-Shift Keying) transmission protocol with a bandwidth rate of 8-16 bytes/sec. The library is responsible for generating and analyzing RAW waveforms; developers are expected to provide audio callbacks for queuing and dequeuing samples using any audio backend (e.g., PulseAudio, ALSA, Web Audio API).

  3. Use ggwave JavaScript bindings

    master

    To use ggwave in a JavaScript environment, import the factory and initialize the library asynchronously. Once initialized, you can create an instance using ggwave.init(parameters), encode strings into audio waveforms using ggwave.encode(), and decode waveforms back into data using ggwave.decode().

    Note that ggwave.decode() returns a buffer/array that typically needs to be decoded via TextDecoder to retrieve the original string.

    var factory = require('ggwave')

factory().then(function(ggwave) {
    // create ggwave instance with default parameters
    var parameters = ggwave.getDefaultParameters();

    // Example: enable DSS (Digital Signature Scheme) mode
    parameters.operatingMode |= ggwave.GGWAVE_OPERATING_MODE_USE_DSS;

    var instance = ggwave.init(parameters);
    console.log('instance: ' + instance);

    var payload = 'hello js';

    // generate audio waveform for string "hello js"
    var waveform = ggwave.encode(instance, payload, ggwave.ProtocolId.GGWAVE_PROTOCOL_AUDIBLE_FAST, 10);

    // decode the audio waveform back to text
    var res = ggwave.decode(instance, waveform);

    // Decode the resulting buffer back to a string
    if (new TextDecoder("utf-8").decode(res) != payload) {
        process.exit(1);
    }
});

  4. Build ggwave from source (C++)

    master

    To build the C++ library and its examples, use CMake. Ensure you have the dependencies installed for your platform (e.g., libsdl2-dev on Ubuntu or sdl2 via brew on macOS).

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

# running
./bin/ggwave-cli

  8. Install the Waver application

    master

    Waver is a GUI application for testing ggwave. It is available on various platforms:

    • Linux (Snap):
      sudo snap install waver
sudo snap connect waver:audio-record :audio-record
    - **macOS (Homebrew):**
  ```bash
brew install ggerganov/ggerganov/waver
    • Mobile: Available on the App Store (iOS) and Google Play (Android).

  9. Create a source distribution for ggwave

    master

    To create a source distribution (tarball) located in the dist/ directory to verify the package structure before publishing, run make sdist. You can test the resulting tarball by installing it locally using pip:

    sudo pip install dist/ggwave-*.tar.gz
    make sdist

  11. Publish ggwave to PyPI

    master

    Before publishing, ensure you have updated the version in setup.py.

    There are two ways to publish:

    1. Automatic: Create a tag and push it to GitHub. Travis CI will automatically create the sdist, build wheels, and push them to PyPI.
    2. Manual: Run make publish to create a source distribution and upload it directly to PyPI.
    make publish

  12. Build the ggwave Python extension module

    master
    To build the ggwave extension module as a .so file for local development and testing, run make build. Once built, you can verify the installation by opening a Python interpreter in the same directory as the generated .so file and running import ggwave followed by ggwave.encode('test').
    make build