From 8ef69f57a2687d89f319892aa8f25e8c405a7c92 Mon Sep 17 00:00:00 2001
From: Daniel <62436912+frostplexx@users.noreply.github.com>
Date: Sat, 26 Sep 2026 09:16:37 +0200
Subject: [PATCH 1/3] feat: animated artwork

Animated artwork over the Now Playing artwork tile, behind a
new "Animated Artwork" setting.
---
 package.json                                  |   3 +
 plugins/radiant-lyrics-luna/package.json      |   3 +-
 plugins/radiant-lyrics-luna/src/Settings.tsx  |  15 +
 plugins/radiant-lyrics-luna/src/api.ts        | 104 ++++++
 plugins/radiant-lyrics-luna/src/artwork.ts    | 329 ++++++++++++++++++
 .../radiant-lyrics-luna/src/hls-light.d.ts    |   6 +
 plugins/radiant-lyrics-luna/src/index.ts      | 109 +++++-
 plugins/radiant-lyrics-luna/src/styles.css    |  17 +
 pnpm-lock.yaml                                |  12 +
 9 files changed, 595 insertions(+), 3 deletions(-)
 create mode 100644 plugins/radiant-lyrics-luna/src/artwork.ts
 create mode 100644 plugins/radiant-lyrics-luna/src/hls-light.d.ts

diff --git a/package.json b/package.json
index b164743..26efd05 100644
--- a/package.json
+++ b/package.json
@@ -19,5 +19,8 @@
 		"rimraf": "^6.0.1",
 		"tsx": "^4.19.4",
 		"typescript": "^5.8.3"
+	},
+	"dependencies": {
+		"hls.js": "^1.7.2"
 	}
 }
diff --git a/plugins/radiant-lyrics-luna/package.json b/plugins/radiant-lyrics-luna/package.json
index b465460..bf9a485 100644
--- a/plugins/radiant-lyrics-luna/package.json
+++ b/plugins/radiant-lyrics-luna/package.json
@@ -9,6 +9,7 @@
 	"main": "./src/index.ts",
 	"type": "module",
 	"dependencies": {
-		"@kawarp/core": "*"
+		"@kawarp/core": "*",
+		"hls.js": "^1.7.2"
 	}
 }
