feat(now-playing): full artwork + metadata for every provider

Populate the OS Now Playing widget (macOS Control Center / MPRIS) with
artwork, real artist, and album for all music providers — previously it
showed a blank cover and the service name as the artist.

- Cover art: set_metadata passes thumbnail_path as a percent-encoded
  file:// URL (souvlaki feeds it to NSImage / MPMediaItemArtwork on
  macOS, the MPRIS URI on Linux). Uniform across providers.
- Stream-first SoundCloud/HypeM tracks aren't downloaded and so had no
  art; fetch their thumbnail lazily for the current track via a new
  ytdlp::fetch_thumbnail (one yt-dlp call that writes the thumbnail and
  prints the id used to name it). Done in prepare_track_for_playback so
  a playlist fetches one-at-a-time as tracks play, not all upfront.
- Local files have no embedded art: use a bundled fallback cover
  (assets/local-cover.png, embedded via include_bytes! and materialized
  into the cache) so the widget is never blank.
- Real artist: new TrackInfo.artist, joined from Spotify Track.artists
  and parsed from yt-dlp artist/creator/uploader/channel. set_metadata
  prefers it, falling back to the service name. Album is the
  playlist/album collection name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: program247365

CLAUDE.md

@@ -245,6 +245,15 @@ There are now two major UI modes:
 - a directly-requested **single** Spotify track that is unavailable is caught at
   resolve (`ensure_track_available`) so it shows the modal; unavailable tracks
   inside a playlist/album are silently dropped during concurrent metadata fetch.
+- the OS Now Playing widget (`media_controls::set_metadata`) gets title, artist
+  (real artist when the source provides one — Spotify `Track.artists`, yt-dlp
+  `artist`/`uploader`; falls back to the service name), album (the playlist/album
+  `collection`), and cover art. Cover art is passed as a percent-encoded
+  `file://` URL of `thumbnail_path` (souvlaki hands it to `NSImage` /
+  MPRIS). Stream-first SoundCloud/HypeM tracks fetch their thumbnail lazily at
+  playback via `ytdlp::fetch_thumbnail`; local files (no embedded art) use a
+  bundled fallback cover embedded from `assets/local-cover.png` via
+  `include_bytes!` and materialized into the cache, so the widget is never blank.
 - `souvlaki` is wired with the `use_zbus` feature so Linux builds don't need `libdbus-1-dev`; macOS uses `MPRemoteCommandCenter` + `MPNowPlayingInfoCenter` directly. Windows is intentionally unwired (would need a hidden message-only HWND + a per-tick `pump_event_queue`).
 
 ## Tests

assets/local-cover.png

@@ -2,6 +2,7 @@ use color_eyre::eyre::{eyre, Result};
 use souvlaki::{
     MediaControlEvent, MediaControls, MediaMetadata, MediaPlayback, MediaPosition, PlatformConfig,
 };
