Initial commit — SUB/WAVE Now Playing Tronbyt app

README.md

@@ -0,0 +1,47 @@
+# subwave-nowplaying
+
+Tronbyt/Tidbyt app showing the current track on a [SUB/WAVE](https://github.com/perminder-klair/subwave)
+internet radio station: album art, track title, artist, and station name,
+with title/artist scrolling if they don't fit.
+
+Not tied to any specific station — set your own station's base URL in the
+app's config when adding it to a device.
+
+## Configuration
+
+- **Station URL** — the base URL of your SUB/WAVE instance, e.g.
+  `https://radio.example.com`. No trailing slash needed (stripped
+  automatically). No auth required — SUB/WAVE's now-playing and cover-art
+  endpoints are public.
+
+## How it works
+
+- `GET {station_url}/api/now-playing` — track title, artist, `subsonic_id`,
+  DJ/station name, and stream online status. Cached 20s.
+- `GET {station_url}/api/cover/{subsonic_id}` — album art JPEG, proxied by
+  SUB/WAVE itself (no Navidrome credentials needed). Cached 300s.
+- If the station reports `streamOnline: false`, shows "<station> offline"
+  instead of stale track info.
+- If a track has no `subsonic_id`, or the cover fetch fails, falls back to a
+  full-width layout with no art rather than a broken image.
+
+**Note on unreachable hosts:** if the station URL is wrong or the host is
+completely unreachable (DNS failure, connection refused), `http.get` raises
+a hard error and the render fails for that cycle — this is normal pixlet/
+Starlark behavior (no try/except in the language), not a bug. Only
+HTTP-level errors (404, 500, etc.) are something the app can catch and
+display a message for, which it does.
+
+## Dev/test
+
+```
+pixlet render subwave_nowplaying.star station_url=https://your-station.example.com
+pixlet serve subwave_nowplaying.star
+```
+
+## Deploy
+
+Upload `subwave_nowplaying.star` directly through your Tronbyt server's
+"Upload app" button on a device's Add App page (single file, no bundled
+assets — no need to zip). Configure the Station URL field when adding it to
+your device's schedule.