An open-source numbers-station project for research, education, experimentation, and study.
Explore numerical dictionaries, FSK audio, live decoding and error correction through a local web panel with offline chat/file experiments and automatic audio calibration.
Actual application screenshot with fictional demonstration traffic. No personal station data is included.
Get started · Illustrated how-to · Change the number dictionary · How it works · Protocol · AI/developer guide
Nuclear Messenger turns a computer's microphone or line input into a receiver and its speaker or line output into a transmitter. Two stations exchange exact text or small files over an established audio path. Each computer runs its own local server; the link between them does not need the internet, a cloud account, or a shared network after installation.
Its primary purpose is numbers-station research and education: study how text becomes numerical groups, how audio carries symbols, and how decoders recover messages. Offline communication experiments and emergency-preparedness practice are additional use cases. It is experimental software, not a certified emergency service or a delivery guarantee.
- Send UTF-8 chat, coordinates, checklists and small binary files.
- Select independent RX microphone/line-input and TX speaker/line-output devices.
- Decode live audio with a supervised native minimodem worker, including with the web tab closed.
- Watch tone levels, signal acquisition, growing unverified text previews, clipping and verified receive outcomes.
- Calibrate a local speaker/microphone or cable loop; pair two stations to test both audio directions automatically.
- Recover interrupted transfers from saved fragments and resend selected missing parts.
- Export/import packet WAVs and retain a separate legacy ITA2/numerical-group codec.
- Fork the project and change its number dictionary, UI or behavior; see the license boundaries below.
| Platform | Native audio station | Power management |
|---|---|---|
| macOS | Supported; microphone/speaker hardware tested on a MacBook Pro with a Yeti | Optional caffeinate sleep prevention |
| Linux | Supported; Ubuntu 24.04 build and automated tests are covered by CI | Configure the desktop/system to stay awake |
| Windows | No supported native build currently; POSIX process control and file locking need porting | Not implemented |
The panel can be opened in a modern browser on the station computer. The native worker owns that computer's audio devices. The browser-only comparison mode is experimental and needs its tab to remain open.
Requirements: Python 3.10+, a C compiler, make, pkg-config, SDL2 2.24+, FFTW3, libsndfile and cJSON. Node.js is needed for development tests, not normal use.
macOS — Homebrew dependencies:
brew install pkg-config sdl2 fftw libsndfile cjsonUbuntu 24.04 / recent Debian:
sudo apt update
sudo apt install -y git build-essential pkg-config python3 python3-venv \
libsdl2-dev libfftw3-dev libsndfile1-dev libcjson-devThen, on either platform:
git clone https://github.com/valinux/nuclear-messenger.git
cd nuclear-messenger
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
make
make runOpen http://127.0.0.1:8000. The server starts one background nm_minimodem
worker automatically. Enter your station ID, choose RX and TX devices, and
start listening on the receiving station. Read the first-message guide
before using an external interface. The service listens only on localhost.
| Connection | What you supply |
|---|---|
| Speaker → microphone | Position and levels; avoid feedback and strong room echoes |
| Audio cable / line interface | Suitable levels and isolation between output and input |
| Analog telephone audio | An established call and appropriate isolated interface or acoustic handset coupling |
| Radio audio | A suitable interface and working manual PTT or VOX; a channel that permits the emission |
The software generates and receives audio. It does not dial a telephone, tune a radio, key CAT/serial/GPIO PTT, or make every voice channel carry data. Speech processing, VoIP codecs, noise suppression and radio squelch can damage tones. The audio link needs testing on the actual hardware at both ends.
Ham radio and CB: compatibility with a radio's audio connection is not permission to transmit data. Operators must check their country, service, band, identification and emission rules. US CBRS ordinary use is specified for plain-language voice in 47 CFR §95.931; this project does not claim that its packet mode is authorized on CB. See operating limits.
Screenshot from a silent software loopback, not a physical radio or microphone test.
In Auto calibration · TX + RX, choose Local for a loop back to this station, or start Partner on one station and Initiate test on the other. The paired test exchanges its replies through audio and reverses directions. It tests output levels and speed, adjusts the RX detection threshold, and requires repeated verified packets before applying a profile. Stop restores the previous settings. Hardware gain, system volume, microphone pattern and PTT remain operator controls.
A local Yeti test selected 100 baud, 18% TX and -62.6 dBFS RX with 3/3 verified packets and no corrections at 48% laptop volume. Those measurements apply to that particular setup, not every microphone or link. See test evidence and the calibration protocol. Paired calibration has software-link coverage; it has not been qualified across physical radio or telephone stations.
| Live NM packet v1 | Legacy numbers-station / ITA2 | |
|---|---|---|
| Primary use | Exact chat and files | Text WAV experiments and five-digit numerical groups |
| Audio | 1200/2200 Hz FSK; 100 or 300 baud | 1250/1750 Hz FSK; 200 baud |
| Integrity | Hamming SECDED, interleaving, CRC-32, complete-transfer SHA-256 | No checksum |
| Text | UTF-8; packet data preserves exact bytes | A–Z/spaces; plain mode also accepts digits |
| Dictionary | No letter-to-number dictionary | Default space=00, A=01 … Z=26 |
Make the number dictionary your own. You are welcome to change, reorder, replace or redesign the legacy mapping in any form you wish. The current implementation is compiled into the C source; it is not a panel setting or a loaded dictionary file. Both ends must use matching encode/decode mappings. The dictionary how-to includes a working reversed-alphabet example, the exact functions to edit, compatibility rules and a round-trip test. More substantial alphabets or word dictionaries require corresponding parser, validation and framing changes. A custom dictionary is not encryption.
Stock minimodem's UART modes, AX.25, Winlink, ordinary RTTY and the legacy WAV codec do not speak NM packet v1. Each end needs this app or a compatible implementation of PROTOCOL.md.
Chat is limited to 8192 UTF-8 bytes; files to 256 KiB, split into 192-byte fragments. These are slow links: keep files small. Packet copies add airtime. “AUDIO SENT” only confirms local playback. Operators confirm remote receipt and request missing parts; ordinary transfers have no automatic ACK/ARQ. Incoming files are saved, never automatically executed or opened.
A partial text preview is unverified. Chat/file delivery requires packet CRC and complete-transfer SHA-256 checks. Packets are unencrypted and station IDs are not authenticated. Incoming tones cannot wake a sleeping or powered-off computer. Keep the local server and computer running.
| Guide | Contents |
|---|---|
| Quick start | Dependencies, Linux/macOS setup, first message, updates |
| Illustrated how-to | Routing, chat, files, calibration, WAVs and missing parts |
| Dictionary customization | Default table, customization examples and compatibility |
| Architecture | Components, data flow, background workers and storage |
| HTTP API | Auth, endpoints, examples and units |
| Protocol | Bits, byte layout, sync, FEC, CRC and reassembly |
| Streaming RX | Live decoding and preview timing |
| Detailed operation | Hardware, recovery, wake behavior and troubleshooting |
| Development / AI guide | Tests, project rules, reproducible demo and safe fixtures |
| Security / Licenses | Trust boundaries, reporting, terms and responsibility |
.venv/bin/python -m pip install -r requirements-dev.txt
make testAll automated audio tests use dummy devices or WAV files. Actual hardware validation remains separate. See the testing guide for browser checks and reproducible screenshots.
Original project code and documentation: MIT, including the standard no-warranty and limitation-of-liability terms. Users are responsible for their operation, modifications and transmitted content. The author and contributors do not accept responsibility for users' misuse, subject to applicable law.
The bundled modem is not MIT-only: minimodem, its native adapters and the browser minimodem adaptation retain GPL-3.0-or-later. Preserve their notices and satisfy the applicable GPL distribution/source requirements. Read LICENSE and LICENSES.md before redistributing a bundle.
Created by Renan Rocha / valinux. The native and browser modems build on Kamal Mostafa's minimodem, with the pinned upstream source and attribution retained in this repository.