Skip to content

boybook/tx-5dr

BranchesTags

Repository files navigation

TX-5DR

A modern digital radio station for amateur radio operators. Operate FT8, FT4, and voice modes from any web browser — anywhere, anytime.

中文文档 (Chinese)

Why TX-5DR?

Beautifully crafted, powerfully simple

TX-5DR features a polished, modern UI with real-time WebGL spectrum waterfall, intuitive controls, and responsive layouts that work beautifully on desktop and mobile. Every interaction — from one-click auto-CQ to drag-and-drop frequency tuning — is designed to feel natural. Complex capabilities like multi-operator parallel TX, OpenWebRX SDR integration, and remote voice QSO are seamlessly integrated behind a clean interface, so you get professional-grade power without the learning curve.

Access from anywhere — no client installation needed

TX-5DR uses a modern client-server architecture. Once the server is running (on a desktop, a Linux box, or Docker), you operate your radio from any web browser — laptop, tablet, phone, across your LAN or over the internet. No software to install on the client side.

Even the desktop app (Electron) runs a full server inside, so you can always connect remotely via browser while the app is running.

Share your radio — multiple operators at once

A complete role-based permission system (Admin / Operator / Viewer) lets you share your station with others. Multiple operators can use the same radio simultaneously — each with their own callsign, frequency, and automation settings, transmitting FT8 in parallel with automatic audio mixing.

OpenWebRX Integration — Full-duplex & Dual-cycle TX

TX-5DR can connect to OpenWebRX SDR receivers as an auxiliary RX source. By routing a remote SDR's audio into the local decode pipeline, you get:

  • Full-duplex operation — transmit on your local radio while simultaneously receiving on the SDR, eliminating the TX/RX gap
  • Dual-cycle transmission — decode both even and odd slots in real-time, enabling TX in every slot instead of alternating
  • Superior RX performance — leverage high-quality, low-noise-floor SDR stations (e.g. a remote KiwiSDR or WebSDR site) for decoding, while your local radio handles TX only

This turns a single half-duplex transceiver into an effectively full-duplex FT8/FT4 station.

Key Features

  • Digital Modes: FT8 (15s), FT4 (7.5s), Voice (SSB/FM/AM), with Fox/Hound DXpedition support
  • Real-time Spectrum: GPU-accelerated WebGL waterfall display with zoom/pan
  • Radio Control: Hamlib (network/serial), ICOM WLAN (IC-705 WiFi direct), or no-radio monitor mode
  • OpenWebRX SDR RX: Connect to remote OpenWebRX receivers for full-duplex decode and dual-cycle TX
  • Multi-operator: Independent callsign, grid, frequency, and TX strategy per operator — auto-CQ, auto-reply, parallel encoding with audio mixing
  • Remote Voice QSO: Transmit and receive voice (SSB/FM) remotely through the browser — your microphone audio is streamed to the server and transmitted via the radio (requires HTTPS)
  • Logbook & Sync: Built-in ADIF logbook with two-way sync to WaveLog, QRZ.com, and LoTW
  • PSKReporter: Auto-report decoded signals to the global PSKReporter network
  • Audio Monitoring: Real-time browser audio monitoring over LiveKit/WebRTC
  • Multi-language: Full English and Chinese UI

Deployment Options

Option Best for How
Desktop App (Electron) Windows / macOS / Linux with GUI Download from GitHub Releases
Linux Server (deb/rpm) Headless servers, low-cost hardware tx5dr start — see Server Install
Docker Containers, quick setup docker-compose up -d — see Docker

Desktop App

Download the installer for your platform from GitHub Releases. Mainland China builds are also published to the OSS mirror during release workflows:

  • Windows: .msi installer or .7z portable
  • macOS: .dmg (Apple Silicon & Intel)
  • Linux: .deb / .rpm (includes Electron GUI)

Linux Server

Server-only deployment — no desktop environment required. Access via web browser.

Quick Install

Release pages:

The one-click online installer and tx5dr update now use OSS only when geolocation detects mainland China, and use GitHub everywhere else. If the OSS mirror is unavailable, they fall back to GitHub automatically.

# One-click install (auto-detects arch, resolves latest package metadata, fixes dependencies)
curl -fsSL https://github.com/boybook/tx-5dr/releases/download/nightly-server/install-online.sh | sudo bash

Or manually:

# Download TX-5DR-nightly-server-linux-amd64.deb from GitHub Releases or the OSS mirror first
sudo dpkg -i --force-depends ./TX-5DR-nightly-server-linux-amd64.deb
sudo bash /usr/share/tx5dr/install.sh

Commands

Command Description
tx5dr start Start server, show Web UI URL with auth token
tx5dr stop Stop server
tx5dr restart Restart server
tx5dr status Status dashboard (server, nginx, ports, SSL)
tx5dr token Show admin token and login URL
tx5dr update Download and install latest nightly
tx5dr doctor Full environment diagnostics
tx5dr logs Follow server logs (--nginx for nginx)
tx5dr livekit-creds status Show managed LiveKit credential status
tx5dr livekit-creds rotate Rotate managed LiveKit credentials and config
tx5dr enable-livekit Install and enable LiveKit (optional, can be added later)
tx5dr disable-livekit Disable LiveKit, switch to ws-compat mode

Service Layout

Linux Server is not a single standalone process. The installer sets up and wires together:

  • tx5dr: the backend application and Web API
  • livekit-server (optional): the bundled realtime audio and signaling service
  • nginx: the public reverse proxy and HTTPS entrypoint

install.sh and the tx5dr CLI handle installation, configuration, diagnostics, and coordinated restarts across these components. During installation, you can choose whether to install LiveKit. Without it, voice features run over WebSocket audio (ws-compat) — you can always add LiveKit later via sudo tx5dr enable-livekit.

