v1.4.1: bug fixes, enrichment resilience, frontend lint cleanup

Audio & Playback:
- Fix doubled audio on track change (destroy old Howl before creating new)
- Fix play/pause visual desync by using Howler state as source of truth

Soulseek & Downloads:
- Fix Soulseek download 400 error (closes #101)
- Expand Soulseek documentation (closes #27)

Enrichment & Analysis:
- Fix CLAP analyzer clobbering Essentia analysisStatus (root cause of #79)
- Add embedding check to both Python analyzers before resetting tracks
- Set analysisStartedAt when marking tracks as processing
- Clear analysisStartedAt on successful completion
- Include vibe embeddings in isFullyComplete check
- Add keepPreviousData to enrichment progress query for UI resilience
- Shut down idle worker pool to free ~5.6 GB when no work pending
- Fix compilation matching for multi-disc albums (closes #70)
- Add podcast auto-refresh in enrichment cycle (closes #81)

Admin & Auth:
- Add admin password reset via env var (closes #97)
- Add retry failed analysis button in settings (closes #79)
- Add requireAdmin to onboarding config and cleanup routes
- Remove userId from 2FA challenge response

Queue & UI:
- Fix cancelJob/refreshJobMatches not persisting state
- Fix discovery polling leak on batch failure
- Fix withTimeout timer leak in enrichment worker
- Fix useAlbumData infinite re-render loop
- Fix unhandled audio.play() promise rejection

Performance:
- Eliminate N+1 queries in recommendation endpoints
- Idle Essentia worker pool shutdown (8 processes, ~5.6 GB freed)

Frontend Quality:
- Fix all 377 ESLint errors and warnings (0 remaining)
- Fix Rules of Hooks, setState-in-effect, exhaustive-deps
- Type api.ts and 50+ files (remove explicit any)
- Remove 1664 lines of dead code and duplicates
- Extract shared utilities from duplicated patterns

Author: Your Name

CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to Lidify will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.1] - 2026-02-06
+
+### Fixed
+
+- **Doubled audio stream on next-track:** Fixed race condition where clicking next/previous played two streams simultaneously by making track-change cleanup synchronous and guarding the play/pause effect during loading
+- **Soulseek download returns 400 (#101):** Frontend now sends parsed title to the download endpoint; backend derives artist/title from filename when not provided instead of rejecting the request
+- **Admin password reset (#97):** Added `ADMIN_RESET_PASSWORD` environment variable support -- set it and restart to reset the admin password, then remove the variable
+- **Retry failed audio analysis UI (#79):** Added "Retry Failed Analysis" button in Settings that resets permanently failed tracks back to pending for re-processing
+- **Podcast auto-refresh (#81):** Podcasts now automatically refresh during the enrichment cycle (hourly), checking RSS feeds for new episodes without manual intervention
+- **Compilation track matching (#70):** Added title-only fallback matching strategy for playlist reconciliation -- when album artist doesn't match (e.g. "Various Artists" compilations), tracks are matched by title with artist similarity scoring
+- **Soulseek documentation (#27):** Expanded README with detailed Soulseek integration documentation covering setup, search, download workflow, and limitations
+- **Admin route hardening:** Added `requireAdmin` middleware to onboarding config routes and stale job cleanup endpoint
+- **2FA userId leak:** Removed userId from 2FA challenge response (information disclosure)
+- **Queue bugs:** Fixed cancelJob/refreshJobMatches not persisting state, clear button was no-op, reorder not restarting track, shuffle indices not updating on removeFromQueue
+- **Infinite re-render:** Fixed useAlbumData error handling causing infinite re-render loop
+- **2FA status not loading:** Fixed AccountSection not loading 2FA status on mount
+- **Password change error key mismatch:** Fixed error key mismatch in AccountSection password change handler
+- **Discovery polling leak:** Fixed polling never stopping on batch failure
+- **Timer leak:** Fixed withTimeout not clearing timer in enrichment worker
+- **Audio play rejection:** Fixed unhandled promise rejection on audio.play()
+- **Library tab validation:** Added tab parameter validation in library page
+- **Onboarding state:** Separated success/error state in onboarding page
+- **Audio analysis race condition (#79):** CLAP analyzer was clobbering Essentia's `analysisStatus` field, causing completed tracks to be reset and permanently failed after 3 cycles; both Python analyzers now check for existing embeddings before resetting
+- **Enrichment completion check:** `isFullyComplete` now includes CLAP vibe embeddings, not just audio analysis
+- **Enrichment UI resilience:** Added `keepPreviousData` and loading/error states to enrichment progress query so the settings block doesn't vanish on failed refetch
+
+### Performance
+
+- **Recommendation N+1 queries:** Eliminated N+1 queries in all 3 recommendation endpoints (60+ queries down to 3-5)
+- **Idle worker pool shutdown:** Essentia analyzer shuts down its 8-worker process pool (~5.6 GB) after idle period, lazily restarts when work arrives
+
+### Changed
+
+- **Shared utility consolidation:** Replaced 10 inline `formatDuration` copies with shared `formatTime`/`formatDuration`, extracted `formatNumber` to shared utility, consolidated inline Fisher-Yates shuffle with shared `shuffleArray`
+- **Player hook extraction:** Extracted shared `useMediaInfo` hook, eliminating ~120 lines of duplicated media info logic across MiniPlayer, FullPlayer, and OverlayPlayer
+- **Preview hook consolidation:** Consolidated artist/album preview hooks into shared `useTrackPreview`
+- **Redundant logging cleanup:** Removed console.error calls redundant with toast notifications or re-thrown errors
+
+### Removed
+
+- Dead player files: VibeOverlay, VibeGraph, VibeOverlayContainer, enhanced-vibe-test page
+- Dead code: trackEnrichment.ts, discover/types/index.ts, unused artist barrel file
+- Unused exports: `playTrack` from useLibraryActions, `useTrackDisplayData`/`TrackDisplayData` from useMetadataDisplay
+- Unused `streamLimiter` middleware
+- Deprecated `radiosByGenre` from browse API (Deezer radio requires account; internal library radio used instead)
+
 ## [1.4.0] - 2026-02-05
 
 ### Performance

README.md

@@ -515,16 +515,39 @@ Connect to your Audiobookshelf instance to browse and listen to audiobooks withi
 
 ### Soulseek
 
-For finding rare tracks and one-offs that aren't available through traditional sources, Lidify has built-in Soulseek support.
+Lidify includes built-in Soulseek support for finding rare tracks and one-offs that aren't available through traditional download sources like Lidarr.
+
+[Soulseek](https://www.slsknet.org/) is a peer-to-peer file sharing network focused on music. Users share their music libraries and can browse/download from each other. Lidify connects directly to the Soulseek network -- no additional software (like slskd) is required.
 
 **Setup:**
 
 1. Go to Settings in Lidify
 2. Navigate to the Soulseek section
-3. Enter your Soulseek username and password
+3. Enter your Soulseek username and password (create an account at [slsknet.org](https://www.slsknet.org/) if you don't have one)
 4. Save your settings
 
-Lidify connects directly to the Soulseek network - no additional software required.
+**How Search Works:**
+
+When you search for music in Lidify's Discovery tab, Soulseek results appear alongside Last.fm and Deezer results. Each result shows the filename, file size, bitrate, and format (FLAC/MP3). Metadata like artist and album is parsed from the file path structure (typically `Artist/Album/01 - Track.flac`).
+
+**How Download Works:**
+
+1. Click the download button on a Soulseek search result
+2. Lidify searches the Soulseek network for the best match (preferring FLAC, high bitrate)
+3. The file is downloaded directly to your music library path
+4. A library scan is triggered to import the new file
+5. Metadata enrichment runs automatically (artist info, mood tags, audio analysis)
+
+You can also configure Soulseek as a download source for playlist imports. In Settings > Downloads, set Soulseek as primary or fallback source. When importing a Spotify/Deezer playlist, tracks not found in your library will be searched and downloaded from Soulseek automatically.
+
+**Download progress** is visible in the Activity Panel (bell icon in the top bar).
+
+**Limitations:**
+
+- Download speed depends on the sharing user's connection and availability
+- Not all tracks will have results -- Soulseek coverage varies by genre and popularity
+- Some users may have slow connections or go offline during transfers
+- Lidify retries with alternative users if a download fails or times out
 
 ---
 

backend/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lidify-backend",
-    "version": "1.4.0",
+    "version": "1.4.1",
     "description": "Lidify backend API server",
     "license": "GPL-3.0",
     "repository": {

backend/src/index.ts

@@ -45,7 +45,6 @@ import { requireAuth, requireAdmin } from "./middleware/auth";
 import {
     authLimiter,
     apiLimiter,
-    streamLimiter,
     imageLimiter,
 } from "./middleware/rateLimiter";
 import swaggerUi from "swagger-ui-express";
@@ -246,11 +245,33 @@ async function checkRedisConnection() {
     }
 }
 
+async function checkPasswordReset() {
+    const resetPassword = process.env.ADMIN_RESET_PASSWORD;
+    if (!resetPassword) return;
+
+    const bcrypt = await import("bcrypt");
+    const adminUser = await prisma.user.findFirst({ where: { role: "ADMIN" } });
+    if (!adminUser) {
+        logger.warn("[Password Reset] No admin user found");
+        return;
+    }
+
+    const hashedPassword = await bcrypt.hash(resetPassword, 10);
+    await prisma.user.update({
+        where: { id: adminUser.id },
+        data: { passwordHash: hashedPassword },
+    });
+    logger.warn("[Password Reset] Admin password has been reset via ADMIN_RESET_PASSWORD env var. Remove this env var and restart.");
+}
+
 app.listen(config.port, "0.0.0.0", async () => {
     // Verify database connections before proceeding
     await checkPostgresConnection();
     await checkRedisConnection();
 
+    // Check for admin password reset
+    await checkPasswordReset();
+
     logger.debug(
         `Lidify API running on port ${config.port} (accessible on all network interfaces)`
     );

backend/src/middleware/rateLimiter.ts

@@ -47,15 +47,6 @@ export const authLimiter = rateLimit({
     ...trustProxyValidation,
 });
 
-// Media streaming limiter (higher limit: 200 streams/minute)
-export const streamLimiter = rateLimit({
-    windowMs: 1 * 60 * 1000, // 1 minute
-    max: 200, // Allow 200 stream requests per minute
-    message: "Too many streaming requests, please slow down.",
-    standardHeaders: true,
-    legacyHeaders: false,
-    ...trustProxyValidation,
-});
 
 // Image/Cover art limiter (very high limit: 500 req/minute)
 // This is for image proxying - not a security risk, just bandwidth

backend/src/routes/auth.ts

@@ -88,7 +88,6 @@ router.post("/login", async (req, res) => {
                 return res.status(200).json({
                     requires2FA: true,
                     message: "2FA token required",
-                    userId: user.id, // Send userId for next 2FA request
                 });
             }
 

backend/src/routes/browse.ts

@@ -344,9 +344,8 @@ router.get("/all", async (req, res) => {
 
         res.json({
             playlists: playlists.map(deezerPlaylistToUnified),
-            radios: [], // Radio stations are now internal (use /api/library/radio)
+            radios: [],
             genres,
-            radiosByGenre: [], // Deprecated - use internal radios
             source: "deezer",
         });
     } catch (error: any) {

backend/src/routes/library.ts

@@ -1784,11 +1784,7 @@ router.get("/tracks/shuffle", async (req, res) => {
                     },
                 },
             });
-            // Fisher-Yates shuffle
-            for (let i = tracksData.length - 1; i > 0; i--) {
-                const j = Math.floor(Math.random() * (i + 1));
-                [tracksData[i], tracksData[j]] = [tracksData[j], tracksData[i]];
-            }
+            tracksData = shuffleArray(tracksData);
         } else {
             // For large libraries, use database-level randomization
             // Get random track IDs first (efficient, O(limit) memory)

backend/src/routes/onboarding.ts

@@ -7,7 +7,7 @@ import axios from "axios";
 import crypto from "crypto";
 import { encryptField } from "../utils/systemSettings";
 import { writeEnvFile } from "../utils/envWriter";
-import { generateToken, requireAuth } from "../middleware/auth";
+import { generateToken, requireAuth, requireAdmin } from "../middleware/auth";
 
 const router = Router();
 
@@ -164,7 +164,7 @@ router.post("/register", async (req, res) => {
  * POST /onboarding/lidarr
  * Step 2a: Configure Lidarr integration
  */
-router.post("/lidarr", requireAuth, async (req, res) => {
+router.post("/lidarr", requireAuth, requireAdmin, async (req, res) => {
     try {
         const config = lidarrConfigSchema.parse(req.body);
 
@@ -243,7 +243,7 @@ router.post("/lidarr", requireAuth, async (req, res) => {
  * POST /onboarding/audiobookshelf
  * Step 2b: Configure Audiobookshelf integration
  */
-router.post("/audiobookshelf", requireAuth, async (req, res) => {
+router.post("/audiobookshelf", requireAuth, requireAdmin, async (req, res) => {
     try {
         const config = audiobookshelfConfigSchema.parse(req.body);
 
@@ -319,7 +319,7 @@ router.post("/audiobookshelf", requireAuth, async (req, res) => {
  * POST /onboarding/soulseek
  * Step 2c: Configure Soulseek integration (direct connection via slsk-client)
  */
-router.post("/soulseek", requireAuth, async (req, res) => {
+router.post("/soulseek", requireAuth, requireAdmin, async (req, res) => {
     try {
         const config = soulseekConfigSchema.parse(req.body);
 
@@ -377,7 +377,7 @@ router.post("/soulseek", requireAuth, async (req, res) => {
  * POST /onboarding/enrichment
  * Step 3: Configure metadata enrichment
  */
-router.post("/enrichment", requireAuth, async (req, res) => {
+router.post("/enrichment", requireAuth, requireAdmin, async (req, res) => {
     try {
         const config = enrichmentConfigSchema.parse(req.body);
 

backend/src/routes/podcasts.ts

@@ -787,78 +787,22 @@ router.get("/:id/refresh", async (req, res) => {
         logger.debug(`\n [PODCAST] Refresh request`);
         logger.debug(`   Podcast ID: ${id}`);
 
-        const podcast = await prisma.podcast.findUnique({
-            where: { id },
-        });
-
-        if (!podcast) {
-            return res.status(404).json({ error: "Podcast not found" });
-        }
-
-        // Parse RSS feed
-        logger.debug(`   Parsing RSS feed...`);
-        const { podcast: podcastData, episodes } =
-            await rssParserService.parseFeed(podcast.feedUrl);
-
-        // Update podcast metadata
-        await prisma.podcast.update({
-            where: { id },
-            data: {
-                title: podcastData.title,
-                author: podcastData.author,
-                description: podcastData.description,
-                imageUrl: podcastData.imageUrl,
-                language: podcastData.language,
-                explicit: podcastData.explicit || false,
-                episodeCount: episodes.length,
-                lastRefreshed: new Date(),
-            },
-        });
-
-        // Add new episodes (skip duplicates)
-        let newEpisodesCount = 0;
-        for (const ep of episodes) {
-            const existing = await prisma.podcastEpisode.findUnique({
-                where: {
-                    podcastId_guid: {
-                        podcastId: id,
-                        guid: ep.guid,
-                    },
-                },
-            });
-
-            if (!existing) {
-                await prisma.podcastEpisode.create({
-                    data: {
-                        podcastId: id,
-                        guid: ep.guid,
-                        title: ep.title,
-                        description: ep.description,
-                        audioUrl: ep.audioUrl,
-                        duration: ep.duration,
-                        publishedAt: ep.publishedAt,
-                        episodeNumber: ep.episodeNumber,
-                        season: ep.season,
-                        imageUrl: ep.imageUrl,
-                        fileSize: ep.fileSize,
-                        mimeType: ep.mimeType,
-                    },
-                });
-                newEpisodesCount++;
-            }
-        }
+        const result = await refreshPodcastFeed(id);
 
         logger.debug(
-            `   Refresh complete. ${newEpisodesCount} new episodes added.`
+            `   Refresh complete. ${result.newEpisodesCount} new episodes added.`
         );
 
         res.json({
             success: true,
-            newEpisodesCount,
-            totalEpisodes: episodes.length,
-            message: `Found ${newEpisodesCount} new episodes`,
+            newEpisodesCount: result.newEpisodesCount,
+            totalEpisodes: result.totalEpisodes,
+            message: `Found ${result.newEpisodesCount} new episodes`,
         });
     } catch (error: any) {
+        if (error.message?.includes("not found")) {
+            return res.status(404).json({ error: "Podcast not found" });
+        }
         logger.error("Error refreshing podcast:", error);
         res.status(500).json({
             error: "Failed to refresh podcast",
@@ -1657,4 +1601,58 @@ router.get("/episodes/:episodeId/cover", async (req, res) => {
     }
 });
 
+/**
+ * Refresh a single podcast feed -- shared logic used by both the route handler
+ * and the enrichment worker's automatic refresh phase.
+ */
+export async function refreshPodcastFeed(podcastId: string): Promise<{ newEpisodesCount: number; totalEpisodes: number }> {
+    const podcast = await prisma.podcast.findUnique({ where: { id: podcastId } });
+    if (!podcast) throw new Error(`Podcast ${podcastId} not found`);
+
+    const { podcast: podcastData, episodes } = await rssParserService.parseFeed(podcast.feedUrl);
+
+    await prisma.podcast.update({
+        where: { id: podcastId },
+        data: {
+            title: podcastData.title,
+            author: podcastData.author,
+            description: podcastData.description,
+            imageUrl: podcastData.imageUrl,
+            language: podcastData.language,
+            explicit: podcastData.explicit || false,
+            episodeCount: episodes.length,
+            lastRefreshed: new Date(),
+        },
+    });
+
+    let newEpisodesCount = 0;
+    for (const ep of episodes) {
+        const existing = await prisma.podcastEpisode.findUnique({
+            where: { podcastId_guid: { podcastId, guid: ep.guid } },
+        });
+
+        if (!existing) {
+            await prisma.podcastEpisode.create({
+                data: {
+                    podcastId,
+                    guid: ep.guid,
+                    title: ep.title,
+                    description: ep.description,
+                    audioUrl: ep.audioUrl,
+                    duration: ep.duration,
+                    publishedAt: ep.publishedAt,
+                    episodeNumber: ep.episodeNumber,
+                    season: ep.season,
+                    imageUrl: ep.imageUrl,
+                    fileSize: ep.fileSize,
+                    mimeType: ep.mimeType,
+                },
+            });
+            newEpisodesCount++;
+        }
+    }
+
+    return { newEpisodesCount, totalEpisodes: episodes.length };
+}
+
 export default router;