radieo

A personal music radio: an always-on HTTP audio stream, automatically fed from several sources and broadcast with Liquidsoap.

The goal is a hassle-free stream that always has something playing, where the next track is picked automatically. It is meant for personal use (a couple of simultaneous listeners), not for public broadcasting.

How it works

radieo is built as two layers, each running in its own Docker container and sharing a cache volume:

• ingest (Python) — the brain. It decides what to play next, resolves and downloads tracks into a local cache, keeps a pre-filled queue, and exposes the next track over HTTP at GET /next. (currently it only serves the cache directory; the download providers come in later milestones — see roadmap)
• stream (Liquidsoap) — deliberately dumb. It pulls the next track from the ingest daemon, broadcasts the audio over HTTP, and never goes silent thanks to a local cache fallback.

Playback sources (planned): a Navidrome library via the OpenSubsonic API, arbitrary tracks fetched with yt-dlp (Bandcamp, SoundCloud, YouTube…), and listening suggestions from a ListenBrainz RSS feed.

Usage

Requirements: Docker with Compose v2.

# Drop some .mp3 files into the cache directory
cp /path/to/music/*.mp3 cache/

# Build and start the stream
docker compose up -d

# Listen (VLC, a browser, any audio player)
#   http://localhost:8000/radio.mp3

Stop it with docker compose down.

The stream is MP3 at 192 kbps. Multiple clients can listen at the same time. New files dropped into cache/ are picked up automatically (the playlist is reloaded when the directory changes).

Current status

Milestone 2 — ingestion daemon: done.

• ingest (Python) container exposes GET /next, returning the next track as an annotated Liquidsoap URI (or an empty body when nothing is ready).
• stream (Liquidsoap v2.4.5) pulls from ingest via a request.dynamic source, and falls back to the local cache/ directory when the daemon has nothing to offer.
• HTTP stream served at http://localhost:8000/radio.mp3 (MP3, 192 kbps).
• Continuous output guaranteed: silence rather than a crash when everything is empty (mksafe).
• Multiple simultaneous listeners supported.

At this stage the daemon just cycles through the files already in cache/; the download providers (Navidrome, yt-dlp, ListenBrainz) come next.

Roadmap

1. ✅ Broadcasting skeleton — Liquidsoap serving the cache directory.
2. ✅ Ingestion daemon — Python daemon exposing GET /next; Liquidsoap switches to a request.dynamic source with the cache as fallback.
3. Navidrome provider — play from an OpenSubsonic playlist, with caching, LRU retention and play history.
4. yt-dlp provider — fetch tracks from a maintained URL/artist list; weighted mixing between sources.
5. Canonicalizer — ListenBrainz MBID lookup for source-agnostic de-duplication.
6. ListenBrainz provider — parse the RSS suggestions feed and resolve each one to Navidrome or yt-dlp.
7. Polish — crossfade, robustness, optional web player, config file.