Skip to content

eugenedwk/radio

BranchesTags

Repository files navigation

Radio Transcription System

A real-time system that captures trunked radio transmissions, transcribes them using AI, and displays them on an LED matrix.

What It Does

📻 Captures radio transmissions from P25/SmartNet trunked systems using SDR 🎤 Transcribes audio to text using OpenAI Whisper (GPU-accelerated) 📺 Displays live transcriptions on a 64x32 RGB LED matrix 🌐 Serves transcriptions via REST API for other applications

System Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  SDR Hardware   │ --> │  Trunk-Recorder  │ --> │ Transcription   │ --> │  Matrix Portal   │
│  (RTL-SDR, etc) │     │  (Audio Files)   │     │  Service        │     │  M4 Display      │
└─────────────────┘     └──────────────────┘     └─────────────────┘     └──────────────────┘
                                                         │
                                                         ▼
                                                   ┌──────────────┐
                                                   │   REST API   │
                                                   │   :5000      │
                                                   └──────────────┘

Quick Start

New to this project? Start here: QUICKSTART.md (30 minutes)

Need detailed setup? See: SETUP_GUIDE.md (Complete guide)

Choosing hardware? Read: HARDWARE_OPTIONS.md (PC vs Jetson vs Pi)

Hardware Requirements

Minimum Setup (~$100)

  • Computing: PC with NVIDIA GPU (RTX 3060 or similar) OR Jetson Orin Nano
  • Radio: RTL-SDR USB dongle (~$30)
  • Display: Adafruit Matrix Portal M4 ($25) + 64x32 RGB LED Matrix ($30)
  • Power: 5V 4A power supply (~$15)

See HARDWARE_OPTIONS.md for detailed comparisons.

Features

  • ✅ Real-time P25 and SmartNet system recording
  • ✅ GPU-accelerated transcription (CUDA support)
  • ✅ Automatic file monitoring and processing
  • ✅ REST API for external integrations
  • ✅ Scrolling LED matrix display with WiFi
  • ✅ Configurable Whisper models (tiny to large)
  • ✅ Talkgroup filtering and identification
  • ✅ Low latency (3-6 seconds from transmission to display)

Project Structure

radio/
├── README.md                    # This file
├── QUICKSTART.md               # 30-minute setup guide
├── SETUP_GUIDE.md              # Complete setup documentation
├── HARDWARE_OPTIONS.md         # Hardware comparison guide
│
├── trunk-recorder/             # Radio recording configuration
│   ├── README.md              # Installation guide
│   ├── config.json.example    # Example configuration
│   └── recordings/            # Audio files saved here (gitignored)
│
├── transcription-service/      # Python transcription service
│   ├── README.md              # Service documentation
│   ├── requirements.txt       # Python dependencies
│   ├── transcriber.py         # Main service (Whisper + file watcher)
│   └── api_server.py          # Flask REST API
│
└── matrix-portal/             # CircuitPython for LED display
    ├── README.md              # Matrix Portal setup guide
    ├── code.py                # Main CircuitPython application
    └── secrets.py.example     # WiFi configuration template

Installation Overview

1. Install trunk-recorder

# See trunk-recorder/README.md for platform-specific instructions
# Requires: SDR drivers, GNU Radio, gr-osmosdr

2. Install Transcription Service

cd transcription-service
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Set Up Matrix Portal M4

# See matrix-portal/README.md for detailed steps
# 1. Install CircuitPython 9.x
# 2. Copy libraries to lib/
# 3. Configure WiFi in secrets.py
# 4. Copy code.py to device

Running the System

Terminal 1: Start trunk-recorder

cd trunk-recorder
./trunk-recorder --config=config.json

Terminal 2: Start Transcription Service

cd transcription-service
source venv/bin/activate
python transcriber.py --model base

Matrix Portal

Powers on automatically and displays transcriptions as they arrive.

Testing Without Radio

Create a test transcription:

# Generate test audio (Mac)
say "Unit ten responding to scene" -o test.wav

# Or use espeak (Linux)
espeak "Unit ten responding to scene" -w test.wav

# Copy to recordings directory with correct format
cp test.wav trunk-recorder/recordings/$(date +%s)-12345-5.0.wav

Check the results:

  • Transcription service logs show processing
  • API endpoint: curl http://localhost:5000/transcriptions/latest
  • Matrix Portal displays scrolling text

API Endpoints

  • GET /health - Health check
  • GET /transcriptions - Get recent transcriptions (default: 10)
  • GET /transcriptions/latest - Get most recent transcription
  • GET /transcriptions/talkgroup/<id> - Get transcriptions by talkgroup
  • GET /stats - Get system statistics

Example:

curl http://localhost:5000/transcriptions/latest

Configuration

Whisper Models

Choose based on your hardware:

Model Speed Accuracy VRAM Recommended For
tiny Fast Good ~1GB Quick testing, low-end GPUs
base Fast Better ~1GB Recommended default
small Med Great ~2GB Good GPU (RTX 3060+)
medium Slow Best ~5GB High-end GPU, offline processing 
python transcriber.py --model base  # Change model here

Display Customization

Edit matrix-portal/code.py:

POLL_INTERVAL = 3      # Seconds between API checks
SCROLL_SPEED = 0.05    # Scroll speed (lower = slower)
TEXT_COLOR = 0xFF0000  # Color (RGB hex)

Power Consumption

For 24/7 operation:

Hardware Power Cost/Month*
Jetson Orin Nano 10W $0.86
Raspberry Pi 5 10W $0.86
RTX 3060 PC 250W $21.60

*Assuming $0.12/kWh

See HARDWARE_OPTIONS.md for detailed comparison.

Documentation

Troubleshooting

Common issues and solutions in SETUP_GUIDE.md - Part 6.

Quick checks:

  • GPU working? python -c "import torch; print(torch.cuda.is_available())"
  • SDR detected? rtl_test
  • API responding? curl http://localhost:5000/health
  • Matrix Portal connected? Check serial console with screen /dev/ttyACM0 115200

Use Cases

  • 🚒 Monitor local emergency services (fire, police, EMS)
  • 🏭 Industrial radio monitoring and logging
  • 🎓 Educational projects for SDR and machine learning
  • 🔬 Research on radio communications
  • 📊 Data collection and analysis of radio traffic

Future Enhancements

  • Database storage (SQLite/PostgreSQL)
  • Web dashboard for viewing transcriptions
  • Audio playback integration
  • Keyword alerting and notifications
  • Multiple Matrix Portal support
  • Speaker identification and tracking
  • Mobile app integration

Resources

License

See individual component licenses:

  • trunk-recorder: GPL 3.0
  • OpenAI Whisper: MIT
  • Your code: (Add your license here)

Legal Notice

⚠️ Important: This system is intended for monitoring legally accessible radio communications. Be aware of local laws regarding:

  • Recording radio communications
  • Privacy laws
  • Encryption monitoring (typically illegal)

Always comply with local regulations and use this responsibly.

Support

For issues:

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages