How GGWave Transmits Data Through Sound: A Technical Deep Dive

GGWave is the core technology behind GibberLink's audio data transmission. Created by Georgi Gerganov, it is an open-source library that converts digital data into sound and back using Frequency-Shift Keying (FSK) modulation. This article explains exactly how it works at the signal processing level.

The Encoding Pipeline

When you transmit a message through ggwave, the data passes through several stages before it becomes audible sound.

Step 1: Payload Preparation

The input text is first converted to raw bytes. GGWave supports payloads up to 140 bytes. The bytes are then processed through a Reed-Solomon encoder that adds redundancy for error correction.

Reed-Solomon coding is the same error correction scheme used in QR codes, CDs, and deep-space communication. It allows the receiver to reconstruct the original data even if some of the transmitted symbols are corrupted by noise.

Step 2: Symbol Mapping

The encoded bytes are split into 4-bit nibbles (values 0–15). Each nibble maps to a specific audio frequency. GGWave uses 96 frequencies spread across a 4.5 kHz band, which means multiple nibbles can be transmitted simultaneously.

At any given moment, 6 tones are played together, encoding 6 nibbles (3 bytes) at once. This parallel transmission is what gives ggwave its relatively high throughput for an acoustic protocol.

Step 3: Tone Generation

Each frequency is generated as a pure sine wave at the target sample rate (typically 48 kHz). The tones for each symbol period are summed together and windowed to prevent audible clicks at the boundaries.

The transmission structure looks like this:

[Marker Tones] [Data Tones] [Data Tones] ... [Data Tones] [Marker Tones]

Marker tones are fixed-frequency signals at the beginning and end of each transmission. They serve two purposes:

1. Synchronization: The receiver uses them to detect the start of a transmission and align its decoding window.
2. Calibration: They help the receiver estimate the channel characteristics (volume level, frequency response).

Step 4: Sample Format

The final output is a waveform of signed 16-bit integer samples (I16 format). For a short message like "hello" at 48 kHz sample rate, the output is typically around 120,000 samples (~2.5 seconds of audio).

The Decoding Pipeline

Decoding reverses the process, but with additional challenges since the received audio may contain noise, echoes, and timing offsets.

Step 1: Marker Detection

The receiver continuously analyzes incoming audio using a sliding FFT (Fast Fourier Transform) window. It looks for the characteristic pattern of marker tones that signals the start of a ggwave transmission.

The soundMarkerThreshold parameter controls how sensitive this detection is. A lower threshold catches weaker signals but may produce false positives in noisy environments.

Step 2: Frequency Analysis

Once a transmission is detected, the receiver applies FFT to each symbol period to identify which frequencies are present. The 6 strongest peaks in the expected frequency band correspond to the 6 transmitted nibbles.

Step 3: Symbol Recovery

The detected frequencies are mapped back to nibble values, and the nibbles are reassembled into bytes. The Reed-Solomon decoder then checks for and corrects any errors.

If the number of errors exceeds the correction capacity of the Reed-Solomon code, the decode fails and returns null. In practice, the error correction can handle a significant amount of noise — transmissions typically succeed even in moderately noisy environments.

Protocol Variants

GGWave offers several protocol options that trade off speed against reliability:

| Protocol | Speed | Frequency Band | Best For | |----------|-------|----------------|----------| | Audible Normal | ~8 bytes/s | 1.5–6 kHz | Reliable transmission in most environments | | Audible Fast | ~12 bytes/s | 1.5–6 kHz | Faster transmission, moderate noise tolerance | | Audible Fastest | ~16 bytes/s | 1.5–6 kHz | Maximum speed, requires quiet environment | | Ultrasound Normal | ~8 bytes/s | 15–20 kHz | Inaudible to most humans | | DT Normal | ~8 bytes/s | 1.5–6 kHz | Dual-tone variant for specific use cases |

The ultrasound protocols are particularly interesting for applications where the transmission should be imperceptible to humans. However, many laptop and phone speakers have limited output above 15 kHz, which can reduce reliability.

Browser Implementation

In a web browser, ggwave runs as a WebAssembly (WASM) module compiled from C++ via Emscripten. The integration with the Web Audio API works as follows:

Transmitting:

1. Call ggwave.encode() to get raw audio samples (I16 format)
2. Convert I16 samples to Float32 (divide by 32768) for the Web Audio API
3. Create an AudioBuffer, fill it with the Float32 data
4. Play through an AudioBufferSourceNode connected to the audio output

Receiving:

1. Capture microphone input via getUserMedia()
2. Route audio through a ScriptProcessorNode (or AudioWorkletNode)
3. Convert Float32 samples to I16 format (multiply by 32768)
4. Pass I16 bytes to ggwave.decode()
5. If decode returns data, the transmission was successfully received

The sample format conversion between I16 and Float32 is a critical detail. The Web Audio API exclusively uses Float32 samples in the range [-1.0, 1.0], while ggwave's native format is I16 in the range [-32768, 32767].

Performance Characteristics

We measured ggwave's performance across different conditions:

• Quiet room, 1 meter distance: >99% success rate with Normal protocol
• Office environment, 2 meters: ~95% success rate with Normal protocol
• Same device (speaker to mic): >99% success rate with all protocols
• Phone call (VoIP): ~90% success rate with Normal protocol, depending on codec

The main factors affecting reliability are:

1. Ambient noise level in the transmission frequency band
2. Distance between speaker and microphone
3. Audio codec compression (if transmitting over a call)
4. Speaker/microphone quality of the devices involved

Comparison with Other Data-Over-Sound Solutions

| Feature | GGWave | Chirp (now Sonos) | Quiet Modem | |---------|--------|-------------------|-------------| | Open Source | Yes (MIT) | No | Yes | | Error Correction | Reed-Solomon | Proprietary | Convolutional | | Max Payload | 140 bytes | Varies | Varies | | Ultrasound Support | Yes | Yes | No | | WASM Support | Yes | No | No | | Active Development | Yes | Discontinued | Limited |

GGWave's combination of open-source licensing, WASM support, and active maintenance makes it the most practical choice for web-based data-over-sound applications in 2025.

Try It Yourself

You can experiment with ggwave directly in your browser on our GGWave Demo page. Type a message, click transmit, and watch the real-time frequency spectrum as the data is encoded into sound.

For developers, the ggwave GitHub repository includes examples in C++, Python, and JavaScript.

---

Learn more about how GibberLink uses this technology for AI agent communication in our article: What Is GibberLink?