release: v1.5.9 — iOS MediaSession fix, enrichment pipeline hardening, track formatting

Features:
- DISABLE_CLAP env var for low-memory deployments
- Foobar2000-style track title formatting in Settings > Playback
- Partial playlist creation on cancelled Spotify imports

Fixes:
- iOS lock screen controls showing inverted state (play/pause swapped)
- Enrichment pipeline: 7 fixes covering vibe sweep, crash recovery,
  CLAP supervisor, completion detection, embedding reset, feature detection
- Favicon replaced with waveform-only multi-size ICO
- docker-compose.server.yml healthcheck using removed wget

Author: Your Name

.env.example

@@ -84,6 +84,13 @@ VERSION=latest
 # AUDIO_MODEL_IDLE_TIMEOUT=300    # Seconds before unloading ML models when idle (default: 300)
 #                                 # Set to 0 to keep models loaded permanently
 
+# CLAP Audio Analyzer (AI vibe/mood matching)
+# Set to 'true' to disable the CLAP embedding analyzer on startup.
+# Useful for low-memory deployments or when AI vibe matching is not needed.
+# Only applies to the all-in-one container (docker-compose.prod.yml).
+# For split containers (docker-compose.yml), simply don't start the audio-analyzer-clap service.
+# DISABLE_CLAP=true
+
 # ==============================================================================
 # OPTIONAL: Lidarr Webhook Configuration
 # ==============================================================================

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to Kima 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.5.9] - 2026-02-27
+
+### Added
+
+- **#122** `DISABLE_CLAP=true` environment variable to disable the CLAP audio embedding analyzer on startup in the all-in-one container (useful for low-memory deployments)
+- **#123** Foobar2000-style track title formatting in Settings > Playback -- configure a format string with `%field%`, `[conditional blocks]`, `$if2()`, `$filepart()` syntax; applied in playlist view
+- **#124** Cancelling a playlist import now creates a partial playlist from all tracks already matched to your library, instead of discarding progress
+
+### Fixed
+
+- **#124** Cancel button previously promised "Playlist will be created with tracks downloaded so far" but discarded all progress -- now delivers on that promise
+- **iOS lock screen controls inverted**: MediaSession `playbackState` was driven by React `useEffect` on `isPlaying` state, which fires asynchronously after render -- not synchronously with the actual audio state change. This caused lock screen controls to show the opposite state (play when playing, pause when paused). Rewrote MediaSession to drive `playbackState` directly from `audioEngine` events, call the engine directly from action handlers to preserve iOS user-gesture context, and use ref-based one-time handler registration to avoid re-registration churn.
+- **Favicon showing old Lidify icon or wrong Kima logo**: Browser tab showed the pre-rebrand Lidify favicon. Replaced with the waveform-only icon generated from `kima-black.webp` as a proper multi-size ICO (16/32/48/64/128/256px) with tight cropping so the waveform fills the tab space.
+- **Enrichment pipeline: no periodic vibe sweep**: The enrichment cycle had no phase for queueing vibe/CLAP embedding jobs. The only automatic path was a lossy pub/sub event from Essentia completion -- if missed (crash, restart, migration wipe), tracks were orphaned forever. Added Phase 5 that sweeps for tracks with completed audio but missing embedding rows via LEFT JOIN.
+- **Enrichment pipeline: crash recovery dead end**: Crash recovery reset `vibeAnalysisStatus` from `processing` to `null`, which nothing in the regular cycle re-queued. Changed to reset to `pending` so the periodic sweep picks them up.
+- **Enrichment pipeline: CLAP analyzer permanent death**: When enrichment was stopped, the backend sent a stop command causing the CLAP analyzer to exit cleanly (code 0). Supervisor's `autorestart=unexpected` treated this as expected and never restarted. Changed to `autorestart=true` and removed the stop signal entirely -- the analyzer has its own idle timeout.
+- **Enrichment pipeline: completion never triggers**: `isFullyComplete` required `clapCompleted + clapFailed >= trackTotal`, which was impossible after `track_embeddings` was wiped by migration. Now checks for actual un-embedded tracks via LEFT JOIN.
+- **Enrichment pipeline: "Reset Vibe Embeddings" incomplete**: `reRunVibeEmbeddingsOnly()` reset `vibeAnalysisStatus` but did not delete existing `track_embeddings` rows, so the re-queue query (which uses LEFT JOIN) silently skipped tracks that already had embeddings. Now deletes all embeddings first for full regeneration.
+- **Feature detection: CLAP reported available when disabled**: When `DISABLE_CLAP=true` was set, `checkCLAP()` skipped the file-existence check but still fell through to heartbeat and data checks. If old embeddings existed in the database, it returned `true`, causing the vibe sweep to queue jobs that no CLAP worker would ever process. Now returns `false` immediately when disabled.
+- **docker-compose.server.yml healthcheck using removed tool**: Healthcheck used `wget` which is removed from the production image during security hardening. Changed to `node /app/healthcheck.js` to match docker-compose.prod.yml.
+
 ## [1.5.8] - 2026-02-26
 
 ### Fixed

