ggwave-go

[!WARNING] Experimental. This is an unofficial, early-stage port. It is not affiliated with or endorsed by upstream ggwave. The API may change without notice and it has not been battle-tested in production — expect rough edges, and pin a specific commit/tag if you depend on it.

A pure-Go port of ggwave by Georgi Gerganov — a tiny data-over-sound library — plus a command-line tool to send text as an FSK-modulated audio signal and receive/decode it back through the microphone.

The core codec is a faithful reimplementation of the reference C++: the encoder produces bit-identical PCM to upstream ggwave, and the decoder interoperates with waveforms produced by the reference (and vice-versa) across every standard protocol. See Interoperability.

This is an independent Go port. For the original C/C++ library, the browser demos, and the "Waver" apps, see ggerganov/ggwave.

Features

• Send text through the speakers and receive it through the mic (send / receive).
• Encode to / decode from WAV files (encode / decode) — no audio hardware needed.
• All 12 built-in protocols: audible & ultrasound (normal/fast/fastest), and the low-frequency DT / mono-tone MT variants.
• Variable-length (with sound markers) and fixed-length (-l) payloads.
• Optional Direct Sequence Spread (-d, DSS).
• Reed-Solomon error correction, Ooura FFT, and sinc resampling — all pure Go, zero dependencies for the core ggwave package.
• Live audio via PortAudio (cgo); builds without cgo too (file I/O only, with an afplay/aplay fallback for playback).

Install / build

Live audio needs PortAudio:

# macOS
brew install portaudio

# Debian/Ubuntu
sudo apt install portaudio19-dev

Build the CLI:

go build -o bin/ggwave ./cmd/ggwave      # local binary at ./bin/ggwave
# or
go install github.com/TempledUX/ggwave-go/cmd/ggwave@latest   # installs "ggwave"

Without a C toolchain / PortAudio you can still build the file-based tool:

CGO_ENABLED=0 go build -o bin/ggwave ./cmd/ggwave

Usage

ggwave send    [flags] [message]   emit a message through the speakers
ggwave receive [flags]             listen on the microphone and print messages
ggwave encode  [flags] [message]   write the modulated waveform to a WAV file
ggwave decode  [flags] <file.wav>  decode a WAV file and print decoded messages
ggwave list                        list the available protocols

Common flags: -p N protocol id (default 1), -v N volume in (0,100] (default 50), -s N sample rate (default 48000), -l N fixed payload length in [1,64], -d enable DSS. Combined short flags like -p2 work, as does -p 2.

If [message] is omitted for send/encode, it is read from standard input.

Examples

# Play "Hello, world!" out loud (audible fast protocol)
ggwave send "Hello, world!"

# Listen and print any messages heard on the mic (Ctrl-C to stop)
ggwave receive

# Ultrasound (near-inaudible) transmission
ggwave send -p4 "over ultrasound"

# Write a WAV instead of playing, then decode it
ggwave encode -p1 -o hello.wav "Hello, world!"
ggwave decode hello.wav

# Pipe a WAV straight out
ggwave encode "piped" > out.wav

Library

The ggwave package can be used directly (go get github.com/TempledUX/ggwave-go/ggwave) — it has zero dependencies:

p := ggwave.DefaultParameters()
p.OperatingMode = ggwave.OperatingModeTX
inst, _ := ggwave.New(p)
inst.Encode([]byte("hi"), ggwave.ProtocolAudibleFast, 25)
samples := inst.TxWaveformF32() // []float32 in [-1,1]

p := ggwave.DefaultParameters()
p.OperatingMode = ggwave.OperatingModeRX
p.SampleFormatInp = ggwave.SampleFormatF32
inst, _ := ggwave.New(p)
inst.Decode(ggwave.Float32ToBytesLE(frame)) // feed ~1024 samples at a time
if data, n := inst.RxTakeData(); n > 0 {
    fmt.Println(string(data))
}

Protocol summary

Data is split into 4-bit chunks; each chunk selects one of 16 tones in a 4.5 kHz band divided into 96 equally-spaced bins (dF = 46.875 Hz). Non-ultrasound protocols start at F0 = 1875 Hz, ultrasound at 15000 Hz. Reed-Solomon ECC is added, and start/end sound markers delimit variable-length transmissions. Bandwidth is ~8–16 bytes/sec depending on the protocol.

Interoperability

go test ./ggwave verifies encode/decode roundtrips, Reed-Solomon, and fixed-length decoding. If the reference ggwave-to-file / ggwave-from-file binaries are available, additional tests assert cross-compatibility and byte-exact PCM output. Point GGWAVE_REF_DIR at the directory containing them (defaults to /tmp/ggref):

GGWAVE_REF_DIR=/path/to/ggwave/build/bin go test -v ./ggwave

Note: the mono-tone (MT) protocols 9–11 are fixed-length only. As with the reference ggwave-to-file/ggwave-from-file tools, MT does not round-trip through these simple file utilities; the generated audio is nonetheless byte-identical to the reference.

Android / mobile

ggmobile/ is a gomobile bind facade over the core codec — build it into an Android AAR (or iOS framework) and drive audio I/O from the host app. Because the encoder is byte-exact, an app built on it interoperates with the reference ggwave apps and demos. See android/README.md for the API surface, Kotlin send/receive examples, and build instructions.

Layout

ggwave/          pure-Go core: protocols, Reed-Solomon, FFT, encode, decode, WAV, resampler
audio/           PortAudio playback/capture (cgo) with a non-cgo stub
cmd/ggwave/      the CLI
ggmobile/        gomobile binding facade (Android AAR / iOS framework)
android/         Android integration guide

Status

Experimental. The core codec is verified byte-exact against the reference (see Interoperability), but this is an early-stage, unofficial port maintained on a best-effort basis. Expect API changes, gaps, and rough edges; pin a commit or tag if you build on it, and please file issues for anything that misbehaves.

Credits & acknowledgements

This project is a Go port; all credit for the design, protocols, and DSP goes to the original authors.

• ggwave by Georgi Gerganov — the original data-over-sound library this port reimplements (MIT). If you find this useful, please star and support the upstream project.
• Reed-Solomon codec by Mike Lubinets (MIT).
• FFT routines by Takuya Ooura (1996–2001).

License

MIT. The original ggwave and the bundled Reed-Solomon and FFT components are used under their respective MIT / permissive licenses; see LICENSE for the full notices.