ggwave

Tiny data-over-sound library.

# generate audio waveform for string "hello python"
waveform = ggwave.encode("hello python")

# decode audio waveform
text = ggwave.decode(instance, waveform)

Features

Audible and ultrasound transmissions available
Bandwidth of 8-16 bytes/s (depending on the transmission protocol)
Robust FSK modulation
Reed-Solomon based error correction

Installation

pip install ggwave

API

encode()

encode(payload, [protocolId], [volume], [instance])

Encodes payload into an audio waveform.

Output of help(ggwave.encode):

cython_function_or_method in module ggwave

encode(payload, protocolId=1, volume=10, instance=None)
    Encode payload into an audio waveform.
    @param {string} payload, the data to be encoded
    @return Generated audio waveform bytes representing 16-bit signed integer samples.

decode()

decode(instance, waveform)

Analyzes and decodes waveform into to try and obtain the original payload. A preallocated ggwave instance is required.

Output of help(ggwave.decode):

cython_function_or_method in module ggwave

decode(instance, waveform)
    Analyze and decode audio waveform to obtain original payload
    @param {bytes} waveform, the audio waveform to decode
    @return The decoded payload if successful.

Usage

Encode and transmit data with sound:

import ggwave
import pyaudio

p = pyaudio.PyAudio()

# generate audio waveform for string "hello python"
waveform = ggwave.encode("hello python", protocolId = 1, volume = 20)

print("Transmitting text 'hello python' ...")
stream = p.open(format=pyaudio.paFloat32, channels=1, rate=48000, output=True, frames_per_buffer=4096)
stream.write(waveform, len(waveform)//4)
stream.stop_stream()
stream.close()

p.terminate()

Capture and decode audio data:

import ggwave
import pyaudio

p = pyaudio.PyAudio()

stream = p.open(format=pyaudio.paFloat32, channels=1, rate=48000, input=True, frames_per_buffer=1024)

print('Listening ... Press Ctrl+C to stop')
instance = ggwave.init()

try:
    while True:
        data = stream.read(1024, exception_on_overflow=False)
        res = ggwave.decode(instance, data)
        if (not res is None):
            try:
                print('Received text: ' + res.decode("utf-8"))
            except:
                pass
except KeyboardInterrupt:
    pass

ggwave.free(instance)

stream.stop_stream()
stream.close()

p.terminate()

Check out http://github.com/ggerganov/ggwave for more information about ggwave!

Development

Check out ggwave python package on Github.

Release files for ggwave 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ggwave 0.4.3
File	Size	Uploaded
ggwave-0.4.3.tar.gz	98.1 kB	Mar 21, 2026	Details

Release files / ggwave-0.4.3.tar.gz

Download URL	ggwave-0.4.3.tar.gz
Size	98.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`8699244804231eed6e7c1e0a7fa5bd1c7b495c32ea735f65690b896180cfbfac`
BLAKE2b-256 checksum How to use checksums	`225aac1d3125e6e9aff6be467c2bc754bdbb7a548730b2399b495f5856402960`
Upload date	Mar 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.12.3`