# subwave-nowplaying

Tronbyt/Tidbyt app showing the current track on a [SUB/WAVE](https://github.com/perminder-klair/subwave)
internet radio station: album art with a slow zoom/pan reveal, and four
scrolling lines — track title/artist, a thin separator, the current show
and host, and local time/temperature — plus a track progress bar pinned to
the bottom of the 32px-wide text column. Color scheme (cyan title/artist,
white show name, magenta host/progress bar) is loosely modeled on SUB/WAVE's
own web now-playing display.

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.
- Album art gets a slow "Ken Burns" breathing effect: eases from one corner
  of the image out to the full frame, then back into that same corner, on a
  continuous ~60s round-trip loop (not a one-shot reveal — see below).
  Rendered oversized (45x45 vs. the 32x32 display slot) and scaled between
  1.0 and ~0.71, since `animation.Scale` above 1.0 has no visible effect on
  a widget whose declared size already matches its container. Which corner
  it uses is derived from the track's `subsonic_id` (not true randomness) so
  a still-playing track re-rendered on the `NOWPLAYING_TTL` cache doesn't
  jarringly jump corners — only a genuinely new track does. Verified this
  doesn't blow the payload budget: counterintuitively, a *slower* zoom
  compresses *smaller*, since more adjacent ticks become pixel-identical at
  this resolution and WebP dedupes them — measured 97-264KB depending on the
  art's own visual complexity, all well under the 460KB device limit.

  **Why a loop, not a one-shot reveal:** a one-way "start in corner, end on
  full frame, then hold" version looked jumpy in practice — since the app
  re-renders on `NOWPLAYING_TTL`, each fresh render restarts its own
  animation from tick 0, so whatever the *previous* pushed image happened to
  be showing gets abruptly replaced by a fresh "zoomed into a corner" frame.
  Looping back-and-forth doesn't eliminate that (a server-side re-render
  always restarts at tick 0 regardless of app logic), but ending exactly
  where it started means the animation also loops seamlessly *on-device*
  between refreshes, which reads as far less jarring than a one-way reveal
  that snaps back. Considered using genuinely random per-frame content (like
  `ormakers-tronbyt`'s LoRa segment, which pre-crops 60 frames directly from
  a high-resolution *static* source photo via offline Pillow processing) for
  a sharper zoom, but that technique fundamentally doesn't transfer here:
  album art is fetched live per-track at render time, and pixlet's Starlark
  sandbox has no image-cropping/pixel-analysis capability at all (confirmed
  by checking its full module list) — so there's no way to pre-bake or
  crop-at-render-time from a source we don't have until the request hits
  the live station.
- Shows the current show name (`context.activeShow.name`) and host name
  (`dj.name`) below the artist, separated by a thin divider line, and the
  local time/temperature (`context.clock`/`context.weather`) below that —
  all as independently scrolling Marquee lines, confined to the 32px-wide
  text column next to the album art (no overlay/overlap with the art).

**Known quirk — occasional Marquee glitch:** pixlet's `render.Marquee` runs
its own internal scroll-cycle animation, and stacking several Marquees of
different text lengths in one Root can occasionally desync them — a line
may briefly blank or show a garbled frame while another Marquee is
mid-cycle. This is a real, currently-unfixed pixlet bug (there's an
open `FIXME: Behaviour when children themselves are animated is a bit
weird` in pixlet's own widget docs), not something introduced by this app.
It's also not unique to this app: `tronbyt/apps/apps/goosefm/goose_fm.star`
(an accepted official community app) stacks 3 Marquees for the same kind of
now-playing info and exhibits the identical occasional glitch on close
frame-by-frame inspection. In practice it's subtle enough to be easy to
miss on a real, continuously-scrolling display. A custom hand-rolled scroll
(via `animation.Transformation` + `Translate`, avoiding `Marquee` entirely)
was prototyped and could fully eliminate this, but only by consolidating
down to 2 scrolling lines total (title alone, everything else combined into
one line) — full independent lines for every field was preferred instead,
accepting the same minor quirk real Tidbyt/Tronbyt apps already ship with.

**Progress bar caveat:** the now-playing API reports track `duration` but
not elapsed/remaining time, so the app tracks playback position itself —
the first time it sees a given `subsonic_id`, it stamps the current
wall-clock time in pixlet's cache, then diffs against that stamp on later
renders to compute elapsed seconds. This only works correctly on a
long-lived server process with a persistent cache (true for
`tronbyt/server`'s in-memory cache) — a one-shot `pixlet render` CLI
invocation always starts a fresh process with an empty cache, so the bar
will always show 0% when testing locally. This is expected, not a bug.

**Note on JSON nulls:** SUB/WAVE sends some fields as explicit JSON `null`
(e.g. `context.activeShow` between scheduled shows) rather than omitting the
key. Starlark's `dict.get(key, default)` only falls back to `default` when
the key is *absent* — an explicit `null` (decoded to Starlark `None`) passes
straight through, so this app also does `... or {}` on those lookups before
chaining another `.get()` off them, to avoid a `NoneType has no .get` crash.

**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.