Dockerfile

@@ -276,7 +276,7 @@ priority=50
 [program:audio-analyzer-clap]
 command=/bin/bash -c "/app/wait-for-db.sh 120 && cd /app/audio-analyzer-clap && python3 analyzer.py"
 autostart=true
-autorestart=unexpected
+autorestart=true
 startretries=3
 startsecs=30
 stdout_logfile=/dev/stdout
@@ -490,8 +490,25 @@ TRANSCODE_CACHE_PATH=/data/cache/transcodes
 SESSION_SECRET=$SESSION_SECRET
 SETTINGS_ENCRYPTION_KEY=$SETTINGS_ENCRYPTION_KEY
 INTERNAL_API_SECRET=kima-internal-aio
+DISABLE_CLAP=${DISABLE_CLAP:-}
 ENVEOF
 
+# Optionally disable CLAP audio analyzer (for low-memory deployments)
+if [ "${DISABLE_CLAP:-false}" = "true" ] || [ "${DISABLE_CLAP:-0}" = "1" ]; then
+    python3 -c "
+import re
+conf = open('/etc/supervisor/conf.d/kima.conf').read()
+conf = re.sub(
+    r'(\[program:audio-analyzer-clap\][^\[]*autostart=)true',
+    r'\g<1>false',
+    conf,
+    flags=re.DOTALL
+)
+open('/etc/supervisor/conf.d/kima.conf', 'w').write(conf)
+"
+    echo "CLAP audio analyzer disabled (DISABLE_CLAP=${DISABLE_CLAP})"
+fi
+
 echo "Starting Kima..."
 exec env \
     NODE_ENV=production \

