GGWave Python Wrapper

A Python wrapper for GGWave, a data-over-sound communication library.

This Python library is built on top of the existing Python bindings from the official GGWave repository. However, the original bindings are minimal and lack usability features, so this wrapper provides a more user-friendly API with enum support, streamlined encoding/decoding, and optional PyAudio integration.

📌 Features

• Encode and decode messages using sound waves.
• Support for multiple transmission protocols.
• Optional real-time audio transmission and reception via PyAudio.

🚀 Installation

Basic installation

pip install ggwave_python

With audio support (PyAudio)

pip install ggwave_python[audio]

🔧 Usage

Encoding and decoding messages

from ggwave_python import GGWave, ProtocolId

gg = GGWave()
try:
    waveform = gg.encode("Hello, world!", ProtocolId.AUDIBLE_FAST, volume=20)
    decoded = gg.decode(waveform)
    print(decoded.decode("utf-8"))  # "Hello, world!"
finally:
    gg.free()

Real-time audio transmission (requires PyAudio)

from ggwave_python import GGWave, ProtocolId, waveform_utils

gg = GGWave()
try:
    waveform = gg.encode("Test message", ProtocolId.AUDIBLE_FAST, volume=20)
    waveform_utils.play_waveform(waveform)
finally:
    gg.free()

Real-time audio reception

from ggwave_python import GGWave, waveform_utils

gg = GGWave()
try:
    for message in waveform_utils.listen():
        print("Received:", message.decode("utf-8"))
finally:
    gg.free()

WAV Tools

On how to convert waveforms into WAV-format and back, please see WAV Example.

More examples

For more examples please see Examples.

⚙️ Technical Details

GGWave transmits data using frequency-shift keying (FSK), allowing devices to communicate via sound. The transmission rate is 8-16 bytes/sec, depending on the selected protocol.

🛠️ Development and Code Formatting

This project follows strict code style and formatting rules, enforced via pre-commit hooks.
We use the following tools:

• Ruff → Linter, import sorting, and lightweight formatter.
• Black → Code auto-formatter.
• Pytest → For unit testing.

🔧 Setting Up the Development Environment

To ensure a consistent environment, use poetry shell instead of installing packages globally.

poetry shell  # Activate the virtual environment
make init     # Install all dependencies

✅ Linting and Formatting

Our project requires clean, formatted code. Use make check to validate your code.

Check code style (without modifying files)

make check

Fix code style issues automatically

make fix

🛠 Pre-Commit Hooks (Mandatory)

This project requires pre-commit hooks to ensure formatting and linting before commits.
You must install the pre-commit hook before making changes.

Install pre-commit hook

pre-commit install

Run pre-commit manually on all files

make pre-commit

Remove pre-commit hooks (if needed)

pre-commit uninstall

🧪 Running Tests

Tests are managed with pytest.

Run all tests

make tests

Run a specific test

pytest tests/test_ggwave.py -k test_encode_decode

📜 Makefile for Development Workflow

All development tasks can be executed via make commands.

Now your development workflow is fully automated! 🚀

📝 License

This project is licensed under the MIT License.