feat(scrobble): own timestamped play-log service (stats/Wrapped foundation)

Phase 1+2 of a self-hosted, multi-user listening archive — the basis for
day/month/year stats and a yearly "Wrapped". Runs IN ADDITION to the existing
Navidrome/Last.fm scrobble; never replaces it.

Service (isolated, own container):
- scrobble/scrobble-server.js — node:sqlite play-log (own volume), routes
  POST /scrobble/plays (idempotent by uuid), GET /scrobble/history (archive),
  DELETE /scrobble/plays?user= (test cleanup), GET /scrobble/health.
  Multi-user auth via Navidrome ping.view (cached) -> user not spoofable.
- docker-compose: novasonic-scrobble service (node:22, port 3710) + volume;
  backend bumped node:20->22 (EOL); SCROBBLE_URL plumbing (entrypoint, .env.example).

Capture (both platforms, offline-safe queue, idempotent batch flush):
- Fires at the existing scrobbleMode counted-play moment — consistent with
  Last.fm, respects the user's setting (no separate 50%/4min rule).
- Web: src/player/scrobbleLog.js (localStorage queue) + subsonicAuthParams()
  in api.js + hooks in player.js + flush init in main.js; S.cfg.scrobbleUrl.
- Android: data/PlayLogClient.kt (filesDir queue, reused Ktor client) +
  repo.logPlay/flushPlayLog + PlayerController hook + NovaSonicApp flush +
  scrobbleUrl in PrefsStore/SettingsViewModel/SettingsScreen (with test button).

Plan + design decisions documented in docs/scrobble-plan.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

android/app/src/main/kotlin/com/novasonic/app/NovaSonicApp.kt

@@ -6,6 +6,10 @@ import com.novasonic.app.offline.OfflineRepository
 import com.novasonic.app.player.AbsPlayerController
 import com.novasonic.app.player.PlayerController
 import com.novasonic.app.player.PreviewController
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
 
 class NovaSonicApp : Application() {
 
@@ -27,6 +31,10 @@ class NovaSonicApp : Application() {
         playerController    = PlayerController(applicationContext, repository)
         playerController.connect()
         absPlayerController = AbsPlayerController(applicationContext)
+        // Flush any plays queued while offline to the scrobble service.
+        CoroutineScope(Dispatchers.IO + SupervisorJob()).launch {
+            runCatching { repository.flushPlayLog() }
+        }
     }
 }
 

android/app/src/main/kotlin/com/novasonic/app/data/MusicRepository.kt

