cat ./safydo

SAFYDO Raspberry Pi radio stream player

A Raspberry Pi, a Bluetooth speaker, and a web page. That is the whole stereo.

SAFYDO streams internet radio, FM and the audio of YouTube-style links, plays your own music from a USB stick, records any of it, and sends it to a Bluetooth speaker at the best codec that speaker will accept — all driven from a page it serves itself. No app to install, no account, nothing leaving the house. It runs on boards with 512 MB of RAM, which is the constraint behind almost every decision below.

  • raspberry pi
  • 512 mb
  • bluetooth a2dp
  • web ui
  • fm + rds
  • recording
  • no cloud
  • open source
The SAFYDO web interface: a 90s-hits playlist playing with a seek bar and stereo VU meter, playback with previous, next and record buttons, volume, the FM radio tuner, the equaliser and the Bluetooth panel showing SBC-XQ at 570 kbps.
The whole control surface, on one page — a playlist of 90s hits with its seek bar, the record button, FM, the equaliser, and the Bluetooth panel naming the codec actually negotiated: SBC-XQ at 570 kbps, the one thing most players never tell you.

Below the fold: the station list, web-link playlists, files and recordings — see the whole page.

./what-it-does

Everything from one page, on any phone in the house.

  • Internet radio from an editable station list, with genre and category filters, favourites, and discovery through Radio Browser and Jamendo. A station can carry several genres — ambient, chill — and sits under each of them, every genre in its own colour.
  • Live rewind. Every live stream keeps up to 45 minutes in memory: drag back to hear what you missed, press LIVE to return. The buffer is sized from what the stream really costs in RAM, so the minutes you ask for are the minutes you get.
  • Web links and playlists. The audio of pages from YouTube, SoundCloud, Mixcloud, Vimeo, Dailymotion and Rumble, kept in playlists you can reorder while they play, with shuffle and loop.
  • FM radio on an add-on tuner board, with RDS station names and radio text, presets, band scans and a mono switch for weak signals.
  • Recording. One button records what is playing live — a station, a live link or FM — to MP3, Opus, FLAC or the untouched broadcast, onto a USB stick or the SD card, with a browser to play, download and rename what you kept.
  • Your own music from a USB stick — auto-mounted whatever its filesystem — and from network shares over SMB or NFS.
  • Bluetooth pairing from the browser. Scan, pair, connect, forget. Known speakers reconnect on their own at boot, and when several are around it takes the one with the strongest signal.
  • The best codec the speaker supports, negotiated automatically and shown in the interface — SBC-XQ, AAC, aptX, aptX-HD or LDAC — with a manual override for devices whose firmware misbehaves.
  • A five-band equaliser with presets and custom curves, off by default so nothing touches the signal unless asked.
  • A stereo VU meter driven by the real left and right levels, plus an optional eight-LED hardware meter on a Blinkt board.
  • WiFi setup with no screen and no keyboard. If it cannot get online it raises its own access point; you join it, pick your network from a list, and it joins and stands the AP down.
  • Settings for the tinkerer: reconnect attempts, read-ahead, refill after a stall, timeouts and user agent for flaky streams; recording format and quality; the box’s own .local name; and switches to hide the panels you never use.
SAFYDO on a phone: a playlist track playing with its seek bar, previous, pause, next, record and stop buttons, the volume slider and the FM radio tuner.
The same page on a phone. Every panel folds away to its title.
Settings, Streams tab: unlimited reconnect retries, buffering before the first sound, read-ahead cache, refill after a stall, connect timeout, longest wait between reconnects, Bluetooth output buffer and user agent.
Settings → Streams: how a stream behaves on a flaky network, applied without a restart.
Settings, Recording tab: format MP3, Opus, FLAC or original, bitrate with megabytes per hour, where to save and when to stop by itself.
Settings → Recording: format, quality, where it goes and when it stops by itself.

./hardware

Two boards, one codebase.

It runs on the Raspberry Pi Zero 2 W and the Raspberry Pi 3 A+ — both 512 MB, both on Raspberry Pi OS Lite, 32-bit. The installer works out which board and which OS release it is on and adapts: overclock profiles, boot configuration, the development link, and which recovery path to print if something goes wrong all differ between them.

Networking is normally a USB ethernet or WiFi dongle rather than the onboard radio, for a reason worth its own note below.

A Raspberry Pi Zero 2 W in a metal case with a Blinkt LED strip lit green and yellow as a VU meter, a USB ethernet adapter attached, and a USB stick of music plugged in.
A Zero 2 W doing the whole job: eight LEDs as a hardware VU meter, music on the USB stick, network on the ethernet dongle — and the onboard WiFi switched off so Bluetooth gets the 2.4 GHz band to itself.

./stack

Deliberately thin.

BlueZ and ALSA carry the Bluetooth audio, with bluez-alsa built from source for the HD codecs. mpv does the playing, driven over its JSON IPC socket. A FastAPI backend exposes it all as a small HTTP and WebSocket API, and the interface is React and Tailwind compiled to static files and served by nginx.

Web links go through yt-dlp, kept in its own environment and updated weekly because the sites change under it; recording hands the packets mpv already receives to ffmpeg, so nothing is downloaded twice.

