# 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`).