+use std::path::Path;
 use std::sync::{
     mpsc::{Receiver, Sender},
     Arc, Mutex,
@@ -70,10 +71,18 @@ pub struct MediaSessionHandle {
 
 impl MediaSessionHandle {
     pub fn set_metadata(&self, track: &TrackInfo) {
+        // souvlaki loads the cover via NSURL (macOS) / MPRIS URI (Linux), so the
+        // downloaded album art / thumbnail has to be handed over as a `file://`
+        // URL. `cover_url` borrows the string, so it must outlive the call.
+        let cover_url = track.thumbnail_path.as_deref().map(file_url);
         let mut controls = self.controls.lock().unwrap();
         let _ = controls.set_metadata(MediaMetadata {
             title: Some(&track.title),
-            artist: track.service.as_deref(),
+            // Real artist when the source gave us one; otherwise the service
+            // name so the widget subtitle is never empty.
+            artist: track.artist.as_deref().or(track.service.as_deref()),
+            album: track.collection.as_deref(),
+            cover_url: cover_url.as_deref(),
             duration: track.duration_secs.map(Duration::from_secs_f64),
             ..Default::default()
         });
@@ -94,3 +103,43 @@ impl MediaSessionHandle {
         let _ = controls.set_playback(state);
     }
 }
+
+/// Build a `file://` URL for a local path. souvlaki passes `cover_url` straight
+/// to `NSURL URLWithString:` (macOS) / a MPRIS URI (Linux), both of which need a
+/// percent-encoded URL — so a raw path with spaces would silently fail to load.
+/// Keeps RFC 3986 unreserved characters and `/`, percent-encodes everything else
+/// per UTF-8 byte.
+fn file_url(path: &Path) -> String {
+    let mut url = String::from("file://");
+    for byte in path.to_string_lossy().bytes() {
+        match byte {
+            b'/' | b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
+                url.push(byte as char)
+            }
+            _ => url.push_str(&format!("%{byte:02X}")),
+        }
+    }
+    url
+}
+
+#[cfg(test)]
+mod tests {
+    use super::file_url;
+    use std::path::Path;
+
+    #[test]
+    fn encodes_spaces_and_keeps_slashes() {
+        assert_eq!(
+            file_url(Path::new("/Users/First Last/art/a b.jpg")),
+            "file:///Users/First%20Last/art/a%20b.jpg"
+        );
+    }
+
+    #[test]
+    fn leaves_plain_paths_untouched() {
+        assert_eq!(
+            file_url(Path::new("/Users/kevin/Library/Caches/sh.kbr.looper/spotify/art/ab12.jpg")),
+            "file:///Users/kevin/Library/Caches/sh.kbr.looper/spotify/art/ab12.jpg"
+        );
+    }
+}

assets/local-cover.svg

@@ -179,6 +179,19 @@ fn browse_history_session(
     }
 }
 
+/// Path to the bundled fallback album cover for local files, which have no
+/// embedded art. The PNG is embedded in the binary and materialized into the
+/// cache on first use, so a Homebrew-installed binary needs no external asset.
+/// Best-effort: `None` if it can't be written (then the cover is simply blank).
+fn local_file_cover() -> Option<std::path::PathBuf> {
+    const COVER: &[u8] = include_bytes!("../assets/local-cover.png");
+    let path = plugin::cache_dir_path().ok()?.join("local-cover.png");
+    if !path.exists() {
+        std::fs::write(&path, COVER).ok()?;
+    }
+    Some(path)
+}
+
 fn play_file_session(
     terminal: &mut ratatui::Terminal<ratatui::backend::CrosstermBackend<std::io::Stdout>>,
     title_state: &mut TitleState,
@@ -231,9 +244,12 @@ fn play_file_session(
                     source_url: None,
                     pending_download: None,
                     service: None,
-                    thumbnail_path: None,
+                    // Local files have no embedded art; use the bundled fallback
+                    // cover so the macOS Now Playing widget is never blank.
+                    thumbnail_path: local_file_cover(),
                     is_live: false,
                     collection: None,
+                    artist: None,
                 }],
                 false,
                 ctx,
@@ -1355,6 +1371,23 @@ fn prepare_track_for_playback(
         }
     }
 
+    // Stream-first tracks (SoundCloud/HypeM) are never downloaded, so the
+    // cached-file backfill above never runs and they'd have no artwork. Fetch
+    // the thumbnail lazily for the current track only (not every track in a
+    // playlist upfront). Spotify and YouTube-live already carry their art.
+    if track.thumbnail_path.is_none()
+        && matches!(
+            track.playback,
+            PlaybackInput::HttpStream { .. } | PlaybackInput::ProcessStdout { .. }
+        )
+    {
+        if let Some(source_url) = track.source_url.clone() {
+            if let Ok(cache_dir) = plugin::cache_dir_path() {
+                track.thumbnail_path = ytdlp::fetch_thumbnail(&source_url, &cache_dir);
+            }
+        }
+    }
+
     let Some(pending) = track.pending_download.clone() else {
         return Ok(false);
     };

src/media_controls.rs