No PulseAudio, no PipeWire, no Node server in production. The whole box uses about 175 MB idle and ~200 MB playing, plus whatever rewind window you allow it.

./field-notes

Things that were only obvious afterwards.

Bluetooth and WiFi are fighting over one antenna

On both of these boards the onboard 2.4 GHz radio is shared between WiFi and Bluetooth, and A2DP is what loses. The fix is unglamorous: turn the onboard WiFi off, put the network on a USB dongle, and let Bluetooth have the air to itself. The installer now does this by default — but it refuses when that would cut the only way back into the box, and says so loudly rather than skipping it quietly.

The packaged Bluetooth audio only speaks SBC

If you want AAC, aptX, aptX-HD or SBC-XQ — and on a decent speaker you can hear the difference — the distribution’s build will not give them to you. So the installer builds bluez-alsa from source with the codec libraries compiled in, and on one of the target systems the AAC library is not in the package archive at all, so it builds that from source too. It is a long build. It is also the difference between 328 and 570 kbps to the same speaker.

A captive portal that hands out no addresses looks exactly like a broken one

The setup access point appeared, phones could see it, and joining silently failed after about eight seconds. The access point was fine. The dnsmasq package installs a system-wide resolver that binds every interface, so the portal’s own DHCP server could never claim the port and had been crash-looping unnoticed. Clients associated, waited for an address that never arrived, and gave up. From a phone, indistinguishable from a router that hates you.

A radio cannot scan for networks while it is a network

The setup page lists the WiFi networks around you, which sounds trivial until you notice the player has one radio and is currently using it to host the access point you are connected to. Scanning would knock you off the very page you are reading. So the survey is taken in the last moment before the access point goes up, cached, and served from there — and the page says so, rather than pretending it is live.

An instrument that can go quiet in the same shape as the bug

While chasing an audio dropout, the monitoring tool reported zero Bluetooth packets for the better part of an hour — twice — while a second copy of the same tool, started by hand at that exact moment, counted a hundred a second. The process was alive, its reader thread was alive, and it was still burning CPU on packets that never reached the counter. Two false conclusions came out of that before it was caught.

The count now comes from the kernel’s own statistics with nothing in between, and every line of the log records whether the witness itself is healthy. A measuring device that can fail in the same shape as the fault you are hunting is worse than no measuring device.

Sometimes it really is the hardware

One of the two boards drops Bluetooth mid-stream: the controller raises a hardware error, stops answering the host entirely, and only a reboot brings it back. It was chased for a long time as a software problem — the audio daemon, the Bluetooth stack version, the OS release, radio interference — and it is none of them. The same failure is reported on a different Pi model, a different kernel, a different Bluetooth stack version and a completely different audio server. What those two have in common is the controller chip.

That is where it stands: identified, documented, unfixed upstream, and worked around by putting the audio on the board that does not do it.

A buffer pays for its own bookkeeping

The rewind window was first sized the obvious way: minutes times the station’s bitrate. Users got half the minutes they set. The player stores each compressed packet with its own header and padding, and an MP3 stream arrives as dozens of small packets a second — a station declaring 168 kbps costs about 320 kbps in memory. The size now comes from measuring what the cache actually holds for how many seconds, and the settings page says so when the cap is shorter than what you asked for.

Recording without a second download

The naive recorder opens the stream again and saves it, doubling the bandwidth and, for FM, writing uncompressed audio to an SD card that should be spared. Instead the player hands over the packets it already has, wrapped so that any codec fits, through a pipe to an encoder that writes the final format directly. FM’s raw tuner audio goes the same way and lands as FLAC.

The first version froze the whole player the moment you changed station mid-recording. The player keeps its recording switched on from one stream to the next, and for the new one it reopened the pipe — whose reader had just finished and gone. Opening a pipe nobody reads waits forever, so the player stopped answering, and the recorder’s own stop could not reach it either. Now the recording is closed before anything new is loaded, while the player is still listening. The same mechanism explains a rule: only live sources can be recorded. An on-demand track is already fetched a minute ahead of what you hear, so a recording would start late, or — for a short clip — come out empty.

./rules

Four rules it is built to.

  • The web interface is the product. Playback, equaliser, pairing, recording, network setup, renaming the box, diagnostics, shutdown — all of it reachable from the page. SSH is for development, not for operating the thing.
  • Quality is never traded for convenience. If audio breaks up, the cause gets fixed; the bitrate does not get quietly lowered to hide it.
  • Assume the power will be cut. Logs live in RAM, the filesystem is tuned for it, and there is a graceful shutdown button for when there is time to use it.
  • One command to install. Idempotent, detects the board and the OS release, safe to re-run at any time.

./status

Working and in daily use: streaming with live rewind, web links and playlists, FM with RDS, recording, local and network files, Bluetooth pairing and HD codec selection, the equaliser, the visualiser, the WiFi setup portal, ethernet priority, and the installer. Open: the controller fault above, re-testing the newest features on the Zero 2 W, and the usual long tail of polish.

Source, and the full engineering notes including everything that went wrong on the way: github.com/anducampu/SAFYDO

ready

Discotheque