TRUCKER RADIO - PLAYER AGENT PROTOCOL  (v0.1)
All ports (PC, Android, iPhone/iPad, Pi, media center) talk to the server the same way.
Base URL: http://<server>:6969

1. LISTEN
   GET /stream                 audio/mpeg, 192 kbps MP3, endless
     Request header  Icy-MetaData: 1  -> server sends icy-metaint: 16000 and
     StreamTitle='Artist - Title' blocks (standard Shoutcast/Icecast format).
     Title markers are sent in-band at the point the new song starts, so update
     the screen when that audio is PLAYED, not when it is downloaded.
   Optional headers:  X-Agent-Name: "Android - John's phone"   (shows in listener log)
   If stream_password is set: ?key=<password>  or HTTP Basic auth (any user).
   Any HTTP/Icecast player works (VLC, Kodi, Winamp, Android ExoPlayer, AVPlayer).

2. NOW PLAYING
   GET /api/nowplaying  ->
   { "now":  {id, artist, title, album, year, genre, deck, source, started, position, length, ...},
     "next": {id, artist, title, source},
     "history": [ {id, artist, title, album, year, deck, ts}, ... newest first ],
     "listeners": n, "station": "...", "server_time": epoch }
   Match the ICY title against now + history to get the song id you are HEARING
   (you are a few seconds behind the server).

3. ALBUM ART
   GET /api/art/<id>   image/jpeg|png (embedded art or folder.jpg);
   image/svg+xml placeholder when there is none (header X-Placeholder: 1).

4. NEXT (skip)
   POST /api/skip   Content-Type: application/json   {"song_id": <id you are hearing>}
   Headers: X-Agent-Name, and X-Agent-Key: <agent_key> when outside the LAN.
   Server fades the song out (1.5 s) and starts the next deck.
   The song's weight drops (x0.7); songs played through gain weight (+0.1).

5. RECONNECT
   If the stream drops, wait 2-3 s and dial in again. New connections get a
   3 s burst so audio starts immediately.