From ca5cbc61df39c4500c0d1ac1b72d36128c6f0ea8 Mon Sep 17 00:00:00 2001
From: Pierre-Olivier Mercier <nemunaire@nemunai.re>
Date: Thu, 2 Jul 2026 22:47:20 +0800
Subject: [PATCH] docs: describe milestone 7 (web player, robustness)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 31 +++++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6d29cfa..c00bea3 100644
--- a/README.md
+++ b/README.md
@@ -76,9 +76,28 @@ The relative mix between sources is set by `RADIEO_WEIGHT_NAVIDROME` /
 `RADIEO_WEIGHT_YTDLP` / `RADIEO_WEIGHT_LISTENBRAINZ` (a weight of 0 disables a
 source); an empty URL / missing file also disables the corresponding source.
 
+Open the player at `http://localhost:8000/` — a small web page with an
+`<audio>` player and the current track (title/artist), which it refreshes from
+`GET /nowplaying`. The raw stream stays at `http://localhost:8000/radio.mp3`.
+
 ## Current status
 
-**Milestone 6 — ListenBrainz provider: done.**
+**Milestone 7 — polish: done.**
+
+- A small web player is served by Liquidsoap at `http://localhost:8000/`
+  (alongside the stream), showing the track currently on air; it reads
+  `/nowplaying` (JSON), fed from the broadcast source's live metadata — so it
+  is accurate even though the ingest daemon runs a track ahead (prefetch).
+- A 3 s crossfade smooths transitions between tracks.
+- The fallback playlist now ignores non-audio and hidden files (`.gitkeep`,
+  in-progress `.part`), so the earlier startup ffmpeg "Invalid data" warnings
+  are gone.
+- Robustness: the ingest daemon shuts down cleanly on SIGTERM (fast
+  `docker compose down`), has a Docker healthcheck on `/healthz` (the stream
+  waits for it to be healthy), and outgoing HTTP calls retry transient
+  connection errors.
+
+**Playback (milestones 3–6).**
 
 - Three playback sources feed a weighted scheduler: a Navidrome/OpenSubsonic
   playlist, a hand-maintained list of yt-dlp URLs (`config/urls.txt`), and a
@@ -107,10 +126,9 @@ source); an empty URL / missing file also disables the corresponding source.
 - HTTP stream served at `http://localhost:8000/radio.mp3` (MP3, 192 kbps),
   multiple simultaneous listeners supported.
 
-Polish comes next (crossfade tuning, robustness, optional web player, config
-file). (Known cosmetic quirk: at startup the fallback logs a few harmless
-ffmpeg "Invalid data" warnings while probing non-audio files such as
-`.gitkeep`; to be quieted in the polish milestone.)
+The radio is feature-complete for personal use. A future nicety would be moving
+the source weights and settings from environment variables into a single config
+file.
 
 ## Roadmap
 
@@ -125,4 +143,5 @@ ffmpeg "Invalid data" warnings while probing non-audio files such as
    de-duplication.
 6. ✅ **ListenBrainz provider** — parse the recommendations feed and resolve
    each suggestion to Navidrome or yt-dlp.
-7. **Polish** — crossfade, robustness, optional web player, config file.
+7. ✅ **Polish** — crossfade, web player, quieter logs, robustness (graceful
+   shutdown, healthcheck, HTTP retries). *(Config file: still env-based.)*