SDR-MC: RTL-SDR Radio Jukebox for Minecraft

Play live FM radio in Minecraft using an RTL-SDR dongle connected to your server!

This mod adds a Radio Jukebox block that streams real FM radio audio from an RTL-SDR software-defined radio. Players nearby can hear the radio, with volume that decreases as you walk away.

Features

• Live FM Radio: Listen to real radio stations in Minecraft
• Positional Audio: Volume decreases with distance from the radio
• Multiple Stations: Configure any number of FM stations
• Simple UI: Easy-to-use interface for controlling the radio
• Server-Controlled: Only the server needs RTL-SDR hardware

Requirements

Server Requirements

• Minecraft server with NeoForge (ATM10 compatible)
• RTL-SDR dongle (RTL2832U-based)
• Radio Service running (Python-based)

Client Requirements

• Minecraft client with NeoForge (ATM10 compatible)
• This mod installed

Quick Start

1. Set Up the Radio Service (Server Machine)

The Radio Service is a Python application that controls the RTL-SDR and streams audio.

Using Docker (Recommended)

cd radio-service
docker-compose up -d

Native Installation

See radio-service/README.md for detailed instructions.

2. Install the Mod

Server Installation

1. Download sdrradio-1.0.0.jar from releases
2. Place in your server's mods/ folder
3. Restart the server

Client Installation (CurseForge/ATM10)

1. Open CurseForge Launcher
2. Go to your ATM10 profile
3. Click the three dots → "Open Folder"
4. Place sdrradio-1.0.0.jar in the mods/ folder
5. Launch the game

3. Configure Stations

Edit config/sdrradio-server.toml on your server:

[radio_service]
base_url = "http://localhost:8765"

[stations]
list = [
    "kzoo:KZOO FM:88.5",
    "rock101:Rock 101:101.1",
    "jazz97:Smooth Jazz:97.3"
]

Format: id:name:frequency_mhz

4. Use the Radio Jukebox

1. Craft a Radio Jukebox:

   [ Iron  ] [Redstone] [ Iron  ]
   [Redstone] [Jukebox] [Redstone]
   [ Iron  ] [Redstone] [ Iron  ]
   

2. Place it in your world

3. Right-click to open the UI

4. Select a station and turn it on!

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     SERVER MACHINE                               │
│                                                                 │
│  ┌──────────────┐     ┌─────────────────────────────────────┐  │
│  │  RTL-SDR     │────▶│         Radio Service (Python)      │  │
│  │  Dongle      │     │  rtl_fm → ffmpeg → Opus/Ogg Stream  │  │
│  └──────────────┘     └─────────────────────────────────────┘  │
│                                      │                          │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                Minecraft Server (NeoForge)               │   │
│  │          Tracks players, sends stream URLs               │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                          Network
                              │
┌─────────────────────────────────────────────────────────────────┐
│                     CLIENT MACHINE                               │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                Minecraft Client (NeoForge)               │   │
│  │   Receives stream URL → Decodes Opus → OpenAL playback  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Configuration

Server Config (config/sdrradio-server.toml)

Option	Default	Description
radio_service.base_url	http://localhost:8765	Radio service URL
radio_service.timeout_ms	5000	API timeout
gameplay.default_radius	24	Default audible radius (blocks)
gameplay.max_radius	64	Maximum allowed radius
stations.list	See above	Station definitions

Client Config (config/sdrradio-client.toml)

Option	Default	Description
audio.master_volume	1.0	Volume multiplier (0.0-1.0)
audio.buffer_ms	1500	Audio buffer size
audio.muted	false	Mute all radio audio

Troubleshooting

Radio service not responding

1. Check if the service is running: curl http://localhost:8765/health
2. Verify RTL-SDR is connected: rtl_test -t
3. Check service logs: docker-compose logs -f or check terminal output

No audio playing

1. Check client is not muted in config
2. Verify you're within range of the radio block
3. Check server logs for tune errors
4. Test stream directly: ffplay http://server:8765/stream

Static or poor audio quality

1. Try a different/stronger station
2. Check antenna connection
3. Move RTL-SDR away from computer for less interference

Version mismatch errors

Ensure both server and client have the same mod version and are running compatible NeoForge versions (21.1.x for ATM10).

Known Limitations (MVP)

1. Single frequency at a time: All radio jukeboxes play the same station (last one selected)
2. Mono audio only: Stereo FM is not decoded
3. ~1-3 second latency: Due to buffering for smooth playback

Building from Source

Radio Service

cd radio-service
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
python src/radio_service.py

Minecraft Mod

Requires JDK 21.

cd mod
./gradlew build

Output JAR will be in mod/build/libs/.

License

MIT License - See LICENSE

Credits

• NeoForge team for the modding API
• RTL-SDR community for the software-defined radio tools
• Concentus for pure Java Opus decoding
• JOgg for Ogg container parsing