diff --git a/plugins/radiant-lyrics-luna/src/Settings.tsx b/plugins/radiant-lyrics-luna/src/Settings.tsx
index 88b2baf..a931ce7 100644
--- a/plugins/radiant-lyrics-luna/src/Settings.tsx
+++ b/plugins/radiant-lyrics-luna/src/Settings.tsx
@@ -8,6 +8,7 @@ declare global {
 		updateRadiantLyricsTextGlow?: () => void;
 		updateRadiantLyricsPlayerBarTint?: () => void;
 		updateRadiantLyricsBackdrop?: () => void;
+		updateAnimatedArtwork?: (target?: unknown) => void;
 		updateQualityProgressColor?: () => void;
 		updateIntegratedSeekBar?: () => void;
 		updateLyricsStyle?: () => void;
@@ -48,6 +49,7 @@ export const settings = await ReactiveStore.getPluginStorage("RadiantLyrics", {
 	playerBarTintCustomColors: [] as string[],
 	// Master switch
 	backdropEnabled: true,
+	animatedArtwork: true,
 	backdropStyle: 0,
 	backdropPlaybackReactive: true,
 	CoverEverywhere: true,
@@ -82,6 +84,9 @@ export const Settings = () => {
 	const [backdropEnabled, setBackdropEnabled] = React.useState(
 		settings.backdropEnabled,
 	);
+	const [animatedArtwork, setAnimatedArtwork] = React.useState(
+		settings.animatedArtwork,
+	);
 	const [backdropStyle, setBackdropStyle] = React.useState(
 		settings.backdropStyle,
 	);
@@ -915,6 +920,16 @@ export const Settings = () => {
 					refreshBackdrop();
 				}}
 			/>
+			<AnySwitch
+				title="Animated Artwork"
+				desc="Show animated artwork over the artwork tile in the Now Playing view"
+				checked={animatedArtwork}
+				onChange={(_: unknown, checked: boolean) => {
+					settings.animatedArtwork = checked;
+					setAnimatedArtwork(checked);
+					window.updateAnimatedArtwork?.();
+				}}
+			/>
 			{backdropEnabled && (
 				<>
 					<LunaNumberSetting
diff --git a/plugins/radiant-lyrics-luna/src/api.ts b/plugins/radiant-lyrics-luna/src/api.ts
index e0015b2..009c865 100644
--- a/plugins/radiant-lyrics-luna/src/api.ts
+++ b/plugins/radiant-lyrics-luna/src/api.ts
@@ -202,6 +202,110 @@ export async function fetchLyrics(
 	return null;
 }
 
+export interface AnimatedArtwork {
+	url: string;
+	url_tall: string;
+}
+
+function artworkSearchUrl(
+	title: string,
+	artist: string,
+	album?: string,
+): string {
+	let q = `title=${encodeURIComponent(title)}&artist=${encodeURIComponent(artist)}`;
+	// Omit the album param entirely when absent (a literal "undefined" string makes the endpoint miss)
+	if (album && album.trim() !== "") q += `&album=${encodeURIComponent(album.trim())}`;
+	return `https://ama.trainswift.net/api/v1/artwork/search?${q}`;
+}
+
+/**
+ * Lookups keyed by track, including misses (`null`): most tracks have no animated
+ * art, and re-opening the lyrics view or revisiting a track would otherwise hit
+ * the network again for an answer that does not change.
+ */
+const animatedArtworkCache = new Map<string, AnimatedArtwork | null>();
+const ARTWORK_CACHE_MAX = 200;
+
+export async function fetchAnimatedArtwork(
+	title: string,
+	artist: string,
+	album?: string,
+	signal?: AbortSignal,
+): Promise<AnimatedArtwork | null> {
+	// Keyed by album, matching artworkKey() in index.ts: the endpoint returns the
+	// album's artwork, so every track on one album resolves to the same entry.
+	const cacheKey =
+		album && album.trim() !== ""
+			? `${artist}\u0000${album.trim()}`
+			: `${artist}\u0000\u0000${title}`;
+	if (animatedArtworkCache.has(cacheKey)) {
+		return animatedArtworkCache.get(cacheKey) ?? null;
+	}
+
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), 10000);
+	// Caller-driven cancellation (track changed) on top of the timeout.
+	const onAbort = () => controller.abort();
+	signal?.addEventListener("abort", onAbort, { once: true });
+	if (signal?.aborted) controller.abort();
+	const tryFetch = async (url: string): Promise<AnimatedArtwork | null> => {
+		try {
+			sylTrace(`Animated Artwork: fetching ${url}`);
+			const res = await fetch(url, { signal: controller.signal });
+			if (!res.ok) {
+				trace.log(`Animated Artwork: fetch failed ${res.status} | ${url}`);
+				return null;
+			}
+			const data = (await res.json()) as {
+				url?: string;
+				url_tall?: string;
+				message?: string;
+			};
+			if (data.url && data.url_tall) {
+				return { url: data.url, url_tall: data.url_tall };
+			}
+			trace.log(`Animated Artwork: none found | ${url}`);
+			return null;
+		} catch (err) {
+			if (err instanceof DOMException && err.name === "AbortError") {
+				trace.log(`Animated Artwork: request timed out | ${url}`);
+			} else {
+				trace.log(`Animated Artwork: request error | ${url} | ${err}`);
+			}
+			return null;
+		}
+	};
+
+	const remember = (result: AnimatedArtwork | null): AnimatedArtwork | null => {
+		// Never cache a cancelled attempt — it says nothing about the track.
+		if (controller.signal.aborted) return result;
+		if (animatedArtworkCache.size >= ARTWORK_CACHE_MAX) {
+			const oldest = animatedArtworkCache.keys().next().value;
+			if (oldest !== undefined) animatedArtworkCache.delete(oldest);
+		}
+		animatedArtworkCache.set(cacheKey, result);
+		return result;
+	};
+
+	try {
+		// Exact album first; on a miss retry once without the album (server-side disambiguation is imperfect)
+		const withAlbum = await tryFetch(
+			artworkSearchUrl(title, artist, album),
+		);
+		if (withAlbum) return remember(withAlbum);
+		if (album && album.trim() !== "") {
+			const withoutAlbum = await tryFetch(
+				artworkSearchUrl(title, artist),
+			);
+			if (withoutAlbum) return remember(withoutAlbum);
+		}
+		return remember(null);
+	} finally {
+		clearTimeout(timeout);
+		signal?.removeEventListener("abort", onAbort);
+	}
+}
+
 export async function flushLyrics(track: {
 	title: string;
 	artist: string;
diff --git a/plugins/radiant-lyrics-luna/src/artwork.ts b/plugins/radiant-lyrics-luna/src/artwork.ts
new file mode 100644
index 0000000..0aa2f37
--- /dev/null
+++ b/plugins/radiant-lyrics-luna/src/artwork.ts
@@ -0,0 +1,329 @@
+// MARKER: Animated Artwork (live artwork in the lyrics view)
+//   Renders the API HLS stream over TIDAL's static artwork tile.
+//   Orchestration (track change, visibility, settings) lives in index.ts.
+
+import { Tracer } from "@luna/core";
+// The light build drops alt-audio, subtitles and EME — none of which a muted
+// artwork loop uses — and saves ~230kB of bundle. See hls-light.d.ts for types.
+import Hls from "hls.js/light";
+
+import { fetchAnimatedArtwork } from "./api";
+import { settings } from "./Settings";
+
+const { trace } = Tracer("[Radiant Lyrics]");
+
+export const ART_TILE_SELECTOR = '[data-test="now-playing-artwork"]';
+/** Elements that cannot render child nodes, so the video must go beside them. */
+const REPLACED_TAGS = new Set(["IMG", "PICTURE", "VIDEO", "CANVAS", "SVG"]);
+
+export class AnimatedArtworkLayer {
+	private video: HTMLVideoElement | null = null;
+	private hls: Hls | null = null;
+	private tile: HTMLElement | null = null;
+	/** Where the video actually lives — the tile itself, or its parent when the tile is a replaced element. */
+	private mount: HTMLElement | null = null;
+	private resizeObs: ResizeObserver | null = null;
+	private resizeRaf = 0;
+	private artwork: { url: string; url_tall: string } | null = null;
+	/** Identity of the artwork currently mounted (see artworkKey() in index.ts). */
+	private artworkKey: string | null = null;
+	private liveSrc: string | null = null;
+	private loadToken = 0;
+	private nowPlayingVisible = true;
+	/** True when we set `position: relative` on the mount and owe a revert. */
+	private mountPositioned = false;
+	/** Aborts the in-flight lookup when the track changes underneath us. */
+	private fetchAbort: AbortController | null = null;
+
+	/** Give TIDAL's element back the inline style we found it with. */
+	private releaseMount(): void {
+		if (this.mount && this.mountPositioned) this.mount.style.removeProperty("position");
+		this.mountPositioned = false;
+		this.mount = null;
+	}
+
+	/** True while a matching artwork tile is alive. */
+	private tileAlive(): boolean {
+		if (this.tile?.isConnected) return true;
+		const tile = document.querySelector<HTMLElement>(ART_TILE_SELECTOR);
+		if (!tile) return false;
+		this.host(tile);
+		return true;
+	}
+
+	private host(tile: HTMLElement): void {
+		this.tile = tile;
+		// TIDAL's artwork tile is an <img>: a replaced element never renders children,
+		// so an appended <video> would vanish without error. Host it in the parent and
+		// position it over the tile instead.
+		const replaced = REPLACED_TAGS.has(tile.tagName);
+		const mount = replaced ? tile.parentElement : tile;
+		if (mount !== this.mount) this.releaseMount();
+		this.mount = mount;
+		if (this.mount && getComputedStyle(this.mount).position === "static") {
+			// Remember that the inline style is ours so teardown can undo it.
+			this.mountPositioned = true;
+			this.mount.style.position = "relative";
+		}
+		this.watchSizing();
+	}
+
+	/** Lay the video over the tile when it is not a direct child of it. */
+	private syncGeometry(): void {
+		const { video, tile, mount } = this;
+		if (!video || !tile || !mount) return;
+		if (mount === tile) return;
+		video.style.left = `${tile.offsetLeft}px`;
+		video.style.top = `${tile.offsetTop}px`;
+		video.style.width = `${tile.offsetWidth}px`;
+		video.style.height = `${tile.offsetHeight}px`;
+		video.style.right = "auto";
+		video.style.bottom = "auto";
+		video.style.borderRadius = getComputedStyle(tile).borderRadius;
+	}
+
+	private watchSizing(): void {
+		if (!this.tile) return;
+		// host() can re-run against a fresh tile, so always re-target the observer.
+		this.resizeObs?.disconnect();
+		this.resizeObs ??= new ResizeObserver(() => {
+			if (!this.artwork || !this.video) return;
+			// Deferred to the next frame: syncGeometry reads layout and then writes
+			// styles, which inside the callback would retrigger the observer.
+			if (this.resizeRaf !== 0) return;
+			this.resizeRaf = requestAnimationFrame(() => {
+				this.resizeRaf = 0;
+				// Only rebuild the stream if the aspect actually flipped.
+				if (this.pickSrc() !== this.liveSrc) this.mountVideo(false);
+				this.syncGeometry();
+			});
+		});
+		this.resizeObs.observe(this.tile);
+	}
+
+	/**
+	 * Resolve and mount the artwork identified by `key`. Uses the exact album
+	 * first and retries without it on a miss (handled inside the fetch).
+	 *
+	 * The currently playing video is deliberately left alone until a replacement
+	 * is known: animated artwork belongs to the album, so skipping tracks within
+	 * one must not tear the video down and refetch it. Returns false when the
+	 * attempt could not be completed because no artwork tile was on screen, so
+	 * the caller can retry once the view appears.
+	 */
+	async load(
+		key: string,
+		title: string,
+		artist: string,
+		album: string | undefined,
+	): Promise<boolean> {
+		// Already showing this album's artwork — keep playing, touch nothing.
+		if (key === this.artworkKey && this.artwork && this.video?.isConnected) {
+			this.ensurePlaying();
+			return true;
+		}
+		const token = ++this.loadToken;
+		// Stop the previous lookup from holding a connection open for a track we left.
+		this.fetchAbort?.abort();
+		this.fetchAbort = new AbortController();
+		const signal = this.fetchAbort.signal;
+
+		if (!settings.animatedArtwork) return true;
+		// Only confirm a tile exists; hosting happens after the fetch resolves so
+		// the outgoing video keeps its mount (and keeps playing) until then.
+		if (!document.querySelector<HTMLElement>(ART_TILE_SELECTOR)) return false;
+
+		const artwork = await fetchAnimatedArtwork(title, artist, album, signal);
+		if (token !== this.loadToken) return true;
+		if (!this.tileAlive()) return false;
+
+		if (!artwork) {
+			// A definitive miss — no point retrying when the view remounts.
+			trace.log(`Animated Artwork: no animated art for "${title}"`);
+			this.detach(false);
+			// Set after detach(), which clears the key along with the artwork.
+			this.artworkKey = key;
+			return true;
+		}
+		// Same stream as what is already on screen (e.g. a compilation whose
+		// tracks resolve to one album): adopt the key and leave the video be.
+		const unchanged =
+			this.artwork?.url === artwork.url &&
+			this.artwork?.url_tall === artwork.url_tall &&
+			this.video?.isConnected === true;
+		this.artwork = artwork;
+		this.artworkKey = key;
+		if (unchanged) {
+			this.ensurePlaying();
+			return true;
+		}
+		this.mountVideo(false);
+		return true;
+	}
+
+	/** Re-bind to the artwork tile after the Now Playing view (re)mounted. */
+	reattach(): void {
+		if (!this.artwork || !settings.animatedArtwork) return;
+		const tile = document.querySelector<HTMLElement>(ART_TILE_SELECTOR);
+		if (!tile) return;
+		if (tile === this.tile && this.video?.isConnected) {
+			this.ensurePlaying();
+			return;
+		}
+		this.host(tile);
+		this.mountVideo(true);
+	}
+
+	/** (Re)mount the video into the tile, honouring the current aspect + settings. */
+	mountVideo(force: boolean): void {
+		if (!this.tileAlive() || !this.artwork || !settings.animatedArtwork) {
+			this.detach(false);
+			return;
+		}
+		const src = this.pickSrc();
+		if (!this.tile || !this.mount) {
+			this.detach(false);
+			return;
+		}
+		if (src === this.liveSrc && this.video && !force) {
+			this.ensurePlaying();
+			return;
+		}
+		this.video?.remove();
+		this.hls?.destroy();
+		this.hls = null;
+		this.video = null;
+		this.liveSrc = src;
+
+		const video = document.createElement("video");
+		video.className = "rl-animated-art";
+		video.muted = true;
+		video.autoplay = true;
+		video.loop = true;
+		video.playsInline = true;
+		video.crossOrigin = "anonymous";
+		video.tabIndex = -1;
+		video.setAttribute("aria-hidden", "true");
+		video.addEventListener(
+			"error",
+			() => {
+				const err = video.error;
+				this.fail(
+					err ? `media error ${err.code}: ${err.message}` : "media error",
+				);
+			},
+			{ once: true },
+		);
+		this.mount.appendChild(video);
+		this.video = video;
+		this.syncGeometry();
+
+		// MSE first: Chromium answers "maybe" to canPlayType for HLS but then fails
+		// the native demuxer on the playlist itself (DEMUXER_ERROR_COULD_NOT_PARSE),
+		// so native playback is only a fallback for engines without MSE.
+		if (typeof Hls === "function" && Hls.isSupported()) {
+			const hls = new Hls({
+				autoStartLoad: true,
+				// The tile is ~516 CSS px; without this, ABR happily picks the
+				// 2160x2160 ladder rung (91MB for a 34s loop, vs 6MB at 768x768)
+				// and decodes 4x more pixels than the display can show.
+				capLevelToPlayerSize: true,
+			});
+			this.hls = hls;
+			hls.loadSource(src);
+			hls.attachMedia(video);
+			hls.on(Hls.Events.ERROR, (_evt, data) => {
+				if (!data.fatal) return;
+				this.fail(
+					`hls ${data.type}/${data.details}${data.reason ? ` (${data.reason})` : ""}${data.error ? ` (${data.error.message})` : ""}`,
+				);
+			});
+		} else if (video.canPlayType("application/x-mpegurl")) {
+			video.src = src;
+		} else {
+			trace.log("Animated Artwork: HLS unsupported on this client");
+			this.detach(false);
+			return;
+		}
+		video.classList.add("rl-animated-art-visible");
+		this.ensurePlaying();
+	}
+
+	private pickSrc(): string {
+		if (!this.artwork || !this.tile) return "";
+		const rect = this.tile.getBoundingClientRect();
+		if (rect.width && rect.height && rect.height > rect.width) {
+			return this.artwork.url_tall;
+		}
+		return this.artwork.url;
+	}
+
+	private fail = (reason: string): void => {
+		trace.log(`Animated Artwork: ${reason} — hiding video (src: ${this.liveSrc})`);
+		this.detach(false);
+	};
+
+	/** Respect settings + panel visibility when toggling play/pause. */
+	ensurePlaying(): void {
+		if (
+			this.artwork &&
+			this.video &&
+			settings.animatedArtwork &&
+			this.nowPlayingVisible &&
+			!document.hidden &&
+			this.tile?.isConnected
+		) {
+			void this.video.play().catch(() => {});
+		} else {
+			this.video?.pause();
+		}
+	}
+
+	/** Set whether the Now Playing view is currently visible on screen. */
+	setNowPlayingVisible(visible: boolean): void {
+		// Called from the 200ms activity tick: bail unless the state actually flipped.
+		if (visible === this.nowPlayingVisible) return;
+		this.nowPlayingVisible = visible;
+		// Re-show has to resume explicitly: the view is hidden by CSS rather than
+		// unmounted, so the tile observer never fires and nothing else would restart it.
+		this.ensurePlaying();
+	}
+
+	/** Keep the video mounted but re-evaluate play state (settings / visibility). */
+	refresh(): void {
+		if (!this.liveSrc) return;
+		if (settings.animatedArtwork) {
+			if (this.video) this.ensurePlaying();
+			else this.mountVideo(true);
+		} else {
+			this.detach(true);
+		}
+	}
+
+	private detach(keepData: boolean): void {
+		if (this.video?.parentNode) this.video.remove();
+		this.video = null;
+		this.hls?.destroy();
+		this.hls = null;
+		this.liveSrc = keepData ? this.liveSrc : null;
+		if (!keepData) {
+			this.artwork = null;
+			this.artworkKey = null;
+		}
+	}
+
+	/** Full teardown, including tile references. */
+	dispose(): void {
+		this.loadToken++;
+		this.fetchAbort?.abort();
+		this.fetchAbort = null;
+		this.resizeObs?.disconnect();
+		this.resizeObs = null;
+		if (this.resizeRaf !== 0) cancelAnimationFrame(this.resizeRaf);
+		this.resizeRaf = 0;
+		// detach(true) keeps nothing on disk, but we are disposing
+		this.detach(false);
+		this.releaseMount();
+		this.tile = null;
+	}
+}
\ No newline at end of file
diff --git a/plugins/radiant-lyrics-luna/src/hls-light.d.ts b/plugins/radiant-lyrics-luna/src/hls-light.d.ts
new file mode 100644
index 0000000..420de0e
--- /dev/null
+++ b/plugins/radiant-lyrics-luna/src/hls-light.d.ts
@@ -0,0 +1,6 @@
+// hls.js ships types for its main entry only. The light build is the same public
+// API with alt-audio, subtitles and EME stripped, so point it at those types.
+declare module "hls.js/light" {
+	export * from "hls.js";
+	export { default } from "hls.js";
+}
diff --git a/plugins/radiant-lyrics-luna/src/index.ts b/plugins/radiant-lyrics-luna/src/index.ts
index 569f62f..de42ae3 100644
--- a/plugins/radiant-lyrics-luna/src/index.ts
+++ b/plugins/radiant-lyrics-luna/src/index.ts
@@ -20,6 +20,7 @@ import {
 	romanizeLyrics as romanizeLyricsApi,
 } from "./api";
 import { KawarpLayer } from "./backdrop";
+import { AnimatedArtworkLayer, ART_TILE_SELECTOR } from "./artwork";
 import { Settings, settings } from "./Settings";
 
 import backdropStylesCss from "file://backdrop-styles.css?minify";
@@ -731,6 +732,18 @@ const setLayerRunning = (
 	if (now - pauseHiddenSince[slot] >= PAUSE_GRACE_MS) layer.setPaused(true);
 };
 
+// Cached so the 200ms activity tick does not re-run a document-wide
+// attribute-substring query; invalidated as soon as the node detaches.
+let cachedNowPlayingPanel: HTMLElement | null = null;
+
+// Is the Now Playing view actually on screen? (visibility, not just mounted)
+const artPanelVisible = (panel: HTMLElement): boolean => {
+	if (typeof panel.checkVisibility === "function") {
+		return panel.checkVisibility({ checkVisibilityCSS: true });
+	}
+	return getComputedStyle(panel).visibility !== "hidden";
+};
+
 const syncBackdropActivity = (): void => {
 	// Stock backdrop keeps current (no shader loop)
 	if (stockContainer) applyStockCoverEverywhere();
@@ -763,6 +776,19 @@ const syncBackdropActivity = (): void => {
 			(global?.isVisible() ?? false),
 		now,
 	);
+
+	// Animated artwork only runs while the Now Playing view is visible.
+	// Guarded: without a layer there is nothing to tell, and this runs 5x/second.
+	if (animatedArtworkLayer) {
+		if (!cachedNowPlayingPanel?.isConnected) {
+			cachedNowPlayingPanel = document.querySelector(
+				'[class*="_nowPlayingContainer"]',
+			) as HTMLElement | null;
+		}
+		animatedArtworkLayer.setNowPlayingVisible(
+			!!cachedNowPlayingPanel && artPanelVisible(cachedNowPlayingPanel),
+		);
+	}
 };
 
 /** cover art @ resolution worth sampling */
@@ -1019,6 +1045,60 @@ const updateRadiantLyricsBackdrop = function (): void {
 	}
 };
 
+// MARKER: Animated Artwork (live artwork on the artwork tile)
+let animatedArtworkLayer: AnimatedArtworkLayer | null = null;
+let lastArtworkKey: string | null = null;
+// The tile element we have already reacted to, so the DOM observer stays O(1).
+let lastArtworkTile: Element | null = null;
+
+/**
+ * Identity of a track's animated artwork. Animated art is an *album*
+ * asset, so every track on one album shares it: keying by album means skipping
+ * within an album neither refetches nor restarts the video. Falls back to the
+ * title only when the album is unknown, which is the finest identity available.
+ */
+const artworkKey = (t: TrackInfo): string =>
+	t.album && t.album.trim() !== ""
+		? `${t.artist}\u0000${t.album.trim()}`
+		: `${t.artist}\u0000\u0000${t.title}`;
+
+// Load + show animated art for the current (or given) track
+const updateAnimatedArtwork = async (
+	target?: TrackInfo | null,
+	rehost = false,
+): Promise<void> => {
+	if (!settings.animatedArtwork) {
+		animatedArtworkLayer?.dispose();
+		animatedArtworkLayer = null;
+		lastArtworkKey = null;
+		lastArtworkTile = null;
+		return;
+	}
+	if (!animatedArtworkLayer) animatedArtworkLayer = new AnimatedArtworkLayer();
+	target ??= await getTrackInfo();
+	if (!target) return;
+	// Re-check after the await: another caller may have claimed this track already.
+	if (!settings.animatedArtwork || !animatedArtworkLayer) return;
+	const key = artworkKey(target);
+	if (key === lastArtworkKey) {
+		// Same artwork, but the view may have remounted underneath us.
+		if (rehost) animatedArtworkLayer.reattach();
+		return;
+	}
+	lastArtworkKey = key;
+	const done = await animatedArtworkLayer.load(
+		key,
+		target.title,
+		target.artist,
+		target.album,
+	);
+	// No artwork tile was on screen (lyrics view not open yet) — clear the key so
+	// the tile observer can retry instead of treating this track as handled.
+	if (!done && lastArtworkKey === key) lastArtworkKey = null;
+};
+
+(window as any).updateAnimatedArtwork = updateAnimatedArtwork;
+
 // Make these functions available globally so Settings can call them
 (window as any).updateRadiantLyricsStyles = updateRadiantLyricsStyles;
 (window as any).updateRadiantLyricsBackdrop = updateRadiantLyricsBackdrop;
@@ -1053,8 +1133,16 @@ updateRadiantLyricsTextGlow();
 // Init global background
 updateCoverArtBackground(1);
 
+// Init animated artwork (handles already-playing track on startup).
+// Deferred: getTrackInfo() is a `const` declared further down this module, so
+// calling it during module evaluation would hit the uninitialised binding.
+queueMicrotask(() => void updateAnimatedArtwork());
+
 // Cleanups
 unloads.add(() => {
+	animatedArtworkLayer?.dispose();
+	animatedArtworkLayer = null;
+	cachedNowPlayingPanel = null;
 	cleanUpDynamicArt();
 	cleanUpStockCoverEverywhere();
 	document.body.classList.remove("rl-backdrop-active");
@@ -1390,6 +1478,19 @@ function setupLyricsMenuObserver(): void {
 		}
 	});
 
+	// Animated artwork: the tile only exists once the Now Playing view is open,
+	// so the initial load has to run from here as well as on track change.
+	// `observe` is a document-wide childList MutationObserver, so this fires on
+	// virtually every DOM change. Bail synchronously unless the tile is genuinely
+	// new — anything heavier (or anything that mutates) would feed itself.
+	observe<HTMLElement>(unloads, ART_TILE_SELECTOR, (tile) => {
+		// Identity check only: cheap, and it stops us reacting to our own <video>
+		// insertion, whose mutation target (the tile's parent) re-matches the tile.
+		if (tile === lastArtworkTile) return;
+		lastArtworkTile = tile;
+		void updateAnimatedArtwork(undefined, true);
+	});
+
 	// Apply word lyrics when lyrics container appears or reappears
 	observe<HTMLElement>(unloads, '[data-test="now-playing-lyrics"]', () => {
 		if (isTrackChangeRunning) return;
@@ -1424,6 +1525,7 @@ interface TrackInfo {
 	title: string;
 	artist: string;
 	isrc?: string;
+	album?: string;
 }
 
 interface SyntheticNativeLyricsState {
@@ -2083,8 +2185,9 @@ const trackInfoFromReduxProductId = (productId: string): TrackInfo | null => {
 	const title = String(attr.title ?? "");
 	const artist = String(attr.artist?.name ?? getPrimaryArtistName(attr.artists) ?? "");
 	const isrc = attr.isrc ?? undefined;
+	const album = attr.album?.title ?? undefined;
 	if (!title || !artist) return null;
-	return { trackId: productId, title, artist, isrc };
+	return { trackId: productId, title, artist, isrc, album };
 };
 
 // MARKER: Playback clock
@@ -2301,9 +2404,10 @@ const getTrackInfo = async (): Promise<TrackInfo | null> => {
 			mi.tidalItem.artist?.name ?? getPrimaryArtistName(mi.tidalItem.artists) ?? ""; // REMIX Detection
 		const isrc = mi.tidalItem.isrc ?? undefined;
 		const trackId = String(mi.tidalItem.id ?? PlayState.playbackContext?.actualProductId ?? "");
+		const album = mi.tidalItem.album?.title ?? undefined;
 
 		if (!baseTitle || !artist || !trackId) return null;
-		return { trackId, title, artist, isrc };
+		return { trackId, title, artist, isrc, album };
 	}
 
 	const state = getReduxState();
@@ -4303,6 +4407,7 @@ function setupHeaderObserver(): void {
 // Apply seeker color on track change
 onGlobalTrackChange(() => {
 	updateCoverArtBackground();
+	void updateAnimatedArtwork();
 	if (settings.qualityProgressColor) applyQualityProgressColor();
 });
 
diff --git a/plugins/radiant-lyrics-luna/src/styles.css b/plugins/radiant-lyrics-luna/src/styles.css
index ef3a3d6..1128802 100644
--- a/plugins/radiant-lyrics-luna/src/styles.css
+++ b/plugins/radiant-lyrics-luna/src/styles.css
@@ -837,6 +837,23 @@ body.rl-owns-lyric-scroll [class*="_syncButtonContainer_"] {
 	border-radius: 10px !important;
 }
 
+/* Animated artwork (live art) overlays the tile */
+.rl-animated-art {
+	position: absolute;
+	inset: 0;
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+	border-radius: inherit;
+	z-index: 1;
+	pointer-events: none;
+	transition: opacity 0.3s ease;
+	opacity: 0;
+}
+.rl-animated-art-visible {
+	opacity: 1;
+}
+
 /* Hide the Overlay Scrollbar (people just use mouse scroll) */
 .os-scrollbar {
 	display: none !important;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9a35446..658d919 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -7,6 +7,10 @@ settings:
 importers:
 
   .:
+    dependencies:
+      hls.js:
+        specifier: ^1.7.2
+        version: 1.7.2
     devDependencies:
       '@types/node':
         specifier: ^22.15.29
@@ -52,6 +56,9 @@ importers:
       '@kawarp/core':
         specifier: '*'
         version: 1.2.0
+      hls.js:
+        specifier: ^1.7.2
+        version: 1.7.2
 
 packages:
 
@@ -462,6 +469,9 @@ packages:
     resolution: {integrity: sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==}
     hasBin: true
 
+  hls.js@1.7.2:
+    resolution: {integrity: sha512-CW/pPvSOFIRsosbwxrYaE9ERmpTo5fbTqL7wCvuCFlqW1Bmb1K5fXsY7yiH95rmlr4rVuA7UXHbM/cIXQ6AXwg==}
+
   html-encoding-sniffer@3.0.0:
     resolution: {integrity: sha512-oWv4T4yJ52iKrufjnyZPkrN0CH3QnrUqdB6In1g5Fe1mia8GmF36gnfNySxoZtxD5+NmYw1EElVXiBk93UeskA==}
     engines: {node: '>=12'}
@@ -1068,6 +1078,8 @@ snapshots:
 
   he@1.2.0: {}
 
+  hls.js@1.7.2: {}
+
   html-encoding-sniffer@3.0.0:
     dependencies:
       whatwg-encoding: 2.0.0

From 47813e0559b6ae1e8e6713673dd85b5aed8b41fd Mon Sep 17 00:00:00 2001
From: Daniel <62436912+frostplexx@users.noreply.github.com>
Date: Sat, 26 Sep 2026 10:11:26 +0200
Subject: [PATCH 2/3] feat: add fps setting

---
 plugins/radiant-lyrics-luna/src/Settings.tsx | 20 +++++
 plugins/radiant-lyrics-luna/src/api.ts       | 12 +--
 plugins/radiant-lyrics-luna/src/artwork.ts   | 82 ++++++++++----------
 plugins/radiant-lyrics-luna/src/index.ts     | 37 +++------
 4 files changed, 74 insertions(+), 77 deletions(-)

diff --git a/plugins/radiant-lyrics-luna/src/Settings.tsx b/plugins/radiant-lyrics-luna/src/Settings.tsx
index a931ce7..139195d 100644
--- a/plugins/radiant-lyrics-luna/src/Settings.tsx
+++ b/plugins/radiant-lyrics-luna/src/Settings.tsx
@@ -9,6 +9,7 @@ declare global {
 		updateRadiantLyricsPlayerBarTint?: () => void;
 		updateRadiantLyricsBackdrop?: () => void;
 		updateAnimatedArtwork?: (target?: unknown) => void;
+		updateAnimatedArtworkRate?: () => void;
 		updateQualityProgressColor?: () => void;
 		updateIntegratedSeekBar?: () => void;
 		updateLyricsStyle?: () => void;
@@ -50,6 +51,7 @@ export const settings = await ReactiveStore.getPluginStorage("RadiantLyrics", {
 	// Master switch
 	backdropEnabled: true,
 	animatedArtwork: true,
+	animatedArtworkFps: 25,
 	backdropStyle: 0,
 	backdropPlaybackReactive: true,
 	CoverEverywhere: true,
@@ -87,6 +89,9 @@ export const Settings = () => {
 	const [animatedArtwork, setAnimatedArtwork] = React.useState(
 		settings.animatedArtwork,
 	);
+	const [animatedArtworkFps, setAnimatedArtworkFps] = React.useState(
+		settings.animatedArtworkFps,
+	);
 	const [backdropStyle, setBackdropStyle] = React.useState(
 		settings.backdropStyle,
 	);
@@ -930,6 +935,21 @@ export const Settings = () => {
 					window.updateAnimatedArtwork?.();
 				}}
 			/>
+			{animatedArtwork && (
+				<LunaNumberSetting
+					title="Animated Artwork Frame Rate"
+					desc="Frames per second for the animated artwork. Lower is cheaper but choppier; 25 is native speed."
+					min={1}
+					max={25}
+					step={1}
+					value={animatedArtworkFps}
+					onNumber={(value: number) => {
+						settings.animatedArtworkFps = value;
+						setAnimatedArtworkFps(value);
+						window.updateAnimatedArtworkRate?.();
+					}}
+				/>
+			)}
 			{backdropEnabled && (
 				<>
 					<LunaNumberSetting
diff --git a/plugins/radiant-lyrics-luna/src/api.ts b/plugins/radiant-lyrics-luna/src/api.ts
index 009c865..f2ae935 100644
--- a/plugins/radiant-lyrics-luna/src/api.ts
+++ b/plugins/radiant-lyrics-luna/src/api.ts
@@ -218,11 +218,7 @@ function artworkSearchUrl(
 	return `https://ama.trainswift.net/api/v1/artwork/search?${q}`;
 }
 
-/**
- * Lookups keyed by track, including misses (`null`): most tracks have no animated
- * art, and re-opening the lyrics view or revisiting a track would otherwise hit
- * the network again for an answer that does not change.
- */
+// Cached including misses; most tracks have none and the answer never changes.
 const animatedArtworkCache = new Map<string, AnimatedArtwork | null>();
 const ARTWORK_CACHE_MAX = 200;
 
@@ -232,8 +228,7 @@ export async function fetchAnimatedArtwork(
 	album?: string,
 	signal?: AbortSignal,
 ): Promise<AnimatedArtwork | null> {
-	// Keyed by album, matching artworkKey() in index.ts: the endpoint returns the
-	// album's artwork, so every track on one album resolves to the same entry.
+	// Keyed by album, matching artworkKey() in index.ts.
 	const cacheKey =
 		album && album.trim() !== ""
 			? `${artist}\u0000${album.trim()}`
@@ -244,7 +239,6 @@ export async function fetchAnimatedArtwork(
 
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), 10000);
-	// Caller-driven cancellation (track changed) on top of the timeout.
 	const onAbort = () => controller.abort();
 	signal?.addEventListener("abort", onAbort, { once: true });
 	if (signal?.aborted) controller.abort();
@@ -277,7 +271,7 @@ export async function fetchAnimatedArtwork(
 	};
 
 	const remember = (result: AnimatedArtwork | null): AnimatedArtwork | null => {
-		// Never cache a cancelled attempt — it says nothing about the track.
+		// A cancelled attempt says nothing about the track.
 		if (controller.signal.aborted) return result;
 		if (animatedArtworkCache.size >= ARTWORK_CACHE_MAX) {
 			const oldest = animatedArtworkCache.keys().next().value;
diff --git a/plugins/radiant-lyrics-luna/src/artwork.ts b/plugins/radiant-lyrics-luna/src/artwork.ts
index 0aa2f37..8d777a9 100644
--- a/plugins/radiant-lyrics-luna/src/artwork.ts
+++ b/plugins/radiant-lyrics-luna/src/artwork.ts
@@ -3,8 +3,7 @@
 //   Orchestration (track change, visibility, settings) lives in index.ts.
 
 import { Tracer } from "@luna/core";
-// The light build drops alt-audio, subtitles and EME — none of which a muted
-// artwork loop uses — and saves ~230kB of bundle. See hls-light.d.ts for types.
+// Light build: no alt-audio/subtitles/EME needed here. Types in hls-light.d.ts.
 import Hls from "hls.js/light";
 
 import { fetchAnimatedArtwork } from "./api";
@@ -15,27 +14,37 @@ const { trace } = Tracer("[Radiant Lyrics]");
 export const ART_TILE_SELECTOR = '[data-test="now-playing-artwork"]';
 /** Elements that cannot render child nodes, so the video must go beside them. */
 const REPLACED_TAGS = new Set(["IMG", "PICTURE", "VIDEO", "CANVAS", "SVG"]);
+// Keeps ABR off the 2160x2160 rung (91MB a loop). Bandwidth only, not CPU.
+const ART_MAX_DPR = 1;
+const ART_NATIVE_FPS = 25;
 
 export class AnimatedArtworkLayer {
 	private video: HTMLVideoElement | null = null;
 	private hls: Hls | null = null;
 	private tile: HTMLElement | null = null;
-	/** Where the video actually lives — the tile itself, or its parent when the tile is a replaced element. */
+	/** The tile, or its parent when the tile is a replaced element. */
 	private mount: HTMLElement | null = null;
 	private resizeObs: ResizeObserver | null = null;
 	private resizeRaf = 0;
 	private artwork: { url: string; url_tall: string } | null = null;
-	/** Identity of the artwork currently mounted (see artworkKey() in index.ts). */
+	/** See artworkKey() in index.ts. */
 	private artworkKey: string | null = null;
 	private liveSrc: string | null = null;
 	private loadToken = 0;
 	private nowPlayingVisible = true;
-	/** True when we set `position: relative` on the mount and owe a revert. */
+	/** True when the mount's inline position is ours to revert. */
 	private mountPositioned = false;
-	/** Aborts the in-flight lookup when the track changes underneath us. */
 	private fetchAbort: AbortController | null = null;
+	private nativeFps = ART_NATIVE_FPS;
+
+	// CPU tracks presented fps and nothing else, so this is the only perf knob.
+	private applyRate(): void {
+		if (!this.video) return;
+		const target = Number(settings.animatedArtworkFps) || ART_NATIVE_FPS;
+		const rate = Math.min(1, Math.max(0.05, target / this.nativeFps));
+		if (this.video.playbackRate !== rate) this.video.playbackRate = rate;
+	}
 
-	/** Give TIDAL's element back the inline style we found it with. */
 	private releaseMount(): void {
 		if (this.mount && this.mountPositioned) this.mount.style.removeProperty("position");
 		this.mountPositioned = false;
@@ -53,15 +62,13 @@ export class AnimatedArtworkLayer {
 
 	private host(tile: HTMLElement): void {
 		this.tile = tile;
-		// TIDAL's artwork tile is an <img>: a replaced element never renders children,
-		// so an appended <video> would vanish without error. Host it in the parent and
-		// position it over the tile instead.
+		// The tile is an <img>; a replaced element silently drops children, so
+		// host the video in the parent and lay it over the tile.
 		const replaced = REPLACED_TAGS.has(tile.tagName);
 		const mount = replaced ? tile.parentElement : tile;
 		if (mount !== this.mount) this.releaseMount();
 		this.mount = mount;
 		if (this.mount && getComputedStyle(this.mount).position === "static") {
-			// Remember that the inline style is ours so teardown can undo it.
 			this.mountPositioned = true;
 			this.mount.style.position = "relative";
 		}
@@ -84,12 +91,11 @@ export class AnimatedArtworkLayer {
 
 	private watchSizing(): void {
 		if (!this.tile) return;
-		// host() can re-run against a fresh tile, so always re-target the observer.
+		// host() can re-run against a fresh tile.
 		this.resizeObs?.disconnect();
 		this.resizeObs ??= new ResizeObserver(() => {
 			if (!this.artwork || !this.video) return;
-			// Deferred to the next frame: syncGeometry reads layout and then writes
-			// styles, which inside the callback would retrigger the observer.
+			// Deferred: syncGeometry writes styles and would retrigger us.
 			if (this.resizeRaf !== 0) return;
 			this.resizeRaf = requestAnimationFrame(() => {
 				this.resizeRaf = 0;
@@ -102,14 +108,8 @@ export class AnimatedArtworkLayer {
 	}
 
 	/**
-	 * Resolve and mount the artwork identified by `key`. Uses the exact album
-	 * first and retries without it on a miss (handled inside the fetch).
-	 *
-	 * The currently playing video is deliberately left alone until a replacement
-	 * is known: animated artwork belongs to the album, so skipping tracks within
-	 * one must not tear the video down and refetch it. Returns false when the
-	 * attempt could not be completed because no artwork tile was on screen, so
-	 * the caller can retry once the view appears.
+	 * Mount the artwork for `key`, leaving any playing video alone until a
+	 * replacement resolves. False means no tile was on screen, so retry later.
 	 */
 	async load(
 		key: string,
@@ -123,14 +123,12 @@ export class AnimatedArtworkLayer {
 			return true;
 		}
 		const token = ++this.loadToken;
-		// Stop the previous lookup from holding a connection open for a track we left.
 		this.fetchAbort?.abort();
 		this.fetchAbort = new AbortController();
 		const signal = this.fetchAbort.signal;
 
 		if (!settings.animatedArtwork) return true;
-		// Only confirm a tile exists; hosting happens after the fetch resolves so
-		// the outgoing video keeps its mount (and keeps playing) until then.
+		// Only check a tile exists; host after the fetch so the old video keeps playing.
 		if (!document.querySelector<HTMLElement>(ART_TILE_SELECTOR)) return false;
 
 		const artwork = await fetchAnimatedArtwork(title, artist, album, signal);
@@ -138,15 +136,13 @@ export class AnimatedArtworkLayer {
 		if (!this.tileAlive()) return false;
 
 		if (!artwork) {
-			// A definitive miss — no point retrying when the view remounts.
 			trace.log(`Animated Artwork: no animated art for "${title}"`);
 			this.detach(false);
-			// Set after detach(), which clears the key along with the artwork.
+			// After detach(), which clears the key too.
 			this.artworkKey = key;
 			return true;
 		}
-		// Same stream as what is already on screen (e.g. a compilation whose
-		// tracks resolve to one album): adopt the key and leave the video be.
+		// Same stream already on screen: adopt the key, leave the video be.
 		const unchanged =
 			this.artwork?.url === artwork.url &&
 			this.artwork?.url_tall === artwork.url_tall &&
@@ -218,20 +214,24 @@ export class AnimatedArtworkLayer {
 		this.video = video;
 		this.syncGeometry();
 
-		// MSE first: Chromium answers "maybe" to canPlayType for HLS but then fails
-		// the native demuxer on the playlist itself (DEMUXER_ERROR_COULD_NOT_PARSE),
-		// so native playback is only a fallback for engines without MSE.
+		// MSE first: Chromium says "maybe" to canPlayType for HLS then fails to
+		// demux the playlist, so native is only a fallback for engines without MSE.
 		if (typeof Hls === "function" && Hls.isSupported()) {
 			const hls = new Hls({
 				autoStartLoad: true,
-				// The tile is ~516 CSS px; without this, ABR happily picks the
-				// 2160x2160 ladder rung (91MB for a 34s loop, vs 6MB at 768x768)
-				// and decodes 4x more pixels than the display can show.
 				capLevelToPlayerSize: true,
+				// H.264 ladder; the artwork has no use for 10-bit HEVC.
+				videoPreference: { videoCodec: "avc1", allowedVideoRanges: ["SDR"] },
+				maxDevicePixelRatio: ART_MAX_DPR,
 			});
 			this.hls = hls;
 			hls.loadSource(src);
 			hls.attachMedia(video);
+			hls.on(Hls.Events.LEVEL_SWITCHED, () => {
+				const fps = hls.levels[hls.currentLevel]?.frameRate;
+				if (fps && fps > 0) this.nativeFps = fps;
+				this.applyRate();
+			});
 			hls.on(Hls.Events.ERROR, (_evt, data) => {
 				if (!data.fatal) return;
 				this.fail(
@@ -246,6 +246,7 @@ export class AnimatedArtworkLayer {
 			return;
 		}
 		video.classList.add("rl-animated-art-visible");
+		this.applyRate();
 		this.ensurePlaying();
 	}
 
@@ -263,7 +264,6 @@ export class AnimatedArtworkLayer {
 		this.detach(false);
 	};
 
-	/** Respect settings + panel visibility when toggling play/pause. */
 	ensurePlaying(): void {
 		if (
 			this.artwork &&
@@ -279,20 +279,18 @@ export class AnimatedArtworkLayer {
 		}
 	}
 
-	/** Set whether the Now Playing view is currently visible on screen. */
 	setNowPlayingVisible(visible: boolean): void {
-		// Called from the 200ms activity tick: bail unless the state actually flipped.
+		// Called from the 200ms tick, so bail unless it actually flipped.
 		if (visible === this.nowPlayingVisible) return;
 		this.nowPlayingVisible = visible;
-		// Re-show has to resume explicitly: the view is hidden by CSS rather than
-		// unmounted, so the tile observer never fires and nothing else would restart it.
+		// Must resume explicitly; nothing else restarts a paused video.
 		this.ensurePlaying();
 	}
 
-	/** Keep the video mounted but re-evaluate play state (settings / visibility). */
 	refresh(): void {
 		if (!this.liveSrc) return;
 		if (settings.animatedArtwork) {
+			this.applyRate();
 			if (this.video) this.ensurePlaying();
 			else this.mountVideo(true);
 		} else {
@@ -312,7 +310,6 @@ export class AnimatedArtworkLayer {
 		}
 	}
 
-	/** Full teardown, including tile references. */
 	dispose(): void {
 		this.loadToken++;
 		this.fetchAbort?.abort();
@@ -321,7 +318,6 @@ export class AnimatedArtworkLayer {
 		this.resizeObs = null;
 		if (this.resizeRaf !== 0) cancelAnimationFrame(this.resizeRaf);
 		this.resizeRaf = 0;
-		// detach(true) keeps nothing on disk, but we are disposing
 		this.detach(false);
 		this.releaseMount();
 		this.tile = null;
diff --git a/plugins/radiant-lyrics-luna/src/index.ts b/plugins/radiant-lyrics-luna/src/index.ts
index de42ae3..aa33d8d 100644
--- a/plugins/radiant-lyrics-luna/src/index.ts
+++ b/plugins/radiant-lyrics-luna/src/index.ts
@@ -732,11 +732,10 @@ const setLayerRunning = (
 	if (now - pauseHiddenSince[slot] >= PAUSE_GRACE_MS) layer.setPaused(true);
 };
 
-// Cached so the 200ms activity tick does not re-run a document-wide
-// attribute-substring query; invalidated as soon as the node detaches.
+// Cached so the 200ms tick skips a document-wide query.
 let cachedNowPlayingPanel: HTMLElement | null = null;
 
-// Is the Now Playing view actually on screen? (visibility, not just mounted)
+// On screen, not just mounted.
 const artPanelVisible = (panel: HTMLElement): boolean => {
 	if (typeof panel.checkVisibility === "function") {
 		return panel.checkVisibility({ checkVisibilityCSS: true });
@@ -777,8 +776,7 @@ const syncBackdropActivity = (): void => {
 		now,
 	);
 
-	// Animated artwork only runs while the Now Playing view is visible.
-	// Guarded: without a layer there is nothing to tell, and this runs 5x/second.
+	// Only runs while the Now Playing view is visible. Guarded: this ticks 5x/second.
 	if (animatedArtworkLayer) {
 		if (!cachedNowPlayingPanel?.isConnected) {
 			cachedNowPlayingPanel = document.querySelector(
@@ -1048,15 +1046,9 @@ const updateRadiantLyricsBackdrop = function (): void {
 // MARKER: Animated Artwork (live artwork on the artwork tile)
 let animatedArtworkLayer: AnimatedArtworkLayer | null = null;
 let lastArtworkKey: string | null = null;
-// The tile element we have already reacted to, so the DOM observer stays O(1).
 let lastArtworkTile: Element | null = null;
 
-/**
- * Identity of a track's animated artwork. Animated art is an *album*
- * asset, so every track on one album shares it: keying by album means skipping
- * within an album neither refetches nor restarts the video. Falls back to the
- * title only when the album is unknown, which is the finest identity available.
- */
+/** Animated art is an album asset, so key by album and skips within one are free. */
 const artworkKey = (t: TrackInfo): string =>
 	t.album && t.album.trim() !== ""
 		? `${t.artist}\u0000${t.album.trim()}`
@@ -1077,7 +1069,7 @@ const updateAnimatedArtwork = async (
 	if (!animatedArtworkLayer) animatedArtworkLayer = new AnimatedArtworkLayer();
 	target ??= await getTrackInfo();
 	if (!target) return;
-	// Re-check after the await: another caller may have claimed this track already.
+	// Re-check after the await; another caller may have claimed this already.
 	if (!settings.animatedArtwork || !animatedArtworkLayer) return;
 	const key = artworkKey(target);
 	if (key === lastArtworkKey) {
@@ -1092,12 +1084,13 @@ const updateAnimatedArtwork = async (
 		target.artist,
 		target.album,
 	);
-	// No artwork tile was on screen (lyrics view not open yet) — clear the key so
-	// the tile observer can retry instead of treating this track as handled.
+	// No tile on screen yet; clear the key so the tile observer retries.
 	if (!done && lastArtworkKey === key) lastArtworkKey = null;
 };
 
 (window as any).updateAnimatedArtwork = updateAnimatedArtwork;
+(window as any).updateAnimatedArtworkRate = (): void =>
+	animatedArtworkLayer?.refresh();
 
 // Make these functions available globally so Settings can call them
 (window as any).updateRadiantLyricsStyles = updateRadiantLyricsStyles;
@@ -1133,9 +1126,7 @@ updateRadiantLyricsTextGlow();
 // Init global background
 updateCoverArtBackground(1);
 
-// Init animated artwork (handles already-playing track on startup).
-// Deferred: getTrackInfo() is a `const` declared further down this module, so
-// calling it during module evaluation would hit the uninitialised binding.
+// Deferred: getTrackInfo() is declared further down and would be uninitialised.
 queueMicrotask(() => void updateAnimatedArtwork());
 
 // Cleanups
@@ -1478,14 +1469,10 @@ function setupLyricsMenuObserver(): void {
 		}
 	});
 
-	// Animated artwork: the tile only exists once the Now Playing view is open,
-	// so the initial load has to run from here as well as on track change.
-	// `observe` is a document-wide childList MutationObserver, so this fires on
-	// virtually every DOM change. Bail synchronously unless the tile is genuinely
-	// new — anything heavier (or anything that mutates) would feed itself.
+	// The tile only exists once the view is open, so load from here too. This fires
+	// on nearly every DOM change, so bail synchronously unless the tile is new.
 	observe<HTMLElement>(unloads, ART_TILE_SELECTOR, (tile) => {
-		// Identity check only: cheap, and it stops us reacting to our own <video>
-		// insertion, whose mutation target (the tile's parent) re-matches the tile.
+		// Identity only; also stops us reacting to our own <video> insertion.
 		if (tile === lastArtworkTile) return;
 		lastArtworkTile = tile;
 		void updateAnimatedArtwork(undefined, true);

From d76ed2ce553f7a7dc870c0c56b1a6c6103ae8dcc Mon Sep 17 00:00:00 2001
From: Daniel <62436912+frostplexx@users.noreply.github.com>
Date: Fri, 2 Oct 2026 09:00:41 +0200
Subject: [PATCH 3/3] fix: animated artwork album cache poisoned by title-only
 fallback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Only cache artwork results that were matched by album. Previously the
first track looked up in an album decided the cached answer for every
other track: the title-only fallback (and its miss) was stored under the
album key, so later tracks in the album inherited it even when a
title-specific lookup would have found artwork.

fetchAnimatedArtwork now returns a scope key alongside the result — the
album key only when album-matched, else the title key. The dedupe skips
in artwork.ts and index.ts compare against that effective scope, so
skipping within an album stays free whenever the album matched.
---
 plugins/radiant-lyrics-luna/src/api.ts     | 50 ++++++++++++++------
 plugins/radiant-lyrics-luna/src/artwork.ts | 54 +++++++++++++---------
 plugins/radiant-lyrics-luna/src/index.ts   | 22 +++++++--
 3 files changed, 87 insertions(+), 39 deletions(-)

diff --git a/plugins/radiant-lyrics-luna/src/api.ts b/plugins/radiant-lyrics-luna/src/api.ts
index f2ae935..657f5ca 100644
--- a/plugins/radiant-lyrics-luna/src/api.ts
+++ b/plugins/radiant-lyrics-luna/src/api.ts
@@ -207,6 +207,21 @@ export interface AnimatedArtwork {
 	url_tall: string;
 }
 
+export interface ArtworkLookup {
+	artwork: AnimatedArtwork | null;
+	/**
+	 * Scope the result is valid for, as a dedupe key: the album key only when
+	 * the answer was matched by album. A title-only fallback (or a miss) is
+	 * specific to this track, so its key scopes to the title — the album's
+	 * other tracks must not inherit it.
+	 */
+	key: string;
+}
+
+/** Title-scoped artwork key: a result only valid for this exact track. */
+export const artworkTitleKey = (artist: string, title: string): string =>
+	`${artist}\u0000\u0000${title}`;
+
 function artworkSearchUrl(
 	title: string,
 	artist: string,
@@ -219,6 +234,8 @@ function artworkSearchUrl(
 }
 
 // Cached including misses; most tracks have none and the answer never changes.
+// Only album-matched results go under the album key — a title-only fallback
+// must not stand in for the album's other tracks (see ArtworkLookup).
 const animatedArtworkCache = new Map<string, AnimatedArtwork | null>();
 const ARTWORK_CACHE_MAX = 200;
 
@@ -227,14 +244,16 @@ export async function fetchAnimatedArtwork(
 	artist: string,
 	album?: string,
 	signal?: AbortSignal,
-): Promise<AnimatedArtwork | null> {
-	// Keyed by album, matching artworkKey() in index.ts.
-	const cacheKey =
-		album && album.trim() !== ""
-			? `${artist}\u0000${album.trim()}`
-			: `${artist}\u0000\u0000${title}`;
+): Promise<ArtworkLookup> {
+	const albumName = album?.trim() || "";
+	const albumPresent = albumName !== "";
+	// Album key, matching artworkKey() in index.ts; without an album the
+	// answer is only ever matched by title, so key by title directly.
+	const cacheKey = albumPresent
+		? `${artist}\u0000${albumName}`
+		: artworkTitleKey(artist, title);
 	if (animatedArtworkCache.has(cacheKey)) {
-		return animatedArtworkCache.get(cacheKey) ?? null;
+		return { artwork: animatedArtworkCache.get(cacheKey) ?? null, key: cacheKey };
 	}
 
 	const controller = new AbortController();
@@ -286,14 +305,17 @@ export async function fetchAnimatedArtwork(
 		const withAlbum = await tryFetch(
 			artworkSearchUrl(title, artist, album),
 		);
-		if (withAlbum) return remember(withAlbum);
-		if (album && album.trim() !== "") {
-			const withoutAlbum = await tryFetch(
-				artworkSearchUrl(title, artist),
-			);
-			if (withoutAlbum) return remember(withoutAlbum);
+		// Album-matched: cacheable, and its scope is the whole album.
+		if (withAlbum) return { artwork: remember(withAlbum), key: cacheKey };
+		if (albumPresent) {
+			// Album lookup missed: the title-only answer — hit or miss — is
+			// matched by title, so never cache it under the album key (that
+			// would poison the album's other tracks) and scope it to the title.
+			const artwork = await tryFetch(artworkSearchUrl(title, artist));
+			return { artwork, key: artworkTitleKey(artist, title) };
 		}
-		return remember(null);
+		// No album: the title key is already track-specific.
+		return { artwork: remember(null), key: cacheKey };
 	} finally {
 		clearTimeout(timeout);
 		signal?.removeEventListener("abort", onAbort);
diff --git a/plugins/radiant-lyrics-luna/src/artwork.ts b/plugins/radiant-lyrics-luna/src/artwork.ts
index 8d777a9..4d46912 100644
--- a/plugins/radiant-lyrics-luna/src/artwork.ts
+++ b/plugins/radiant-lyrics-luna/src/artwork.ts
@@ -6,7 +6,7 @@ import { Tracer } from "@luna/core";
 // Light build: no alt-audio/subtitles/EME needed here. Types in hls-light.d.ts.
 import Hls from "hls.js/light";
 
-import { fetchAnimatedArtwork } from "./api";
+import { artworkTitleKey, fetchAnimatedArtwork } from "./api";
 import { settings } from "./Settings";
 
 const { trace } = Tracer("[Radiant Lyrics]");
@@ -27,7 +27,10 @@ export class AnimatedArtworkLayer {
 	private resizeObs: ResizeObserver | null = null;
 	private resizeRaf = 0;
 	private artwork: { url: string; url_tall: string } | null = null;
-	/** See artworkKey() in index.ts. */
+	/**
+	 * Scope key of the displayed artwork (see fetchAnimatedArtwork): the album
+	 * key only when the answer was matched by album, else the title key.
+	 */
 	private artworkKey: string | null = null;
 	private liveSrc: string | null = null;
 	private loadToken = 0;
@@ -109,52 +112,61 @@ export class AnimatedArtworkLayer {
 
 	/**
 	 * Mount the artwork for `key`, leaving any playing video alone until a
-	 * replacement resolves. False means no tile was on screen, so retry later.
+	 * replacement resolves. `done: false` means no tile was on screen, so
+	 * retry later. Returns the scope `key` the result is valid under (see
+	 * fetchAnimatedArtwork), which may be narrower than the request key.
 	 */
 	async load(
 		key: string,
 		title: string,
 		artist: string,
 		album: string | undefined,
-	): Promise<boolean> {
-		// Already showing this album's artwork — keep playing, touch nothing.
-		if (key === this.artworkKey && this.artwork && this.video?.isConnected) {
+	): Promise<{ done: boolean; key: string }> {
+		// Already showing artwork that covers this track (album-matched, or the
+		// same track again) — keep playing, touch nothing.
+		if (
+			(key === this.artworkKey ||
+				artworkTitleKey(artist, title) === this.artworkKey) &&
+			this.artwork &&
+			this.video?.isConnected
+		) {
 			this.ensurePlaying();
-			return true;
+			return { done: true, key: this.artworkKey };
 		}
 		const token = ++this.loadToken;
 		this.fetchAbort?.abort();
 		this.fetchAbort = new AbortController();
 		const signal = this.fetchAbort.signal;
 
-		if (!settings.animatedArtwork) return true;
+		if (!settings.animatedArtwork) return { done: true, key };
 		// Only check a tile exists; host after the fetch so the old video keeps playing.
-		if (!document.querySelector<HTMLElement>(ART_TILE_SELECTOR)) return false;
+		if (!document.querySelector<HTMLElement>(ART_TILE_SELECTOR))
+			return { done: false, key };
 
-		const artwork = await fetchAnimatedArtwork(title, artist, album, signal);
-		if (token !== this.loadToken) return true;
-		if (!this.tileAlive()) return false;
+		const lookup = await fetchAnimatedArtwork(title, artist, album, signal);
+		if (token !== this.loadToken) return { done: true, key: lookup.key };
+		if (!this.tileAlive()) return { done: false, key: lookup.key };
 
-		if (!artwork) {
+		if (!lookup.artwork) {
 			trace.log(`Animated Artwork: no animated art for "${title}"`);
 			this.detach(false);
 			// After detach(), which clears the key too.
-			this.artworkKey = key;
-			return true;
+			this.artworkKey = lookup.key;
+			return { done: true, key: lookup.key };
 		}
 		// Same stream already on screen: adopt the key, leave the video be.
 		const unchanged =
-			this.artwork?.url === artwork.url &&
-			this.artwork?.url_tall === artwork.url_tall &&
+			this.artwork?.url === lookup.artwork.url &&
+			this.artwork?.url_tall === lookup.artwork.url_tall &&
 			this.video?.isConnected === true;
-		this.artwork = artwork;
-		this.artworkKey = key;
+		this.artwork = lookup.artwork;
+		this.artworkKey = lookup.key;
 		if (unchanged) {
 			this.ensurePlaying();
-			return true;
+			return { done: true, key: lookup.key };
 		}
 		this.mountVideo(false);
-		return true;
+		return { done: true, key: lookup.key };
 	}
 
 	/** Re-bind to the artwork tile after the Now Playing view (re)mounted. */
diff --git a/plugins/radiant-lyrics-luna/src/index.ts b/plugins/radiant-lyrics-luna/src/index.ts
index aa33d8d..83d199b 100644
--- a/plugins/radiant-lyrics-luna/src/index.ts
+++ b/plugins/radiant-lyrics-luna/src/index.ts
@@ -15,6 +15,7 @@ import {
 	type LyricsApiResponse,
 	type WordLine,
 	type WordTiming,
+	artworkTitleKey,
 	fetchLyrics as fetchLyricsApi,
 	flushLyrics as flushLyricsApi,
 	romanizeLyrics as romanizeLyricsApi,
@@ -1048,7 +1049,12 @@ let animatedArtworkLayer: AnimatedArtworkLayer | null = null;
 let lastArtworkKey: string | null = null;
 let lastArtworkTile: Element | null = null;
 
-/** Animated art is an album asset, so key by album and skips within one are free. */
+/**
+ * Request key for an animated-artwork lookup: album-scoped when an album is
+ * present (skips within one are free). A result may still be scoped tighter —
+ * see fetchAnimatedArtwork() — so skipping compares lastArtworkKey, the
+ * effective scope, not this request key.
+ */
 const artworkKey = (t: TrackInfo): string =>
 	t.album && t.album.trim() !== ""
 		? `${t.artist}\u0000${t.album.trim()}`
@@ -1072,20 +1078,28 @@ const updateAnimatedArtwork = async (
 	// Re-check after the await; another caller may have claimed this already.
 	if (!settings.animatedArtwork || !animatedArtworkLayer) return;
 	const key = artworkKey(target);
-	if (key === lastArtworkKey) {
+	// Free skip: the shown artwork's scope covers this track — it was matched
+	// by album (album key), or it is the same track again (title key).
+	if (
+		key === lastArtworkKey ||
+		artworkTitleKey(target.artist, target.title) === lastArtworkKey
+	) {
 		// Same artwork, but the view may have remounted underneath us.
 		if (rehost) animatedArtworkLayer.reattach();
 		return;
 	}
 	lastArtworkKey = key;
-	const done = await animatedArtworkLayer.load(
+	const res = await animatedArtworkLayer.load(
 		key,
 		target.title,
 		target.artist,
 		target.album,
 	);
+	// Adopt the effective scope — a title-matched result (or a miss) must not
+	// stand in for the album's other tracks — unless a newer trigger claimed.
+	if (lastArtworkKey === key) lastArtworkKey = res.key;
 	// No tile on screen yet; clear the key so the tile observer retries.
-	if (!done && lastArtworkKey === key) lastArtworkKey = null;
+	if (!res.done && lastArtworkKey === res.key) lastArtworkKey = null;
 };
 
 (window as any).updateAnimatedArtwork = updateAnimatedArtwork;