diff --git a/widgets/internet-radio-player/README.md b/widgets/internet-radio-player/README.md new file mode 100644 index 00000000..3c5c7a4e --- /dev/null +++ b/widgets/internet-radio-player/README.md @@ -0,0 +1,266 @@ +![playing](preview.png) +![paused](paused.png) + +# Internet Radio Player + +Stream internet radio stations from your Glance dashboard. Supports optional now-playing metadata (track title, artist, album art) via configurable API endpoints. + +```yaml +- type: custom-api + title: Radio + cache: 30s + frameless: true + options: + stations: + - name: KEXP 90.3 + url: https://kexp.streamguys1.com/kexp160.aac + metadata-url: https://api.kexp.org/v2/plays/?limit=1 + title-path: "results.0.song" + artist-path: "results.0.artist" + image-path: "results.0.thumbnail_uri" + - name: SomaFM Groove Salad + url: https://ice1.somafm.com/groovesalad-128-mp3 + - name: NTS Radio + url: https://stream-relay-geo.ntslive.net/stream + template: | + + + {{ $stations := .Options.stations }} + {{ $metaTitle := "" }} + {{ $metaArtist := "" }} + {{ $metaImage := "" }} + + {{ $s0 := index $stations 0 }} + {{ $metaUrl := index $s0 "metadata-url" }} + {{ if $metaUrl }} + {{ $res := newRequest $metaUrl | getResponse }} + {{ if eq $res.Response.StatusCode 200 }} + {{ $data := $res.JSON }} + {{ $tp := index $s0 "title-path" }} + {{ if $tp }}{{ $metaTitle = $data.String $tp }}{{ end }} + {{ $ap := index $s0 "artist-path" }} + {{ if $ap }}{{ $metaArtist = $data.String $ap }}{{ end }} + {{ $ip := index $s0 "image-path" }} + {{ if $ip }}{{ $metaImage = $data.String $ip }}{{ end }} + {{ end }} + {{ end }} + + {{ if $stations }} +
+ + + +
+
♫
+ +
+ +
+ {{ (index $stations 0).name }} + +
+
+ Internet Radio +
+ +
+ +
+
+ {{ else }} +

No stations configured

+ {{ end }} +``` + +## Configuration + +### Station Fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | Display name shown in the station dropdown | +| `url` | Yes | Direct audio stream URL (MP3 or AAC over HTTP) | +| `metadata-url` | No | JSON API endpoint that returns now-playing info | +| `title-path` | No | JSON path to the track title in the metadata response | +| `artist-path` | No | JSON path to the artist name in the metadata response | +| `image-path` | No | JSON path to the album art URL in the metadata response | + +### Metadata + +Metadata fields (`metadata-url`, `title-path`, `artist-path`, `image-path`) are entirely optional. Stations without them display the station name when playing. + +When configured, the widget fetches the metadata URL server-side and extracts fields using the JSON paths you provide. Paths use dot notation with array indices, for example `results.0.song` accesses `{"results": [{"song": "..."}]}`. + +**Metadata is only fetched for the first station in the list.** If you switch to another station, the widget shows the station name only. Reorder your stations list to put your preferred metadata-enabled station first. + +### Cache + +The `cache` value controls how often Glance re-renders the widget and fetches fresh metadata. `30s` keeps track info current. Longer values (e.g. `5m`) reduce API calls but show stale track info. + +Audio playback is **not** interrupted by cache refreshes — the player uses a persistent audio object that survives re-renders. + +### Finding Stream URLs + +Most internet radio stations publish their stream URLs on their websites. Look for "listen" or "stream" links, often ending in `.mp3`, `.aac`, or `.m3u`. If you get an `.m3u` file, open it in a text editor — the actual stream URL is inside. + +### Example Stations + +```yaml +# KEXP (Seattle) — has a public now-playing API +- name: KEXP 90.3 + url: https://kexp.streamguys1.com/kexp160.aac + metadata-url: https://api.kexp.org/v2/plays/?limit=1 + title-path: "results.0.song" + artist-path: "results.0.artist" + image-path: "results.0.thumbnail_uri" + +# SomaFM Groove Salad — no metadata API needed +- name: SomaFM Groove Salad + url: https://ice1.somafm.com/groovesalad-128-mp3 +``` diff --git a/widgets/internet-radio-player/meta.yml b/widgets/internet-radio-player/meta.yml new file mode 100644 index 00000000..57d47aed --- /dev/null +++ b/widgets/internet-radio-player/meta.yml @@ -0,0 +1,3 @@ +title: Internet Radio Player +description: Stream internet radio stations with now-playing metadata display +author: dankozlowski diff --git a/widgets/internet-radio-player/paused.png b/widgets/internet-radio-player/paused.png new file mode 100644 index 00000000..c0732954 Binary files /dev/null and b/widgets/internet-radio-player/paused.png differ diff --git a/widgets/internet-radio-player/preview.png b/widgets/internet-radio-player/preview.png new file mode 100644 index 00000000..64f95838 Binary files /dev/null and b/widgets/internet-radio-player/preview.png differ