Listen to an RTL-SDR from anywhere. A small client next to the dongle demodulates a frequency and streams the audio to a relay server. A web page connects to the server and plays the audio live. The page is listen-only: it can't send anything back to the client or the SDR.
RTL-SDR -> rtl_fm -> client.py --(WebSocket)--> server.py --(WebSocket)--> browser (index.html)
(Pi / laptop) (PC / VPS) (any device)
| File | Runs on | Purpose |
|---|---|---|
client.py |
machine with the RTL-SDR | Runs rtl_fm, streams 16-bit mono PCM to the server, reconnects automatically |
server.py |
machine reachable by both | Accepts the client on /ingest, relays audio to listeners on /listen, serves the page |
index.html |
served by server.py |
Player: frequency display, live status, level meter, volume |
Keep server.py and index.html in the same folder.
- Client machine (Raspberry Pi or laptop): Linux, Python 3.9+,
rtl-sdr,websocketssudo apt install rtl-sdr python3-websockets
- Server machine: Python 3.9+ and
aiohttpsudo apt install python3-aiohttp # or: pip install aiohttp - Listener: any modern browser (Chrome, Firefox, Safari)
Terminal 1, the server:
SDR_TOKEN=test python3 server.pyTerminal 2, the client:
python3 client.py --server ws://localhost:8080/ingest --token test \
--freq 438.5M --mode fm --gain 35 --squelch 100Open http://localhost:8080/ and press Start listening. Browsers block audio until you click, so the button is required.
- Start
server.pyon a machine the client can reach over the internet (see "Reaching the server").SDR_TOKEN=a-long-random-string python3 server.py
- On the machine with the dongle:
python3 client.py --server ws://SERVER_ADDRESS:8080/ingest --token a-long-random-string \ --freq 438.5M --mode fm --gain 35 --squelch 100
- Open
http://SERVER_ADDRESS:8080/from any device and press Start listening.
Generate a token with python3 -c "import secrets; print(secrets.token_urlsafe(24))".
The client connects outbound, so the dongle's side needs no open ports. The server's side does need to be reachable. Pick one:
- Tailscale on both machines: easiest and encrypted. Use the server's Tailscale name as
SERVER_ADDRESS. - Cheap VPS: copy
server.pyandindex.htmlwithscp, run it there, and open port 8080 (ufw allow 8080/tcp). - Home PC + port forward + dynamic DNS: forward TCP 8080 to the PC.
- Quick tunnel for testing:
cloudflared tunnel --url http://localhost:8080gives an HTTPS link. Then usewss://in--server.
GitHub Pages does not work for the server: it only hosts static files and can't hold WebSocket connections.
| Option | Default | Meaning |
|---|---|---|
--server |
$SDR_SERVER |
Server ingest URL, e.g. ws://host:8080/ingest (wss:// if behind HTTPS) |
--token |
$SDR_TOKEN |
Must match the server's SDR_TOKEN |
--freq |
required | Frequency: 438.5M, 118.1M, 98300k, or plain Hz |
--mode |
fm |
fm (narrowband), wbfm (broadcast), am, usb, lsb |
--gain |
auto | Tuner gain in dB. A fixed value (30-40) makes squelch behave consistently |
--squelch |
0 (off) | Silences noise when nobody transmits. Raise in steps (100, 200, 300...) |
--ppm |
0 | Frequency correction for cheap dongles that drift |
--bw |
12500 for fm |
Demodulation bandwidth in Hz. Narrower means less noise |
--rate |
24000 | Maximum audio rate. The real rate is min(rate, bandwidth); use 32000 with wbfm |
--no-deemp |
off | Turn off FM de-emphasis |
--device |
0 | Dongle index if you have several |
--name |
empty | Label shown on the web page |
-v |
off | Show rtl_fm's own output (use when it won't start) |
Examples:
# 70 cm ham band, narrowband FM
python3 client.py --freq 438.5M --mode fm --gain 35 --squelch 100 ...
# Airband (AM)
python3 client.py --freq 118.1M --mode am --gain 40 ...
# Broadcast FM
python3 client.py --freq 98.3M --mode wbfm --rate 32000 ...| Variable | Meaning |
|---|---|
SDR_TOKEN |
Required. Secret the client must present |
SDR_LISTEN_KEY |
Optional. If set, the page must be opened as /?key=VALUE |
PORT |
Optional. Default 8080 |
Create /etc/systemd/system/sdr-client.service:
[Unit]
Description=SDR stream client
After=network-online.target
Wants=network-online.target
[Service]
User=pi
WorkingDirectory=/home/pi/sdr-stream
Environment=SDR_TOKEN=a-long-random-string
Environment=SDR_SERVER=ws://SERVER_ADDRESS:8080/ingest
ExecStart=/usr/bin/python3 client.py --freq 438.5M --mode fm --gain 35 --squelch 100
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.targetThen:
sudo systemctl daemon-reload
sudo systemctl enable --now sdr-client
journalctl -u sdr-client -f # watch the logChange User and WorkingDirectory to match your system. The same pattern works for server.py (set SDR_TOKEN and ExecStart=/usr/bin/python3 server.py).
- Noise when idle: raise
--squelch, and set a fixed--gainso the threshold doesn't move. - Quiet audio: raise the volume slider on the page (it goes up to 6x).
- Muffled or distorted signal: the dongle may be a few kHz off. Try
--ppm 30, or a different value. - Weak reception: extend the telescopic antenna to a quarter wavelength (about 17 cm at 438.5 MHz), keep it vertical and high, and put the dongle on a USB extension away from the laptop or Pi, since they radiate noise.
- Overload: very high gain can make things worse. Try 30, 40, then 49 and compare.
| Symptom | Likely cause and fix |
|---|---|
Client: Connect call failed |
The server isn't running, or the address or port is wrong or blocked by a firewall |
Client: 401 / Unauthorized |
--token doesn't match SDR_TOKEN on the server |
Client: rtl_fm exited |
Run with -v. Common causes: dongle not detected (unplug and replug), another program using it, DVB driver grabbed it (reboot) |
| Page says "Waiting for the Pi" | The client isn't connected to the server yet |
| Page is live but silent | You pressed nothing yet (click Start listening), the volume is at 0, or the squelch is too high |
| Audio stutters or lags | Network too slow. Latency is normally 0.5-1 s; the page drops audio if it falls over 2 s behind |
- Bandwidth: raw PCM, so about 25 KB/s at the default narrowband FM setting (12.5 kHz audio) and about 64 KB/s for
wbfmat 32 kHz. - Security: without HTTPS, the token and the audio are sent unencrypted. That's fine on Tailscale or for a quick test; for public use, put Caddy or a similar proxy in front and use
wss://. SetSDR_LISTEN_KEYif the page shouldn't be open to everyone. - Legality: what you may monitor or rebroadcast depends on your country. Check local rules before making a stream public.