A Raspberry Pi that turns any radio, speaker, or amplifier with an aux input into an internet radio with presets and Spotify Connect. You control it from a web page on your phone: up to 20 preset buttons, Stop Playing, and volume.
- Presets for internet radio stations, with a station search and a check that an address really works.
- Spotify Connect: the Pi shows up as a speaker in the Spotify app (needs Spotify Premium).
- Artist and song shown when the station provides them, with a heart to save the ones you like.
- Keeps itself running: restarts a station whose stream drops, installs updates overnight, and starts by itself after a power cut.
Why the aux input. The Pi connects to the radio by cable for three reasons:
- Sound. A cable carries the audio as it is. Bluetooth compresses it a second time on the way to the speaker, on top of the compression the station or Spotify already applied, and that second pass is the one you can sometimes hear.
- Reliability. A cable has no pairing, no dropouts, and no reconnecting after a power cut.
- Simplicity. The radio stays on its aux source permanently, and everything else is chosen from the phone.
It works with any radio, speaker, or amplifier that has an aux or line input. How good it sounds depends on the audio adapter between the Pi and the cable; an inexpensive USB adapter is already well ahead of the Pi's built-in headphone jack.
Unofficial. This project is not affiliated with or endorsed by Spotify, Tivoli Audio, the Raspberry Pi Foundation, Radio Browser, or any radio station. Station addresses and Spotify Connect can change or stop working at any time. Use it at your own risk.
What has and hasn't been tested: everything here has been run on Raspberry Pi 4 boards, both through the built-in headphone jack and through a USB audio adapter in shared mode, including a from-scratch install following this page: the install, radio presets, Spotify Connect and the handover with radio, the song display, favorites, automatic reconnection, station search and the address check, the nightly update check, --fast-boot and --undo-fast-boot, the health check, and the Power off button. Not yet tested: any other Pi model, an update that actually installs something, and the automatic 3 AM restart. The troubleshooting section covers the places most likely to need a tweak.
- A Raspberry Pi 3, 4, or 5 with its power supply, a case, and a microSD card (a Pi 4 kit has all of these)
- A USB audio adapter with a 3.5mm headphone socket (about $10)
- A 3.5mm to 3.5mm cable, or 3.5mm to RCA if your radio's input is RCA
- A computer with a microSD slot or reader
- Spotify Premium, if you want Spotify Connect
The headphone jack on a Pi 3 or 4 works, and the installer uses it when no USB adapter is plugged in. It is fine for trying things out. A USB adapter is recommended for regular use because:
- The built-in jack is a simple circuit that shares power with the rest of the board, so it has more background hiss, which is easier to hear through a radio or amplifier turned up in a quiet room.
- The Pi 5, Pi 400, and Zero 2 W have no headphone jack at all.
Only the Pi 4 has been tested. The rest of this table is what should happen, not what has been confirmed.
| Model | Expected | Notes |
|---|---|---|
| Pi 4 | Works (tested) | Built-in jack or USB adapter |
| Pi 3 | Should work | Built-in jack or USB adapter |
| Pi 5, Pi 400 | Should work | No headphone jack, so a USB adapter is required |
| Zero 2 W | Should work | No headphone jack; needs a USB adapter and a micro-USB adapter cable. Slower, and Wi-Fi only |
| Pi 2 | Probably | Needs the 32-bit version of Raspberry Pi OS Lite, and has no built-in Wi-Fi |
| Pi 1, original Zero | No | Spotify Connect (Raspotify) does not support these processors |
On a Pi with no headphone jack and no USB adapter, the installer stops with "No audio output found".
Install Raspberry Pi Imager on your computer (raspberrypi.com/software) and put the microSD card in. The Imager lists its steps down the left side; these are the ones in version 2. Older versions ask for the same things in a different layout.
| Step | What to do |
|---|---|
| Device | Choose your Pi model |
| OS | Choose Raspberry Pi OS (other), then Raspberry Pi OS Lite (64-bit) |
| Storage | Choose the microSD card |
| Customisation: Hostname | piradio |
| Customisation: Localisation | Your country's capital, your time zone, and your keyboard layout. The time zone matters: the nightly update runs at 11 PM by the Pi's clock |
| Customisation: User | A username and password (the examples below use pi). You will need both to connect later |
| Customisation: Wi-Fi | Secure network, then your network's name (SSID) and its password, twice |
| Customisation: Remote access | Turn on Enable SSH and choose Use password authentication |
| Customisation: Raspberry Pi Connect | Leave it off. It is Raspberry Pi's service for reaching a Pi from outside your home through their website, and needs a Raspberry Pi account. PiRadio does not use it; everything here works over your own Wi-Fi with SSH |
| Writing | Check the summary lists the hostname, localisation, user account, Wi-Fi and SSH, then click Write |
- Put the card in the Pi.
- Plug the USB audio adapter into any USB port on the Pi. They all work the same for audio. On a Pi 4 or 5, one of the black (USB 2) ports is the natural choice, which leaves the faster blue (USB 3) ports free for anything that needs them.
- Run the cable from the adapter's headphone socket (green, or marked with a headphone symbol) to the radio's aux input.
- Power the Pi and wait about two minutes for the first boot.
- Set the radio to its aux source, with its volume low for now.
In a terminal on your computer (Terminal on Mac, Command Prompt or PowerShell on Windows), connect to the Pi and bring it up to date:
ssh pi@piradio.local
sudo apt update
sudo apt full-upgrade -y
sudo reboot
Wait a minute, connect again, then download the project and run the installer:
ssh pi@piradio.local
sudo apt install -y git
git clone https://github.com/madooroy/PiRadioAux.git
cd PiRadioAux
sudo bash install.sh
The installer takes a few minutes. It sets up the radio player (MPD), Spotify Connect (Raspotify), the audio output, and the preset page, and makes them all start on boot. It ends by printing the status of the three services and the address to open.
It is safe to run again, and it keeps presets you have edited from the phone.
A different name. The page and the Spotify speaker are called "PiRadio". To choose another name, for a second one in the house say, add it to the install command. --hostname also renames the Pi on the network:
sudo bash ~/PiRadioAux/install.sh --name "Kitchen Radio" --hostname kitchenradio
Updating later. On the Pi:
cd ~/PiRadioAux
git pull
sudo bash install.sh
Without Git. Copy the project folder from your computer and install from it:
scp -r PiRadioAux pi@piradio.local:~
ssh pi@piradio.local
cd PiRadioAux
sudo bash install.sh
On Windows, update-pi.bat in the project folder does those steps when you double-click it.
- On your phone (same Wi-Fi) open http://piradio.local
- Turn the radio's own volume right down, then tap a preset. A new install starts the page's volume slider at 50. Bring the radio's volume up to a comfortable level, and from then on leave it alone and use the phone. If you are listening on headphones, start with the page's slider low: a USB audio adapter is much louder than the Pi's built-in jack.
- Add the page to your home screen:
- iPhone: Share → Add to Home Screen
- Android: menu → Add to Home screen
- For Spotify, open the Spotify app, tap the devices icon, and choose PiRadio.
When nothing is playing, the Stop Playing button reads "Not Playing" and is greyed out.
Starting Spotify stops the radio. Tapping a preset or Stop Playing ends the Spotify session. While Spotify is playing through the Pi, the page shows "Spotify" with the artist and song in the Now-playing box, and no preset is highlighted. Radio volume is the slider on the page; Spotify volume is in the Spotify app. Spotify starts each session at 50, and its slider is set up to sit close to the radio's, so switching between the two should not make you jump. They will not match exactly: stations are louder than Spotify at the same setting, and differ from one another.
If a station drops. Internet streams stop now and then, because of a hiccup at the station or on your network. The Pi checks every 10 seconds that the station you chose is still playing, and restarts it if it has stopped or frozen. The page shows "Reconnecting…" while it does. If the station is down for a while, the Pi keeps trying, up to once a minute, until it returns or you press Stop Playing. While your own internet is down, it waits for it, however long that takes. It only does this for a station you started; Stop Playing, Power off, and starting Spotify all end it. A station that never produces any sound after you tap it (a wrong address, say) is the exception: the Pi gives up after about a minute and says why under the volume slider.
The page starts with four example stations. Replace them with your own from Edit presets: you can rename, reorder, remove, or add presets, up to 20. Sort by frequency puts them in dial order using the number in each name (92.5 before 103.9); stations with no number in the name go last, in alphabetical order. With more than eight presets the list scrolls, while the now-playing box, Stop Playing, volume, and Power off stay in place.
| # | Example station | Stream address |
|---|---|---|
| 1 | SomaFM Groove Salad | https://ice1.somafm.com/groovesalad-128-mp3 |
| 2 | KEXP 90.3 Seattle | https://kexp-mp3-128.streamguys1.com/kexp128.mp3 |
| 3 | Radio Paradise | https://stream.radioparadise.com/aac-320 |
| 4 | WFMU 91.1 | https://stream0.wfmu.org/freeform-128k |
Station addresses belong to the stations and change from time to time, so none of them is guaranteed to keep working. This project has no connection with any station or directory it mentions.
Find a station. In Edit presets, tap Find a station, type part of the name, and tap a result to add it. The search uses Radio Browser, a free community-run directory. Big and mid-sized stations are usually there; small local ones often are not, and for those you add the address by hand (see below). If a search finds nothing, it is tried again without the frequency and "FM", so WXYZ-FM or wxyz 92.5 still finds a station listed as "WXYZ".
Which entry to pick. A station often appears several times in the results, once for each stream it offers. The line under each name shows the format and rate, such as "MP3 128k" or "AAC 64k". To choose:
-
Skip any marked "chunked" if a plain one is listed.
-
Take the highest quality on this ladder, best first:
AAC at 256k or 320k The best ordinary streams MP3 at 256k or 320k AAC at 128k to 192k, or MP3 at 192k About equal MP3 at 128k The most common, and fine AAC or AAC+ at 64k and below Made for slow connections; choose only if nothing better exists
AAC is the more efficient format, so at the same number choose AAC, and treat 128k AAC as roughly equal to 192k MP3. Past the middle of the ladder the difference is hard to hear through a radio's speaker; it shows more on good headphones or a hi-fi. If two entries have the same format and rate, they are usually the same stream added twice, or relays in different countries: any of them will do, and an address without a country in it (stream. rather than stream-uk1.) normally picks the server nearest you.
Address check. When you save, the Pi tries each new or changed address and tells you what it found: live audio, a web page that is not a stream, an error from the server, a chunked address, or a station that blocks listeners outside its own country. You can fix the address or tap Save anyway.
Avoid chunked (HLS) addresses. A station's web player often uses an address ending in .m3u8, where the audio arrives as a playlist of ten-second chunks. The Pi's radio player (MPD) plays these but keeps stopping at commercial breaks: in a one-hour test it had to be restarted 11 times. Use a plain continuous stream instead. For stations on AmperWave (addresses containing live.amperwave.net), change manifest/NAME-hlscN.m3u8 to direct/NAME-ibcN, keeping the same number, or no number if there was none. The address check offers this change for you when the continuous address answers.
Artist and song. The "Now playing" box shows the artist and song when the stream carries them, and --- when it doesn't. Some stations publish what is playing in a separate now-playing feed instead; a preset can have one in its optional third field. Only AmperWave's feed format is understood, for example https://api-nowplaying.amperwave.net/api/v1/prtplus/nowplaying/20/STATION-ID/nowplaying.json, where the station ID is the number in the station's web player address. These feeds belong to the stations and could change without notice, in which case the line shows ---.
Favorites. While a song's name is showing, tap the heart beside it to save it. Favorites, at the top of the page, lists what you saved, with the station and date. Find in Spotify opens a Spotify search for that song, where you can play it or add it to your Liked Songs. Type in the filter box to narrow the list by song, artist, station, or date ("oct", "friday", "2026-10"), and use the menu beside it to sort by newest, oldest, song, or station. The heart also works while Spotify is playing through the Pi. It needs a song name, so it is greyed out on stations that do not send one. The list is kept on the Pi in /opt/piradio/favorites.json.
Export and import. In Edit presets, Export saves your presets to a file called piradio-presets.json on the phone or computer you are using, and Import loads such a file back in. Use them to keep a backup, or to move your stations to another Pi or a fresh card. Export contains the presets as last saved. Import replaces the list on screen and changes nothing until you tap Save. On an iPhone, Export may offer "Open in…" instead of saving straight away; tap More… and then Save to Files.
Keeping your own list. To have a fresh install start with your stations, save them as presets.local.json next to presets.json, in the same format. The installer uses it when present, and Git ignores it. The installer never overwrites presets already on the Pi.
To find the address of another station (Chrome or Edge on a computer):
-
Open the station's web player and start it playing.
-
Press F12 and click the Console tab.
-
Paste this line and press Enter (type
allow pastingfirst if Chrome asks):console.log([...document.querySelectorAll('audio,video')].map(a => a.currentSrc).concat(performance.getEntriesByType('resource').map(e => e.name).filter(n => !/\.(png|jpe?g|gif|svg|css|js|woff2?|ico)(\?|$)/i.test(n) && !/google|doubleclick|adsrvr|rubicon|sync\./.test(n))).join('\n')) -
Look for an address on a streaming server, and drop everything from the
?onward (that part is often a temporary pass that expires within a minute). One ending in.aacor.mp3, or with no ending, is best. If the only one ends in.m3u8, see the note above about chunked addresses.
The Pi is meant to stay powered all the time. It uses about 3 watts idle, is ready the moment you open the page or pick PiRadio in Spotify, and needs to be on in the evening for the automatic updates. Switch the radio off as you like; the Pi doesn't mind.
If you ever need to unplug the Pi (moving it, for example), shut it down first so the memory card isn't damaged:
- On the preset page, tap Power off PiRadio at the bottom (it shows the name you gave the device) and confirm.
- Wait until the Pi's green light stops flickering and stays off, about 30 seconds.
- Unplug it.
It starts again by itself when you plug it back in, and is ready in under a minute. The same shutdown from a computer is ssh pi@piradio.local then sudo shutdown -h now.
After a power cut the Pi also restarts by itself; that is nearly always fine.
Recovering by itself. In testing, a Raspberry Pi 4 on Wi-Fi now and then dropped off the network and stopped, with only the red light on, until it was unplugged. The installer sets up these so it comes back without help:
| What | Does | Why |
|---|---|---|
| Wi-Fi power saving off | Keeps the Wi-Fi fully awake | Power saving is a known cause of Pi 4 Wi-Fi hangs |
| Network check, every minute | If neither the router nor the internet answers for 3 minutes, restarts the network; at 5 minutes, reloads the Wi-Fi driver; at 8, restarts the Pi (at most once every 6 hours, so a router that's switched off doesn't cause repeated restarts) | Catches a hung Wi-Fi while the rest of the Pi keeps running |
| Copy of the Wi-Fi settings | Kept by the network check while the Wi-Fi works, and put back within a minute if the settings go missing | Once, after a power-off, the Wi-Fi settings came back as empty files, and the Pi had no network to join |
| Hardware watchdog | Restarts the Pi within about 15 seconds if it freezes completely | Catches a full freeze, which nothing running on the Pi can |
After a restart, the radio plays again if it was playing when the Pi stopped: after a freeze, a power cut, a restart by the network check, or an update. If it was stopped, or you used Power off, it comes back quiet. It waits up to two minutes for the network before starting the station, and if the router takes longer than that to come back (after a power cut, say), it keeps trying until the station plays. The system log is also kept across restarts (up to 50 MB), so the reason for an unexpected stop can be looked up. The health check's "Staying on" section shows that all of this is active, and warns if, in the last week, the network check had to go further than restarting the network. A plain network restart is routine: a router that restarts itself (some mesh systems do so every night) also triggers one, and the health check just notes it.
Updates are automatic. The installer sets the Pi to check every night around 11 PM and install whatever is available: the system, the radio player, and Spotify Connect. If an update needs a restart, the Pi restarts itself at 3 AM. Your presets are not affected.
What this means in practice:
- If something is playing around 11 PM, it may stop for a moment when the radio player or Spotify Connect is updated. The radio picks the station up again by itself within a few seconds; for Spotify, press play again.
- The Pi must be powered and on Wi-Fi at 11 PM for that night's update to happen. If it misses one, it catches up the next time it can.
- To see what was updated:
cat /var/log/unattended-upgrades/unattended-upgrades.log - To update by hand at any time:
sudo apt update && sudo apt full-upgrade -y - To turn automatic updates off:
sudo systemctl disable --now apt-daily-upgrade.timer - To change the time, edit the two
OnCalendartimes and theReboot-Timenear the top ofinstall.shand run it again.
The Pi is meant to stay on, so start-up time only matters after a power cut, an overnight update restart, or when you move it. If you want it shorter, run the installer once with --fast-boot:
sudo bash ~/PiRadioAux/install.sh --fast-boot
sudo reboot
Measured on a new Raspberry Pi 4 with a stopwatch, from plugging in the power to the page loading:
| Before | After | |
|---|---|---|
| Power in to page loaded | about 39 seconds | about 28 seconds |
Of which Linux itself (systemd-analyze) |
22 seconds | 17 seconds |
About half of the gain is in the firmware and bootloader stage before Linux starts, which systemd-analyze cannot see.
What it changes, all for a Pi with no screen attached:
| Where | Change | Why |
|---|---|---|
/boot/firmware/cmdline.txt |
Adds cloud-init=disabled |
cloud-init applies the Raspberry Pi Imager settings on the very first start, then costs about 2 seconds on every later one |
| NetworkManager | Waits 3 seconds, not 6, for a network cable | The Pi otherwise waits the full 6 seconds on an empty wired socket even when Wi-Fi is already connected |
/boot/firmware/config.txt |
camera_auto_detect=0, display_auto_detect=0, boot_delay=0, disable_splash=1 |
No looking for a camera or display, no firmware pause, no splash screen |
/boot/firmware/config.txt |
auto_initramfs=0, only when the Pi starts from an SD card |
The initramfs is not needed to start from a card |
/etc/initramfs-tools/conf.d/piradio-fast-boot |
MODULES=most, alongside auto_initramfs=0 |
Without it, rebuilding the (unused) initramfs fails, and with it any nightly update that includes a kernel or driver package |
| Bootloader (Pi 4 only) | NET_INSTALL_AT_POWER_ON=0 |
No pause at power-on waiting for a keyboard. This is stored on the Pi's board, not on the card |
To put everything back:
sudo bash ~/PiRadioAux/install.sh --undo-fast-boot
sudo reboot
Things to know:
- Run it only after the Pi has started once and is on your Wi-Fi. That is always the case by the time you can run the installer.
- A camera or DSI display added later would not be detected until you undo.
- The undo restores
config.txtas it was before the first--fast-boot, so any other change you made to that file since then is lost. - If the Pi does not come back afterwards: the installer keeps the original files beside the changed ones as
config.txt.piradio-bakandcmdline.txt.piradio-bak. Both are on the card's small boot partition, which a Windows or Mac computer can open. Put the card in a computer, copyconfig.txt.piradio-bakoverconfig.txt, and delete the wordscloud-init=disabledfrom the end ofcmdline.txt.
With a Pimoroni Display HAT Mini on the Pi, you can see what is playing and work the radio without a phone. It is a 2-inch screen with four buttons and a small light, and it presses onto the Pi's 40-pin header without soldering.
Tested on a Raspberry Pi 4 with Raspberry Pi OS Lite (trixie).
The screen shows the preset number and station, then the artist and the song, in large type. It does the same for Spotify. The volume is shown along the bottom.
| Button | Mark on screen | Tap | Hold 1.5 seconds |
|---|---|---|---|
| Top left | ▲ with a small heart | Previous preset | Save the song to Favorites |
| Bottom left | ▼ | Next preset | |
| Top right | + | Volume up | Keeps going up |
| Bottom right | − with a small square | Volume down | Stop playing |
The marks sit in narrow strips down each side of the screen, beside their buttons.
- Choosing a station: press previous or next as many times as you like. The station starts one second after the last press, so you can skip past several without each one connecting.
- From Stopped: either previous or next brings back the last station you listened to, even after the Pi has been off or restarted.
- Saving a song works the same as the heart on the phone page, for radio and for Spotify. A heart appears beside the volume while the song showing is in your Favorites. Holding on a song that's already saved changes nothing, and songs are removed from the phone page.
- Spotify's volume is set in the Spotify app. The volume buttons only change the radio's.
- The light stays off while all is well. It shows amber while a station is connecting or reconnecting, and red when a station couldn't be played or the page can't be reached.
- The screen goes dark a minute after playing stops. Any button wakes it.
- Switching off: after Power off on the phone page (or
sudo poweroff), the screen shows "Switching off…" and then "Safe to unplug" once the Pi has fully stopped. Wait for that before pulling the power. A restart shows "Restarting…" instead. - The light is dimmed to a fifth of full brightness. To change it, add
PIRADIO_LED_LEVEL="0.5"(anything from 0 to 1) to/etc/default/piradio, thensudo systemctl restart piradio-display. The installer keeps settings like this one when it runs again.
To set it up, fit the HAT with the Pi switched off and unplugged, then:
sudo bash ~/PiRadioAux/install.sh --display
sudo reboot
The restart is needed once, to switch on the Pi's SPI connection, which the screen uses. The installer switches it on without its MISO (data-in) line, dtoverlay=spi0-2cs,no_miso in config.txt: the screen uses that pin, GPIO 9, for something else, and with the usual dtparam=spi=on the Pi won't let go of it, so the screen stays blank. After that, updates keep the screen as it is.
| Command | Does |
|---|---|
sudo bash ~/PiRadioAux/install.sh --flip-display |
Turns the picture the other way up, for when the Pi sits the other way round. The buttons follow, so top left is always previous. |
sudo bash ~/PiRadioAux/install.sh --display |
Back to the normal way up |
sudo bash ~/PiRadioAux/install.sh --no-display |
Stops using the screen and buttons |
Things to know:
- A fan on the header has nowhere to plug in once the HAT is on. The Pi doesn't need one for this job. The health check reports the chip temperature while the screen is in use.
- Tall heatsinks can touch the back of the HAT. An 11 mm stacking header between the two raises it.
--fast-bootdoesn't affect this screen. Itsdisplay_auto_detect=0setting is about screens on the Pi's ribbon-cable connector.
Start with the health check. On the Pi, after ssh pi@piradio.local:
sudo bash ~/PiRadioAux/tools/health_check.sh
It changes nothing. It prints one line per check, marked OK, WARN or FAIL, covering the services, the installed files and presets, the page, the radio player, the audio output, Spotify Connect, automatic updates, the network, and the SD card and power supply. A FAIL line says what to do next. If you ask for help, include its output.
For a specific problem:
| Problem | Try |
|---|---|
| Page won't load | Use the Pi's IP address (shown at the end of the installer, or in your router's device list) in place of piradio.local. |
| Page says it can't reach the player | sudo systemctl status mpd |
| Preset selected but silent | speaker-test -c 2 -t wav -l 1 plays a voice through the same output. If that is silent too, run aplay -l to confirm the adapter is listed, then sudo bash ~/PiRadioAux/install.sh again. |
| One station fails, others work | That stream address is wrong or has moved. mpc status shows the error. |
| "…couldn't be played" under the volume slider | The station never produced sound, so PiRadio stopped retrying after about a minute. The message gives the reason when it can find one. A station that "blocks listeners outside its own country" cannot be fixed with a different address. |
| A station keeps showing "Reconnecting…" | Its address is probably the chunked (.m3u8) kind; see "Avoid chunked (HLS) addresses" above. journalctl -u piradio -n 30 lists each restart. |
| PiRadio missing in Spotify | sudo systemctl status raspotify and journalctl -u raspotify -n 30. Phone and Pi must be on the same Wi-Fi network. |
| Spotify shows playing but silent, or radio keeps playing under Spotify | Look at journalctl -u raspotify -n 30. The likely cause is Raspotify's security sandbox blocking the audio output or the hand-over script (/usr/local/bin/piradio-spotify-event). |
Health check says "an install was left unfinished", or the update log shows update-initramfs: failed and "failed to determine device for /" |
A Pi set up with an earlier --fast-boot. Run sudo bash ~/PiRadioAux/install.sh (it adds the missing setting), then sudo dpkg --configure -a. |
| Page doesn't load and the Pi shows only its red light | It stopped. Unplug and replug it. Then, on the Pi: journalctl --list-boots --no-pager | tail -n 3 and journalctl -b -1 -n 40 --no-pager show what it logged just before stopping. The health check's "Staying on" section should show all OK. |
| Hum through the radio | A ground loop isolator (about $10) on the audio cable. |
| File | Purpose |
|---|---|
app.py, templates/index.html |
The preset page |
static/ |
Home screen icon |
presets.json |
The example presets a fresh install starts with |
presets.local.json |
Optional: your own starting presets, used in place of the examples |
update-pi.bat |
Windows helper that copies the folder to the Pi and installs |
tools/health_check.sh |
Read-only check of the whole setup, see Troubleshooting |
tests/ |
Checks for the preset page that run without a Pi: python3 tests/run_all.py |
LICENSE |
GNU General Public License, version 3 |
install.sh |
Sets everything up on the Pi |
config/asound-shared.conf |
Audio output with a software mixer, for the USB adapter |
config/asound-direct.conf |
Audio output used directly, for the Pi's built-in jack |
config/mpd.conf |
Radio player settings |
config/spotify-event.sh |
Hands over to Spotify: stops the radio and tells the preset page |
config/piradio.service |
Starts the preset page on boot |
config/netcheck.sh, config/piradio-netcheck.* |
The network check that restarts a hung Wi-Fi, see Leave the Pi on |
display.py, config/piradio-display.service, config/piradio-display.shutdown |
Optional screen and buttons, see Screen and buttons |
On the Pi the app lives in /opt/piradio, and its presets in /opt/piradio/presets.json. The program files there belong to root; the page runs as its own piradio user, which can change only its own data (presets, favorites, the last station).
Anyone on your home network can open the page and use it, as with any home speaker. A few things keep other people's web pages from using it behind your back:
- The page answers only when it is opened by the Pi's own name (
piradio,piradio.local,piradio.lanand the like, or the name you gave with--hostname) or by its IP address. If you reach it by another name (one set up in your router, say), add it to/etc/default/piradioasPIRADIO_ALLOWED_HOSTS="radio.example.lan"(several separated by commas), thensudo systemctl restart piradio. - Changes (playing, stopping, editing presets, Power off) must come from the page itself, which marks its requests; a link or form on another site can't make them.
- Check and the now-playing lookup won't fetch addresses on the Pi itself or link-local addresses.
- The page uses port 80. To use another, add
PIRADIO_PORT="8080"to/etc/default/piradio, thensudo systemctl restart piradio piradio-display; the Spotify hand-over and the screen follow it.
PiRadioAux is a small layer over other people's work:
- MPD plays the radio streams.
- Raspotify and librespot provide Spotify Connect.
- Radio Browser is the community directory behind Find a station.
- The screen driver follows Pimoroni's own libraries for the Display HAT Mini's pins and start-up sequence.
- Flask, Waitress and python-mpd2 run the preset page.
If you want a full music player for the Pi, with a music library, AirPlay, Bluetooth and support for high-end audio boards, look at moOde audio or Volumio.
Copyright (C) 2026 madooroy
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but without any warranty; see the LICENSE file for the full text.