Clarify real-world use cases and problem statement in README

[nixkitax]

The README provides great technical details and many examples, but it’s not immediately clear what core problems ggwave is meant to solve or when it should be preferred over alternatives like QR codes, BLE, or NFC.

A short section such as “Why ggwave?” or “When does ggwave make sense?” could help newcomers quickly understand the intended use cases (air-gapped, zero pairing, one-to-many, etc.) and the main tradeoffs (very low bandwidth, robustness vs speed)

It would significantly improve approachability by new users

[Manamama]

True. I was investigating if it could be used over VOIP (sic) connections where (VOIP) voice calls are allowed, but not the Net. There is a related Dolphin demodulation protocol proposed for that, cannot find the URL that easily *. See also somehow related: https://www.mdpi.com/1424-8220/17/11/2447

• Update: found it:
  https://petsymposium.org/popets/2023/popets-2023-0034.pdf (or the full paper "Dolphin: A Cellular Voice Based Internet Shutdown Circumvention Tool").

[Manamama]

Update: I have asked Grok xAI to come up with some and:

Why ggwave? / When does ggwave make sense?

ggwave is a lightweight library for transmitting small amounts of data over sound (acoustic or ultrasonic) using a robust FSK-based protocol with error correction. It shines in scenarios where traditional wireless methods fall short.

Core problems it solves

• True air-gapped communication: Devices with no shared network, Bluetooth, Wi-Fi, or cables can still exchange data simply by playing and listening to audio. Perfect for high-security or isolated environments.
• Zero pairing / zero configuration: No Bluetooth pairing, NFC tap, QR code alignment, or app installation required by receiving party, beyond a speaker + microphone plus browser. Just play the sound and the receiver picks it up. [see note]
• One-to-many broadcast: A single transmitter can reach any number of listeners in range simultaneously — ideal for announcements or sharing without unicast overhead.
• Works with everyday hardware: Uses built-in speakers/microphones on phones, laptops, microcontrollers (Arduino, ESP32, RP2040), or even PC speakers/buzzers. No extra radios needed.
• Stealth / ultrasonic options: Can operate in ultrasonic frequencies (inaudible to humans) for discreet transfers.

When to prefer ggwave over alternatives

Scenario	ggwave	QR Codes	BLE / NFC	Why ggwave?
Air-gapped / no hardware add-ons	Excellent	Good (visual)	Poor (needs radios)	Sound works where cameras or radios are blocked or unavailable.
One-to-many	Excellent (broadcast)	Good (one display, many scanners)	Poor (pairing)	Naturally reaches everyone in earshot.
Zero setup / ad-hoc	Excellent	Good	Medium (pairing)	Play sound → done. No alignment or discovery needed. [see note]
Low-light / non-line-of-sight	Excellent	Poor	Good	Audio goes around corners and works in dark.
Microcontroller / IoT with minimal hardware	Excellent	Medium	Medium	Cheap speaker/buzzer + mic is enough.
High bandwidth needs	Poor (8-16 bytes/sec)	Excellent	Excellent	Use alternatives for large data.
Very short range (< few meters)	Excellent	Good	Excellent	But ggwave needs no physical contact.

Key tradeoffs

• Very low bandwidth — Best for small payloads: URLs, Wi-Fi credentials, contact info, short commands, public keys, configuration snippets, or telemetry. Not for files or streaming.
• Robustness vs. speed — Slower modes with more error correction handle noisy environments better (background noise, distance, lower volume). Faster modes trade reliability for speed.
• Range — Typically a few meters in normal conditions; depends on volume, noise, and protocol settings. Ultrasonic is shorter but stealthier.
• Directionality & interference — Audio is omnidirectional but can be affected by loud environments or barriers that block sound.

Invented / expanded real-world use cases

• Secure device provisioning — Factory-reset IoT devices or cameras receive Wi-Fi credentials or initial config via sound from a phone (similar to existing audio-based setup but fully open and customizable).
• Contact / key exchange in privacy-sensitive settings — Conferences, protests, or offline meetups where you want to share vCards or public keys without enabling Bluetooth or scanning QR in public.
• Audio "QR codes" for broadcasting — Share a link, clipboard content, or small message to everyone nearby (e.g., event info, emergency alerts).
• Talking buttons / assistive tech — Record commands or phrases that play as ggwave data to trigger actions on nearby devices.
• Offline multi-device coordination — Robots, drones, or sensor networks in areas without network coverage (e.g., caves, industrial sites, disaster zones).
• AI agent communication (emerging) — Agents on a voice call detect each other and switch to efficient data-over-sound for faster, lower-overhead exchange while still using the audio channel.
• Creative & fun — Sound-programmable e-paper badges, game sync (e.g., syncing recordings), embedding metadata in video takes, or serverless file-sharing demos.

In short: Choose ggwave when you need simple, infrastructure-free, air-gapped data transfer for small payloads with minimal hardware and zero setup. It trades speed for accessibility, robustness, and universality — making it a great complement (or fallback) to QR codes, BLE, and NFC.

This section could be added near the top of the README for better newcomer onboarding.

OTOH, "zero setup" is ehm ... debatable. (I created a PR yesterday so I know a bit why "zero setup" is not fully correct). So a note about it:

Near-zero configuration
The sender usually needs a tool or device with ggwave integrated. The receiver can often participate with just a web browser: open the official demo, allow microphone access, and start listening. No pairing, no accounts, no special hardware.