feat(enrichment): oximedia BPM/mood facts, mood search, and queue display (#863)

* feat(enrichment): oximedia BPM/mood facts, mood search, and queue UI

Run client-side oximedia analysis after CPU seed and persist BPM, mood JSON,
and searchable mood_tag facts. Add product mood groups (joy/sadness/dance/work/
romance) with Advanced Search filter on the local index, queue BPM/mood display,
migration 008 mood_tag index, and refreshed licenses for oximedia crates.

* fix(enrichment): keep mood_groups module comment in English

* feat(search): virtual mood groups, anger filter, and Advanced Search UX

Expand mood search via overlapping virtual groups (tag expansion only),
add anger/Злость group, skip album/artist shortcuts for track-only filters,
and simplify mood search UI (songs-only, hide type tabs). Fix CustomSelect
spurious scrollbar on short option lists.

* feat(analysis): unified track analysis plan and enqueue path

Add TrackAnalysisPlan (waveform, LUFS, enrichment) with a single
enqueue_track_analysis entry for all byte-backed triggers. Run enrichment
when cache is full but library facts are missing; route playback, cache,
and backfill through the planner. Fix browseTextSearch LocalSearchOpts tsc
gap and remove obsolete read_seed_bytes_if_needed helper.

* fix(analysis): wire playback dispatch, preload enrichment, and UI refresh

Route stream, gapless, preload, and local-file playback through analysis_dispatch
so BPM/mood enrichment runs when waveform/LUFS are already cached. Fix audio_preload
cache-hit and hot-cache paths, emit preload-cancelled for retry, and add
analysis:enrichment-updated plus content_cache_coverage key resolution.

* fix(audio): preload local files from disk and stop analysis retry loop

Seed hot/offline next tracks via LocalFilePlayback (512 MiB) instead of copying
into the RAM preload slot. Keep bytePreloadingId set after preload-ready so
progress ticks do not re-invoke audio_preload every second.

* fix(enrichment): clippy, album bpm filter routing, and queue mood display

Clippy-clean analysis_dispatch and engine imports; restrict track-derived album
routing to mood_group/mood_tag only so bpm is skipped on album queries. Log
enrichment plan errors with retry-all plan; filter queue mood labels to oximedia ids.

* fix(enrichment): simplify mood_tag backfill branch in plan_track_enrichment

Remove empty if-block; keep same behaviour when backfill fails and moods row exists.

* docs: CHANGELOG and credits for track enrichment PR #863

* docs(credits): track enrichment PR #863 contributor line

* chore(enrichment): clippy-clean plan branch and trim dead exports

Collapse mood_tag backfill if for clippy; remove unused moodGroupById and
OXIMEDIA_MOOD_LABELS re-exports; stop poll when server BPM is already known.

* fix(enrichment): close R2/S1–S3 limits and Song Info BPM fallback

Return TrackEnrichmentOutcome::Failed on oximedia errors so retries are not
masked as complete; extract mood Advanced Search SQL, unify top-3 mood tag
selection in mood_groups with TS invariant tests, and show measured BPM in
Song Info when tag BPM is missing or zero.

* fix(enrichment): restore offline coverage and show mood in Song Info

Add unit tests for offline download cancel/clear registry after the analysis
seed refactor dropped read_seed_bytes coverage; show localized mood labels in
Song Info when library enrichment facts exist.

* fix(enrichment): soft mood scoring and unblock offline cancel tests

Replace oximedia quadrant happy/excited mapping with valence/arousal
soft scores across all mood tags for display, storage, and backfill;
fix offline cancel unit tests that deadlocked by calling clear while
holding the global offline_cancel_flags mutex.

* fix(enrichment): dedupe joy cluster and cap mood display at two labels

Never show happy and excited together; pick one tag per V/A cluster,
tighten oximedia recalibration, and limit queue/Song Info to two moods
that pass a relative score floor.

* fix(enrichment): disable oximedia mood labels in UI and search tags

Oximedia 0.1.7 mood is a spectral energy heuristic, not independent mood
weights; valence correlates with loud/bright audio and false-labels metal
and lyrical tracks as happy. Hide queue/Song Info mood and stop writing
mood_tag facts until a reliable detector lands; keep V/A/moods JSON stored.

* fix(enrichment): disable oximedia mood analysis and add BPM advanced search

Stop planning, running, and storing oximedia mood facts; purge accumulated
mood rows via migration 009. Hide mood filters in Advanced Search, expose
BPM range filter with dual-storage resolution, and show a BPM column in song
results when that filter is active.

* feat(search): analysis BPM priority, source tooltip, and filter UX

Prefer analysis track_fact over file tags for BPM resolution; show source
in list tooltips. Validate BPM range on blur, add clear button, fix double tooltip.

* fix(enrichment): prefer analysis BPM in Song Info and queue tech row

Show measured track_fact BPM before file tags until analysis completes;
pick the highest-confidence analysis fact when several exist.

src/components/CustomSelect.tsx

@@ -30,10 +30,13 @@ export default function CustomSelect({ value, options, onChange, className = '',
     if (!triggerRef.current) return;
     const rect = triggerRef.current.getBoundingClientRect();
     const MARGIN = 6;
-    const maxH = 240;
+    const maxH = 320;
     const spaceBelow = window.innerHeight - rect.bottom - MARGIN;
     const spaceAbove = rect.top - MARGIN;
     const useAbove = spaceBelow < 80 && spaceAbove > spaceBelow;
+    const viewportCap = Math.min(maxH, useAbove ? spaceAbove : spaceBelow);
+    const contentH = listRef.current?.scrollHeight ?? 0;
+    const needsScroll = contentH > viewportCap;
     setDropStyle({
       position: 'fixed',
       left: rect.left,
@@ -41,7 +44,8 @@ export default function CustomSelect({ value, options, onChange, className = '',
       ...(useAbove
         ? { bottom: window.innerHeight - rect.top + MARGIN }
         : { top: rect.bottom + MARGIN }),
-      maxHeight: Math.min(maxH, useAbove ? spaceAbove : spaceBelow),
+      maxHeight: needsScroll ? viewportCap : contentH || viewportCap,
+      overflowY: needsScroll ? 'auto' : 'hidden',
       zIndex: 99998,
     });
   };
@@ -49,7 +53,10 @@ export default function CustomSelect({ value, options, onChange, className = '',
   useLayoutEffect(() => {
     if (!open) return;
     updateDropStyle();
-  }, [open]);
+    // Re-measure after layout so short lists (e.g. mood groups) don't get a spurious scrollbar.
+    const id = requestAnimationFrame(updateDropStyle);
+    return () => cancelAnimationFrame(id);
+  }, [open, options]);
 
   useEffect(() => {
     if (!open) return;

src/components/PagedSongList.tsx

@@ -10,6 +10,8 @@ interface Props {
   loadingMore: boolean;
   /** Fetch the next page. Called as the sentinel nears the viewport. */
   onLoadMore: () => void;
+  /** Show a BPM column (Advanced Search when the BPM filter is active). */
+  showBpm?: boolean;
 }
 
 /**
@@ -19,7 +21,7 @@ interface Props {
  * one chrome + paging path (no transform-positioned rows, so the sticky header
  * is never painted over — issue #841).
  */
-export default function PagedSongList({ songs, hasMore, loadingMore, onLoadMore }: Props) {
+export default function PagedSongList({ songs, hasMore, loadingMore, onLoadMore, showBpm }: Props) {
   const sentinelRef = useRef<HTMLDivElement>(null);
 
   // Re-observe whenever `onLoadMore` changes identity (callers rebuild it after
@@ -36,9 +38,9 @@ export default function PagedSongList({ songs, hasMore, loadingMore, onLoadMore
 
   return (
     <>
-      <SongListHeader />
+      <SongListHeader showBpm={showBpm} />
       {songs.map(song => (
-        <SongRow key={song.id} song={song} />
+        <SongRow key={song.id} song={song} showBpm={showBpm} />
       ))}
       {hasMore && (
         <div ref={sentinelRef} style={{ display: 'flex', justifyContent: 'center', padding: '1rem' }}>

src/components/SongInfoModal.tsx

@@ -1,4 +1,5 @@
 import { getSong } from '../api/subsonicLibrary';
+import { libraryGetFacts } from '../api/library';
 import type { SubsonicSong } from '../api/subsonicTypes';
 import React, { useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
@@ -7,11 +8,19 @@ import { usePlayerStore } from '../store/playerStore';
 import { useShallow } from 'zustand/react/shallow';
 import { ndGetSongPath } from '../api/navidromeAdmin';
 import { useAuthStore } from '../store/authStore';
+import { useLibraryIndexStore } from '../store/libraryIndexStore';
 import { useTranslation } from 'react-i18next';
 import { copyTextToClipboard } from '../utils/server/serverMagicString';
 import { showToast } from '../utils/ui/toast';
 import { formatTrackTime } from '../utils/format/formatDuration';
 import { formatLastSeen } from '../utils/componentHelpers/userMgmtHelpers';
+import { libraryIsReady } from '../utils/library/libraryReady';
+import {
+  formatQueueMoodLabels,
+  parseTrackEnrichmentFacts,
+  resolveQueueBpm,
+  type ParsedTrackEnrichment,
+} from '../utils/library/trackEnrichment';
 import i18n from '../i18n';
 
 function formatSize(bytes?: number): string | null {
@@ -61,6 +70,7 @@ export default function SongInfoModal() {
     useShallow(s => ({ songInfoModal: s.songInfoModal, closeSongInfo: s.closeSongInfo }))
   );
   const [song, setSong] = useState<SubsonicSong | null>(null);
+  const [enrichment, setEnrichment] = useState<ParsedTrackEnrichment | null>(null);
   const [loading, setLoading] = useState(false);
   // Absolute filesystem path resolved via Navidrome's native API in parallel
   // with the Subsonic getSong call. Subsonic only ever returns a relative
@@ -71,16 +81,40 @@ export default function SongInfoModal() {
   useEffect(() => {
     if (!songInfoModal.isOpen || !songInfoModal.songId) {
       setSong(null);
+      setEnrichment(null);
       setAbsolutePath(null);
       return;
     }
     let cancelled = false;
     setLoading(true);
+    setEnrichment(null);
     setAbsolutePath(null);
     const songId = songInfoModal.songId;
-    getSong(songId).then(s => {
-      if (!cancelled) { setSong(s); setLoading(false); }
-    });
+    void (async () => {
+      const s = await getSong(songId);
+      if (cancelled) return;
+      setSong(s);
+      setLoading(false);
+      if (!s) {
+        setEnrichment(null);
+        return;
+      }
+      const auth = useAuthStore.getState();
+      const sid = auth.activeServerId;
+      const indexEnabled = sid ? useLibraryIndexStore.getState().isIndexEnabled(sid) : false;
+      if (sid && indexEnabled && await libraryIsReady(sid)) {
+        try {
+          const facts = await libraryGetFacts(sid, songId);
+          if (!cancelled) {
+            setEnrichment(parseTrackEnrichmentFacts(facts, s.bpm ?? null));
+          }
+        } catch {
+          if (!cancelled) setEnrichment(null);
+        }
+      } else if (!cancelled) {
+        setEnrichment(null);
+      }
+    })();
     // Try the native API in parallel; only when the active server is Navidrome
     // and we have credentials. Failures are silent — modal falls back to
     // whatever the Subsonic `path` field carried (typically nothing).
@@ -124,6 +158,17 @@ export default function SongInfoModal() {
   const hasReplayGain = song?.replayGain &&
     (song.replayGain.trackGain !== undefined || song.replayGain.albumGain !== undefined);
 
+  const displayBpm = song
+    ? resolveQueueBpm(
+      enrichment ?? {
+        serverBpm: song.bpm != null && song.bpm > 0 ? song.bpm : null,
+        measuredBpm: null,
+        moodLabels: [],
+      },
+    )
+    : null;
+  const displayMood = enrichment ? formatQueueMoodLabels(enrichment.moodLabels, t) : null;
+
   return createPortal(
     <>
       <div className="song-info-backdrop" onClick={closeSongInfo} />
@@ -151,7 +196,8 @@ export default function SongInfoModal() {
                 <Row label={t('songInfo.genre')} value={song.genre} />
                 <Row label={t('songInfo.duration')} value={formatTrackTime(song.duration)} />
                 <Row label={t('songInfo.track')} value={trackLabel} />
-                <Row label={t('songInfo.bpm')} value={song.bpm} />
+                <Row label={t('songInfo.bpm')} value={displayBpm} />
+                <Row label={t('songInfo.mood')} value={displayMood} />
                 <Row label={t('songInfo.playCount')} value={song.playCount} />
                 <Row label={t('songInfo.lastPlayed')} value={song.played ? formatLastSeen(song.played, i18n.language, '—') : null} />
 

src/components/SongRow.tsx

@@ -12,10 +12,12 @@ import { formatTrackTime } from '../utils/format/formatDuration';
 
 interface Props {
   song: SubsonicSong;
+  showBpm?: boolean;
 }
 
-function SongRow({ song }: Props) {
+function SongRow({ song, showBpm }: Props) {
   const navigate = useNavigate();
+  const { t } = useTranslation();
   const enqueue = usePlayerStore(s => s.enqueue);
   const openContextMenu = usePlayerStore(s => s.openContextMenu);
   const isCurrent = usePlayerStore(s => s.currentTrack?.id === song.id);
@@ -34,9 +36,16 @@ function SongRow({ song }: Props) {
     enqueue([songToTrack(song)]);
   };
 
+  const bpmTooltip =
+    song.localBpmSource === 'analysis'
+      ? t('search.bpmSourceAnalysis')
+      : song.localBpmSource === 'tag'
+        ? t('search.bpmSourceTag')
+        : undefined;
+
   return (
     <div
-      className={`song-list-row${isCurrent ? ' is-current' : ''}`}
+      className={`song-list-row${isCurrent ? ' is-current' : ''}${showBpm ? ' song-list-row--with-bpm' : ''}`}
       onDoubleClick={handlePlay}
       onContextMenu={(e) => {
         e.preventDefault();
@@ -102,21 +111,35 @@ function SongRow({ song }: Props) {
       <div className="song-list-row-cell song-list-row-genre truncate" title={song.genre ?? ''}>
         {song.genre ?? '—'}
       </div>
+      {showBpm && (
+        <div
+          className="song-list-row-cell song-list-row-bpm"
+          data-tooltip={bpmTooltip}
+        >
+          {song.bpm != null && song.bpm > 0 ? song.bpm : '—'}
+        </div>
+      )}
       <div className="song-list-row-cell song-list-row-duration">{formatTrackTime(song.duration, '–')}</div>
     </div>
   );
 }
 
 /** Column header with the same grid as <SongRow>. Optional — pages can render it above the list. */
-export function SongListHeader() {
+export function SongListHeader({ showBpm }: { showBpm?: boolean } = {}) {
   const { t } = useTranslation();
   return (
-    <div className="song-list-row song-list-row--header" role="row">
+    <div
+      className={`song-list-row song-list-row--header${showBpm ? ' song-list-row--with-bpm' : ''}`}
+      role="row"
+    >
       <div className="song-list-row-cell song-list-row-actions" />
       <div className="song-list-row-cell">{t('albumDetail.trackTitle')}</div>
       <div className="song-list-row-cell">{t('albumDetail.trackArtist')}</div>
       <div className="song-list-row-cell">{t('albumDetail.trackAlbum')}</div>
       <div className="song-list-row-cell">{t('randomMix.trackGenre')}</div>
+      {showBpm && (
+        <div className="song-list-row-cell song-list-row-bpm">{t('albumDetail.trackBpm')}</div>
+      )}
       <div className="song-list-row-cell song-list-row-duration">{t('albumDetail.trackDuration')}</div>
     </div>
   );

src/components/queuePanel/QueueCurrentTrack.tsx

@@ -10,6 +10,8 @@ import {
 } from '../../utils/componentHelpers/queuePanelHelpers';
 import { loudnessGainPlaceholderUntilCacheDb } from '../../utils/audio/loudnessPlaceholder';
 import { effectiveLoudnessPreAnalysisAttenuationDb } from '../../utils/audio/loudnessPreAnalysisSlider';
+import { formatQueueBpmTech, formatQueueMoodLabels } from '../../utils/library/trackEnrichment';
+import { useQueueTrackEnrichment } from '../../hooks/useQueueTrackEnrichment';
 import { QueueLufsTargetMenu } from './QueueLufsTargetMenu';
 import { PlaybackBufferingOverlay } from '../playback/PlaybackBufferingOverlay';
 import { usePlayerStore } from '../../store/playerStore';
@@ -48,6 +50,9 @@ export function QueueCurrentTrack({
   lufsTgtBtnRef, lufsTgtMenuRef, lufsTgtPopStyle, t,
 }: Props) {
   const showBufferingOverlay = usePlayerStore(s => s.isPlaybackBuffering);
+  const enrichment = useQueueTrackEnrichment(currentTrack.id);
+  const bpmTech = formatQueueBpmTech(enrichment, t);
+  const moodLine = formatQueueMoodLabels(enrichment.moodLabels, t);
   return (
     <div className="queue-current-track">
       {(() => {
@@ -62,6 +67,7 @@ export function QueueCurrentTrack({
             if (sr) return sr;
             return undefined;
           })(),
+          bpmTech ?? undefined,
         ].filter(Boolean) as string[];
         const rgParts = formatQueueReplayGainParts(currentTrack, t);
         const baseLine = baseParts.join(' · ');
@@ -86,7 +92,7 @@ export function QueueCurrentTrack({
         })();
         const tgtNum = normalizationTargetLufs ?? authLoudnessTargetLufs;
         const targetLabel = `${tgtNum} LUFS`;
-        if (!baseLine && !rgLine && !playbackSource) return null;
+        if (!baseLine && !rgLine && !playbackSource && !bpmTech) return null;
         const showRgLine = !isLoudnessActive && expandReplayGain && !!rgLine;
         const showLufsLine = isLoudnessActive && expandReplayGain;
         return (
@@ -215,6 +221,9 @@ export function QueueCurrentTrack({
           {currentTrack.year && (
             <div className="queue-current-sub">{currentTrack.year}</div>
           )}
+          {moodLine && (
+            <div className="queue-current-sub queue-current-enrichment">{moodLine}</div>
+          )}
           {(() => {
             const label = orbitAttributionLabel(currentTrack.id);
             return label ? <div className="queue-current-sub queue-current-attribution">{label}</div> : null;