215 lines
13 KiB
Plaintext
215 lines
13 KiB
Plaintext
# 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`).
|