# Implementation Plan: OpenSubsonic Music Server (Kotlin / Ktor) ## 1. Projektziel & Kontext Entwickle einen leichtgewichtigen, selbstgehosteten **OpenSubsonic-kompatiblen Musik-Server** in **Kotlin**, der Plex für Musik-Streaming ablöst und speziell auf die Zusammenarbeit mit dem Android-Client **Symfonium** optimiert ist. ### Kernanforderungen (MVP) 1. **Library-Indexing:** Einlesen eines lokalen Musik-Verzeichnisses (primär MP3, zusätzlich FLAC/OGG/M4A/OPUS), Auslesen der Metadaten (Tag-First mit Ordnerstruktur `Artist/Album/Track` als Fallback) und Persistierung in SQLite. 2. **Symfonium-Sync:** Vollständige Unterstützung der OpenSubsonic-Browsing-Endpunkte, damit Symfonium den gesamten Katalog sauber in seine lokale Offline-First-Datenbank synchronisiert. 3. **Streaming & Offline-Downloads:** Auslieferung der Audiodateien inkl. HTTP `Range`-Requests (`206 Partial Content`) sowie exakter Byte-Größen, damit Seeking und Symfoniums Offline-Download-Manager zuverlässig funktionieren. 4. **Bidirektionale Interaktion:** Scrobbling (Play-Counts), Favoriten (`star`/`unstar`), Bewertungen (`setRating`), Playlists und Startseiten-Feeds (`getAlbumList2`, `getRandomSongs`). 5. **Erweiterbarkeit:** Saubere Trennung zwischen Media-Scanner, Datenbank-Layer und HTTP-API, sodass später ein automatisierter Music-Downloader und eine Discovery-/Recommendation-Engine (z. B. über ListenBrainz/Last.fm oder Staging-Playlists) angedockt werden können. --- ## 2. Tech-Stack & Dependencies * **Sprache & Runtime:** Kotlin 2.x auf JVM 21 (`eclipse-temurin:21-jre-alpine`) * **Build-Tool:** Gradle (Kotlin DSL `build.gradle.kts`) mit `ShadowJar` Plugin (Fat-JAR) * **Web-Framework:** **Ktor Server (Netty)** * `ktor-server-core`, `ktor-server-netty` * `ktor-server-content-negotiation` + `ktor-serialization-kotlinx-json` * `ktor-server-partial-content` (Pflicht für HTTP `Range` / `206 Partial Content`) * `ktor-server-status-pages`, `ktor-server-call-logging`, `ktor-server-auto-head-response` * **Datenbank:** **SQLite** (im `WAL`-Mode) + **JetBrains Exposed** (`exposed-core`, `exposed-dao`, `exposed-jdbc`, `exposed-java-time`) + `sqlite-jdbc` + `HikariCP` * **Audio-Metadaten & Cover:** * `net.jthink:jaudiotagger` (Auslesen von ID3v1/v2, FLAC, Ogg, M4A, Dauer, Bitrate, Cover, Lyrics) * `net.coobird:thumbnailator` (On-the-fly Resizing von Album-Covern für `getCoverArt?size=...`) * **Logging:** `logback-classic` + `kotlin-logging-jvm` --- ## 3. Projektstruktur ```text src/main/kotlin/com/musicserver/ ├── Application.kt # Ktor Einstiegspunkt, Plugins, Graceful Shutdown ├── config/ │ └── AppConfig.kt # Env-Vars (MUSIC_DIR, DATA_DIR, SUBSONIC_USER, SUBSONIC_PASS, PORT) ├── db/ │ ├── DatabaseFactory.kt # SQLite Init, PRAGMA journal_mode=WAL, Schema-Migration │ ├── Tables.kt # Exposed Table-Definitionen │ └── Repositories.kt # CRUD- & Query-Logik für Artists, Albums, Songs, Playlists ├── scanner/ │ ├── MediaScanner.kt # Rekursiver Verzeichnis-Scan, Delta-Updates, Orphan-Cleanup │ ├── TagExtractor.kt # jaudiotagger Wrapper (Tags, Fallback auf Pfad, Dauer, Bitrate) │ └── CoverArtService.kt # Cover-Extraktion aus Tags/Ordnern, Disk-Cache & Resizing ├── subsonic/ │ ├── SubsonicAuth.kt # Ktor Plugin/Interceptor für Token-Auth (u, t, s) & Plaintext (p) │ ├── SubsonicResponse.kt # Standardisierter JSON-Envelope ("subsonic-response") & Fehlercodes │ ├── models/ # kotlinx.serialization DTOs für OpenSubsonic │ │ ├── SystemModels.kt │ │ ├── BrowsingModels.kt │ │ └── PlaylistModels.kt │ └── routes/ # Routing unter /rest/{endpoint} und /rest/{endpoint}.view │ ├── SystemRoutes.kt # ping, getLicense, getOpenSubsonicExtensions, startScan, getScanStatus │ ├── BrowsingRoutes.kt # getMusicFolders, getIndexes, getArtists, getArtist, getAlbum, getSong, search3, getAlbumList2, getRandomSongs │ ├── MediaRoutes.kt # stream, download, getCoverArt, getLyricsBySongId │ ├── InteractionRoutes.kt # scrobble, star, unstar, setRating │ └── PlaylistRoutes.kt # getPlaylists, getPlaylist, createPlaylist, updatePlaylist, deletePlaylist └── util/ └── IdGenerator.kt # Deterministische SHA-256 ID-Generierung ``` --- ## 4. Kritische Architektur-Regeln (Symfonium-Kompatibilität) 1. **Deterministische IDs (Extrem wichtig!):** * IDs dürfen sich bei einem erneuten Library-Scan **niemals** ändern, sonst verliert Symfonium den Offline-Download-Status und Playlist-Zuordnungen. * **Artist-ID:** `"ar-" + sha256(normalizedAlbumArtist).take(16)` * **Album-ID:** `"al-" + sha256(normalizedAlbumArtist + "|" + normalizedAlbumTitle).take(16)` * **Song-ID:** `"sg-" + sha256(relativeFilePathFromMusicDir).take(16)` * **Cover-ID:** Identisch zur `Album-ID` (`"al-..."`) bzw. `Artist-ID` (`"ar-..."`). 2. **Album-Gruppierung über `AlbumArtist`:** * Alben müssen primär über den `ALBUM_ARTIST`-Tag gruppiert werden (Fallback: `ARTIST`-Tag, Fallback: Elternordner). Andernfalls zerfallen Alben mit Featuring-Artists in einzelne Fragmente. 3. **Exakte Datei-Metadaten für Offline-Downloads:** * Jedes Song-Objekt muss zwingend die exakte Dateigröße in Bytes (`size: Long`), die Spieldauer in Sekunden (`duration: Int`), `bitRate: Int`, `suffix: String` (z. B. `"mp3"`) und `contentType: String` (z. B. `"audio/mpeg"`) liefern. Symfonium prüft nach jedem Offline-Download, ob die heruntergeladenen Bytes exakt mit `size` übereinstimmen. 4. **Routing-Konvention & `formPost`:** * Symfonium sendet Requests wahlweise an `/rest/getArtists` oder `/rest/getArtists.view` und nutzt bei langen Parameterlisten (z. B. `updatePlaylist`) `POST` mit `application/x-www-form-urlencoded`. * Registriere alle Endpunkte für **beide** URL-Varianten (`/{method}` und `/{method}.view`) und lies Parameter vereinheitlicht aus `call.request.queryParameters` **und** `call.receiveParameters()` (bei POST). 5. **OpenSubsonic JSON-Envelope:** * Jede Antwort (Standard `f=json`) muss in folgendes Root-Objekt verpackt sein: ```json { "subsonic-response": { "status": "ok", "version": "1.16.1", "type": "subsonic-kt", "serverVersion": "0.1.0", "openSubsonic": true } } ``` --- ## 5. Datenbank-Schema (SQLite) ```sql CREATE TABLE artists ( id TEXT PRIMARY KEY, name TEXT NOT NULL, sort_name TEXT NOT NULL, cover_art TEXT, starred_at TEXT ); CREATE TABLE albums ( id TEXT PRIMARY KEY, artist_id TEXT NOT NULL REFERENCES artists(id) ON DELETE CASCADE, name TEXT NOT NULL, year INTEGER, genre TEXT, cover_art TEXT, created_at TEXT NOT NULL, starred_at TEXT, user_rating INTEGER ); CREATE TABLE songs ( id TEXT PRIMARY KEY, album_id TEXT NOT NULL REFERENCES albums(id) ON DELETE CASCADE, artist_id TEXT NOT NULL REFERENCES artists(id) ON DELETE CASCADE, title TEXT NOT NULL, artist_name TEXT NOT NULL, album_name TEXT NOT NULL, track_number INTEGER, disc_number INTEGER DEFAULT 1, year INTEGER, genre TEXT, duration INTEGER NOT NULL, bit_rate INTEGER NOT NULL, size INTEGER NOT NULL, suffix TEXT NOT NULL, content_type TEXT NOT NULL, relative_path TEXT NOT NULL UNIQUE, file_mtime INTEGER NOT NULL, created_at TEXT NOT NULL, play_count INTEGER NOT NULL DEFAULT 0, last_played_at TEXT, starred_at TEXT, user_rating INTEGER ); CREATE TABLE playlists ( id TEXT PRIMARY KEY, name TEXT NOT NULL, comment TEXT, owner TEXT NOT NULL, is_public BOOLEAN NOT NULL DEFAULT 1, created_at TEXT NOT NULL, changed_at TEXT NOT NULL ); CREATE TABLE playlist_songs ( playlist_id TEXT NOT NULL REFERENCES playlists(id) ON DELETE CASCADE, song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE, position INTEGER NOT NULL, PRIMARY KEY (playlist_id, position) ); ``` --- ## 6. Spezifikation der MVP-Endpunkte ### Authentifizierung (`SubsonicAuth`) * Prüfe bei jedem `/rest/*`-Call (außer optional Healthcheck): * `u`: Muss mit `SUBSONIC_USER` übereinstimmen. * Entweder Token-Auth: `t` und `s` vorhanden -> prüfe `t.equals(md5(SUBSONIC_PASS + s), ignoreCase = true)`. * Oder Passwort-Auth: `p` vorhanden -> falls `p.startsWith("enc:")`, Hex-dekodieren, sonst direkt mit `SUBSONIC_PASS` vergleichen. * Bei Fehler: HTTP 200 mit Subsonic-Error-JSON (`code = 40`, `message = "Wrong username or password"`). ### Endpunkt-Liste 1. **System & Scan:** * `ping`: Leeres `subsonic-response` mit `status: "ok"`. * `getLicense`: `{"license": {"valid": true}}`. * `getOpenSubsonicExtensions`: Deklariert `[{"name": "formPost", "versions": [1]}, {"name": "songLyrics", "versions": [1]}]`. * `startScan` / `getScanStatus`: Startet asynchronen Coroutine-Scan und gibt `{"scanStatus": {"scanning": Boolean, "count": Long}}` zurück. 2. **Browsing & Suche:** * `getMusicFolders`: Liefert `[{"id": 1, "name": "Music"}]`. * `getIndexes`: Alphabetisch gruppierte Artists (`index: [{name: "A", artist: [...]}]`). * `getArtists`: Identische Alphabet-Struktur für ID3-basiertes Browsing (`artists: {ignoredArticles: "The El La Los Las Le Les", index: [...]}`). * `getArtist(id)`: Artist-Details inkl. Liste aller zugehörigen `album`-Objekte. * `getAlbum(id)`: Album-Details inkl. aller `song`-Objekte (sortiert nach `discNumber`, `trackNumber`). * `getSong(id)`: Einzelnes Song-Objekt. * `search3(query, artistCount, artistOffset, albumCount, albumOffset, songCount, songOffset)`: SQL-`LIKE`-Suche über Artists, Alben und Songs (`query=""` darf leere oder paginierte Ergebnisse liefern). 3. **Home-Feeds:** * `getAlbumList2(type, size, offset, fromYear, toYear, genre)`: Unterstützt `type` = `newest`, `recent`, `frequent`, `random`, `alphabeticalByName`, `alphabeticalByArtist`, `starred`, `byYear`, `byGenre`. * `getRandomSongs(size, genre, fromYear, toYear)`: Zufällige Songs aus der DB. 4. **Media & Artwork:** * `stream(id, maxBitRate, format)`: Liefert die Datei via `call.respondFile(file)` aus (Direct Play; `PartialContent`-Plugin übernimmt `Range`-Requests). Setzt `Content-Type` passend zur Datei. * `download(id)`: Wie `stream`, zusätzlich mit `Content-Disposition: attachment; filename="..."`. * `getCoverArt(id, size)`: Lädt das gecachte Cover aus `DATA_DIR/covers/{id}.jpg`. Falls `size` (Int) angegeben ist, skaliert `Thumbnailator` das Bild proportional auf `size x size` und cached die skalierte Variante (`{id}_{size}.jpg`). * `getLyricsBySongId(id)`: Liest eingebettete Lyrics (`FieldKey.LYRICS`) oder eine gleichnamige `.lrc`-Datei neben der Audiodatei und gibt sie im OpenSubsonic-`lyricsList`-Format zurück. 5. **Interaktion & Playlists:** * `scrobble(id, time, submission)`: Bei `submission=true` (Default) `play_count + 1` und `last_played_at` aktualisieren. * `star(id, albumId, artistId)` / `unstar(id, albumId, artistId)`: Setzt bzw. löscht `starred_at`. * `setRating(id, rating)`: Setzt `user_rating` (1–5; bei `0` auf `null`). * `getPlaylists`, `getPlaylist(id)`, `createPlaylist(playlistId, name, songId)`, `updatePlaylist(playlistId, name, comment, public, songIdToAdd, songIndexToRemove)`, `deletePlaylist(playlistId)`. --- ## 7. Schrittweise Implementierungs-Reihenfolge Setze das Projekt inkrementell in folgenden Schritten um und verifiziere jeden Schritt über `./gradlew test` bzw. `curl`: 1. **Setup & DB:** Erstelle `build.gradle.kts`, `AppConfig.kt`, `DatabaseFactory.kt` (inkl. SQLite WAL-Pragma) und `Tables.kt`. 2. **Scanner & Cover-Cache:** Implementiere `IdGenerator.kt`, `TagExtractor.kt` (`jaudiotagger`), `CoverArtService.kt` (`Thumbnailator`) und `MediaScanner.kt` (inkl. Entfernen gelöschter Dateien aus der DB). Führe beim Serverstart automatisch einen initialen Scan aus, falls die DB leer ist. 3. **Ktor Core & Auth:** Konfiguriere Ktor mit `PartialContent`, `ContentNegotiation` (`ignoreUnknownKeys = true`, `encodeDefaults = true`), `SubsonicAuth` und dem `SubsonicResponse`-Wrapper. 4. **Endpoints (Browsing + Media):** Implementiere System-, Browsing- und Media-Routes (`stream`, `download`, `getCoverArt`). 5. **Endpoints (Sync + Interaktion + Playlists):** Implementiere `getAlbumList2`, `search3`, `scrobble`, `star`/`unstar`, `setRating` und alle Playlist-Endpunkte. 6. **Containerisierung:** Erstelle ein Multi-Stage `Dockerfile` (Gradle Build -> `eclipse-temurin:21-jre-alpine` Runtime mit `-XX:+UseSerialGC -Xmx256m`) sowie eine `docker-compose.yml` mit Volumes für `/music:ro` und `/data`. 7. **Automatisierte Tests:** Schreibe Ktor-Integrationstests (`ktor-server-test-host`) für Auth-Hashing, deterministische IDs, `Range`-Header (`206 Partial Content`) beim Streaming und den kompletten Browsing-Flow (`getArtists` -> `getArtist` -> `getAlbum` -> `stream`).