CORE: Improve media paths and player reliability

Cargo.lock

@@ -1418,7 +1418,7 @@ checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
 
 [[package]]
 name = "furumusic"
-version = "0.1.21"
+version = "0.1.22"
 dependencies = [
  "anyhow",
  "async-trait",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "furumusic"
-version = "0.1.21"
+version = "0.2.0"
 edition = "2024"
 description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
 

src/agent/cover_art.rs

@@ -3,6 +3,7 @@
 //! Sources (in priority order):
 //! 1. Standalone image files in the album folder (cover.jpg, folder.jpg, etc.)
 //! 2. Embedded cover art in audio file metadata (ID3 APIC, Vorbis METADATA_BLOCK_PICTURE, etc.)
+//! 3. Remote metadata providers used by background backfill jobs.
 //!
 //! The first usable image found is saved as a MediaFile with file_type="cover_art"
 //! and linked to the Release via cover_file_id.
@@ -26,6 +27,8 @@ pub enum CoverSource {
     FolderFile(PathBuf),
     /// Embedded in an audio file's metadata.
     Embedded(PathBuf),
+    /// Downloaded from a remote metadata provider.
+    Remote(String),
 }
 
 /// Well-known cover art filenames, in priority order.
@@ -335,12 +338,7 @@ pub async fn save_cover_to_storage(
         .fetch_optional(pool)
         .await?
         {
-            let path = PathBuf::from(&file_path);
-            let path = if path.is_absolute() {
-                path
-            } else {
-                Path::new(storage_dir).join(path)
-            };
+            let path = crate::media_paths::resolve_media_file_path(storage_dir, &file_path);
             if let Err(err) = crate::agent::cover_variants::ensure_cover_variants(&path).await {
                 tracing::warn!(media_file_id = id, error = %err, "Failed to generate cover variants");
             }
@@ -362,7 +360,13 @@ pub async fn save_cover_to_storage(
     // Write image data
     tokio::fs::write(&dest_path, &cover.data).await?;
 
-    let relative_path = dest_path.to_string_lossy().to_string();
+    let relative_path = crate::media_paths::media_file_path_for_storage(storage_dir, &dest_path)
+        .ok_or_else(|| {
+            anyhow::anyhow!(
+                "cover destination is outside agent_storage_dir: {}",
+                dest_path.display()
+            )
+        })?;
     let file_size = cover.data.len() as i64;
 
     let media_file = crate::music::MediaFile::create(

src/config.rs

@@ -329,8 +329,8 @@ impl_env_overrides!(
 
 impl AppConfig {
     fn normalize_host_paths(&mut self) {
-        self.agent_inbox_dir = normalize_host_path(&self.agent_inbox_dir);
-        self.agent_storage_dir = normalize_host_path(&self.agent_storage_dir);
+        self.agent_inbox_dir = crate::media_paths::resolve_config_path(&self.agent_inbox_dir);
+        self.agent_storage_dir = crate::media_paths::resolve_config_path(&self.agent_storage_dir);
     }
 
     /// Build config: start from defaults, then overlay env vars.
@@ -413,44 +413,6 @@ impl AppConfig {
     }
 }
 
-fn normalize_host_path(value: &str) -> String {
-    let trimmed = value.trim();
-    if trimmed.is_empty() {
-        return String::new();
-    }
-
-    normalize_windows_user_path(trimmed).unwrap_or_else(|| trimmed.to_owned())
-}
-
-#[cfg(not(windows))]
-fn normalize_windows_user_path(value: &str) -> Option<String> {
-    let normalized = value.replace('\\', "/");
-    let mut parts = normalized.split('/').filter(|part| !part.is_empty());
-    let drive = parts.next()?;
-    if drive.len() != 2 || !drive.ends_with(':') {
-        return None;
-    }
-    if !parts.next()?.eq_ignore_ascii_case("Users") {
-        return None;
-    }
-    let user = parts.next()?;
-    if user.is_empty() {
-        return None;
-    }
-
-    let mut out = format!("/Users/{user}");
-    for part in parts {
-        out.push('/');
-        out.push_str(part);
-    }
-    Some(out)
-}
-
-#[cfg(windows)]
-fn normalize_windows_user_path(_value: &str) -> Option<String> {
-    None
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -462,21 +424,31 @@ mod tests {
         assert_eq!(cfg.log_level, "info");
     }
 
-    #[cfg(not(windows))]
     #[test]
-    fn normalizes_windows_user_path_on_unix() {
+    fn resolves_relative_media_paths_from_working_dir() {
+        let expected = std::env::current_dir()
+            .unwrap()
+            .join("media")
+            .join("uploads")
+            .to_string_lossy()
+            .to_string();
         assert_eq!(
-            normalize_host_path(r"C:\Users\ab\repos\furumusic\media\uploads"),
-            "/Users/ab/repos/furumusic/media/uploads"
+            crate::media_paths::resolve_config_path("media/uploads"),
+            expected
         );
     }
 
-    #[cfg(not(windows))]
     #[test]
-    fn leaves_unix_path_unchanged() {
+    fn maps_foreign_windows_media_paths_to_working_dir() {
+        let expected = std::env::current_dir()
+            .unwrap()
+            .join("media")
+            .join("uploads")
+            .to_string_lossy()
+            .to_string();
         assert_eq!(
-            normalize_host_path("/Users/ab/repos/furumusic/media/uploads"),
-            "/Users/ab/repos/furumusic/media/uploads"
+            crate::media_paths::resolve_config_path(r"C:\Users\ab\repos\furumusic\media\uploads"),
+            expected
         );
     }
 

src/i18n/phrases.rs

@@ -296,6 +296,8 @@ translations! {
     player_likes_playlist:   "Likes"                           , "Лайки";
     player_listened:         "listened"                        , "прослушано";
     player_search_placeholder: "Search artists, releases, tracks..." , "Поиск артистов, релизов, треков...";
+    player_connection_lost: "Server connection lost"             , "Нет соединения с сервером";
+    player_connection_lost_detail: "Player cannot reach the server. Retrying..." , "Плеер не может связаться с сервером. Повторяю...";
     player_no_results:       "No results found"                , "Ничего не найдено";
     player_new_playlist:     "New Playlist"                    , "Новый плейлист";
     player_rename_playlist:  "Rename Playlist"                 , "Переименовать плейлист";

src/jobs/artist_image_backfill.rs

@@ -1,60 +0,0 @@
-use crate::scheduler::{Job, JobContext, JobLog};
-
-/// Periodic job that auto-assigns artist images from their release covers.
-///
-/// For every artist that has no `image_file_id`, picks the cover of the most
-/// recent release (by year) that has one. Runs after the cover backfill job
-/// so freshly-extracted covers are available.
-pub struct ArtistImageBackfillJob;
-
-#[async_trait::async_trait]
-impl Job for ArtistImageBackfillJob {
-    fn name(&self) -> &'static str {
-        "artist_image_backfill"
-    }
-
-    fn description(&self) -> &'static str {
-        "Auto-assign artist images from release covers"
-    }
-
-    fn default_cron(&self) -> &'static str {
-        // 03:15 daily — after cover_backfill at 03:00
-        "0 15 3 * * *"
-    }
-
-    async fn run(&self, ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
-        let result = sqlx::query(
-            "UPDATE furumusic__artist a \
-             SET image_file_id = ( \
-                 SELECT r.cover_file_id \
-                 FROM furumusic__release_artist ra \
-                 JOIN furumusic__release r ON r.id = ra.release_id \
-                 WHERE ra.artist_id = a.id \
-                   AND r.cover_file_id IS NOT NULL \
-                 ORDER BY r.year DESC NULLS LAST \
-                 LIMIT 1 \
-             ), \
-             updated_at = $1 \
-             WHERE a.image_file_id IS NULL \
-               AND EXISTS ( \
-                   SELECT 1 FROM furumusic__release_artist ra2 \
-                   JOIN furumusic__release r2 ON r2.id = ra2.release_id \
-                   WHERE ra2.artist_id = a.id AND r2.cover_file_id IS NOT NULL \
-               )",
-        )
-        .bind(chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string())
-        .execute(&ctx.pool)
-        .await?;
-
-        let count = result.rows_affected();
-        if count > 0 {
-            log.info(&format!(
-                "Assigned images to {count} artists from release covers"
-            ));
-        } else {
-            log.info("All artists already have images (or no covers available)");
-        }
-
-        Ok(())
-    }
-}

src/jobs/artist_track_image_backfill.rs

@@ -1,69 +0,0 @@
-use crate::scheduler::{Job, JobContext, JobLog};
-
-/// Fallback job that assigns artist images from track cover art.
-///
-/// The primary `artist_image_backfill` job uses release covers.  This job
-/// runs afterwards and covers the case where the release itself has no
-/// cover but individual tracks do (e.g. when cover art is embedded in the
-/// audio file and extracted per-track rather than per-release).
-///
-/// For every artist that *still* has no `image_file_id` after the release-
-/// based backfill, picks the `cover_file_id` of the most recent track
-/// (by year, then track id) that has one.
-pub struct ArtistTrackImageBackfillJob;
-
-#[async_trait::async_trait]
-impl Job for ArtistTrackImageBackfillJob {
-    fn name(&self) -> &'static str {
-        "artist_track_image_backfill"
-    }
-
-    fn description(&self) -> &'static str {
-        "Auto-assign artist images from track covers (fallback)"
-    }
-
-    fn default_cron(&self) -> &'static str {
-        // 03:30 daily — after artist_image_backfill at 03:15
-        "0 30 3 * * *"
-    }
-
-    async fn run(&self, ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
-        let result = sqlx::query(
-            "UPDATE furumusic__artist a \
-             SET image_file_id = ( \
-                 SELECT t.cover_file_id \
-                 FROM furumusic__track_artist ta \
-                 JOIN furumusic__track t ON t.id = ta.track_id \
-                 WHERE ta.artist_id = a.id \
-                   AND t.cover_file_id IS NOT NULL \
-                   AND t.is_hidden = false \
-                 ORDER BY t.year DESC NULLS LAST, t.id DESC \
-                 LIMIT 1 \
-             ), \
-             updated_at = $1 \
-             WHERE a.image_file_id IS NULL \
-               AND a.is_hidden = false \
-               AND EXISTS ( \
-                   SELECT 1 FROM furumusic__track_artist ta2 \
-                   JOIN furumusic__track t2 ON t2.id = ta2.track_id \
-                   WHERE ta2.artist_id = a.id \
-                     AND t2.cover_file_id IS NOT NULL \
-                     AND t2.is_hidden = false \
-               )",
-        )
-        .bind(chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string())
-        .execute(&ctx.pool)
-        .await?;
-
-        let count = result.rows_affected();
-        if count > 0 {
-            log.info(&format!(
-                "Assigned images to {count} artists from track covers"
-            ));
-        } else {
-            log.info("All artists already have images (or no track covers available)");
-        }
-
-        Ok(())
-    }
-}

src/jobs/artwork_backfill.rs

@@ -0,0 +1,965 @@
+use std::path::PathBuf;
+
+use reqwest::Client;
+use serde::Deserialize;
+
+use crate::agent::cover_art::{self, CoverImage, CoverSource};
+use crate::agent::cover_variants;
+use crate::scheduler::{Job, JobContext, JobLog};
+
+pub struct ArtworkBackfillJob;
+
+const LASTFM_REQUEST_DELAY: std::time::Duration = std::time::Duration::from_millis(1200);
+const MAX_LASTFM_RELEASE_LOOKUPS: i64 = 200;
+const MAX_LASTFM_ARTIST_LOOKUPS: i64 = 200;
+
+#[derive(Debug, sqlx::FromRow)]
+struct ReleaseCandidate {
+    id: i64,
+    title: String,
+    artist_name: Option<String>,
+}
+
+#[derive(Debug, sqlx::FromRow)]
+struct ArtistCandidate {
+    id: i64,
+    name: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct LastfmAlbumResponse {
+    album: Option<LastfmImageContainer>,
+    error: Option<i32>,
+    message: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct LastfmArtistResponse {
+    artist: Option<LastfmImageContainer>,
+    error: Option<i32>,
+    message: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct LastfmImageContainer {
+    image: Option<Vec<LastfmImage>>,
+}
+
+#[derive(Debug, Deserialize)]
+struct LastfmImage {
+    #[serde(rename = "#text")]
+    url: String,
+    size: String,
+}
+
+#[derive(Default)]
+struct ArtworkStats {
+    release_local_assigned: u64,
+    release_lastfm_assigned: u64,
+    release_lastfm_not_found: u64,
+    release_skipped_no_audio: u64,
+    artist_lastfm_assigned: u64,
+    artist_lastfm_not_found: u64,
+    artist_album_fallback_assigned: u64,
+    variants_created: usize,
+    variants_unchanged: usize,
+    variants_missing_original: usize,
+    failed: u64,
+}
+
+#[async_trait::async_trait]
+impl Job for ArtworkBackfillJob {
+    fn name(&self) -> &'static str {
+        "artwork_backfill"
+    }
+
+    fn description(&self) -> &'static str {
+        "Backfill and repair release, track, and artist artwork"
+    }
+
+    fn default_cron(&self) -> &'static str {
+        // Nightly, after inbox processing has had a chance to import new files.
+        "0 30 3 * * *"
+    }
+
+    async fn run(&self, ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
+        let storage_dir = ctx.config.agent_storage_dir.trim();
+        if storage_dir.is_empty() {
+            log.warn("agent_storage_dir is not configured, skipping artwork backfill");
+            return Ok(());
+        }
+
+        let client = Client::builder()
+            .user_agent(format!(
+                "furumusic-artwork-backfill/{}",
+                env!("CARGO_PKG_VERSION")
+            ))
+            .timeout(std::time::Duration::from_secs(20))
+            .build()?;
+        let mut stats = ArtworkStats::default();
+
+        let normalized_paths =
+            crate::media_paths::normalize_media_file_paths(&ctx.pool, storage_dir).await?;
+        if normalized_paths > 0 {
+            log.info(&format!(
+                "Media path normalization pass: rewrote {normalized_paths} media file path(s) to relative storage paths"
+            ));
+        } else {
+            log.info("Media path normalization pass: all media file paths are already relative");
+        }
+
+        backfill_release_local(ctx, log, storage_dir, &mut stats).await?;
+
+        let api_key = ctx.config.lastfm_api_key.trim();
+        if api_key.is_empty() {
+            log.warn("lastfm_api_key is not configured; skipping Last.fm artwork fallback");
+        } else {
+            backfill_release_lastfm(ctx, log, storage_dir, api_key, &client, &mut stats).await?;
+            backfill_artist_lastfm(ctx, log, storage_dir, api_key, &client, &mut stats).await?;
+        }
+
+        repair_cover_variants(ctx, log, storage_dir, &mut stats).await?;
+
+        log.info(&format!(
+            "Artwork backfill complete: release_local_assigned={}, release_lastfm_assigned={}, release_lastfm_not_found={}, release_skipped_no_audio={}, artist_lastfm_assigned={}, artist_lastfm_not_found={}, artist_album_fallback_assigned={}, variants_created={}, variants_unchanged={}, variants_missing_original={}, failed={}",
+            stats.release_local_assigned,
+            stats.release_lastfm_assigned,
+            stats.release_lastfm_not_found,
+            stats.release_skipped_no_audio,
+            stats.artist_lastfm_assigned,
+            stats.artist_lastfm_not_found,
+            stats.artist_album_fallback_assigned,
+            stats.variants_created,
+            stats.variants_unchanged,
+            stats.variants_missing_original,
+            stats.failed
+        ));
+        Ok(())
+    }
+}
+
+async fn backfill_release_local(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let releases = sqlx::query_as::<_, ReleaseCandidate>(
+        r#"SELECT r.id,
+                  r.title::text AS title,
+                  (
+                    SELECT a.name::text
+                      FROM furumusic__release_artist ra
+                      JOIN furumusic__artist a ON a.id = ra.artist_id
+                     WHERE ra.release_id = r.id
+                     ORDER BY ra.position
+                     LIMIT 1
+                  ) AS artist_name
+             FROM furumusic__release r
+            WHERE r.cover_file_id IS NULL
+              AND r.is_hidden = false
+            ORDER BY r.id"#,
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    if releases.is_empty() {
+        log.info("Release local artwork pass: all visible releases already have covers");
+        return Ok(());
+    }
+    log.info(&format!(
+        "Release local artwork pass: checking {} release(s) without covers",
+        releases.len()
+    ));
+
+    for (index, release) in releases.iter().enumerate() {
+        log.info(&format!(
+            "Release local artwork {}/{}: release {} \"{}\"",
+            index + 1,
+            releases.len(),
+            release.id,
+            release.title
+        ));
+
+        let audio_paths: Vec<String> = sqlx::query_scalar(
+            r#"SELECT mf.file_path::text
+                 FROM furumusic__track t
+                 JOIN furumusic__media_file mf ON mf.id = t.audio_file_id
+                WHERE t.release_id = $1
+                  AND mf.file_type = 'audio'
+                ORDER BY t.disc_number NULLS LAST, t.track_number NULLS LAST, t.id"#,
+        )
+        .bind(release.id)
+        .fetch_all(&ctx.pool)
+        .await
+        .unwrap_or_default();
+
+        if audio_paths.is_empty() {
+            stats.release_skipped_no_audio += 1;
+            log.warn(&format!(
+                "Release {} \"{}\": no audio files found for local cover extraction",
+                release.id, release.title
+            ));
+            continue;
+        }
+
+        let audio_files: Vec<PathBuf> = audio_paths
+            .iter()
+            .map(|path| crate::media_paths::resolve_media_file_path(storage_dir, path))
+            .collect();
+        let Some(folder) = audio_files.first().and_then(|path| path.parent()) else {
+            stats.failed += 1;
+            log.warn(&format!(
+                "Release {} \"{}\": could not determine audio folder",
+                release.id, release.title
+            ));
+            continue;
+        };
+
+        let Some(cover) = cover_art::find_best_cover(folder, &audio_files).await else {
+            continue;
+        };
+
+        let source_desc = cover_source_description(&cover.source);
+        let artist_name = release.artist_name.as_deref().unwrap_or("Unknown Artist");
+        match cover_art::save_cover_to_storage(
+            &ctx.db,
+            &ctx.pool,
+            storage_dir,
+            artist_name,
+            &release.title,
+            &cover,
+        )
+        .await
+        {
+            Ok(cover_file_id) => {
+                cover_art::assign_cover_to_release(&ctx.pool, release.id, cover_file_id).await?;
+                stats.release_local_assigned += 1;
+                log.info(&format!(
+                    "Release {} \"{}\": assigned local cover from {source_desc}",
+                    release.id, release.title
+                ));
+            }
+            Err(err) => {
+                stats.failed += 1;
+                log.warn(&format!(
+                    "Release {} \"{}\": failed to save local cover: {err}",
+                    release.id, release.title
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn backfill_release_lastfm(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    api_key: &str,
+    client: &Client,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let failed_cutoff = cutoff_iso(1);
+    let not_found_cutoff = cutoff_iso(30);
+    let releases = sqlx::query_as::<_, ReleaseCandidate>(
+        r#"SELECT r.id,
+                  r.title::text AS title,
+                  COALESCE(
+                    (
+                      SELECT a.name::text
+                        FROM furumusic__release_artist ra
+                        JOIN furumusic__artist a ON a.id = ra.artist_id
+                       WHERE ra.release_id = r.id
+                       ORDER BY ra.position
+                       LIMIT 1
+                    ),
+                    (
+                      SELECT a.name::text
+                        FROM furumusic__track t
+                        JOIN furumusic__track_artist ta ON ta.track_id = t.id
+                        JOIN furumusic__artist a ON a.id = ta.artist_id
+                       WHERE t.release_id = r.id AND ta.role <> 'featuring'
+                       ORDER BY t.disc_number NULLS LAST, t.track_number NULLS LAST, ta.position
+                       LIMIT 1
+                    )
+                  ) AS artist_name
+             FROM furumusic__release r
+             LEFT JOIN furumusic__artwork_lookup_state s
+               ON s.entity_kind = 'release'
+              AND s.entity_id = r.id
+              AND s.source = 'lastfm'
+            WHERE r.cover_file_id IS NULL
+              AND r.is_hidden = false
+              AND (
+                    s.entity_id IS NULL
+                 OR s.status = 'failed' AND s.last_attempt_at < $1
+                 OR s.status = 'not_found' AND (s.attempt_count < 3 OR s.last_attempt_at < $2)
+                 OR s.status = 'found' AND s.last_attempt_at < $1
+              )
+            ORDER BY s.last_attempt_at NULLS FIRST, r.id
+            LIMIT $3"#,
+    )
+    .bind(&failed_cutoff)
+    .bind(&not_found_cutoff)
+    .bind(MAX_LASTFM_RELEASE_LOOKUPS)
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    if releases.is_empty() {
+        log.info("Release Last.fm artwork pass: no eligible releases need lookup");
+        return Ok(());
+    }
+    log.info(&format!(
+        "Release Last.fm artwork pass: looking up {} release(s)",
+        releases.len()
+    ));
+
+    for (index, release) in releases.iter().enumerate() {
+        let Some(artist_name) = release
+            .artist_name
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        else {
+            stats.release_lastfm_not_found += 1;
+            record_lookup_state(
+                &ctx.pool,
+                "release",
+                release.id,
+                "not_found",
+                Some("release has no primary artist for Last.fm lookup"),
+                None,
+            )
+            .await?;
+            log.warn(&format!(
+                "Release {} \"{}\": no primary artist for Last.fm lookup",
+                release.id, release.title
+            ));
+            continue;
+        };
+
+        log.info(&format!(
+            "Release Last.fm artwork {}/{}: release {} \"{}\" by \"{}\"",
+            index + 1,
+            releases.len(),
+            release.id,
+            release.title,
+            artist_name
+        ));
+
+        match fetch_lastfm_album_image(client, api_key, artist_name, &release.title).await {
+            Ok(Some(image_url)) => match download_remote_cover(client, &image_url).await {
+                Ok(cover) => match cover_art::save_cover_to_storage(
+                    &ctx.db,
+                    &ctx.pool,
+                    storage_dir,
+                    artist_name,
+                    &release.title,
+                    &cover,
+                )
+                .await
+                {
+                    Ok(cover_file_id) => {
+                        cover_art::assign_cover_to_release(&ctx.pool, release.id, cover_file_id)
+                            .await?;
+                        record_lookup_state(
+                            &ctx.pool,
+                            "release",
+                            release.id,
+                            "found",
+                            None,
+                            Some(&image_url),
+                        )
+                        .await?;
+                        stats.release_lastfm_assigned += 1;
+                        log.info(&format!(
+                            "Release {} \"{}\": assigned Last.fm cover",
+                            release.id, release.title
+                        ));
+                    }
+                    Err(err) => {
+                        stats.failed += 1;
+                        record_lookup_state(
+                            &ctx.pool,
+                            "release",
+                            release.id,
+                            "failed",
+                            Some(&err.to_string()),
+                            Some(&image_url),
+                        )
+                        .await?;
+                        log.warn(&format!(
+                            "Release {} \"{}\": failed to save Last.fm cover: {err}",
+                            release.id, release.title
+                        ));
+                    }
+                },
+                Err(err) => {
+                    stats.failed += 1;
+                    record_lookup_state(
+                        &ctx.pool,
+                        "release",
+                        release.id,
+                        "failed",
+                        Some(&err.to_string()),
+                        Some(&image_url),
+                    )
+                    .await?;
+                    log.warn(&format!(
+                        "Release {} \"{}\": failed to download Last.fm cover: {err}",
+                        release.id, release.title
+                    ));
+                }
+            },
+            Ok(None) => {
+                stats.release_lastfm_not_found += 1;
+                record_lookup_state(&ctx.pool, "release", release.id, "not_found", None, None)
+                    .await?;
+                log.info(&format!(
+                    "Release {} \"{}\": Last.fm did not return artwork",
+                    release.id, release.title
+                ));
+            }
+            Err(err) if err.to_string().contains("rate limit") => {
+                stats.failed += 1;
+                record_lookup_state(
+                    &ctx.pool,
+                    "release",
+                    release.id,
+                    "failed",
+                    Some(&err.to_string()),
+                    None,
+                )
+                .await?;
+                log.error(
+                    "Last.fm rate limit exceeded during release artwork lookup; stopping this pass",
+                );
+                break;
+            }
+            Err(err) => {
+                stats.failed += 1;
+                record_lookup_state(
+                    &ctx.pool,
+                    "release",
+                    release.id,
+                    "failed",
+                    Some(&err.to_string()),
+                    None,
+                )
+                .await?;
+                log.warn(&format!(
+                    "Release {} \"{}\": Last.fm artwork lookup failed: {err}",
+                    release.id, release.title
+                ));
+            }
+        }
+
+        tokio::time::sleep(LASTFM_REQUEST_DELAY).await;
+    }
+
+    Ok(())
+}
+
+async fn backfill_artist_lastfm(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    api_key: &str,
+    client: &Client,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let failed_cutoff = cutoff_iso(1);
+    let not_found_cutoff = cutoff_iso(30);
+    let artists = sqlx::query_as::<_, ArtistCandidate>(
+        r#"SELECT a.id, a.name::text AS name
+             FROM furumusic__artist a
+             LEFT JOIN furumusic__artwork_lookup_state s
+               ON s.entity_kind = 'artist'
+              AND s.entity_id = a.id
+              AND s.source = 'lastfm'
+            WHERE a.image_file_id IS NULL
+              AND a.is_hidden = false
+              AND (
+                    s.entity_id IS NULL
+                 OR s.status = 'failed' AND s.last_attempt_at < $1
+                 OR s.status = 'not_found' AND (s.attempt_count < 3 OR s.last_attempt_at < $2)
+                 OR s.status = 'found' AND s.last_attempt_at < $1
+              )
+            ORDER BY s.last_attempt_at NULLS FIRST, a.id
+            LIMIT $3"#,
+    )
+    .bind(&failed_cutoff)
+    .bind(&not_found_cutoff)
+    .bind(MAX_LASTFM_ARTIST_LOOKUPS)
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    if artists.is_empty() {
+        log.info("Artist Last.fm artwork pass: no eligible artists need lookup");
+        return Ok(());
+    }
+    log.info(&format!(
+        "Artist Last.fm artwork pass: looking up {} artist(s)",
+        artists.len()
+    ));
+
+    for (index, artist) in artists.iter().enumerate() {
+        log.info(&format!(
+            "Artist Last.fm artwork {}/{}: artist {} \"{}\"",
+            index + 1,
+            artists.len(),
+            artist.id,
+            artist.name
+        ));
+
+        match fetch_lastfm_artist_image(client, api_key, &artist.name).await {
+            Ok(Some(image_url)) => match download_remote_cover(client, &image_url).await {
+                Ok(cover) => match cover_art::save_cover_to_storage(
+                    &ctx.db,
+                    &ctx.pool,
+                    storage_dir,
+                    &artist.name,
+                    "__artist_image__",
+                    &cover,
+                )
+                .await
+                {
+                    Ok(image_file_id) => {
+                        sqlx::query(
+                            r#"UPDATE furumusic__artist
+                                      SET image_file_id = $1,
+                                          updated_at = $3
+                                    WHERE id = $2
+                                      AND image_file_id IS NULL"#,
+                        )
+                        .bind(image_file_id)
+                        .bind(artist.id)
+                        .bind(now_iso())
+                        .execute(&ctx.pool)
+                        .await?;
+                        record_lookup_state(
+                            &ctx.pool,
+                            "artist",
+                            artist.id,
+                            "found",
+                            None,
+                            Some(&image_url),
+                        )
+                        .await?;
+                        stats.artist_lastfm_assigned += 1;
+                        log.info(&format!(
+                            "Artist {} \"{}\": assigned Last.fm image",
+                            artist.id, artist.name
+                        ));
+                    }
+                    Err(err) => {
+                        stats.failed += 1;
+                        record_lookup_state(
+                            &ctx.pool,
+                            "artist",
+                            artist.id,
+                            "failed",
+                            Some(&err.to_string()),
+                            Some(&image_url),
+                        )
+                        .await?;
+                        log.warn(&format!(
+                            "Artist {} \"{}\": failed to save Last.fm image: {err}",
+                            artist.id, artist.name
+                        ));
+                    }
+                },
+                Err(err) => {
+                    stats.failed += 1;
+                    record_lookup_state(
+                        &ctx.pool,
+                        "artist",
+                        artist.id,
+                        "failed",
+                        Some(&err.to_string()),
+                        Some(&image_url),
+                    )
+                    .await?;
+                    log.warn(&format!(
+                        "Artist {} \"{}\": failed to download Last.fm image: {err}",
+                        artist.id, artist.name
+                    ));
+                }
+            },
+            Ok(None) => {
+                record_lookup_state(&ctx.pool, "artist", artist.id, "not_found", None, None)
+                    .await?;
+                log.info(&format!(
+                    "Artist {} \"{}\": Last.fm did not return artwork",
+                    artist.id, artist.name
+                ));
+                stats.artist_lastfm_not_found += 1;
+                match assign_artist_album_fallback(ctx, artist.id).await {
+                    Ok(Some(media_file_id)) => {
+                        stats.artist_album_fallback_assigned += 1;
+                        log.info(&format!(
+                            "Artist {} \"{}\": assigned random local album cover (media_file_id={media_file_id})",
+                            artist.id, artist.name
+                        ));
+                    }
+                    Ok(None) => {
+                        log.info(&format!(
+                            "Artist {} \"{}\": no local album cover available for fallback",
+                            artist.id, artist.name
+                        ));
+                    }
+                    Err(err) => {
+                        stats.failed += 1;
+                        log.warn(&format!(
+                            "Artist {} \"{}\": failed to assign album fallback artwork: {err}",
+                            artist.id, artist.name
+                        ));
+                    }
+                }
+            }
+            Err(err) if err.to_string().contains("rate limit") => {
+                stats.failed += 1;
+                record_lookup_state(
+                    &ctx.pool,
+                    "artist",
+                    artist.id,
+                    "failed",
+                    Some(&err.to_string()),
+                    None,
+                )
+                .await?;
+                log.error(
+                    "Last.fm rate limit exceeded during artist artwork lookup; stopping this pass",
+                );
+                break;
+            }
+            Err(err) => {
+                stats.failed += 1;
+                record_lookup_state(
+                    &ctx.pool,
+                    "artist",
+                    artist.id,
+                    "failed",
+                    Some(&err.to_string()),
+                    None,
+                )
+                .await?;
+                log.warn(&format!(
+                    "Artist {} \"{}\": Last.fm artwork lookup failed: {err}",
+                    artist.id, artist.name
+                ));
+            }
+        }
+
+        tokio::time::sleep(LASTFM_REQUEST_DELAY).await;
+    }
+
+    Ok(())
+}
+
+async fn repair_cover_variants(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let rows: Vec<(i64, String)> = sqlx::query_as(
+        "SELECT id, file_path FROM furumusic__media_file WHERE file_type = 'cover_art' ORDER BY id",
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    if rows.is_empty() {
+        log.info("Cover variant pass: no cover art media files found");
+        return Ok(());
+    }
+    log.info(&format!(
+        "Cover variant pass: checking {} cover art media file(s)",
+        rows.len()
+    ));
+
+    for (media_file_id, file_path) in rows {
+        let path = crate::media_paths::resolve_media_file_path(storage_dir, &file_path);
+        if !path.exists() {
+            stats.variants_missing_original += 1;
+            log.warn(&format!(
+                "Media file {media_file_id}: original cover not found at {}",
+                path.display()
+            ));
+            continue;
+        }
+
+        match cover_variants::ensure_cover_variants(&path).await {
+            Ok(0) => stats.variants_unchanged += 1,
+            Ok(count) => {
+                stats.variants_created += count;
+                log.info(&format!(
+                    "Media file {media_file_id}: created {count} variant(s)"
+                ));
+            }
+            Err(err) => {
+                stats.failed += 1;
+                log.warn(&format!(
+                    "Media file {media_file_id}: failed to create variants: {err}"
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn assign_artist_album_fallback(
+    ctx: &JobContext,
+    artist_id: i64,
+) -> anyhow::Result<Option<i64>> {
+    let media_file_id: Option<i64> = sqlx::query_scalar(
+        r#"SELECT media_file_id
+             FROM (
+                    SELECT DISTINCT r.cover_file_id AS media_file_id
+                      FROM furumusic__release r
+                      JOIN furumusic__release_artist ra ON ra.release_id = r.id
+                     WHERE ra.artist_id = $1
+                       AND r.cover_file_id IS NOT NULL
+                       AND r.is_hidden = false
+                    UNION
+                    SELECT DISTINCT r.cover_file_id AS media_file_id
+                      FROM furumusic__release r
+                      JOIN furumusic__track t ON t.release_id = r.id
+                      JOIN furumusic__track_artist ta ON ta.track_id = t.id
+                     WHERE ta.artist_id = $1
+                       AND r.cover_file_id IS NOT NULL
+                       AND r.is_hidden = false
+                  ) covers
+            ORDER BY random()
+            LIMIT 1"#,
+    )
+    .bind(artist_id)
+    .fetch_optional(&ctx.pool)
+    .await?;
+
+    let Some(media_file_id) = media_file_id else {
+        return Ok(None);
+    };
+
+    let result = sqlx::query(
+        r#"UPDATE furumusic__artist
+              SET image_file_id = $1,
+                  updated_at = $3
+            WHERE id = $2
+              AND image_file_id IS NULL"#,
+    )
+    .bind(media_file_id)
+    .bind(artist_id)
+    .bind(now_iso())
+    .execute(&ctx.pool)
+    .await?;
+
+    if result.rows_affected() == 0 {
+        Ok(None)
+    } else {
+        Ok(Some(media_file_id))
+    }
+}
+
+async fn fetch_lastfm_album_image(
+    client: &Client,
+    api_key: &str,
+    artist: &str,
+    album: &str,
+) -> anyhow::Result<Option<String>> {
+    let response = client
+        .get("https://ws.audioscrobbler.com/2.0/")
+        .query(&[
+            ("method", "album.getInfo"),
+            ("api_key", api_key),
+            ("artist", artist),
+            ("album", album),
+            ("autocorrect", "1"),
+            ("format", "json"),
+        ])
+        .send()
+        .await?;
+    let body = response.text().await?;
+    let parsed: LastfmAlbumResponse = serde_json::from_str(&body)?;
+    if let Some(code) = parsed.error {
+        if code == 6 || code == 7 {
+            return Ok(None);
+        }
+        if code == 29 {
+            anyhow::bail!("Last.fm rate limit exceeded");
+        }
+        anyhow::bail!(
+            "Last.fm API error {code}: {}",
+            parsed.message.unwrap_or_default()
+        );
+    }
+    Ok(parsed
+        .album
+        .and_then(|album| choose_best_image(album.image)))
+}
+
+async fn fetch_lastfm_artist_image(
+    client: &Client,
+    api_key: &str,
+    artist: &str,
+) -> anyhow::Result<Option<String>> {
+    let response = client
+        .get("https://ws.audioscrobbler.com/2.0/")
+        .query(&[
+            ("method", "artist.getInfo"),
+            ("api_key", api_key),
+            ("artist", artist),
+            ("autocorrect", "1"),
+            ("format", "json"),
+        ])
+        .send()
+        .await?;
+    let body = response.text().await?;
+    let parsed: LastfmArtistResponse = serde_json::from_str(&body)?;
+    if let Some(code) = parsed.error {
+        if code == 6 || code == 7 {
+            return Ok(None);
+        }
+        if code == 29 {
+            anyhow::bail!("Last.fm rate limit exceeded");
+        }
+        anyhow::bail!(
+            "Last.fm API error {code}: {}",
+            parsed.message.unwrap_or_default()
+        );
+    }
+    Ok(parsed
+        .artist
+        .and_then(|artist| choose_best_image(artist.image)))
+}
+
+fn choose_best_image(images: Option<Vec<LastfmImage>>) -> Option<String> {
+    let mut images = images.unwrap_or_default();
+    images.sort_by_key(|image| image_size_rank(&image.size));
+    images
+        .into_iter()
+        .rev()
+        .map(|image| image.url.trim().to_string())
+        .find(|url| is_usable_lastfm_image(url))
+}
+
+fn image_size_rank(size: &str) -> u8 {
+    match size {
+        "mega" => 5,
+        "extralarge" => 4,
+        "large" => 3,
+        "medium" => 2,
+        "small" => 1,
+        _ => 0,
+    }
+}
+
+fn is_usable_lastfm_image(url: &str) -> bool {
+    let value = url.trim();
+    !value.is_empty()
+        && !value.contains("2a96cbd8b46e442fc41c2b86b821562f")
+        && !value.contains("default_")
+}
+
+async fn download_remote_cover(client: &Client, url: &str) -> anyhow::Result<CoverImage> {
+    let response = client.get(url).send().await?;
+    if !response.status().is_success() {
+        anyhow::bail!("image download failed with HTTP {}", response.status());
+    }
+    let header_mime = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .and_then(normalize_image_mime);
+    let data = response.bytes().await?.to_vec();
+    if data.is_empty() {
+        anyhow::bail!("downloaded image is empty");
+    }
+    let mime_type = header_mime
+        .or_else(|| guess_image_mime(&data))
+        .ok_or_else(|| anyhow::anyhow!("downloaded file is not a supported image"))?;
+    Ok(CoverImage {
+        data,
+        mime_type,
+        source: CoverSource::Remote(url.to_string()),
+    })
+}
+
+fn normalize_image_mime(value: &str) -> Option<String> {
+    let mime = value.split(';').next()?.trim().to_ascii_lowercase();
+    match mime.as_str() {
+        "image/jpeg" | "image/jpg" => Some("image/jpeg".to_string()),
+        "image/png" => Some("image/png".to_string()),
+        "image/webp" => Some("image/webp".to_string()),
+        "image/gif" => Some("image/gif".to_string()),
+        "image/bmp" => Some("image/bmp".to_string()),
+        _ => None,
+    }
+}
+
+fn guess_image_mime(data: &[u8]) -> Option<String> {
+    if data.starts_with(&[0xFF, 0xD8, 0xFF]) {
+        Some("image/jpeg".to_string())
+    } else if data.starts_with(&[0x89, 0x50, 0x4E, 0x47]) {
+        Some("image/png".to_string())
+    } else if data.starts_with(b"RIFF") && data.len() > 12 && &data[8..12] == b"WEBP" {
+        Some("image/webp".to_string())
+    } else if data.starts_with(b"GIF8") {
+        Some("image/gif".to_string())
+    } else if data.starts_with(&[0x42, 0x4D]) {
+        Some("image/bmp".to_string())
+    } else {
+        None
+    }
+}
+
+async fn record_lookup_state(
+    pool: &sqlx::PgPool,
+    entity_kind: &str,
+    entity_id: i64,
+    status: &str,
+    error: Option<&str>,
+    source_url: Option<&str>,
+) -> anyhow::Result<()> {
+    sqlx::query(
+        r#"INSERT INTO furumusic__artwork_lookup_state
+              (entity_kind, entity_id, source, status, attempt_count, last_attempt_at, last_error, source_url)
+           VALUES ($1, $2, 'lastfm', $3, 1, $4, $5, $6)
+           ON CONFLICT (entity_kind, entity_id, source) DO UPDATE SET
+              status = EXCLUDED.status,
+              attempt_count = furumusic__artwork_lookup_state.attempt_count + 1,
+              last_attempt_at = EXCLUDED.last_attempt_at,
+              last_error = EXCLUDED.last_error,
+              source_url = EXCLUDED.source_url"#,
+    )
+    .bind(entity_kind)
+    .bind(entity_id)
+    .bind(status)
+    .bind(now_iso())
+    .bind(error)
+    .bind(source_url)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+fn cover_source_description(source: &CoverSource) -> String {
+    match source {
+        CoverSource::FolderFile(path) => format!("folder: {}", path.display()),
+        CoverSource::Embedded(path) => format!("embedded: {}", path.display()),
+        CoverSource::Remote(url) => format!("remote: {url}"),
+    }
+}
+
+fn cutoff_iso(days: i64) -> String {
+    (chrono::Utc::now() - chrono::Duration::days(days))
+        .format("%Y-%m-%dT%H:%M:%SZ")
+        .to_string()
+}
+
+fn now_iso() -> String {
+    chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string()
+}

src/jobs/cover_backfill.rs

@@ -1,167 +0,0 @@
-use std::path::{Path, PathBuf};
-
-use crate::agent::cover_art;
-use crate::scheduler::{Job, JobContext, JobLog};
-
-/// One-shot / periodic job that finds releases without cover art and attempts
-/// to extract or discover covers from their audio files in storage.
-pub struct CoverBackfillJob;
-
-#[async_trait::async_trait]
-impl Job for CoverBackfillJob {
-    fn name(&self) -> &'static str {
-        "cover_backfill"
-    }
-
-    fn description(&self) -> &'static str {
-        "Backfill cover art for releases missing covers"
-    }
-
-    fn default_cron(&self) -> &'static str {
-        // Once a day at 03:00
-        "0 0 3 * * *"
-    }
-
-    async fn run(&self, ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
-        let storage_dir = &ctx.config.agent_storage_dir;
-        if storage_dir.is_empty() {
-            log.warn("agent_storage_dir is not configured, skipping cover backfill");
-            return Ok(());
-        }
-
-        // Find all releases without a cover
-        let rows: Vec<(i64, String)> = sqlx::query_as(
-            "SELECT r.id, r.title \
-             FROM furumusic__release r \
-             WHERE r.cover_file_id IS NULL \
-             ORDER BY r.id",
-        )
-        .fetch_all(&ctx.pool)
-        .await?;
-
-        if rows.is_empty() {
-            log.info("All releases already have cover art, nothing to backfill");
-            return Ok(());
-        }
-
-        log.info(&format!(
-            "Found {} releases without cover art, starting backfill...",
-            rows.len()
-        ));
-
-        let mut assigned = 0u32;
-        let mut failed = 0u32;
-        let mut skipped_no_audio = 0u32;
-        let mut skipped_no_cover = 0u32;
-        let total = rows.len();
-
-        for (i, (release_id, release_title)) in rows.iter().enumerate() {
-            log.info(&format!(
-                "[{}/{}] Processing release {release_id} \"{release_title}\"...",
-                i + 1,
-                total,
-            ));
-
-            // Find audio files belonging to this release via tracks → media_file
-            let audio_paths: Vec<(String,)> = sqlx::query_as(
-                "SELECT mf.file_path \
-                 FROM furumusic__track t \
-                 JOIN furumusic__media_file mf ON mf.id = t.audio_file_id \
-                 WHERE t.release_id = $1 AND mf.file_type = 'audio'",
-            )
-            .bind(release_id)
-            .fetch_all(&ctx.pool)
-            .await
-            .unwrap_or_default();
-
-            if audio_paths.is_empty() {
-                log.warn(&format!(
-                    "Release {release_id} \"{release_title}\": no audio files found, skipping"
-                ));
-                skipped_no_audio += 1;
-                continue;
-            }
-
-            // Determine the folder from the first audio file's path
-            let first_path = Path::new(&audio_paths[0].0);
-            let folder = first_path.parent().unwrap_or(Path::new("."));
-
-            // Collect all audio file paths as PathBuf
-            let audio_files: Vec<PathBuf> =
-                audio_paths.iter().map(|(p,)| PathBuf::from(p)).collect();
-
-            // Try to find cover art
-            let cover = match cover_art::find_best_cover(folder, &audio_files).await {
-                Some(c) => c,
-                None => {
-                    log.info(&format!(
-                        "Release {release_id} \"{release_title}\": no cover image found in {} audio files, skipping",
-                        audio_files.len(),
-                    ));
-                    skipped_no_cover += 1;
-                    continue;
-                }
-            };
-
-            let source_desc = match &cover.source {
-                cover_art::CoverSource::FolderFile(p) => format!("folder: {}", p.display()),
-                cover_art::CoverSource::Embedded(p) => format!("embedded: {}", p.display()),
-            };
-
-            // Look up artist name for storage path
-            let artist_name: String = sqlx::query_scalar(
-                "SELECT a.name FROM furumusic__artist a \
-                 JOIN furumusic__release_artist ra ON ra.artist_id = a.id \
-                 WHERE ra.release_id = $1 \
-                 ORDER BY ra.position LIMIT 1",
-            )
-            .bind(release_id)
-            .fetch_optional(&ctx.pool)
-            .await
-            .ok()
-            .flatten()
-            .unwrap_or_else(|| "Unknown Artist".to_string());
-
-            match cover_art::save_cover_to_storage(
-                &ctx.db,
-                &ctx.pool,
-                storage_dir,
-                &artist_name,
-                release_title,
-                &cover,
-            )
-            .await
-            {
-                Ok(cover_file_id) => {
-                    if let Err(e) =
-                        cover_art::assign_cover_to_release(&ctx.pool, *release_id, cover_file_id)
-                            .await
-                    {
-                        log.warn(&format!(
-                            "Release {release_id} \"{release_title}\": saved cover but failed to assign: {e}"
-                        ));
-                        failed += 1;
-                    } else {
-                        log.info(&format!(
-                            "Release {release_id} \"{release_title}\": assigned cover from {source_desc}"
-                        ));
-                        assigned += 1;
-                    }
-                }
-                Err(e) => {
-                    log.warn(&format!(
-                        "Release {release_id} \"{release_title}\": failed to save cover: {e}"
-                    ));
-                    failed += 1;
-                }
-            }
-        }
-
-        log.info(&format!(
-            "Cover backfill complete: {assigned} assigned, {failed} failed, \
-             {skipped_no_audio} skipped (no audio), {skipped_no_cover} skipped (no cover found)"
-        ));
-
-        Ok(())
-    }
-}

src/jobs/cover_variant_backfill.rs

@@ -1,96 +0,0 @@
-use std::path::{Path, PathBuf};
-
-use crate::agent::cover_variants;
-use crate::scheduler::{Job, JobContext, JobLog};
-
-pub struct CoverVariantBackfillJob;
-
-#[async_trait::async_trait]
-impl Job for CoverVariantBackfillJob {
-    fn name(&self) -> &'static str {
-        "cover_variant_backfill"
-    }
-
-    fn description(&self) -> &'static str {
-        "Generate missing resized cover image variants"
-    }
-
-    fn default_cron(&self) -> &'static str {
-        // Once a day after cover extraction and artist image assignment.
-        "0 45 3 * * *"
-    }
-
-    async fn run(&self, ctx: &JobContext, log: &mut JobLog) -> anyhow::Result<()> {
-        let storage_dir = &ctx.config.agent_storage_dir;
-        if storage_dir.is_empty() {
-            log.warn("agent_storage_dir is not configured, skipping cover variant backfill");
-            return Ok(());
-        }
-
-        let rows: Vec<(i64, String)> = sqlx::query_as(
-            "SELECT id, file_path FROM furumusic__media_file WHERE file_type = 'cover_art' ORDER BY id",
-        )
-        .fetch_all(&ctx.pool)
-        .await?;
-
-        if rows.is_empty() {
-            log.info("No cover art media files found");
-            return Ok(());
-        }
-
-        log.info(&format!(
-            "Found {} cover art media file(s), checking variants...",
-            rows.len()
-        ));
-
-        let mut created = 0usize;
-        let mut unchanged = 0usize;
-        let mut missing_original = 0usize;
-        let mut failed = 0usize;
-
-        for (media_file_id, file_path) in rows {
-            let path = resolve_media_path(storage_dir, &file_path);
-            if !path.exists() {
-                missing_original += 1;
-                log.warn(&format!(
-                    "Media file {media_file_id}: original cover not found at {}",
-                    path.display()
-                ));
-                continue;
-            }
-
-            match cover_variants::ensure_cover_variants(&path).await {
-                Ok(0) => unchanged += 1,
-                Ok(count) => {
-                    created += count;
-                    log.info(&format!(
-                        "Media file {media_file_id}: created {count} variant(s)"
-                    ));
-                }
-                Err(err) => {
-                    failed += 1;
-                    log.warn(&format!(
-                        "Media file {media_file_id}: failed to create variants: {err}"
-                    ));
-                }
-            }
-        }
-
-        log.info(&format!(
-            "Cover variant backfill complete: {created} variant(s) created, \
-             {unchanged} original(s) already complete, {missing_original} missing original(s), \
-             {failed} failed original(s)"
-        ));
-
-        Ok(())
-    }
-}
-
-fn resolve_media_path(storage_dir: &str, file_path: &str) -> PathBuf {
-    let path = PathBuf::from(file_path);
-    if path.is_absolute() {
-        path
-    } else {
-        Path::new(storage_dir).join(path)
-    }
-}

src/jobs/inbox_process.rs

@@ -798,16 +798,29 @@ pub async fn finalize_approved(
         )
         .await?
         {
-            mover::MoveOutcome::Moved(p) => p.to_string_lossy().to_string(),
-            mover::MoveOutcome::Merged(p) => p.to_string_lossy().to_string(),
+            mover::MoveOutcome::Moved(p) | mover::MoveOutcome::Merged(p) => {
+                crate::media_paths::media_file_path_for_storage(storage_dir_str, &p).ok_or_else(
+                    || {
+                        anyhow::anyhow!(
+                            "storage destination is outside agent_storage_dir: {}",
+                            p.display()
+                        )
+                    },
+                )?
+            }
         }
     } else {
-        storage_dir
+        let expected_path = storage_dir
             .join(sanitize_filename(artist_name))
             .join(sanitize_filename(release_title))
-            .join(&dest_filename)
-            .to_string_lossy()
-            .to_string()
+            .join(&dest_filename);
+        crate::media_paths::media_file_path_for_storage(storage_dir_str, &expected_path)
+            .ok_or_else(|| {
+                anyhow::anyhow!(
+                    "storage destination is outside agent_storage_dir: {}",
+                    expected_path.display()
+                )
+            })?
     };
 
     let media_file = MediaFile::create(
@@ -887,6 +900,9 @@ pub async fn finalize_approved(
                     crate::agent::cover_art::CoverSource::Embedded(p) => {
                         format!("embedded in: {}", p.display())
                     }
+                    crate::agent::cover_art::CoverSource::Remote(url) => {
+                        format!("remote: {url}")
+                    }
                 };
                 match crate::agent::cover_art::save_cover_to_storage(
                     db,

src/jobs/metadata_backfill.rs

@@ -1,5 +1,3 @@
-use std::path::{Path, PathBuf};
-
 use crate::scheduler::{Job, JobContext, JobLog};
 
 #[derive(Debug, Clone, Copy)]
@@ -104,11 +102,15 @@ pub async fn run_with_options(
 
     for row in rows {
         scanned += 1;
-        let Some(path) = resolve_media_path(&row.file_path, &ctx.config.agent_storage_dir) else {
+        let path = crate::media_paths::resolve_media_file_path(
+            &ctx.config.agent_storage_dir,
+            &row.file_path,
+        );
+        if !path.exists() {
             missing += 1;
             log.warn(&format!("missing file: {}", row.file_path));
             continue;
-        };
+        }
 
         let extract_path = path.clone();
         let raw_meta = match tokio::task::spawn_blocking(move || {
@@ -218,17 +220,3 @@ fn should_update<T>(current: Option<T>, overwrite: bool) -> bool {
 fn should_update_duration(current: Option<f64>, overwrite: bool) -> bool {
     overwrite || current.unwrap_or(0.0) <= 0.0
 }
-
-fn resolve_media_path(file_path: &str, storage_dir: &str) -> Option<PathBuf> {
-    let path = Path::new(file_path);
-    if path.exists() {
-        return Some(path.to_path_buf());
-    }
-    if path.is_relative() && !storage_dir.is_empty() {
-        let joined = Path::new(storage_dir).join(path);
-        if joined.exists() {
-            return Some(joined);
-        }
-    }
-    None
-}

src/jobs/mod.rs

@@ -1,7 +1,4 @@
-pub mod artist_image_backfill;
-pub mod artist_track_image_backfill;
-pub mod cover_backfill;
-pub mod cover_variant_backfill;
+pub mod artwork_backfill;
 pub mod inbox_discover;
 pub mod inbox_process;
 pub mod lastfm_popularity;

src/main.rs

@@ -6,6 +6,7 @@ mod config;
 mod i18n;
 mod jobs;
 mod lastfm;
+mod media_paths;
 mod music;
 mod oidc;
 mod player;
@@ -50,10 +51,7 @@ fn build_registry() -> Arc<JobRegistry> {
     registry.register(jobs::inbox_discover::InboxDiscoverJob);
     registry.register(jobs::inbox_process::InboxProcessJob);
     registry.register(jobs::inbox_process::FileProcessJob);
-    registry.register(jobs::cover_backfill::CoverBackfillJob);
-    registry.register(jobs::artist_image_backfill::ArtistImageBackfillJob);
-    registry.register(jobs::artist_track_image_backfill::ArtistTrackImageBackfillJob);
-    registry.register(jobs::cover_variant_backfill::CoverVariantBackfillJob);
+    registry.register(jobs::artwork_backfill::ArtworkBackfillJob);
     registry.register(jobs::metadata_backfill::MetadataBackfillJob);
     registry.register(jobs::lastfm_popularity::LastfmPopularityJob);
     registry.register(jobs::lastfm_scrobble::LastfmScrobbleJob);

src/media_paths.rs

@@ -0,0 +1,310 @@
+use std::path::{Component, Path, PathBuf};
+
+const KNOWN_MEDIA_ROOTS: &[&str] = &["media/library", "media/uploads"];
+
+pub fn resolve_config_path(value: &str) -> String {
+    let path = resolve_config_path_buf(value);
+    if path.as_os_str().is_empty() {
+        String::new()
+    } else {
+        path.to_string_lossy().to_string()
+    }
+}
+
+pub fn resolve_config_path_buf(value: &str) -> PathBuf {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return PathBuf::new();
+    }
+
+    let normalized = normalize_slashes(trimmed);
+    if is_host_absolute(&normalized) {
+        return PathBuf::from(normalized);
+    }
+
+    if looks_like_windows_absolute(&normalized) {
+        if let Some(relative) = extract_known_media_root(&normalized) {
+            return app_root().join(slash_path(&relative));
+        }
+        return PathBuf::from(normalized);
+    }
+
+    app_root().join(slash_path(&normalized))
+}
+
+pub fn resolve_media_file_path(storage_dir: &str, file_path: &str) -> PathBuf {
+    let storage_root = resolve_config_path_buf(storage_dir);
+    if let Some(relative) = normalize_stored_media_file_path(storage_dir, file_path) {
+        return storage_root.join(slash_path(&relative));
+    }
+
+    let normalized = normalize_slashes(file_path.trim());
+    let path = PathBuf::from(&normalized);
+    if path.is_absolute() {
+        path
+    } else {
+        storage_root.join(path)
+    }
+}
+
+pub fn media_file_path_for_storage(storage_dir: &str, path: &Path) -> Option<String> {
+    let storage_root = resolve_config_path_buf(storage_dir);
+    if let Ok(relative) = path.strip_prefix(&storage_root) {
+        return relative_path_string(relative);
+    }
+
+    let normalized = normalize_slashes(&path.to_string_lossy());
+    relative_after_storage_marker(&storage_root, &normalized).or_else(|| {
+        if !is_host_absolute(&normalized) && !looks_like_windows_absolute(&normalized) {
+            normalize_relative_path(&normalized)
+        } else {
+            None
+        }
+    })
+}
+
+pub fn normalize_stored_media_file_path(storage_dir: &str, file_path: &str) -> Option<String> {
+    let trimmed = file_path.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+
+    let storage_root = resolve_config_path_buf(storage_dir);
+    let normalized = normalize_slashes(trimmed);
+    let path = PathBuf::from(&normalized);
+    if path.is_absolute() {
+        if let Ok(relative) = path.strip_prefix(&storage_root) {
+            return relative_path_string(relative);
+        }
+        return relative_after_storage_marker(&storage_root, &normalized);
+    }
+
+    if looks_like_windows_absolute(&normalized) {
+        return relative_after_storage_marker(&storage_root, &normalized);
+    }
+
+    if let Some(relative) = relative_after_storage_marker_prefix(&storage_root, &normalized) {
+        return Some(relative);
+    }
+
+    normalize_relative_path(&normalized)
+}
+
+pub async fn normalize_media_file_paths(
+    pool: &sqlx::PgPool,
+    storage_dir: &str,
+) -> anyhow::Result<u64> {
+    let rows: Vec<(i64, String)> =
+        sqlx::query_as("SELECT id, file_path FROM furumusic__media_file ORDER BY id")
+            .fetch_all(pool)
+            .await?;
+
+    let mut updated = 0;
+    for (id, file_path) in rows {
+        let Some(relative) = normalize_stored_media_file_path(storage_dir, &file_path) else {
+            continue;
+        };
+        if relative == file_path {
+            continue;
+        }
+        sqlx::query("UPDATE furumusic__media_file SET file_path = $1 WHERE id = $2")
+            .bind(&relative)
+            .bind(id)
+            .execute(pool)
+            .await?;
+        updated += 1;
+    }
+
+    Ok(updated)
+}
+
+fn app_root() -> PathBuf {
+    std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
+}
+
+fn normalize_slashes(value: &str) -> String {
+    value.trim().replace('\\', "/")
+}
+
+fn is_host_absolute(value: &str) -> bool {
+    Path::new(value).is_absolute()
+}
+
+fn looks_like_windows_absolute(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    bytes.len() >= 3 && bytes[1] == b':' && bytes[2] == b'/' && bytes[0].is_ascii_alphabetic()
+}
+
+fn slash_path(value: &str) -> PathBuf {
+    value
+        .split('/')
+        .filter(|part| !part.is_empty() && *part != ".")
+        .fold(PathBuf::new(), |mut path, part| {
+            path.push(part);
+            path
+        })
+}
+
+fn normalize_relative_path(value: &str) -> Option<String> {
+    let parts: Vec<&str> = value
+        .split('/')
+        .filter(|part| !part.is_empty() && *part != ".")
+        .collect();
+    if parts.is_empty() || parts.iter().any(|part| *part == "..") {
+        return None;
+    }
+    Some(parts.join("/"))
+}
+
+fn relative_path_string(path: &Path) -> Option<String> {
+    let mut parts = Vec::new();
+    for component in path.components() {
+        match component {
+            Component::Normal(value) => parts.push(value.to_string_lossy().to_string()),
+            Component::CurDir => {}
+            _ => return None,
+        }
+    }
+    if parts.is_empty() {
+        None
+    } else {
+        Some(parts.join("/"))
+    }
+}
+
+fn extract_known_media_root(value: &str) -> Option<String> {
+    KNOWN_MEDIA_ROOTS
+        .iter()
+        .filter_map(|marker| relative_from_marker(value, marker, true))
+        .next()
+}
+
+fn relative_after_storage_marker(storage_root: &Path, value: &str) -> Option<String> {
+    let marker = storage_marker(storage_root)?;
+    relative_from_marker(value, &marker, false)
+}
+
+fn relative_after_storage_marker_prefix(storage_root: &Path, value: &str) -> Option<String> {
+    let marker = storage_marker(storage_root)?;
+    let normalized = normalize_slashes(value);
+    let normalized_lower = normalized.to_ascii_lowercase();
+    let marker_lower = marker.to_ascii_lowercase();
+    if normalized_lower == marker_lower {
+        return None;
+    }
+    normalized_lower
+        .strip_prefix(&(marker_lower + "/"))
+        .and_then(|_| normalize_relative_path(&normalized[marker.len() + 1..]))
+}
+
+fn storage_marker(storage_root: &Path) -> Option<String> {
+    let parts: Vec<String> = storage_root
+        .components()
+        .filter_map(|component| match component {
+            Component::Normal(value) => Some(value.to_string_lossy().to_string()),
+            _ => None,
+        })
+        .collect();
+
+    if parts.len() >= 2 {
+        Some(format!(
+            "{}/{}",
+            parts[parts.len() - 2],
+            parts[parts.len() - 1]
+        ))
+    } else {
+        parts.last().cloned()
+    }
+}
+
+fn relative_from_marker(value: &str, marker: &str, include_marker: bool) -> Option<String> {
+    let normalized = normalize_slashes(value);
+    let haystack = format!("/{}", normalized.trim_matches('/'));
+    let marker = marker.trim_matches('/');
+    let needle = format!("/{marker}");
+    let haystack_lower = haystack.to_ascii_lowercase();
+    let needle_lower = needle.to_ascii_lowercase();
+    let index = haystack_lower.rfind(&needle_lower)?;
+    let after_marker = index + needle.len();
+    if after_marker < haystack.len() && haystack.as_bytes().get(after_marker) != Some(&b'/') {
+        return None;
+    }
+    let tail = haystack[after_marker..].trim_matches('/');
+    if include_marker {
+        if tail.is_empty() {
+            Some(marker.to_string())
+        } else {
+            Some(format!("{marker}/{tail}"))
+        }
+    } else {
+        normalize_relative_path(tail)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resolves_relative_config_path_from_app_root() {
+        let expected = app_root().join("media").join("library");
+        assert_eq!(resolve_config_path_buf("media/library"), expected);
+    }
+
+    #[test]
+    fn maps_foreign_windows_config_media_root_to_app_root() {
+        let expected = app_root().join("media").join("uploads");
+        assert_eq!(
+            resolve_config_path_buf(r"C:\Users\ab\repos\furumusic\media\uploads"),
+            expected
+        );
+    }
+
+    #[test]
+    fn stores_path_relative_to_storage_root() {
+        let storage = app_root().join("media").join("library");
+        let path = storage.join("Artist").join("Album").join("track.flac");
+        assert_eq!(
+            media_file_path_for_storage(&storage.to_string_lossy(), &path).as_deref(),
+            Some("Artist/Album/track.flac")
+        );
+    }
+
+    #[test]
+    fn normalizes_legacy_windows_media_file_path() {
+        let storage = app_root().join("media").join("library");
+        assert_eq!(
+            normalize_stored_media_file_path(
+                &storage.to_string_lossy(),
+                r"C:\Users\ab\repos\furumusic\media\library\Buckethead\Pike\cover.jpg",
+            )
+            .as_deref(),
+            Some("Buckethead/Pike/cover.jpg")
+        );
+    }
+
+    #[test]
+    fn strips_accidental_relative_storage_root_prefix() {
+        let storage = app_root().join("media").join("library");
+        assert_eq!(
+            normalize_stored_media_file_path(
+                &storage.to_string_lossy(),
+                "media/library/Buckethead/Pike/cover.jpg",
+            )
+            .as_deref(),
+            Some("Buckethead/Pike/cover.jpg")
+        );
+    }
+
+    #[test]
+    fn resolves_legacy_windows_media_file_path_to_current_storage() {
+        let storage = app_root().join("media").join("library");
+        assert_eq!(
+            resolve_media_file_path(
+                &storage.to_string_lossy(),
+                r"C:\Users\ab\repos\furumusic\media\library\Buckethead\Pike\cover.jpg",
+            ),
+            storage.join("Buckethead").join("Pike").join("cover.jpg")
+        );
+    }
+}

src/music/mod.rs

@@ -1769,6 +1769,52 @@ pub mod db_migrations {
             &[Operation::custom(create_lastfm_scrobbling).build()];
     }
 
+    // -- M0034: Artwork lookup state --------------------------------------
+
+    #[cot::db::migrations::migration_op]
+    async fn create_artwork_lookup_state(
+        ctx: migrations::MigrationContext<'_>,
+    ) -> cot::db::Result<()> {
+        ctx.db
+            .raw(
+                "CREATE TABLE IF NOT EXISTS furumusic__artwork_lookup_state (
+                    id BIGSERIAL PRIMARY KEY,
+                    entity_kind VARCHAR(32) NOT NULL,
+                    entity_id BIGINT NOT NULL,
+                    source VARCHAR(32) NOT NULL,
+                    status VARCHAR(32) NOT NULL,
+                    attempt_count INTEGER NOT NULL DEFAULT 0,
+                    last_attempt_at VARCHAR(32) NOT NULL,
+                    last_error TEXT,
+                    source_url TEXT,
+                    UNIQUE(entity_kind, entity_id, source)
+                )",
+            )
+            .await?;
+        ctx.db
+            .raw(
+                "CREATE INDEX IF NOT EXISTS idx_artwork_lookup_state_retry
+                   ON furumusic__artwork_lookup_state (entity_kind, source, status, last_attempt_at)",
+            )
+            .await?;
+        Ok(())
+    }
+
+    #[derive(Debug, Copy, Clone)]
+    pub struct M0034CreateArtworkLookupState;
+
+    impl migrations::Migration for M0034CreateArtworkLookupState {
+        const APP_NAME: &'static str = "furumusic";
+        const MIGRATION_NAME: &'static str = "m_0034_create_artwork_lookup_state";
+        const DEPENDENCIES: &'static [migrations::MigrationDependency] =
+            &[migrations::MigrationDependency::migration(
+                "furumusic",
+                "m_0033_create_lastfm_scrobbling",
+            )];
+        const OPERATIONS: &'static [Operation] =
+            &[Operation::custom(create_artwork_lookup_state).build()];
+    }
+
     pub const MIGRATIONS: &[&SyncDynMigration] = &[
         &M0006CreateMediaFile,
         &M0007CreateArtist,
@@ -1793,5 +1839,6 @@ pub mod db_migrations {
         &M0031CreateTorrentSession,
         &M0032CreateLastfmTrackPopularity,
         &M0033CreateLastfmScrobbling,
+        &M0034CreateArtworkLookupState,
     ];
 }

src/player/mod.rs

@@ -217,10 +217,10 @@ async fn lastfm_connect_handler(
     };
     let (config, _) = AppConfig::load_with_db(&db).await;
     let Some(credentials) = LastfmCredentials::from_config(&config) else {
-        return Ok(redirect_response("/?lastfm=not_configured"));
+        return Ok(redirect_response("/"));
     };
     let Some(origin) = request_origin(&request) else {
-        return Ok(redirect_response("/?lastfm=bad_origin"));
+        return Ok(redirect_response("/"));
     };
 
     let state = uuid::Uuid::new_v4().simple().to_string();
@@ -270,7 +270,7 @@ async fn lastfm_callback_handler(
         .map(str::trim)
         .filter(|v| !v.is_empty())
     else {
-        return Ok(redirect_response("/?lastfm=missing_token"));
+        return Ok(redirect_response("/"));
     };
     let Some(state) = query
         .0
@@ -279,7 +279,7 @@ async fn lastfm_callback_handler(
         .map(str::trim)
         .filter(|v| !v.is_empty())
     else {
-        return Ok(redirect_response("/?lastfm=missing_state"));
+        return Ok(redirect_response("/"));
     };
 
     let state_user_id = sqlx::query_scalar::<_, i64>(
@@ -290,7 +290,7 @@ async fn lastfm_callback_handler(
     .await
     .map_err(|e| cot::Error::internal(e.to_string()))?;
     if state_user_id != Some(user.id) {
-        return Ok(redirect_response("/?lastfm=bad_state"));
+        return Ok(redirect_response("/"));
     }
     sqlx::query("DELETE FROM furumusic__lastfm_auth_state WHERE state = $1")
         .bind(state)
@@ -300,7 +300,7 @@ async fn lastfm_callback_handler(
 
     let (config, _) = AppConfig::load_with_db(&db).await;
     let Some(credentials) = LastfmCredentials::from_config(&config) else {
-        return Ok(redirect_response("/?lastfm=not_configured"));
+        return Ok(redirect_response("/"));
     };
     let client = LastfmClient::new(credentials).map_err(|e| cot::Error::internal(e.to_string()))?;
     match client.get_session(token).await {
@@ -324,11 +324,11 @@ async fn lastfm_callback_handler(
             .execute(pool)
             .await
             .map_err(|e| cot::Error::internal(e.to_string()))?;
-            Ok(redirect_response("/?lastfm=connected"))
+            Ok(redirect_response("/"))
         }
         Err(err) => {
             tracing::warn!("Last.fm auth failed for user {}: {err}", user.id);
-            Ok(redirect_response("/?lastfm=auth_failed"))
+            Ok(redirect_response("/"))
         }
     }
 }
@@ -460,6 +460,98 @@ async fn update_lastfm_account_error(
     Ok(())
 }
 
+async fn enqueue_lastfm_scrobble(
+    pool: &sqlx::PgPool,
+    config: &AppConfig,
+    user_id: i64,
+    track_id: i64,
+    started_at: Option<i64>,
+    listened_seconds: i32,
+) -> cot::Result<LastfmActionResponse> {
+    if !crate::lastfm::is_configured(config) {
+        return Ok(LastfmActionResponse {
+            ok: false,
+            queued: false,
+            sent: false,
+            message: Some("Last.fm is not configured".to_string()),
+        });
+    }
+    if load_lastfm_account(pool, user_id).await?.is_none() {
+        return Ok(LastfmActionResponse {
+            ok: false,
+            queued: false,
+            sent: false,
+            message: Some("Last.fm account is not connected".to_string()),
+        });
+    }
+    let Some(track) = load_lastfm_track_payload(pool, track_id).await? else {
+        return Ok(LastfmActionResponse {
+            ok: false,
+            queued: false,
+            sent: false,
+            message: Some("Track has no primary artist for Last.fm".to_string()),
+        });
+    };
+    let duration_seconds = track.duration_seconds.unwrap_or(0).max(0);
+    if duration_seconds <= 30 {
+        return Ok(LastfmActionResponse {
+            ok: false,
+            queued: false,
+            sent: false,
+            message: Some("Track is too short to scrobble".to_string()),
+        });
+    }
+    let threshold = ((duration_seconds as f64 / 2.0).min(240.0)).ceil() as i32;
+    let listened_seconds = listened_seconds.max(0);
+    if listened_seconds < threshold {
+        return Ok(LastfmActionResponse {
+            ok: false,
+            queued: false,
+            sent: false,
+            message: Some("Scrobble threshold has not been reached".to_string()),
+        });
+    }
+
+    let now_ts = chrono::Utc::now().timestamp();
+    let started_at = started_at
+        .unwrap_or(now_ts - listened_seconds as i64)
+        .min(now_ts);
+    let now = chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
+    let dedupe_key = format!("{user_id}:{track_id}:{started_at}");
+    sqlx::query(
+        r#"INSERT INTO furumusic__lastfm_scrobble_outbox
+              (user_id, track_id, started_at, listened_seconds, duration_seconds, status, created_at, updated_at, dedupe_key)
+           VALUES ($1, $2, $3, $4, $5, 'pending', $6, $6, $7)
+           ON CONFLICT (dedupe_key) DO NOTHING"#,
+    )
+    .bind(user_id)
+    .bind(track_id)
+    .bind(started_at)
+    .bind(listened_seconds)
+    .bind(duration_seconds)
+    .bind(&now)
+    .bind(&dedupe_key)
+    .execute(pool)
+    .await
+    .map_err(|e| cot::Error::internal(e.to_string()))?;
+
+    let sent = match crate::lastfm::process_pending_scrobbles(pool, config, Some(user_id), 10).await
+    {
+        Ok(summary) => summary.sent > 0,
+        Err(err) => {
+            tracing::warn!("Last.fm immediate scrobble send failed: {err:#}");
+            false
+        }
+    };
+
+    Ok(LastfmActionResponse {
+        ok: true,
+        queued: true,
+        sent,
+        message: None,
+    })
+}
+
 async fn lastfm_now_playing_handler(
     session: Session,
     db: Database,
@@ -542,93 +634,17 @@ async fn lastfm_scrobble_handler(
         return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
     };
     let (config, _) = AppConfig::load_with_db(&db).await;
-    if !crate::lastfm::is_configured(&config) {
-        return Json(LastfmActionResponse {
-            ok: false,
-            queued: false,
-            sent: false,
-            message: Some("Last.fm is not configured".to_string()),
-        })
-        .into_response();
-    }
-    if load_lastfm_account(pool, user.id).await?.is_none() {
-        return Json(LastfmActionResponse {
-            ok: false,
-            queued: false,
-            sent: false,
-            message: Some("Last.fm account is not connected".to_string()),
-        })
-        .into_response();
-    }
-    let Some(track) = load_lastfm_track_payload(pool, entry.track_id).await? else {
-        return Json(LastfmActionResponse {
-            ok: false,
-            queued: false,
-            sent: false,
-            message: Some("Track has no primary artist for Last.fm".to_string()),
-        })
-        .into_response();
-    };
-    let duration_seconds = track.duration_seconds.unwrap_or(0).max(0);
-    if duration_seconds <= 30 {
-        return Json(LastfmActionResponse {
-            ok: false,
-            queued: false,
-            sent: false,
-            message: Some("Track is too short to scrobble".to_string()),
-        })
-        .into_response();
-    }
-    let threshold = ((duration_seconds as f64 / 2.0).min(240.0)).ceil() as i32;
-    let listened_seconds = entry.listened_seconds.max(0);
-    if listened_seconds < threshold {
-        return Json(LastfmActionResponse {
-            ok: false,
-            queued: false,
-            sent: false,
-            message: Some("Scrobble threshold has not been reached".to_string()),
-        })
-        .into_response();
-    }
-
-    let now_ts = chrono::Utc::now().timestamp();
-    let started_at = entry
-        .started_at
-        .unwrap_or(now_ts - listened_seconds as i64)
-        .min(now_ts);
-    let now = chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
-    let dedupe_key = format!("{}:{}:{}", user.id, entry.track_id, started_at);
-    sqlx::query(
-        r#"INSERT INTO furumusic__lastfm_scrobble_outbox
-              (user_id, track_id, started_at, listened_seconds, duration_seconds, status, created_at, updated_at, dedupe_key)
-           VALUES ($1, $2, $3, $4, $5, 'pending', $6, $6, $7)
-           ON CONFLICT (dedupe_key) DO NOTHING"#,
+    Json(
+        enqueue_lastfm_scrobble(
+            pool,
+            &config,
+            user.id,
+            entry.track_id,
+            entry.started_at,
+            entry.listened_seconds,
+        )
+        .await?,
     )
-    .bind(user.id)
-    .bind(entry.track_id)
-    .bind(started_at)
-    .bind(listened_seconds)
-    .bind(duration_seconds)
-    .bind(&now)
-    .bind(&dedupe_key)
-    .execute(pool)
-    .await
-    .map_err(|e| cot::Error::internal(e.to_string()))?;
-
-    let sent =
-        match crate::lastfm::process_pending_scrobbles(pool, &config, Some(user.id), 10).await {
-            Ok(summary) => summary.sent > 0,
-            Err(err) => {
-                tracing::warn!("Last.fm immediate scrobble send failed: {err:#}");
-                false
-            }
-        };
-    Json(LastfmActionResponse {
-        ok: true,
-        queued: true,
-        sent,
-        message: None,
-    })
     .into_response()
 }
 
@@ -1436,7 +1452,8 @@ async fn stream_handler(
         return Ok(json_error(StatusCode::NOT_FOUND, "track not found"));
     };
 
-    let full_path = std::path::Path::new(&config.agent_storage_dir).join(&media.file_path);
+    let full_path =
+        crate::media_paths::resolve_media_file_path(&config.agent_storage_dir, &media.file_path);
 
     if !full_path.exists() {
         return Ok(json_error(
@@ -1505,7 +1522,7 @@ async fn local_upload_handler(
             "agent_inbox_dir is not configured",
         ));
     }
-    let inbox_root = std::path::PathBuf::from(inbox_dir);
+    let inbox_root = crate::media_paths::resolve_config_path_buf(inbox_dir);
     if !inbox_root.is_absolute() {
         return Ok(json_error(
             StatusCode::BAD_REQUEST,
@@ -1728,7 +1745,8 @@ async fn cover_response(
         return Ok(json_error(StatusCode::NOT_FOUND, "media file not found"));
     };
 
-    let full_path = std::path::Path::new(&config.agent_storage_dir).join(&media.file_path);
+    let full_path =
+        crate::media_paths::resolve_media_file_path(&config.agent_storage_dir, &media.file_path);
 
     if !full_path.exists() {
         return Ok(json_error(StatusCode::NOT_FOUND, "file not found on disk"));
@@ -1944,6 +1962,45 @@ async fn history_handler(
     .await
     .map_err(|e| cot::Error::internal(e.to_string()))?;
 
+    if let Some(listened_seconds) = entry.duration_listened {
+        let (config, _) = AppConfig::load_with_db(&db).await;
+        match enqueue_lastfm_scrobble(
+            pool,
+            &config,
+            user.id,
+            entry.track_id,
+            entry.started_at,
+            listened_seconds,
+        )
+        .await
+        {
+            Ok(result) if result.queued => {
+                tracing::info!(
+                    user_id = user.id,
+                    track_id = entry.track_id,
+                    sent = result.sent,
+                    "Queued Last.fm scrobble from play history"
+                );
+            }
+            Ok(result) => {
+                tracing::debug!(
+                    user_id = user.id,
+                    track_id = entry.track_id,
+                    message = ?result.message,
+                    "Play history did not queue Last.fm scrobble"
+                );
+            }
+            Err(err) => {
+                tracing::warn!(
+                    user_id = user.id,
+                    track_id = entry.track_id,
+                    error = %err,
+                    "Failed to queue Last.fm scrobble from play history"
+                );
+            }
+        }
+    }
+
     Json(serde_json::json!({"ok": true})).into_response()
 }
 

src/player/queries.rs

@@ -3,6 +3,7 @@ use serde::Deserialize;
 #[derive(Debug, Deserialize)]
 pub(super) struct HistoryEntry {
     pub(super) track_id: i64,
+    pub(super) started_at: Option<i64>,
     pub(super) duration_listened: Option<i32>,
     pub(super) completed: bool,
 }

src/scheduler/mod.rs

@@ -1360,6 +1360,7 @@ async fn run_scheduled_job(
     if !live_config.agent_enabled
         && job_name != "lastfm_popularity"
         && job_name != "lastfm_scrobble"
+        && job_name != "artwork_backfill"
     {
         tracing::warn!(job = job_name, "Skipping: agent_enabled=false");
         return;
@@ -1470,6 +1471,17 @@ pub async fn start_scheduler(
         Err(e) => tracing::error!("Failed to recover stale reviews: {e}"),
     }
 
+    let (live_config, _) = AppConfig::load_with_db(&db).await;
+    if !live_config.agent_storage_dir.trim().is_empty() {
+        match crate::media_paths::normalize_media_file_paths(&pool, &live_config.agent_storage_dir)
+            .await
+        {
+            Ok(0) => {}
+            Ok(n) => tracing::info!("Normalized {n} media file path(s) to relative storage paths"),
+            Err(e) => tracing::warn!("Failed to normalize media file paths: {e:#}"),
+        }
+    }
+
     // Upsert ScheduledJob rows
     for job in registry.all_jobs() {
         ScheduledJob::upsert(&db, job.name(), job.description(), job.default_cron())

src/torrents.rs

@@ -1242,7 +1242,7 @@ fn validate_selection(files: &[TorrentFileDto], selected_files: &[usize]) -> any
 
 fn validate_inbox_dir(inbox_dir: &str) -> anyhow::Result<PathBuf> {
     let trimmed = inbox_dir.trim();
-    let path = PathBuf::from(trimmed);
+    let path = crate::media_paths::resolve_config_path_buf(trimmed);
     if !path.is_absolute() {
         bail!(
             "agent_inbox_dir must be an absolute path for this host, got `{}`",

templates/player/scripts.html

@@ -38,6 +38,8 @@ const T = {
     lastfmDisconnectConfirm: "{{ t.player_lastfm_disconnect_confirm }}",
     lastfmConnectFailed: "{{ t.player_lastfm_connect_failed }}",
     lastfmDisconnectFailed: "{{ t.player_lastfm_disconnect_failed }}",
+    connectionLost: "{{ t.player_connection_lost }}",
+    connectionLostDetail: "{{ t.player_connection_lost_detail }}",
     trackWord: "{{ t.player_tracks_count }}",
     clientIdle: "{{ t.player_client_idle }}",
     active: "{{ t.player_active }}",
@@ -115,6 +117,42 @@ function coverVariantUrl(url, variant) {
 }
 
 document.addEventListener('alpine:init', () => {
+    // -----------------------------------------------------------------------
+    // Connection monitor
+    // -----------------------------------------------------------------------
+    Alpine.store('connection', {
+        failureCount: 0,
+        disconnected: false,
+        threshold: 2,
+
+        init() {
+            if (navigator.onLine === false) {
+                this.failureCount = this.threshold;
+                this.disconnected = true;
+            }
+            window.addEventListener('online', () => this.recordSuccess());
+            window.addEventListener('offline', () => this.recordFailure());
+        },
+
+        message() {
+            return T.connectionLostDetail;
+        },
+
+        recordSuccess() {
+            this.failureCount = 0;
+            this.disconnected = false;
+        },
+
+        recordFailure() {
+            this.failureCount += 1;
+            if (this.failureCount >= this.threshold) {
+                this.disconnected = true;
+            }
+        },
+    });
+
+    installConnectionFetchMonitor();
+
     // -----------------------------------------------------------------------
     // Audio element
     // -----------------------------------------------------------------------
@@ -174,10 +212,19 @@ document.addEventListener('alpine:init', () => {
         lastfmBusy: false,
 
         init() {
+            this.cleanLastfmQuery();
             this.load();
             this.loadLastfm();
         },
 
+        cleanLastfmQuery() {
+            const url = new URL(window.location.href);
+            if (!url.searchParams.has('lastfm')) return;
+            url.searchParams.delete('lastfm');
+            const clean = `${url.pathname}${url.search}${url.hash}`;
+            window.history.replaceState({}, document.title, clean || '/');
+        },
+
         async load() {
             try {
                 const res = await fetch('/api/player/me');
@@ -356,7 +403,6 @@ document.addEventListener('alpine:init', () => {
         _saveTimer: null,
         _historyRecorded: false,
         _nowPlayingSent: false,
-        _scrobbleSent: false,
         _playbackStartedAt: null,
         _listenedSeconds: 0,
         _lastAudioTime: 0,
@@ -369,12 +415,10 @@ document.addEventListener('alpine:init', () => {
                 this.duration = audio.duration || 0;
                 this.progress = this.duration > 0 ? (this.currentTime / this.duration) * 100 : 0;
                 this._trackListenedDelta();
-                this._maybeScrobble();
             });
 
             audio.addEventListener('ended', () => {
                 this._trackListenedDelta();
-                this._maybeScrobble(true);
                 this._recordHistory(true);
                 this.next();
             });
@@ -450,9 +494,13 @@ document.addEventListener('alpine:init', () => {
             const queue = Alpine.store('queue');
             if (queue.tracks.length === 0) return;
 
+            this._recordHistoryIfListenThresholdReached();
+
             let nextIdx;
             if (this.repeatMode === 'one') {
                 this.seek(0);
+                this._historyRecorded = false;
+                this._resetPlaybackTracking();
                 this.resume();
                 return;
             } else if (this.shuffle) {
@@ -645,20 +693,33 @@ document.addEventListener('alpine:init', () => {
         _recordHistory(completed) {
             if (this._historyRecorded || !this.currentTrack) return;
             this._historyRecorded = true;
+            const listenedSeconds = this._historyListenedSeconds(completed);
             fetch('/api/player/history', {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({
                     track_id: this.currentTrack.id,
-                    duration_listened: Math.floor(this.currentTime),
+                    started_at: this._playbackStartedAt,
+                    duration_listened: listenedSeconds,
                     completed: completed,
                 }),
             }).catch(() => {});
         },
 
+        _recordHistoryIfListenThresholdReached() {
+            if (this._historyRecorded || !this.currentTrack) return false;
+            this._trackListenedDelta();
+            const duration = this._trackDuration();
+            if (duration <= 0) return false;
+            const listened = Math.floor(Number(this._listenedSeconds || 0));
+            const threshold = Math.ceil(duration / 2);
+            if (threshold <= 0 || listened < threshold) return false;
+            this._recordHistory(true);
+            return true;
+        },
+
         _resetPlaybackTracking() {
             this._nowPlayingSent = false;
-            this._scrobbleSent = false;
             this._playbackStartedAt = null;
             this._listenedSeconds = 0;
             this._lastAudioTime = 0;
@@ -696,6 +757,19 @@ document.addEventListener('alpine:init', () => {
             return Math.min(duration / 2, 240);
         },
 
+        _historyListenedSeconds(completed) {
+            const duration = this._trackDuration();
+            const listened = Number(this._listenedSeconds || 0);
+            const finalGrace = completed ? 1 : 0;
+            const precise = Math.floor(listened + finalGrace);
+            if (precise > 0) return precise;
+            const current = Number(audio.currentTime || this.currentTime || 0);
+            if (duration > 0 && Number.isFinite(current)) {
+                return Math.floor(Math.min(current, duration));
+            }
+            return Math.floor(current || 0);
+        },
+
         _sendNowPlaying() {
             if (this._nowPlayingSent || !this.currentTrack) return;
             const lastfm = Alpine.store('user')?.lastfm;
@@ -707,35 +781,6 @@ document.addEventListener('alpine:init', () => {
                 body: JSON.stringify({ track_id: this.currentTrack.id }),
             }).catch(() => {});
         },
-
-        _maybeScrobble(force = false) {
-            if (this._scrobbleSent || !this.currentTrack) return;
-            const lastfm = Alpine.store('user')?.lastfm;
-            if (!lastfm?.configured || !lastfm?.connected || lastfm?.reauth_required) return;
-            const duration = this._trackDuration();
-            if (!duration || duration <= 30) return;
-            const threshold = this._scrobbleThreshold(duration);
-            const listened = force ? this._listenedSeconds + 1 : this._listenedSeconds;
-            if (listened < threshold) return;
-            this._listenedSeconds = Math.max(this._listenedSeconds, listened);
-            this._sendScrobble();
-        },
-
-        _sendScrobble() {
-            if (this._scrobbleSent || !this.currentTrack) return;
-            this._scrobbleSent = true;
-            fetch('/api/player/lastfm/scrobble', {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    track_id: this.currentTrack.id,
-                    started_at: this._playbackStartedAt || Math.floor(Date.now() / 1000),
-                    listened_seconds: Math.floor(this._listenedSeconds),
-                }),
-            }).catch(() => {
-                this._scrobbleSent = false;
-            });
-        },
     });
 
     // -----------------------------------------------------------------------
@@ -2312,4 +2357,39 @@ document.addEventListener('alpine:init', () => {
         },
     });
 });
+
+function installConnectionFetchMonitor() {
+    if (window.__furumusicConnectionMonitorInstalled || !window.fetch) return;
+    window.__furumusicConnectionMonitorInstalled = true;
+    const nativeFetch = window.fetch.bind(window);
+
+    window.fetch = async (...args) => {
+        const tracked = isTrackedPlayerRequest(args[0]);
+        try {
+            const response = await nativeFetch(...args);
+            if (tracked) {
+                if (response.status >= 500) {
+                    Alpine.store('connection')?.recordFailure();
+                } else {
+                    Alpine.store('connection')?.recordSuccess();
+                }
+            }
+            return response;
+        } catch (error) {
+            if (tracked) Alpine.store('connection')?.recordFailure();
+            throw error;
+        }
+    };
+}
+
+function isTrackedPlayerRequest(input) {
+    const rawUrl = typeof input === 'string' ? input : input?.url;
+    if (!rawUrl) return false;
+    try {
+        const url = new URL(rawUrl, window.location.href);
+        return url.origin === window.location.origin && url.pathname.startsWith('/api/player/');
+    } catch {
+        return false;
+    }
+}
 </script>

templates/player/shell.html

@@ -275,6 +275,20 @@
                         <path d="M4 4.5A2.5 2.5 0 016.5 2H20v20H6.5A2.5 2.5 0 014 19.5z"/>
                     </svg>
                 </button>
+                <div class="connection-alert"
+                     x-show="$store.connection.disconnected"
+                     x-cloak
+                     :title="$store.connection.message()"
+                     role="status"
+                     aria-live="polite">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <path d="M2 8.82a15 15 0 0120 0"/>
+                        <path d="M5 12.86a10 10 0 0114 0"/>
+                        <path d="M8.5 16.43a5 5 0 017 0"/>
+                        <line x1="2" y1="2" x2="22" y2="22"/>
+                    </svg>
+                    <span class="connection-alert-text">{{ t.player_connection_lost }}</span>
+                </div>
                 <div class="search-bar">
                     <span class="search-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg></span>
                     <input id="search-input" type="text" placeholder="{{ t.player_search_placeholder }}"

templates/player/styles.html

@@ -1377,6 +1377,37 @@ button.user-stat:hover {
     margin-bottom: 20px;
 }
 
+.connection-alert {
+    flex: 0 0 auto;
+    min-width: 42px;
+    height: 42px;
+    padding: 0 12px;
+    border: 1px solid rgba(248, 113, 113, 0.34);
+    border-radius: 8px;
+    background: rgba(127, 29, 29, 0.2);
+    color: #f87171;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+}
+
+.connection-alert svg {
+    width: 18px;
+    height: 18px;
+    flex: 0 0 auto;
+}
+
+.connection-alert-text {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: #fecaca;
+    font-size: 12px;
+    font-weight: 700;
+}
+
 /* Search bar */
 .search-bar {
     position: relative;
@@ -2676,6 +2707,15 @@ button.user-stat:hover {
         flex: 1 1 auto;
     }
 
+    .connection-alert {
+        width: 42px;
+        padding: 0;
+    }
+
+    .connection-alert-text {
+        display: none;
+    }
+
     .mobile-library-btn {
         display: flex;
     }