System Requirements

  • Debian 12+ (recommended) or Ubuntu 22.04+
  • Node.js 20+ (auto-installed by install.sh)
  • nginx (auto-installed)
  • LiveKit (optional): Linux packages bundle livekit-server at /usr/share/tx5dr/bin/livekit-server. Without LiveKit, voice uses WebSocket audio (ws-compat) — all features remain fully functional
  • For voice features: HTTPS (configure SSL in /etc/nginx/conf.d/tx5dr.conf)
  • If LiveKit is enabled, browsers enter signaling through the site's same-origin /livekit path (7880/tcp does not need public exposure). You still need to expose 7881/tcp and 50000-50100/udp for media transport
  • If you use a dedicated domain, an extra reverse proxy layer, or a non-standard path, configure the custom browser-facing entrypoint in "System Settings > Realtime Audio"; the same page also exposes the shared LAN / Internet Auto / Internet Manual LiveKit media modes
  • Linux Server and Docker now generate a managed livekit.resolved.yaml from that shared configuration. Do not hand-edit the generated runtime YAML
  • Download source override: set TX5DR_DOWNLOAD_SOURCE=github|oss|auto in /etc/tx5dr/config.env if you need to force a specific source

Docker

Image: boybook/tx-5dr:latest (Docker Hub)

mkdir -p data/{config,plugins,logs,cache,realtime}
docker compose pull
docker compose up -d
# Access: http://localhost:8076
docker exec tx5dr cat /app/data/config/.admin-token

This starts TX-5DR in standalone mode with WebSocket audio (ws-compat, ~50–100 ms latency). To enable LiveKit for lower-latency voice (~20–50 ms via WebRTC):

docker compose -f docker-compose.livekit.yml up -d

For the full deployment guide — including device mapping, serial port setup, audio configuration, and troubleshooting — see docker/README.md.

Image release details: GitHub nightly-docker.

Development

Prerequisites

  • Node.js 22+, Yarn 4+ (Berry), Git
  • Platform-specific build tools (see below)

Setup

git clone https://github.com/boybook/tx-5dr.git
cd tx-5dr
yarn install

Run

# Browser mode (server + web)
yarn dev
# → http://localhost:5173

# Electron mode
yarn dev:electron
  • yarn dev / yarn dev:electron auto-manage a local LiveKit instance and its credential file when possible, then expose it to browsers through the same-origin /livekit proxy
  • If port 7880 is already occupied by an unknown LiveKit instance, development mode automatically falls back to ws-compat instead of issuing invalid tokens
  • Running yarn workspace @tx5dr/server dev without LiveKit credentials is supported; the backend starts in ws-compat mode and logs a warning

Build

yarn build           # Build all packages
yarn build:package   # Electron package
yarn package:deb     # Server deb package (requires fpm)

Platform Dependencies

Linux (Ubuntu/Debian) 
sudo apt-get install -y \
  libasound2-dev libpulse-dev libhamlib-dev \
  build-essential python3-dev pkg-config \
  libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev
macOS 
brew install cmake fftw boost gcc pkg-config
Windows

Install Visual Studio 2022 with MSVC toolchain. For native modules, MSYS2/MinGW-w64 may be required.

Project Structure

tx-5dr/
├── packages/
│   ├── contracts/       # Zod schemas and TypeScript types
│   ├── core/            # Runtime-agnostic utilities and API client
│   ├── server/          # Fastify backend + digital radio engine
│   ├── web/             # React frontend (Vite)
│   ├── electron-main/   # Electron main process
│   └── electron-preload/# Electron preload (sandbox)
├── linux/               # Server deployment (systemd, nginx, install script)
├── docker/              # Docker config (nginx, supervisor, entrypoint)
├── scripts/             # Build and packaging scripts
└── .github/workflows/   # CI: electron-release, server-release, docker-release

Tech Stack

Built on Node.js with performance-critical components running as native C/C++/Fortran binaries — FT8 encoding/decoding (WSJT-X), audio I/O (RtAudio), radio control (Hamlib), and FFT processing are all native, not JavaScript.

  • Backend: Fastify, WebSocket, XState v5 state machines, Piscina worker pool (parallel FT8 encode/decode)
  • Frontend: React 18, HeroUI, WebGL (spectrum), i18next
  • Native Binaries: WSJTX-lib (FT8/FT4 codec), Audify (RtAudio), Hamlib (CAT), SerialPort
  • Build: Turborepo, Yarn 4 workspaces, Electron Forge

Core Native Node.js Extensions

TX-5DR relies on several native Node.js addons for real-time radio operation. Most are maintained as part of this project:

Package Description Repository
wsjtx-lib FT8/FT4 encoder & decoder (WSJT-X Fortran core) boybook/wsjtx-lib-nodejs
hamlib Node.js bindings for Hamlib (CAT radio control) boybook/node-hamlib
icom-wlan-node ICOM WLAN (IC-705 WiFi) control protocol boybook/icom-wlan-node
rubato-fft-node High-performance FFT + sample-rate conversion boybook/rubato-fft-node
@openwebrx-js/api OpenWebRX client API for SDR receiver integration boybook/openwebrx-js
audify RtAudio bindings for low-latency audio I/O almoghamdani/audify

License

GNU General Public License v3.0 — see LICENSE.

About

A modern digital radio station for amateur radio operators. Operate FT8, FT4, and voice modes from any web browser — anywhere, anytime.

Resources

Readme

License

GPL-3.0 license
Activity

Stars

14 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

5 tags

Packages

 
 
 

Contributors

Languages