What is Pi Radio?
Pi Radio is a recovered and modernized Raspberry Pi FM radio project. It installs a headless radio service that starts automatically on boot, decodes music and announcement audio with ffmpeg, and pipes raw audio into pifm for FM output.
The goal is not to make a sketchy mystery script that only works on one ancient SD card from 2014. The goal is to make the old Raspberry Pi radio setup reproducible: one repository, one installer, a systemd service, diagnostics, and enough documentation that a future version of me does not have to reverse-engineer the thing from a forgotten folder called new_new_radio_FINAL2.
This project is especially aimed at small boards such as the Raspberry Pi Zero W and Raspberry Pi Zero 2 W, but the setup is written to be understandable and hackable on ordinary Raspberry Pi OS systems too.
What it does
- Boots headless: designed for a Pi you plug in and forget about.
- Uses systemd: the radio starts as a normal Linux service.
- Uses ffmpeg: common audio formats can be decoded into the raw stream expected downstream.
- Uses pifm: raw audio is sent to the FM transmitter program.
- Includes diagnostics: quick checks for common install, service, and audio-path failures.
- Modernized for newer Raspberry Pi OS builds: includes notes for Debian Bookworm-era compatibility.
- Built for tinkering: configuration is plain text, service logs are inspectable, and the install path is not magic.
HEADLESS SYSTEMD PIFM FFMPEG RF SAFETY REQUIRED
Hardware checklist
| Thing | Notes |
|---|---|
| Raspberry Pi | Pi Zero W or Zero 2 W is the natural tiny-board target. Other Raspberry Pi models may work, but check GPIO and OS compatibility. |
| microSD card | Use a normal Raspberry Pi OS install. A Lite image is usually enough. |
| Power supply | Use a stable supply. Weird undervoltage problems are the hidden goblin in half of Raspberry Pi projects. |
| Audio files | Music, clips, announcements, station IDs, or test tones, depending on your setup. |
| RF test setup | For responsible testing: use a dummy load, shielded setup, or very limited legal low-power configuration. Do not add amplifiers or heroic antennas. |
Important: the original Pi Zero has no onboard Wi-Fi. The Zero W and Zero 2 W do. Also, Zero W class boards are 2.4 GHz Wi-Fi only.
Installation
The happy path is intentionally boring: clone the repository, run the installer, check the service, and then adjust configuration.
sudo apt update sudo apt install -y git ffmpeg git clone https://github.com/nialljmiller/piradio.git cd piradio sudo bash install.sh
After install, check whether the service exists and whether systemd is happy:
systemctl status piradio.service journalctl -u piradio.service -n 80 --no-pager
If the repository path or installer name changes, trust the repository README over this page. This page is the friendly public landing page; the repo is the source of truth.
Configuration
The exact config file may evolve, but the usual things you configure are:
- the audio directory or playlist
- the transmit frequency
- the audio gain / volume path
- whether the service loops one file, a playlist, or a folder
- startup behavior after boot
A typical config might look conceptually like this:
# Example only. Check the repo for the current config format. PIRADIO_AUDIO_DIR=/home/pi/piradio/audio PIRADIO_FREQUENCY=100.0 PIRADIO_LOOP=true PIRADIO_GAIN=1.0
Copy audio onto the Pi with scp:
scp song.mp3 pi@raspberrypi.local:/home/pi/piradio/audio/
Then restart the service:
sudo systemctl restart piradio.service sudo journalctl -u piradio.service -f
Running it as a service
The point of Pi Radio is that it behaves like a little appliance. Once installed, you should be able to control it with standard Linux service commands:
sudo systemctl start piradio.service sudo systemctl stop piradio.service sudo systemctl restart piradio.service sudo systemctl enable piradio.service sudo systemctl disable piradio.service
For logs:
journalctl -u piradio.service --no-pager journalctl -u piradio.service -f
For a quick sanity check after boot:
systemctl is-enabled piradio.service systemctl is-active piradio.service
RF safety, legality, and common sense
This project is not an invitation to interfere with licensed radio services. FM transmission rules depend on where you live, and unlicensed operation is often restricted to extremely low power. Before transmitting anything, check your local regulations.
- Use the project for education, lab testing, restoration, and controlled experiments.
- Prefer a dummy load or shielded test setup when developing.
- Do not attach amplifiers.
- Do not attach high-gain antennas.
- Do not transmit over occupied stations or emergency/public-service channels.
- Keep power low and range tiny.
- If you do not know whether your setup is legal, assume it is not ready to radiate.
BE BORING. BE LEGAL. DO NOT BE THE REASON SOMEONE WRITES A FORUM THREAD IN ALL CAPS.
Troubleshooting
The Pi is not on Wi-Fi
Mount the SD card on another Linux machine and add a NetworkManager connection under /etc/NetworkManager/system-connections/. On older images, wpa_supplicant.conf may still be relevant.
The service starts but no audio happens
journalctl -u piradio.service -n 120 --no-pager which ffmpeg which pifm
It worked on an old Pi but fails on a newer OS
Check architecture and runtime-library notes in the repository. Some old Pi FM tooling expected older 32-bit assumptions, while newer Raspberry Pi OS builds may be 64-bit.
Audio sounds bad
- Try a clean WAV test file first.
- Reduce gain before blaming the RF side.
- Check CPU load with
top. - Check undervoltage warnings with
dmesg.
Project status
Early public-release preparation.
- Recovered original code and service layout
- Installer path restored
- systemd service setup
- Diagnostics added
- Compatibility notes started
Still worth confirming: exact board matrix, receiver-side RF output, final bundled dependency/licensing status, and docs polish.
Quick commands
git clone https://github.com/nialljmiller/piradio.git cd piradio sudo bash install.sh systemctl status piradio.service
Why this exists
Because old Raspberry Pi projects are brilliant until they become archaeological digs. Pi Radio turns a recovered hack into something you can reinstall, debug, document, and hand to another small computer gremlin without a séance.
Good test targets
- Raspberry Pi Zero W
- Raspberry Pi Zero 2 W
- Raspberry Pi 3
- Raspberry Pi 4
- Any cheap compatible SBC only if GPIO/audio assumptions are checked carefully
Do not
- blast across the neighborhood
- add an amp
- use a ridiculous antenna
- hide the safety notes
- pretend RF rules are optional