From 842b7249b99fad3d430c5ef3d1238ceaeb8f3821 Mon Sep 17 00:00:00 2001
From: hermes <hermes@obahan.xyz>
Date: Wed, 30 Sep 2026 21:59:34 +0200
Subject: [PATCH] add docs/stereo-setup.md

---
 docs/stereo-setup.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 docs/stereo-setup.md

diff --git a/docs/stereo-setup.md b/docs/stereo-setup.md
new file mode 100644
index 0000000..6154773
--- /dev/null
+++ b/docs/stereo-setup.md
@@ -0,0 +1,38 @@
+# Stereo setup
+
+Your stereo needs one thing: a stream URL.
+
+## Plain HTTP (works on everything old)
+
+```
+http://<vps-host-or-radio.obahan.xyz>:8000/ai-radio.mp3
+```
+
+## HTTPS (if your stereo supports it)
+
+```
+https://radio.example.com/ai-radio.mp3
+```
+
+## Adding it
+
+- **Internet radio presets:** most stereos (Denon HEOS, Yamaha MusicCast,
+  Sonos, Ruark, Roberts, cheap WiFi radios) have "Add station by URL" /
+  "Custom station" / "Manual tune" in their app or menu. Use the URL above.
+- **DLNA/UPnP radios** without URL entry: point them at the shipped
+  `playlist.m3u8` instead (files mode — gaps between songs, but works).
+- **Phone/tablet as proof:** VLC → Open Network Stream → paste the URL.
+
+## Title display
+
+Song titles are written into the stream as ID3 metadata (ID3v2.3 with an
+ID3v1 fallback). Most stereo displays show them within a few seconds of a
+track change. Very old displays may show only the station name — that's
+the radio's limitation, not the stream's.
+
+## If the display shows the wrong/old title
+
+The stream is continuous; some players cache the last metadata block.
+Skip to next track twice, or restart the stream. If it persists across
+players, check the shipper log — the title comes from the generator's
+`title` field (falls back to `style` when empty).