From e3170c13c3599fe328c9ae33d39a7a80dc952ed9 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Mon, 6 Jul 2026 10:46:26 -0500 Subject: docs(specs): add radio-browser lookup UI prototype The prototype is a standalone HTML mockup of the four minibuffer screens for the radio-browser lookup: query, station list, multi-select, and created-and-playing. I drew it with real jazz-search data in the vertico and marginalia style. It shows the two candidate-annotation formats the design picks between. The spec's References section links to it. This sets the convention for a spec's visual companion: docs/specs/.prototype.html, tracked alongside the spec. --- .../specs/2026-07-06-radio-browser-lookup-spec.org | 4 + .../2026-07-06-radio-browser-lookup.prototype.html | 190 +++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 docs/specs/2026-07-06-radio-browser-lookup.prototype.html diff --git a/docs/specs/2026-07-06-radio-browser-lookup-spec.org b/docs/specs/2026-07-06-radio-browser-lookup-spec.org index 9db7b92f..161e95a6 100644 --- a/docs/specs/2026-07-06-radio-browser-lookup-spec.org +++ b/docs/specs/2026-07-06-radio-browser-lookup-spec.org @@ -151,6 +151,10 @@ Add cj/music-radio-search (query -> search -> completing-read multi-select -> wr - url.el error handling is the likeliest rabbit hole. Keep the client tiny: one GET, parse, or a single user-error. Do not build a general HTTP layer. - Stream URL choice: a station can list several codec/bitrate variants under one name. v1 takes url_resolved as-is; picking among a station's variants is a vNext refinement, not a v1 problem. +* References / Appendix +- UI prototype (open in a browser): [[file:2026-07-06-radio-browser-lookup.prototype.html][2026-07-06-radio-browser-lookup.prototype.html]] — faithful vertico + marginalia mockup of the four minibuffer screens (query, station list, multi-select, created+playing) with real jazz-search data. Shows the two candidate-annotation variants the design chooses between (A: codec/bitrate/country/votes/plays; B: codec/bitrate/country/votes/tags). +- API shape verified live 2026-07-06 against de1.api.radio-browser.info (recorded in Problem / Context). + * Review and iteration history ** 2026-07-06 Mon @ 10:12:00 -0500 — Claude (for Craig) — author - What: resolved all four open decisions from Craig's answers and folded them into the design, config, rollout, and acceptance sections. diff --git a/docs/specs/2026-07-06-radio-browser-lookup.prototype.html b/docs/specs/2026-07-06-radio-browser-lookup.prototype.html new file mode 100644 index 00000000..69d3c435 --- /dev/null +++ b/docs/specs/2026-07-06-radio-browser-lookup.prototype.html @@ -0,0 +1,190 @@ + + + + + +Radio-browser lookup — UI prototype + + + +
+
+

Emacs · vertico + marginalia · prototype

+

Radio-browser station lookup — how the screens read

+

One command, cj/music-radio-search, taking you from a query to audio. These are faithful mockups of the four minibuffer screens, drawn with a real live search for jazz (results sorted by popularity). Everything is monospace because it all lives in the minibuffer.

+

The one real design choice is the station line: what metadata rides alongside the name, and in what order. Step 2 shows two variants — pick one.

+
+ + +
1  

The query

+

Bound next to R in the playlist keymap. You type a name or keyword; Enter fires the search.

+
+
+
;; *EMMS-Playlist* — 3 tracks, playing “Kind of Blue / So What”
+
+
*EMMS-Playlist*Radio▶ playing
+
Radio search: jazz
+
+ + +
2  

The station list

 — Variant A: codec · bitrate · country · ♥votes ▶plays
+

vertico lists the matches; marginalia annotates each on the right, dimmed. The current row carries the gold highlight. Codec and bitrate tell you the quality; ♥ is radio-browser votes, ▶ is play count — both proxies for “is this station any good.”

+
+
Stations for “jazz” (TAB to mark, RET to create+play): 7/842
+
Adroit Jazz UndergroundMP3 320k US ♥174208 ▶148
+
101 SMOOTH JAZZMP3 128k US ♥86929 ▶389
+
Adroit Jazz Underground HD OpusOGG 192k US ♥67573 ▶51
+
Jazz Radio BluesMP3 128k FR ♥62960 ▶113
+
Jazz RadioMP3 192k FR ♥49272 ▶108
+
Jazz Radio Classic JazzMP3 128k FR ♥27269 ▶52
+
Radio Swiss JazzMP3 128k CH ♥26626 ▶58
+
Stations for “jazz”…: 
+
+ + +
2  

The station list

 — Variant B: adds a tag snippet, drops play count
+

Same list, but the annotation trades ▶plays for the station’s top tags — more help telling two same-named stations apart by what they actually play, at the cost of a wider line.

+
+
Stations for “jazz” (TAB to mark, RET to create+play): 7/842
+
Adroit Jazz UndergroundMP3 320k US ♥174208 · bebop, hard bop, cool
+
101 SMOOTH JAZZMP3 128k US ♥86929 · smooth jazz, easy
+
Adroit Jazz Underground HD OpusOGG 192k US ♥67573 · avant-garde, opus
+
Jazz Radio BluesMP3 128k FR ♥62960 · blues, jazz
+
Jazz RadioMP3 192k FR ♥49272 · jazz, soul
+
Jazz Radio Classic JazzMP3 128k FR ♥27269 · classical, jazz
+
Radio Swiss JazzMP3 128k CH ♥26626 · public radio
+
Stations for “jazz”…: 
+
+ + +
3  

Marking several

+

It’s completing-read-multiple: TAB marks a row (red bullet, name stays lit), and one search can create several stations at once. Here three are marked; Enter creates all three.

+
+
Stations for “jazz” (TAB to mark, RET to create+play): 7/842
+
●Adroit Jazz UndergroundMP3 320k US ♥174208 ▶148
+
101 SMOOTH JAZZMP3 128k US ♥86929 ▶389
+
Adroit Jazz Underground HD OpusOGG 192k US ♥67573 ▶51
+
●Jazz Radio BluesMP3 128k FR ♥62960 ▶113
+
Jazz RadioMP3 192k FR ♥49272 ▶108
+
Jazz Radio Classic JazzMP3 128k FR ♥27269 ▶52
+
●Radio Swiss JazzMP3 128k CH ♥26626 ▶58
+
Stations for “jazz”…: Adroit Jazz Underground,Jazz Radio Blues,Radio Swiss Jazz
+
+ + +
4  

Created and playing

+

Each pick is written as an .m3u into the MPD playlist directory (Decision 3), then enqueued and started through mpv (Decision 4) — the search ends in sound. The echo area confirms; the three land in the playlist, the first now playing.

+
+
+
▶ Adroit Jazz Underground
+
  Jazz Radio Blues
+
  Radio Swiss Jazz
+
+
*EMMS-Playlist*Radio▶ playing
+
Created + playing 3 stations → ~/.local/share/mpd/playlists/
+
+ +
+
Two things to react to:
+
+ A — quality + popularity (codec · bitrate · country · ♥ ▶) + B — quality + tags (codec · bitrate · country · ♥ · tags) +
+

Everything else (the flow, multi-select, create-and-play into the MPD dir) matches the resolved spec. Data is a live jazz search; ♥ = radio-browser votes, ▶ = play count. This is a static mockup — no live search runs in the page.

+
+
+ + + + -- cgit v1.2.3