backend/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kima-backend",
-    "version": "1.5.8",
+    "version": "1.5.9",
     "description": "Kima backend API server",
     "license": "GPL-3.0",
     "repository": {

backend/src/services/featureDetection.ts

@@ -68,7 +68,12 @@ class FeatureDetectionService {
 
     private async checkCLAP(): Promise<boolean> {
         try {
-            // Analyzer script bundled in image = feature is available
+            // If explicitly disabled via env var, CLAP is not available
+            const disabled = process.env.DISABLE_CLAP;
+            if (disabled === "true" || disabled === "1") {
+                return false;
+            }
+
             if (existsSync(CLAP_ANALYZER_PATH)) {
                 return true;
             }

backend/src/services/spotifyImport.ts

@@ -2644,16 +2644,57 @@ class SpotifyImportService {
       },
     });
 
-    // Mark job as cancelled - do NOT create a playlist
+    // Collect tracks already matched to the library before cancellation
+    const matchedTrackIds = [
+      ...new Set(
+        (job.pendingTracks || [])
+          .map((t) => t.preMatchedTrackId)
+          .filter((id): id is string => !!id),
+      ),
+    ];
+
+    let createdPlaylistId: string | null = null;
+
+    if (matchedTrackIds.length > 0) {
+      try {
+        const playlist = await prisma.playlist.create({
+          data: {
+            userId: job.userId,
+            name: job.playlistName,
+            isPublic: false,
+            spotifyPlaylistId: job.spotifyPlaylistId,
+            items: {
+              create: matchedTrackIds.map((trackId, index) => ({
+                trackId,
+                sort: index,
+              })),
+            },
+          },
+        });
+        createdPlaylistId = playlist.id;
+        logger?.info(
+          `Partial playlist created with ${matchedTrackIds.length} tracks: ${playlist.id}`,
+        );
+      } catch (err: any) {
+        logger?.warn(
+          `Failed to create partial playlist on cancel: ${err?.message}`,
+        );
+      }
+    }
+
     job.status = "cancelled";
+    job.createdPlaylistId = createdPlaylistId;
+    job.tracksMatched = matchedTrackIds.length;
     job.updatedAt = new Date();
     await saveImportJob(job);
-    logger?.info(`Import cancelled by user - no playlist created`);
+    logger?.info(
+      `Import cancelled by user — ${createdPlaylistId ? "partial playlist created" : "no tracks matched"}`,
+    );
 
     return {
-      playlistCreated: false,
-      playlistId: null,
-      tracksMatched: 0,
+      playlistCreated: !!createdPlaylistId,
+      playlistId: createdPlaylistId,
+      tracksMatched: matchedTrackIds.length,
     };
   }
 

backend/src/workers/unifiedEnrichment.ts

@@ -221,8 +221,9 @@ async function setupControlChannel() {
                         "[Enrichment] Stopping gracefully - completing current item...",
                     );
                     // DO NOT override state - let enrichmentStateService.stop() handle it
-                    // Signal CLAP Python container to stop draining its queue
-                    getRedis().publish("audio:clap:control", JSON.stringify({ command: "stop" })).catch(() => {});
+                    // DO NOT kill the CLAP analyzer — it has its own idle timeout (MODEL_IDLE_TIMEOUT=300s)
+                    // and will unload the model when the vibe queue is empty. Killing it caused
+                    // permanent death because supervisor's autorestart didn't revive clean exits.
                 }
             }
         });
