961341b449afbb05556b8e0a32fe7e6d003d40c2
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`).
Languages
Kotlin
89.3%
Shell
9.4%
Dockerfile
0.7%
Go Template
0.5%
Nix
0.1%