Skip to content

ggwave.md

Latest commit

 

History

History
90 lines (66 loc) · 2.36 KB

ggwave.md

File metadata and controls

90 lines (66 loc) · 2.36 KB

ggwave CLI

Transfer JSON metadata between machines via audio using ggwave.

Commands

ggwave send [-protocol N] [-volume N] [-delay N] [-repeat N] [-out file.wav]
ggwave recv [-timeout duration] [-in file.wav]

send

Reads JSON from stdin, compresses, chunks, and transmits via speaker.

Flag Default Description
-protocol 1 (Audible Fast) ggwave protocol ID
-volume 25 Volume (1-50)
-delay 2000 Inter-chunk delay in ms
-repeat 1 Per-chunk repeat count
-out (speaker) Write WAV file instead

recv

Listens on microphone, decodes, reassembles, and writes JSON to stdout.

Flag Default Description
-timeout 30s Silence timeout
-in (microphone) Read WAV file instead

Chunking Protocol

ggwave transmits up to 140 bytes per message. Larger payloads are gzip-compressed and split into chunks.

Data chunk (<=140 bytes)

Offset  Size  Field
0       1     Magic+Version (0x61)
1       1     SessionID
2       1     SeqNum (0-254)
3       1     TotalChunks
4-5     2     CRC-16 CCITT (over payload)
6-139   134   Payload

EOT frame (44 bytes, sent twice)

Offset  Size  Field
0       1     Magic+Version (0x61)
1       1     SessionID
2       1     0xFF (EOT marker)
3       1     TotalChunks
4-7     4     CRC-32 (original data)
8-11    4     Original data size (big-endian)
12-43   32    SHA-256 (compressed data)

Transmission flow

  1. Compress input with gzip
  2. Split into 134-byte chunks with 6-byte headers
  3. Encode each chunk with ggwave, play via speaker
  4. Send EOT frame twice

Reception flow

  1. Decode audio frames with ggwave
  2. Lock to first SessionID received
  3. Verify CRC-16 per chunk, deduplicate by SeqNum
  4. On completion: verify SHA-256 and CRC-32, decompress, output

Estimated Transfer Time

Using Audible Fast protocol with 2-second interval:

Input Compressed Chunks Time
500B ~200B 2 ~12s
1KB ~400B 3 ~17s
5KB ~2KB 15 ~80s

Dependencies

  • ggwave — audio data transmission library (system install)
  • PortAudio — cross-platform audio I/O (brew install portaudio)
  • CGO_ENABLED=1 required