@@ -248,7 +249,7 @@ export async function startUnifiedEnrichmentWorker() {
      });
      const orphanedVibe = await prisma.track.updateMany({
          where: { vibeAnalysisStatus: "processing" },
-         data: { vibeAnalysisStatus: null, vibeAnalysisStartedAt: null },
+         data: { vibeAnalysisStatus: "pending", vibeAnalysisStartedAt: null },
      });
      if (orphanedAudio.count > 0 || orphanedVibe.count > 0) {
          logger.info(
@@ -496,6 +497,9 @@ async function runEnrichmentCycle(fullMode: boolean): Promise<{
         // Podcast refresh phase -- only runs if subscriptions exist
         await runPhase("podcasts", executePodcastRefreshPhase);
 
+        // Vibe embedding sweep — catches tracks missed by the event-driven subscriber
+        await runPhase("vibe", executeVibePhase);
+
         // Orphaned failure cleanup -- runs at most once per hour, never during stop/pause
         const ONE_HOUR_MS = 60 * 60 * 1000;
         if (!isStopping && !isPaused && (!lastOrphanedFailuresCleanup || Date.now() - lastOrphanedFailuresCleanup.getTime() > ONE_HOUR_MS)) {
@@ -853,7 +857,7 @@ async function shouldHaltCycle(): Promise<boolean> {
  * Run a phase and return result. Returns null if cycle should halt.
  */
 async function runPhase(
-    phaseName: "artists" | "tracks" | "audio" | "podcasts",
+    phaseName: "artists" | "tracks" | "audio" | "podcasts" | "vibe",
     executor: () => Promise<number>,
 ): Promise<number | null> {
     await enrichmentStateService.updateState({
@@ -1014,6 +1018,69 @@ async function executeAudioPhase(): Promise<number> {
     return queueAudioAnalysis();
 }
 
+const VIBE_SWEEP_BATCH_SIZE = 100;
+
+async function executeVibePhase(): Promise<number> {
+    const features = await featureDetection.getFeatures();
+    if (!features.vibeEmbeddings) {
+        return 0;
+    }
+
+    // Find tracks with completed audio analysis but no embedding row.
+    // This catches:
+    //   - Tracks orphaned by migration wiping track_embeddings
+    //   - Tracks whose pub/sub completion event was missed (crash, restart)
+    //   - Tracks reset to null/pending by crash recovery
+    //   - Tracks with vibeAnalysisStatus='completed' but no actual embedding (stale status)
+    const tracks = await prisma.$queryRaw<{ id: string; filePath: string }[]>`
+        SELECT t.id, t."filePath"
+        FROM "Track" t
+        LEFT JOIN track_embeddings te ON t.id = te.track_id
+        WHERE te.track_id IS NULL
+          AND t."analysisStatus" = 'completed'
+          AND t."filePath" IS NOT NULL
+          AND (t."vibeAnalysisStatus" IS NULL
+               OR t."vibeAnalysisStatus" = 'pending'
+               OR t."vibeAnalysisStatus" = 'completed')
+          AND (t."vibeAnalysisStatus" IS DISTINCT FROM 'processing')
+        LIMIT ${VIBE_SWEEP_BATCH_SIZE}
+    `;
+
+    if (tracks.length === 0) {
+        return 0;
+    }
+
+    // Reset stale vibeAnalysisStatus for these tracks before queuing
+    const trackIds = tracks.map((t) => t.id);
+    await prisma.track.updateMany({
+        where: { id: { in: trackIds } },
+        data: {
+            vibeAnalysisStatus: "pending",
+            vibeAnalysisError: null,
+        },
+    });
+
+    let queued = 0;
+    for (const track of tracks) {
+        try {
+            await vibeQueue.add(
+                "embed",
+                { trackId: track.id, filePath: track.filePath },
+                { jobId: `vibe-${track.id}` },
+            );
+            queued++;
+        } catch (err) {
+            // jobId dedup: if already queued, BullMQ throws — that's fine
+        }
+    }
+
+    if (queued > 0) {
+        logger.debug(`[Enrichment] Vibe sweep: queued ${queued} tracks for embedding`);
+    }
+
+    return queued;
+}
+
 async function executePodcastRefreshPhase(): Promise<number> {
     const podcastCount = await prisma.podcast.count();
     if (podcastCount === 0) return 0;
@@ -1094,7 +1161,7 @@ export async function getEnrichmentProgress() {
     });
 
     // CLAP embedding progress (for vibe similarity)
-    const [clapEmbeddingCount, clapProcessing, clapQueueCounts, clapFailedCount] = await Promise.all([
+    const [clapEmbeddingCount, clapProcessing, clapQueueCounts, clapFailedCount, clapUnembeddedCount] = await Promise.all([
         prisma.$queryRaw<{ count: bigint }[]>`
             SELECT COUNT(*) as count FROM track_embeddings
         `,
@@ -1105,10 +1172,21 @@ export async function getEnrichmentProgress() {
         prisma.track.count({
             where: { vibeAnalysisStatus: "failed" },
         }),
+        // Tracks with completed audio but no embedding and not failed
+        prisma.$queryRaw<{ count: bigint }[]>`
+            SELECT COUNT(*) as count
+            FROM "Track" t
+            LEFT JOIN track_embeddings te ON t.id = te.track_id
+            WHERE te.track_id IS NULL
+              AND t."analysisStatus" = 'completed'
+              AND t."filePath" IS NOT NULL
+              AND (t."vibeAnalysisStatus" IS DISTINCT FROM 'failed')
+        `,
     ]);
     const clapQueueLength = (clapQueueCounts.active ?? 0) + (clapQueueCounts.waiting ?? 0) + (clapQueueCounts.delayed ?? 0);
     const clapCompleted = Number(clapEmbeddingCount[0]?.count || 0);
     const clapFailed = clapFailedCount;
+    const clapUnembedded = Number(clapUnembeddedCount[0]?.count || 0);
 
     // Core enrichment is complete when artists and track tags are done
     // Audio analysis is separate - it runs in background and doesn't block
@@ -1175,7 +1253,7 @@ export async function getEnrichmentProgress() {
             audioProcessing === 0 &&
             clapProcessing === 0 &&
             clapQueueLength === 0 &&
-            clapCompleted + clapFailed >= trackTotal,
+            clapUnembedded === 0,
     };
 }
 
@@ -1293,12 +1371,14 @@ export async function triggerEnrichmentNow(): Promise<{
          return 0;
      }
 
+     // Delete all existing embeddings so tracks get fully regenerated
+     const deleted = await prisma.trackEmbedding.deleteMany({});
+     logger.debug(`[Enrichment] Deleted ${deleted.count} existing embeddings for full regeneration`);
+
      // Reset all tracks so they can be re-embedded.
-     // Only reset tracks whose audio analysis is complete (no point embedding incomplete audio).
      await prisma.track.updateMany({
          where: {
              analysisStatus: "completed",
-             vibeAnalysisStatus: { not: null },
          },
          data: {
              vibeAnalysisStatus: null,
@@ -1311,9 +1391,7 @@ export async function triggerEnrichmentNow(): Promise<{
      const tracks = await prisma.$queryRaw<{ id: string; filePath: string }[]>`
          SELECT t.id, t."filePath"
          FROM "Track" t
-         LEFT JOIN track_embeddings te ON t.id = te.track_id
-         WHERE te.track_id IS NULL
-           AND t."analysisStatus" = 'completed'
+         WHERE t."analysisStatus" = 'completed'
            AND t."filePath" IS NOT NULL
          LIMIT 5000
      `;

docker-compose.prod.yml

@@ -29,6 +29,7 @@ services:
       # Default uses host.docker.internal which works on most setups with extra_hosts below
       # Override if using custom Docker networks: e.g., http://192.168.0.20:3030
       - KIMA_CALLBACK_URL=${KIMA_CALLBACK_URL:-http://host.docker.internal:3030}
+      - DISABLE_CLAP=${DISABLE_CLAP:-}
     # Makes host.docker.internal work on Linux (already works on Docker Desktop)
     extra_hosts:
       - "host.docker.internal:host-gateway"

docker-compose.server.yml

@@ -27,6 +27,7 @@ services:
             # Default uses host.docker.internal which works on most setups with extra_hosts below
             # Override if using custom Docker networks: e.g., http://192.168.0.20:3030
             - KIMA_CALLBACK_URL=${KIMA_CALLBACK_URL:-http://host.docker.internal:3030}
+            - DISABLE_CLAP=${DISABLE_CLAP:-}
         # Makes host.docker.internal work on Linux (already works on Docker Desktop)
         extra_hosts:
             - "host.docker.internal:host-gateway"
@@ -35,15 +36,7 @@ services:
             - vm.overcommit_memory=1
         restart: unless-stopped
         healthcheck:
-            test:
-                [
-                    "CMD",
-                    "wget",
-                    "--no-verbose",
-                    "--tries=1",
-                    "--spider",
-                    "http://localhost:3030",
-                ]
+            test: ["CMD", "node", "/app/healthcheck.js"]
             interval: 30s
             timeout: 10s
             retries: 3