5 Best Ways to Learn ggwave & Audio Handshake Technology (2026)

Audio handshake technology — sending data through sound waves between nearby devices — has evolved from a niche research topic into a practical feature shipping in consumer apps. At the center of this ecosystem sits ggwave, the tiny, MIT-licensed C library by Georgi Gerganov (creator of whisper.cpp and llama.cpp) that powers everything from browser demos to ESP32 “talking buttons” to production mobile apps.

Whether you’re a developer wanting to add sound-based pairing to your app, a hobbyist building IoT devices, or a product manager evaluating the technology for a feature, here are the 5 best ways to learn ggwave and audio handshake technology — ranked from easiest entry point to deepest technical mastery.

1. Play With It Instantly: Waver Web Demos (Zero Install)

Best for: First contact, concept validation, non-developers
Time to first “hello world”: 30 seconds
URLs: waver.ggerganov.com · ggwave.ggerganov.com · ggwave-js.ggerganov.com

Open two browser tabs (or two phones), hit Init, type a message, and press Broadcast. You’ll hear a brief chirp — that’s your data riding on FSK-modulated sound waves. The receiver decodes it instantly.

No account, no build step, no CLI. Just the WebAssembly-compiled ggwave running in your browser via the Web Audio API.

Pro tip: Open the demo on your phone and laptop simultaneously. The ultrasonic protocol (protocol 4) is inaudible to humans but works great for silent device-to-device transfer.

What you learn: The basic TX/RX loop, protocol differences (audible vs ultrasonic), real-world range and noise robustness.

2. Script It in Python: pip install ggwave

Best for: Data scientists, backend devs, rapid prototyping, automation
Time to first script: 2 minutes
Package: pypi.org/project/ggwave (official, maintained by ggwave team)

import ggwave

# Encode text to waveform (returns bytes ready for WAV or playback)
waveform = ggwave.encode("Hello from Python!", protocolId=1, volume=20)

# Save to file for testing
import wave
with wave.open("hello.wav", "wb") as f:
    f.setnchannels(1)
    f.setsampwidth(2)
    f.setframerate(48000)
    f.writeframes(waveform)

# Decode from microphone or file
# ggwave.decode() accepts raw audio buffers

The Python bindings expose the full API: protocol selection (audible/ultrasonic/fast/ultrasonic-fast), volume control, and direct buffer manipulation. Perfect for Jupyter notebooks, data pipelines, or scripting a “talking button” that reads from a CSV and broadcasts each row.

What you learn: Programmatic encoding/decoding, protocol parameters, integration patterns for larger applications.

3. Build for the Web: npm install ggwave + Web Audio API

Best for: Frontend developers, React/Vue/Astro projects, PWA creators
Time to first component: 10 minutes
Package: npmjs.com/package/ggwave

// React example component
import { useEffect, useRef } from 'react';
import ggwave from 'ggwave';

export function AudioHandshake() {
  const audioCtxRef = useRef<AudioContext>();

  const broadcast = async (text: string) => {
    const audioCtx = audioCtxRef.current || new AudioContext();
    audioCtxRef.current = audioCtx;

    // Generate waveform using ggwave WASM
    const waveform = ggwave.encode(text, 1, 100); // protocol 1 = audible

    // Play via Web Audio API
    const buffer = audioCtx.createBuffer(1, waveform.length, 48000);
    buffer.getChannelData(0).set(new Float32Array(waveform));
    const source = audioCtx.createBufferSource();
    source.buffer = buffer;
    source.connect(audioCtx.destination);
    source.start();
  };

  return <button onClick={() => broadcast("Hello from React!")}>Broadcast</button>;
}

The npm package includes the WebAssembly build and TypeScript definitions. Ideal for adding “share via sound” buttons to web apps, building collaborative whiteboards, or creating interactive museum exhibits.

What you learn: WASM integration, Web Audio API patterns, browser permission handling (microphone access for RX).

4. Go Embedded: ESP32 / Arduino / RP2040 “Talking Buttons”

Best for: IoT builders, hardware hackers, retail/merchant deployments
Time to first hardware demo: 30–60 minutes
Hardware cost: $5–15 (ESP32 DevKit, Arduino Uno R4, or RP2040 Pico)
Examples: examples/esp32-rx, examples/arduino-tx, examples/rp2040-rx, examples/buttons

// Arduino TX example (simplified)
#include <ggwave.h>

GGWave ggwave;
uint8_t txBuffer[GGWAVE_TX_MAX_SIZE];

void setup() {
  Serial.begin(115200);
  ggwave.init();
}

void loop() {
  const char* msg = "Special offer: 20% off!";
  int len = ggwave.encode(msg, strlen(msg), txBuffer, GGWAVE_TX_MAX_SIZE, 1, 20);
  // Send txBuffer to speaker via DAC/PWM/I2S
  delay(5000);
}

This is where ggwave shines for physical-world deployments. Qrblox uses this exact pattern for its Business Portal “Talking Buttons” — merchants place $5 ESP32 devices around their store that continuously broadcast audio handshakes. Shoppers with the Qrblox app receive offers, polls, or loyalty rewards just by walking past.

What you learn: Real-time audio generation on microcontrollers, power optimization, speaker/mic hardware interfacing, protocol selection for noisy environments.

5. Read the Source & Paper: Deep Technical Mastery

Best for: Library authors, protocol designers, grad students, anyone building a competing implementation
Time investment: 2–4 hours for thorough reading
Resources:

• Source: github.com/ggerganov/ggwave — clean, well-commented C (~3k lines core)
• Paper: “Evaluating Acoustic Data Transmission Schemes for Ad-Hoc Communication Between Nearby Smart Devices” (referenced in README)

Key technical areas to study:

The source is remarkably readable. The src/ggwave.c file implements the entire modem; include/ggwave.h is the public API. If you want to port to a new platform (Rust, Go, Zig, bare metal), this is your reference.

What you learn: Production-grade DSP implementation, error correction tradeoffs, cross-platform C library design, acoustic channel modeling.

Bonus: See It in Production — Qrblox App

While the resources above teach you the technology, Qrblox shows you the product.

Qrblox (iOS + Android, free) is the first consumer app to ship ggwave-powered audio handshake as a core feature — not a demo, not a dev tool, but a daily-driver networking utility.

What Makes Qrblox Novel

Real-World Use Cases Enabled

1. Conference Networking — Share your LinkedIn/GitHub across a noisy room without camera fumbling
2. Retail Engagement — “Talking Buttons” broadcast offers to nearby shoppers’ phones
3. Accessibility — Vision-impaired users exchange contacts without visual scanning
4. Zero-Infrastructure — Works offline, no WiFi/Bluetooth/internet for the handshake itself
5. Post-Event Follow-up — Received profiles live in your Qrblox inbox with AI chat history

Quick Comparison: ggwave vs. Alternatives

Bottom line: ggwave hits the sweet spot of active maintenance, permissive license, broad platform support, and proven production use (Qrblox, PairSonic, wave-share, and more).

Which Path Should You Start With?

Further Reading (From the Qrblox Blog)

• Audio Handshake App: Share Data Through Sound with Qrblox — Product overview
• How to Share Data Over Sound Using Your Phone — Step-by-step user guide
• Audio QR vs NFC vs Bluetooth: Which Contactless Sharing Wins? — Detailed comparison
• Audio Business Card: The Modern Way to Share Your Profile — Networking use case
• Build a Talking Button for $5 with ESP32 — Hardware tutorial (coming soon)