@@ -32,6 +32,7 @@ object ClientHolder {
 class MusicRepository(private val context: Context) {
 
     private val prefs = PrefsStore(context)
+    private val playLog = PlayLogClient(context)
 
     private suspend fun api(): SubsonicClient =
         ClientHolder.get(prefs.credentials.first())
@@ -56,6 +57,9 @@ class MusicRepository(private val context: Context) {
     suspend fun star(id: String)                        = api().star(id)
     suspend fun unstar(id: String)                      = api().unstar(id)
     suspend fun scrobble(id: String)                    = api().scrobble(id)
+    // Our own timestamped play-log (stats + Wrapped), in addition to the Navidrome scrobble above.
+    suspend fun logPlay(song: Song)                     = playLog.logPlay(song)
+    suspend fun flushPlayLog()                          = playLog.flush()
     suspend fun getArtistInfo(id: String)               = api().getArtistInfo(id)
     suspend fun getTopSongs(artistName: String)         = api().getTopSongs(artistName)
     suspend fun getGenres()                             = api().getGenres()

android/app/src/main/kotlin/com/novasonic/app/data/PlayLogClient.kt

@@ -0,0 +1,137 @@
+package com.novasonic.app.data
+
+import android.content.Context
+import com.novasonic.app.api.model.Song
+import io.ktor.client.HttpClient
+import io.ktor.client.engine.android.Android
+import io.ktor.client.plugins.HttpTimeout
+import io.ktor.client.request.post
+import io.ktor.client.request.setBody
+import io.ktor.client.statement.HttpResponse
+import io.ktor.http.ContentType
+import io.ktor.http.contentType
+import io.ktor.http.encodeURLParameter
+import io.ktor.http.isSuccess
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+import java.security.MessageDigest
+import java.util.UUID
+import kotlin.random.Random
+
+/**
+ * Records timestamped plays into NovaSonic's own scrobble service (separate origin,
+ * settings.scrobbleUrl) — the basis for day/month/year stats + Wrapped.
+ *
+ * Runs IN ADDITION to the existing Navidrome scrobble (playCount + Last.fm); never
+ * replaces it. Called at the same "counted play" moment as the Navidrome scrobble
+ * (see PlayerController.scheduleScrobble).
+ *
+ * Offline-safe: entries persist to a JSON file and flush as an idempotent batch
+ * (the service dedups by uuid), so a play made offline is delivered later exactly once.
+ *
+ * One instance lives on MusicRepository → a single reused HttpClient (never per-call).
+ */
+class PlayLogClient(context: Context) {
+
+    private val prefs = PrefsStore(context)
+    private val queueFile = File(context.filesDir, "play-queue.json")
+    private val mutex = Mutex()
+    private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
+    private val http = HttpClient(Android) {
+        install(HttpTimeout) { requestTimeoutMillis = 15_000; connectTimeoutMillis = 8_000 }
+    }
+
+    @Serializable
+    data class PlayEntry(
+        val uuid: String,
+        val songId: String,
+        val title: String? = null,
+        val artist: String? = null,
+        val artistId: String? = null,
+        val album: String? = null,
+        val albumId: String? = null,
+        val duration: Int? = null,
+        val playedAt: Long,
+        val source: String = "android",
+    )
+
+    @Serializable
+    private data class Batch(val plays: List<PlayEntry>)
+
+    /** Queue one counted play and try to deliver it. */
+    suspend fun logPlay(song: Song) {
+        val s = prefs.appSettings.first()
+        if (s.scrobbleUrl.isBlank()) return
+        val entry = PlayEntry(
+            uuid     = UUID.randomUUID().toString(),
+            songId   = song.id,
+            title    = song.title,
+            artist   = song.artist,
+            artistId = song.artistId,
+            album    = song.album,
+            albumId  = song.albumId,
+            duration = song.duration,
+            playedAt = System.currentTimeMillis() / 1000,
+        )
+        mutex.withLock {
+            val q = readQueue().toMutableList()
+            q.add(entry)
+            writeQueue(q.takeLast(MAX_QUEUE))
+        }
+        flush(s)
+    }
+
+    /** Deliver everything queued as one idempotent batch. Safe to call repeatedly. */
+    suspend fun flush(settings: PrefsStore.AppSettings? = null) {
+        val s = settings ?: prefs.appSettings.first()
+        val base = s.scrobbleUrl.trimEnd('/')
+        if (base.isBlank() || s.username.isBlank() || s.password.isBlank()) return
+
+        val batch = mutex.withLock { readQueue() }
+        if (batch.isEmpty()) return
+
+        val auth = authParams(s.username, s.password)
+        val ok = runCatching {
+            val resp: HttpResponse = http.post("$base/scrobble/plays?$auth") {
+                contentType(ContentType.Application.Json)
+                setBody(json.encodeToString(Batch(batch)))
+            }
+            resp.status.isSuccess()
+        }.getOrDefault(false)
+
+        if (ok) {
+            // Remove exactly what we sent (accepted + duplicates are durable), preserving
+            // any plays queued while the request was in flight.
+            val sent = batch.map { it.uuid }.toHashSet()
+            mutex.withLock { writeQueue(readQueue().filterNot { it.uuid in sent }) }
+        }
+    }
+
+    private fun readQueue(): List<PlayEntry> =
+        runCatching {
+            if (!queueFile.exists()) emptyList()
+            else json.decodeFromString<List<PlayEntry>>(queueFile.readText())
+        }.getOrDefault(emptyList())
+
+    private fun writeQueue(q: List<PlayEntry>) {
+        runCatching { queueFile.writeText(json.encodeToString(q)) }
+    }
+
+    private fun authParams(user: String, pass: String): String {
+        val salt = Random.nextInt(100_000, 999_999).toString()
+        val token = md5(pass + salt)
+        return "u=${user.encodeURLParameter()}&t=$token&s=$salt"
+    }
+
+    private fun md5(input: String): String =
+        MessageDigest.getInstance("MD5").digest(input.toByteArray())
+            .joinToString("") { "%02x".format(it) }
+
+    companion object { private const val MAX_QUEUE = 500 }
+}

android/app/src/main/kotlin/com/novasonic/app/data/PrefsStore.kt

@@ -18,6 +18,7 @@ class PrefsStore(private val context: Context) {
         val KEY_PASSWORD      = stringPreferencesKey("password")
         val KEY_LASTFM_KEY    = stringPreferencesKey("lastfm_key")
         val KEY_BACKEND_URL   = stringPreferencesKey("backend_url")
+        val KEY_SCROBBLE_URL  = stringPreferencesKey("scrobble_url")
         val KEY_SCROBBLE_MODE = stringPreferencesKey("scrobble_mode")
         val KEY_SHOW_COUNT    = booleanPreferencesKey("show_play_count")
         val KEY_THEME         = stringPreferencesKey("theme")
@@ -40,6 +41,7 @@ class PrefsStore(private val context: Context) {
         val password: String     = "",
         val lastFmKey: String    = "",
         val backendUrl: String   = "",
+        val scrobbleUrl: String  = "",
         val scrobbleMode: String = "30s",
         val showPlayCount: Boolean = false,
         val theme: String        = "dark-ocean",
@@ -70,6 +72,7 @@ class PrefsStore(private val context: Context) {
             password     = prefs[KEY_PASSWORD]      ?: "",
             lastFmKey    = prefs[KEY_LASTFM_KEY]    ?: "",
             backendUrl   = prefs[KEY_BACKEND_URL]   ?: "",
+            scrobbleUrl  = prefs[KEY_SCROBBLE_URL]  ?: "",
             scrobbleMode = prefs[KEY_SCROBBLE_MODE] ?: "30s",
             showPlayCount = prefs[KEY_SHOW_COUNT]   ?: false,
             theme        = prefs[KEY_THEME]         ?: "dark-ocean",
@@ -104,6 +107,7 @@ class PrefsStore(private val context: Context) {
             prefs[KEY_PASSWORD]      = settings.password
             prefs[KEY_LASTFM_KEY]    = settings.lastFmKey
             prefs[KEY_BACKEND_URL]   = settings.backendUrl
+            prefs[KEY_SCROBBLE_URL]  = settings.scrobbleUrl
             prefs[KEY_SCROBBLE_MODE] = settings.scrobbleMode
             prefs[KEY_SHOW_COUNT]    = settings.showPlayCount
             prefs[KEY_THEME]         = settings.theme

android/app/src/main/kotlin/com/novasonic/app/player/PlayerController.kt

@@ -245,6 +245,7 @@ class PlayerController(private val context: Context, private val repo: MusicRepo
             val delayMs = runCatching { repo.getScrobbleDelayMs(durationMs) }.getOrDefault(30_000L)
             delay(delayMs)
             runCatching { repo.scrobble(song.id) }
+            runCatching { repo.logPlay(song) }   // our own play-log, same counted moment
         }
     }
 

android/app/src/main/kotlin/com/novasonic/app/ui/screen/SettingsScreen.kt

@@ -186,6 +186,14 @@ fun SettingsScreen() {
         )
         ConnStatusRow(status = state.backendStatus, label = "Nicht konfiguriert", onTest = vm::testBackend)
 
+        NsTextField(
+            value = state.scrobbleUrl, onValueChange = vm::onScrobbleUrl,
+            label = "NovaSonic Scrobble URL",
+            hint = "Play-Log für Statistiken (Port 3710)",
+            keyboardType = KeyboardType.Uri,
+        )
+        ConnStatusRow(status = state.scrobbleStatus, label = "Nicht konfiguriert", onTest = vm::testScrobble)
+
         Spacer(Modifier.height(4.dp))
 
         // ── 🌐 Navidrome Server ──────────────────────────────────────────────

android/app/src/main/kotlin/com/novasonic/app/viewmodel/SettingsViewModel.kt

@@ -28,6 +28,7 @@ data class SettingsUiState(
     val password: String      = "",
     val lastFmKey: String     = "",
     val backendUrl: String    = "",
+    val scrobbleUrl: String   = "",
     val scrobbleMode: String  = "30s",
     val showPlayCount: Boolean = false,
     val theme: String          = "dark-ocean",
@@ -39,6 +40,7 @@ data class SettingsUiState(
     val error: String?        = null,
     val absStatus: ConnStatus  = ConnStatus.Idle,
     val backendStatus: ConnStatus = ConnStatus.Idle,
+    val scrobbleStatus: ConnStatus = ConnStatus.Idle,
 )
 
 class SettingsViewModel(app: Application) : AndroidViewModel(app) {
@@ -57,6 +59,7 @@ class SettingsViewModel(app: Application) : AndroidViewModel(app) {
                     password     = s.password,
                     lastFmKey    = s.lastFmKey,
                     backendUrl   = s.backendUrl,
+                    scrobbleUrl  = s.scrobbleUrl,
                     scrobbleMode  = s.scrobbleMode,
                     showPlayCount = s.showPlayCount,
                     theme         = s.theme,
@@ -73,6 +76,7 @@ class SettingsViewModel(app: Application) : AndroidViewModel(app) {
     fun onPassword(v: String)        = update { it.copy(password  = v, savedOk = false) }
     fun onLastFmKey(v: String)       = update { it.copy(lastFmKey = v, savedOk = false) }
     fun onBackendUrl(v: String)      = update { it.copy(backendUrl = v, savedOk = false, backendStatus = ConnStatus.Idle) }
+    fun onScrobbleUrl(v: String)     = update { it.copy(scrobbleUrl = v, savedOk = false, scrobbleStatus = ConnStatus.Idle) }
     fun onScrobbleMode(v: String)    = update { it.copy(scrobbleMode = v, savedOk = false) }
     fun onShowPlayCount(v: Boolean)  = update { it.copy(showPlayCount = v, savedOk = false) }
     fun onAbsUrl(v: String)              = update { it.copy(absUrl = v, savedOk = false, absStatus = ConnStatus.Idle) }
@@ -124,6 +128,31 @@ class SettingsViewModel(app: Application) : AndroidViewModel(app) {
         }
     }
 
+    fun testScrobble() {
+        val url = _state.value.scrobbleUrl.trim().trimEnd('/')
+        if (url.isBlank()) {
+            update { it.copy(scrobbleStatus = ConnStatus.Err("Scrobble URL eingeben")) }
+            return
+        }
+        update { it.copy(scrobbleStatus = ConnStatus.Checking) }
+        viewModelScope.launch {
+            try {
+                val http = HttpClient(Android) {
+                    install(HttpTimeout) { requestTimeoutMillis = 5_000; connectTimeoutMillis = 4_000 }
+                }
+                val resp = http.get("$url/scrobble/health")
+                http.close()
+                if (resp.status == HttpStatusCode.OK) {
+                    update { it.copy(scrobbleStatus = ConnStatus.Ok("Verbunden · $url")) }
+                } else {
+                    update { it.copy(scrobbleStatus = ConnStatus.Err("HTTP ${resp.status.value}")) }
+                }
+            } catch (e: Exception) {
+                update { it.copy(scrobbleStatus = ConnStatus.Err("Nicht erreichbar")) }
+            }
+        }
+    }
+
     fun save() {
         val s = _state.value
         if (s.serverUrl.isBlank() || s.username.isBlank() || s.password.isBlank()) {
@@ -139,6 +168,7 @@ class SettingsViewModel(app: Application) : AndroidViewModel(app) {
                     password     = s.password,
                     lastFmKey    = s.lastFmKey.trim(),
                     backendUrl   = s.backendUrl.trimEnd('/'),
+                    scrobbleUrl  = s.scrobbleUrl.trimEnd('/'),
                     scrobbleMode = s.scrobbleMode,
                     showPlayCount = s.showPlayCount,
                     theme        = s.theme,