ggwave-chat

GGWave Chat implements a compact application-layer protocol for audio-transported data, with chunked transport framing suitable for GGWave's ~140-byte payload limit. Messages are modeled as an Envelope carrying compressed Base64 payload which decodes to an Inner Message JSON (addressing, security mode, message type, content). The on-air format uses a minimal ASCII header plus N payload chunks as specified in docs/Protocol.md.

Prerequisites

System Dependencies (Debian/Ubuntu)

Before installing Python dependencies, you need to install some system packages:

# Update package list
sudo apt update

# Install required system dependencies for pyaudio and ggwave
sudo apt install -y \
    portaudio19-dev \
    python3-dev \
    build-essential \
    pkg-config \
    cmake \
    libsdl2-dev \
    gcc \
    g++ \
    make

Fedora/RHEL

sudo dnf install -y \
    portaudio-devel \
    python3-devel \
    gcc \
    gcc-c++ \
    pkgconfig \
    cmake \
    SDL2-devel \
    make

macOS

brew install portaudio sdl2 cmake

Note: These packages are required for building pyaudio and ggwave. The ggwave package uses Cython and requires C++ compilation.

Python Version Compatibility

Important: The ggwave package (version 0.4.2) is currently **only compatible with Python < 3.9 due to deprecated Python C API features that were removed in later Python versions. The package uses Cython-generated code that needs to be updated to support newer Python versions. Therefore we here use ggwave-wheels which is compatible with Python >= 3.10

Workarounds

1. Use Python 3.11 (recommended for now):

   # Create a new project with Python 3.11
   uv init --python 3.11
   

2. Wait for ggwave update: The ggwave maintainers need to update the Cython code to be compatible with Python 3.12+.

3. Build from source: You can try building ggwave from the GitHub repository with updated Cython code.

Installation

This project uses uv for dependency management. Make sure you have uv installed:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

Development Setup

1. Clone the repository:

git clone <repository-url>
cd ggwave-chat

2. Install dependencies:

uv sync

3. Activate the virtual environment:

source .venv/bin/activate

Usage

# Run the main application
ggwave-chat

Development

Adding Dependencies

# Add a new dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

Running Tests

# Run tests with pytest
uv run pytest

# Run tests with coverage
uv run pytest --cov=ggwave_chat

Project Structure

ggwave-chat/
├── docs/Protocol.md      # Protocol spec (Envelope, Inner Message, chunked transport)
├── src/ggwave_chat/
│   ├── protocol/         # Protocol models, builders, codec, transport helpers
│   └── util/             # Audio, crypto, logging helpers
├── protocol_test.py      # Example builder/encoding + GGWave send demo
├── pyproject.toml
└── README.md

Troubleshooting

Build Errors

If you encounter build errors with ggwave:

1. Check Python version: Ensure you're using Python 3.11
2. Install system dependencies: Make sure all required system packages are installed
3. Clean build cache: uv cache clean
4. Check compiler: Ensure you have a compatible C++ compiler (GCC 7+ or Clang 5+)

Audio Issues

If you have audio-related issues:

1. Check PortAudio installation: pkg-config --exists portaudio-2.0
2. Check audio permissions: Ensure your user has access to audio devices
3. Test with pyaudio: Try a simple pyaudio test to verify audio setup

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests to ensure everything works
5. Submit a pull request

License

This project is licensed under the GNU General Public License version 3 or later.

• SPDX-License-Identifier: GPL-3.0-or-later
• Full text: https://www.gnu.org/licenses/gpl-3.0.en.html

Copyright (c) 2025 Stefan Maier and contributors.