@@ -27,6 +27,9 @@ pub struct TrackInfo {
     /// Name of the playlist or album this track was resolved from, if any.
     /// Shown in the playback header so you know what collection is playing.
     pub collection: Option<String>,
+    /// Performing artist(s), when the source provides them. Surfaced in the OS
+    /// Now Playing widget; falls back to the service name when absent.
+    pub artist: Option<String>,
 }
 
 pub trait ServicePlugin {

src/play_loop.rs

@@ -15,6 +15,7 @@ use super::TrackInfo;
 pub struct MetadataEntry {
     pub id: String,
     pub title: String,
+    pub artist: Option<String>,
     pub duration_secs: Option<f64>,
     pub webpage_url: String,
     pub live_status: LiveStatus,
@@ -92,6 +93,7 @@ pub fn cached_track_from_entry(entry: MetadataEntry, cache_dir: &Path, service:
         thumbnail_path,
         is_live: false,
         collection: None,
+        artist: entry.artist,
     }
 }
 
@@ -107,6 +109,7 @@ pub fn streaming_track_from_entry(entry: MetadataEntry, service: &str) -> Result
         thumbnail_path: None,
         is_live: matches!(entry.live_status, LiveStatus::IsLive),
         collection: None,
+        artist: entry.artist,
     })
 }
 
@@ -132,6 +135,7 @@ pub fn resolve_streaming_tracks(url: &str) -> Result<Vec<TrackInfo>> {
                 thumbnail_path: None,
                 is_live,
                 collection: None,
+                artist: entry.artist,
             })
         })
         .collect()
@@ -232,6 +236,38 @@ pub fn download_thumbnail_only(url: &str, cache_dir: &Path) -> Result<()> {
     Ok(())
 }
 
+/// Fetch a track's thumbnail and return its cached path. One yt-dlp call both
+/// writes the thumbnail (named `<id>.jpg`) and prints the id used to name it, so
+/// callers don't need to know the id ahead of time. Best-effort: `None` on any
+/// failure. Used to lazily backfill artwork for stream-first tracks
+/// (SoundCloud/HypeM), which are never downloaded.
+pub fn fetch_thumbnail(url: &str, cache_dir: &Path) -> Option<PathBuf> {
+    let output_template = cache_dir.join("%(id)s.%(ext)s");
+    let output = Command::new("yt-dlp")
+        .arg("--skip-download")
+        .arg("--write-thumbnail")
+        .arg("--convert-thumbnails")
+        .arg("jpg")
+        .arg("--no-playlist")
+        .arg("--no-warnings")
+        .arg("--print")
+        .arg("id")
+        .arg("-o")
+        .arg(&output_template)
+        .arg(url)
+        .stderr(Stdio::null())
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let id = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    if id.is_empty() {
+        return None;
+    }
+    thumbnail_for(cache_dir, &id)
+}
+
 pub fn download_track_with_progress(
     url: &str,
     cache_dir: &Path,
@@ -365,6 +401,9 @@ fn parse_entry(value: Value, fallback_url: &str) -> Result<MetadataEntry> {
         .map(sanitize_id)
         .unwrap_or_else(|| sanitize_id(&title));
 
+    let artist = first_str(&value, &["artist", "creator", "uploader", "channel"])
+        .map(str::to_string)
+        .filter(|s| !s.is_empty());
     let duration_secs = value.get("duration").and_then(Value::as_f64);
     let webpage_url = youtube_watch_url(&value)
         .or_else(|| {
@@ -382,6 +421,7 @@ fn parse_entry(value: Value, fallback_url: &str) -> Result<MetadataEntry> {
     Ok(MetadataEntry {
         id,
         title,
+        artist,
         duration_secs,
         webpage_url,
         live_status,

src/plugin/mod.rs

@@ -141,6 +141,18 @@ fn track_info(
     collection: Option<String>,
     thumbnail_path: Option<PathBuf>,
 ) -> TrackInfo {
+    let artist = if track.artists.is_empty() {
+        None
+    } else {
+        Some(
+            track
+                .artists
+                .iter()
+                .map(|a| a.name.clone())
+                .collect::<Vec<_>>()
+                .join(", "),
+        )
+    };
     TrackInfo {
         title: track.name,
         duration_secs: Some((track.duration.max(0) as f64) / 1000.0),
@@ -151,6 +163,7 @@ fn track_info(
         thumbnail_path,
         is_live: false,
         collection,
+        artist,
     }
 }