GramPy

GramPy is an importable Python library and command-line tooling for decoding MFSK32 and MFSK64 transmissions from SigMF IQ recordings. It is maintained as a standalone project after its extraction from Radiogram.

The PyPI distribution name is radiogrampy; its Python import name is grampy.

Python 3.11 or newer is required.

Use as a library

The supported Python interface is grampy.api. Decode a SigMF metadata/data pair into compact text and quality products:

from pathlib import Path

from grampy.api import DecodeConfig, decode_iq_products

products = decode_iq_products(
    meta_path=Path("recording.sigmf-meta"),
    data_path=Path("recording.sigmf-data"),
    config=DecodeConfig(mode="MFSK64"),
    artifact_dir=Path("results/text.manifest.artifacts"),
    artifact_path_prefix="text.manifest.artifacts",
)

for segment in products.text_manifest["mode_segments"]:
    for item in segment["items"]:
        if item["kind"] == "text":
            print(item["text"])

decode_iq_products returns validated, JSON-compatible text and quality manifests; it does not write them to disk. decode_iq remains available for the detailed diagnostic manifest. The optional artifact arguments control where large decoded-picture artifacts are written. See the Python API guide for the supported arguments, configuration, result contract, errors, and artifact behavior. The manifest schema is the machine-readable format reference.

Setup

Create a virtual environment and install GramPy with its runtime dependencies:

python3 -m venv .venv
.venv/bin/python -m pip install --editable . pillow

Pillow is used by the image-related test suite. The repository uses a src/ layout, so run Python work with both the virtual environment and source tree selected:

PYTHONPATH="$PWD/src" PATH="$PWD/.venv/bin:$PATH" \
  .venv/bin/python -m unittest discover -s tests

For full-suite runs, experiments, corpus jobs, or other potentially long work, follow the managed-execution contract in AGENTS.md. The normal Mac entry point is tools/mac-local.sh; place a temporary command batch in the ignored .local/mac-command.sh when needed.

Tests and corpus

The normal regression suite runs without large external artifacts. Tests that need received IQ or controlled generated fixtures skip cleanly when those optional inputs are absent.

See tests/README.md to install an optional received-IQ corpus, point tests at an existing corpus, or package one for controlled distribution. Large samples are never committed to this repository.

Decode a SigMF recording

GramPy includes a command-line adapter for reproducible decoder work on a SigMF metadata/data pair:

tools/mfsk-iq-decode \
  --in-meta recording.sigmf-meta \
  --in-data recording.sigmf-data \
  --out-text-manifest results/text.manifest.json \
  --out-quality-manifest results/quality.manifest.json

The default automatic mode decodes every resolved MFSK32 and MFSK64 segment and the pictures carried by MFSK64 segments in one run. The command writes ordered readable text and one-second reception and decode quality data. Add --out-manifest results/decode.json to request the large diagnostic manifest as well, or use that option alone for the legacy invocation. Large decoded pictures are written beside the compact manifests in results/text.manifest.artifacts/; small rasters are embedded. See the SigMF decode guide for the accepted metadata, input formats, interval options, and complete output layout.

Development

Use docs/operations/change-management-v1.md for continuous-improvement work. It defines the request, baseline, candidate, evaluation, acceptance, and closeout cycle. Decoder architecture, contracts, validation guidance, and the accepted baseline are indexed in docs/decoder/README.md.

Reusable command-line tools are documented in tools/README.md.