# MusicManager — Self-hosted OpenSubsonic Server (Kotlin / Ktor) ## 1. Goal & Context Build a lightweight, self-hosted **OpenSubsonic-compatible music server** in **Kotlin** that replaces Plex for audio streaming and is optimised for the Android client **Symfonium**. ### Scope (MVP) 1. **Library indexing:** index MP3 files only for now (other extensions are skipped and logged). Tags come first, with the folder layout `Artist/Album/Track` as fallback. Data is persisted in SQLite. 2. **Symfonium sync:** implement the OpenSubsonic browsing endpoints so Symfonium can sync the full catalog into its offline-first database. 3. **Streaming & offline downloads:** serve audio files with HTTP `Range` (`206 Partial Content`), exact byte sizes and correct metadata so seeking and Symfonium's offline download manager work reliably. 4. **Two content types, never mixed:** *music* and *long-form* (audiobooks, podcasts, lectures) live in **separate music folders**. Clients see and select them independently. 5. **Multi-user:** users are defined outside the database (config + HashiCorp Vault). Music roots are assigned per user, long-form is shared. Stars, ratings, play counts, bookmarks and playlists are per user. 6. **Transcoding:** optional on-the-fly MP3 transcoding with `maxBitRate` and `timeOffset` support. 7. **Extensibility:** clean separation between scanner, database layer and HTTP API so a downloader and a discovery/recommendation engine can be added later. ### Explicit non-goals (MVP) - Audio formats other than MP3 (FLAC/OGG/M4A/Opus are future work). - XML responses (JSON only). - Podcast RSS ingestion, chapters or audiobook-specific metadata. - Upload, sharing, social features. - User-management API (users come from config/Vault). - TLS inside the app (terminated by the k3s ingress). - Automatic filesystem watching (scans are manual or on boot when the DB is empty). - Backups (documented manual procedure only). ### Roles - **Admin:** may trigger scans. - **User:** regular library access. - All users share the same long-form roots; each user has their own music roots. - Per-user state: play counts, last played, stars, ratings, bookmarks, playlists. --- ## 2. Tech Stack & Dependencies - **Language & runtime:** Kotlin 2.x on JVM 21 (`eclipse-temurin:21-jre-alpine`) - **Build:** Gradle Kotlin DSL (`build.gradle.kts`), ShadowJar fat JAR - **Web:** Ktor Server (Netty) - `ktor-server-core`, `ktor-server-netty` - `ktor-server-content-negotiation` + `ktor-serialization-kotlinx-json` - `ktor-server-partial-content` (HTTP `Range` / `206`) - `ktor-server-status-pages`, `ktor-server-call-logging`, `ktor-server-auto-head-response` - **Database:** SQLite in `WAL` mode + JetBrains Exposed (`exposed-core`, `exposed-dao`, `exposed-jdbc`, `exposed-java-time`) + `sqlite-jdbc` + HikariCP - **Migrations:** Flyway (`flyway-core`) with versioned SQL under `src/main/resources/db/migration` - **Audio metadata:** `net.jthink:jaudiotagger` (MP3/ID3 only for the MVP) - **Covers:** `net.coobird:thumbnailator` for on-the-fly resizing - **Transcoding:** `ffmpeg` binary in the runtime image (libmp3lame), invoked as a subprocess - **Logging:** `logback-classic` + `kotlin-logging-jvm` - **Config:** YAML (`library.yaml`, `users.yaml`) with env-var overrides for paths and secrets - **Deployment:** multi-stage Dockerfile, Helm chart for k3s, Gitea Actions for image builds --- ## 3. Project Structure ```text src/main/kotlin/win/taptap/musicmanager/ ├── Application.kt # Ktor entry point, plugins, graceful shutdown ├── config/ │ ├── AppConfig.kt # Port, data dir, ffmpeg path, env overrides │ ├── LibraryConfig.kt # Music folders and their type/path │ └── UsersConfig.kt # Users, admins and folder assignments ├── db/ │ ├── DatabaseFactory.kt # SQLite init, PRAGMA journal_mode=WAL, Flyway │ ├── Tables.kt # Exposed table definitions │ ├── Repositories.kt # CRUD & queries for artists, albums, songs, playlists │ └── migrations/ # Flyway SQL (V1__init.sql, ...) ├── scanner/ │ ├── MediaScanner.kt # Recursive scan, delta updates, orphan cleanup │ ├── Mp3TagExtractor.kt # jaudiotagger wrapper (tags, path fallback, duration, bitrate) │ └── CoverArtService.kt # Cover extraction from tags/folders, disk cache, resizing ├── subsonic/ │ ├── SubsonicAuth.kt # Token (u, t, s) and password (p, enc:) auth │ ├── SubsonicResponse.kt # JSON envelope & error codes │ ├── models/ # kotlinx.serialization DTOs │ │ ├── SystemModels.kt │ │ ├── BrowsingModels.kt │ │ ├── MediaModels.kt │ │ └── PlaylistModels.kt │ └── routes/ # /rest/{endpoint} and /rest/{endpoint}.view │ ├── SystemRoutes.kt # ping, getLicense, extensions, startScan, getScanStatus │ ├── BrowsingRoutes.kt # indexes, artists, album, song, search3, lists, genres │ ├── MediaRoutes.kt # stream, download, getCoverArt, lyrics │ ├── InteractionRoutes.kt # scrobble, star/unstar, setRating, getStarred2 │ └── PlaylistRoutes.kt # playlists and playlist songs ├── transcoding/ │ └── FfmpegTranscoder.kt # MP3 transcoding with maxBitRate and timeOffset └── util/ └── IdGenerator.kt # Deterministic SHA-256 IDs ``` --- ## 4. Architecture Rules ### 4.1 Deterministic IDs (critical) IDs must never change on a re-scan; otherwise Symfonium loses offline download state and playlist assignments. - IDs use **24 hex characters** (96 bit). - **Artist ID:** `"ar-" + sha256(normalizedAlbumArtist).take(24)` - **Album ID:** `"al-" + sha256(normalizedAlbumArtist + "|" + normalizedAlbumTitle).take(24)` - **Song ID:** `"sg-" + sha256(folderId + ":" + relativePathFromFolderRoot).take(24)` - **Cover ID:** same as the album ID (`"al-..."`). Artist artwork is not served in the MVP. **Normalization is frozen** and must never change without a migration: 1. Unicode NFC 2. Trim and collapse internal whitespace 3. Lowercase with `Locale.ROOT` Song IDs are path-based: renaming or moving a file creates a new ID. This is accepted. ### 4.2 Album grouping via album artist Albums are grouped by the `ALBUM_ARTIST` tag. Fallbacks: `ARTIST` tag, then parent folder name. This prevents albums with featuring artists from fragmenting. - `albums` have one or more artists (`album_artists`), position 0 is the primary album artist. - Songs additionally keep a display artist string and their full artist list (`song_artists`). - `song.artist_id` in API responses means the **album artist**; track credits are exposed via `displayArtist` / `artists[]`. ### 4.3 User-scoped library visibility - The catalog is global; users see only folders assigned to them. - Every browsing and media query filters songs by the requesting user's visible folder IDs. - Because album IDs are deterministic and roots can contain the same album for different users, an album may aggregate songs from several folders. Therefore: - `getAlbum(id)` returns only songs from folders visible to the caller. - An album/artist is returned only if it has at least one visible song. - Album-level names, years and covers are global; per-user state is never global. - `getMusicFolders` returns the caller's assigned music folders plus the shared long-form folders. - Songs store `folder_id`; `music_folders` is synced from config on startup and referenced by foreign key. - Long-form content uses the same artist/album/song model; separation is via folder type, not a separate API. ### 4.4 Exact file metadata for offline downloads Every song object must include: - `size: Long` — exact byte size - `duration: Int` — seconds - `bitRate: Int` — kbps - `suffix: String` — `"mp3"` - `contentType: String` — `"audio/mpeg"` Symfonium verifies downloaded bytes against `size` after each offline download. ### 4.5 Routing conventions & `formPost` - Register every endpoint for **both** `/{method}` and `/{method}.view`. - Read parameters from `call.request.queryParameters` **and** `call.receiveParameters()` (POST `application/x-www-form-urlencoded`). - Declare the `formPost` OpenSubsonic extension. - Repeatable parameters (`songId`, `songIdToAdd`, `songIndexToRemove`) must be read as lists. ### 4.6 JSON envelope Every response, including errors, uses `status: "ok"` or `status: "failed"` and HTTP 200: ```json { "subsonic-response": { "status": "ok", "version": "1.16.1", "type": "musicmanager", "serverVersion": "0.1.0", "openSubsonic": true } } ``` Error codes: `0` generic, `10` missing parameter, `20` incompatible client, `30` incompatible server, `40` wrong credentials, `50` not authorized, `70` not found. ### 4.7 Transcoding rules - `stream` accepts `maxBitRate` (kbps), `format` and `timeOffset` (seconds). - Direct play when no transcode is requested or when the source bitrate is already `<= maxBitRate`. - Transcoding target is always **MP3** (`libmp3lame`). A requested `format` other than `mp3` falls back to MP3. - `timeOffset` is implemented with `ffmpeg -ss`, declared as the `transcodeOffset` OpenSubsonic extension. - Transcoded responses are chunked and do **not** support byte `Range`. Seeking uses `timeOffset`. - `download` always returns the original file, never a transcode. - Direct-play responses support `Range` / `206` via the `PartialContent` plugin. --- ## 5. Database Schema (SQLite) Identity and folder tables are synced from config at startup; passwords are never stored in SQLite. ```sql CREATE TABLE users ( name TEXT PRIMARY KEY, is_admin BOOLEAN NOT NULL DEFAULT 0, updated_at TEXT NOT NULL ); CREATE TABLE music_folders ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, type TEXT NOT NULL CHECK (type IN ('music', 'longform')), root_path TEXT NOT NULL ); CREATE TABLE artists ( id TEXT PRIMARY KEY, name TEXT NOT NULL, sort_name TEXT NOT NULL, cover_art TEXT, search_text TEXT NOT NULL ); CREATE TABLE albums ( id TEXT PRIMARY KEY, name TEXT NOT NULL, year INTEGER, cover_art TEXT, created_at TEXT NOT NULL, search_text TEXT NOT NULL ); CREATE TABLE album_artists ( album_id TEXT NOT NULL REFERENCES albums(id) ON DELETE CASCADE, artist_id TEXT NOT NULL REFERENCES artists(id) ON DELETE CASCADE, position INTEGER NOT NULL, PRIMARY KEY (album_id, position) ); CREATE TABLE songs ( id TEXT PRIMARY KEY, album_id TEXT NOT NULL REFERENCES albums(id) ON DELETE CASCADE, folder_id INTEGER NOT NULL REFERENCES music_folders(id), title TEXT NOT NULL, display_artist TEXT NOT NULL, album_name TEXT NOT NULL, track_number INTEGER, disc_number INTEGER DEFAULT 1, year INTEGER, 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, file_mtime INTEGER NOT NULL, created_at TEXT NOT NULL, search_text TEXT NOT NULL, UNIQUE (folder_id, relative_path) ); CREATE TABLE song_artists ( song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE, artist_id TEXT NOT NULL REFERENCES artists(id) ON DELETE CASCADE, position INTEGER NOT NULL, PRIMARY KEY (song_id, position) ); -- Multi-value tags. Text keys keep the schema simple; uniqueness is enforced. CREATE TABLE song_genres ( song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE, genre TEXT NOT NULL, PRIMARY KEY (song_id, genre) ); CREATE TABLE album_genres ( album_id TEXT NOT NULL REFERENCES albums(id) ON DELETE CASCADE, genre TEXT NOT NULL, PRIMARY KEY (album_id, genre) ); CREATE TABLE artist_genres ( artist_id TEXT NOT NULL REFERENCES artists(id) ON DELETE CASCADE, genre TEXT NOT NULL, PRIMARY KEY (artist_id, genre) ); -- Per-user state CREATE TABLE user_song_state ( user_name TEXT NOT NULL REFERENCES users(name) ON DELETE CASCADE, song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE, play_count INTEGER NOT NULL DEFAULT 0, last_played_at TEXT, starred_at TEXT, rating INTEGER, PRIMARY KEY (user_name, song_id) ); CREATE TABLE user_stars ( user_name TEXT NOT NULL REFERENCES users(name) ON DELETE CASCADE, item_type TEXT NOT NULL CHECK (item_type IN ('album', 'artist')), item_id TEXT NOT NULL, starred_at TEXT NOT NULL, PRIMARY KEY (user_name, item_type, item_id) ); CREATE TABLE bookmarks ( user_name TEXT NOT NULL REFERENCES users(name) ON DELETE CASCADE, song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE, position_ms INTEGER NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (user_name, song_id) ); CREATE TABLE playlists ( id TEXT PRIMARY KEY, owner TEXT NOT NULL REFERENCES users(name) ON DELETE CASCADE, name TEXT NOT NULL, comment TEXT, 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) ); ``` Required indexes: - `albums(search_text)`, `artists(search_text)`, `songs(search_text)` - `songs(album_id)`, `songs(folder_id)`, `songs(created_at)` - `album_artists(artist_id)`, `song_artists(artist_id)` - `user_song_state(user_name, starred_at)`, `user_stars(user_name, item_type)` - `playlist_songs(song_id)`, `playlists(owner)` All timestamps are ISO 8601 in UTC. --- ## 6. Configuration ### 6.1 `library.yaml` (ConfigMap) ```yaml library: folders: - id: 1 name: "Alice — Music" type: music path: /mnt/media/music/alice - id: 2 name: "Bob — Music" type: music path: /mnt/media/music/bob - id: 10 name: "Audiobooks & Podcasts" type: longform path: /mnt/media/longform ``` ### 6.2 `users.yaml` (Vault-managed Secret) Mounted from a HashiCorp Vault secret and read at startup. Passwords exist only in that secret and in memory — never in SQLite, logs or the Helm chart. ```yaml users: - name: alice password: "" admin: true folders: [1] - name: bob password: "" admin: false folders: [2] ``` - Long-form folders are shared automatically; users only list their music folders. - Env override: `USERS_FILE` (default `./config/users.yaml`; in the container `/etc/musicmanager/users.yaml`). - Env override: `LIBRARY_CONFIG` (default `./config/library.yaml`; in the container `/etc/musicmanager/library.yaml`). - `users` and `music_folders` tables are reconciled on startup; removed users/folders are deleted with their per-user state or orphaned songs. - If `users.yaml` is missing or empty, the server refuses to start (fail closed). ### 6.3 Environment variables | Variable | Default | Purpose | | --- | --- | --- | | `PORT` | `8080` | HTTP listen port | | `DATA_DIR` | `./data` | SQLite DB and cover cache (`/data` in Kubernetes) | | `LIBRARY_CONFIG` | `./config/library.yaml` | Library folder definitions | | `USERS_FILE` | `./config/users.yaml` | Vault-managed users file | | `FFMPEG_PATH` | `ffmpeg` | ffmpeg binary used for transcoding | ### 6.4 Local development ```bash cp config/library.example.yaml config/library.yaml cp config/users.example.yaml config/users.yaml mkdir -p media/music media/longform # edit the paths in config/library.yaml to point at ./media/* nix-shell # optional: JDK 21, Gradle, ffmpeg and sqlite ./gradlew run ``` The database and covers are written to `./data`. `config/users.yaml` is git-ignored. --- ## 7. MVP Endpoint Specification All endpoints live under `/rest/{endpoint}` and `/rest/{endpoint}.view`. ### 7.1 Authentication (`SubsonicAuth`) For every `/rest/*` call (except an optional health check): - `u` must match a configured user. - Token auth: `t` and `s` present → verify `t.equals(md5(password + s), ignoreCase = true)`. - Password auth: `p` present → if `p` starts with `enc:`, hex-decode it; compare to the password. - Comparisons use constant-time equality. - On failure: HTTP 200 with a Subsonic error (`code = 40`). - The authenticated user is attached to the call and used for all per-user filtering and state. ### 7.2 System & scan - `ping`: empty `subsonic-response` with `status: "ok"`. - `getLicense`: `{"license": {"valid": true}}`. - `getOpenSubsonicExtensions`: `[{formPost, [1]}, {songLyrics, [1]}, {transcodeOffset, [1]}]`. - `startScan`: admin only; starts an async coroutine scan. - `getScanStatus`: `{"scanStatus": {"scanning": Boolean, "count": Long}}`. ### 7.3 Browsing & search - `getMusicFolders`: the caller's music folders plus shared long-form folders. - `getIndexes`: alphabetically grouped artists visible to the caller (`index: [{name, artist[]}]`), including `lastModified` and `ignoredArticles`. - `getArtists`: ID3-based alphabet structure (`artists: {ignoredArticles, index[]}`), filtered by visibility. - `getArtist(id)`: artist details plus all visible albums. - `getAlbum(id)`: album details plus visible songs, sorted by `discNumber`, `trackNumber`. - `getSong(id)`: single song, only if visible to the caller. - `search3(query, …Count, …Offset)`: case-insensitive substring search over normalized `search_text` using `LIKE` with escaped wildcards. Empty `query` returns paginated results; `query="*"` returns everything visible. - `getGenres`: distinct genres from visible songs. - `getSongsByGenre(genre, count, offset)`: paginated visible songs in a genre. - `getStarred2`: the caller's starred artists, albums and songs for the home screen. ### 7.4 Home feeds - `getAlbumList2(type, size, offset, fromYear, toYear, genre)`: `newest`, `recent`, `frequent`, `random`, `alphabeticalByName`, `alphabeticalByArtist`, `starred`, `byYear`, `byGenre`. All results are visibility- and user-scoped. - `getRandomSongs(size, genre, fromYear, toYear)`: random visible songs. ### 7.5 Media & artwork - `stream(id, maxBitRate, format, timeOffset)`: - direct play via `call.respondFile` (PartialContent handles `Range`); - otherwise stream ffmpeg MP3 output with chunked transfer; - set `Content-Type` from the actual response. - `download(id)`: original file with `Content-Disposition: attachment; filename*=UTF-8''…` (RFC 5987 for non-ASCII names). - `getCoverArt(id, size)`: serve `DATA_DIR/covers/{albumId}.jpg`; if `size` is given, resize proportionally with Thumbnailator and cache as `{albumId}_{size}.jpg`. Validate `size` (`1..2048`). - `getLyricsBySongId(id)`: read embedded ID3 lyrics or a sibling `.lrc` file; return the OpenSubsonic `lyricsList` format. ### 7.6 Interaction, bookmarks & playlists - `scrobble(id, time, submission)`: per user; `submission=true` (default) increments `play_count` and sets `last_played_at`. - `star(id, albumId, artistId)` / `unstar(...)`: per user. - `setRating(id, rating)`: per user, 1–5; `0` clears. - `getBookmarks` / `createBookmark(id, position)` / `deleteBookmark(id)`: per user; `position` is milliseconds. - `getPlaylists`: the caller's playlists plus all public ones. - `getPlaylist(id)`: if public or owned by the caller. - `createPlaylist(playlistId, name, songId)`: owner is the caller. - `updatePlaylist(playlistId, name, comment, public, songIdToAdd, songIndexToRemove)`: owner only; indices are applied in order. - `deletePlaylist(playlistId)`: owner only. No `createUser` / `updateUser` / `deleteUser` endpoints: config/Vault is the source of truth. --- ## 8. Scanner - Scan all configured folder roots recursively; accept `.mp3` (case-insensitive) only, log every skipped file. - Tag-first: title, artist, album artist, album, track/disc, year, genre(s), duration, bitrate, embedded cover, lyrics. - Fallback: parent folder as album, grandparent as artist; filename as title. - Delta scan by `(file_mtime, size)`; unchanged files are skipped. - Orphan cleanup: delete songs (and their state) whose files disappeared. - Initial scan on startup only when the `songs` table is empty; otherwise rely on `startScan`. - One scan at a time; a second `startScan` returns the current status. - All writes in a single transaction per batch; streaming reads continue under WAL. - Album/artist rows are recomputed after each scan (aggregated genre lists, sort names, cover references). Cover extraction order: embedded APIC frame → `cover.jpg`/`folder.jpg`/`front.jpg` next to the file → album directory → none. --- ## 9. Deployment (k3s + Helm) ### 9.1 Image - Multi-stage Dockerfile: Gradle build → `eclipse-temurin:21-jre-alpine` with `ffmpeg` installed. - Runtime flags: `-XX:+UseSerialGC -Xmx256m` (adjustable via Helm). - Non-root user (UID 10001), read-only root filesystem, `/tmp` as `emptyDir`, `/data` as PVC. - Image: `gitea.tap-tap.win/tap-tap/audiomanager:` (registry paths must be lowercase). - Gitea Actions builds and pushes on tags; `imagePullSecret` is provided by the cluster. ### 9.2 Helm chart `charts/musicmanager` with values for: - image repository/tag, `imagePullSecrets` - `library` config (folders) rendered into a ConfigMap - `users.existingSecret` + key (Vault-managed; never put passwords in values) - ingress host `subsonic.tap-tap.win`, ingress class, TLS via cluster issuer - `/data` PVC (size, storage class) - `hostPath` mounts: `/mnt/media/music` and `/mnt/media/longform`, read-only - no node pinning: every schedulable node must expose the same mounts (documented) - resource requests/limits, security context, liveness/readiness probes (`/health`) - optional `nodeSelector`/`tolerations` for future use The server fails its readiness probe if a configured root path is missing or unreadable. ### 9.3 Operations - Backups: documented manual copy of `DATA_DIR` (SQLite DB + covers) while the server is stopped, or via `sqlite3 .backup`. - Logs to stdout (JSON optional), picked up by the cluster. - Graceful shutdown: stop accepting requests, finish in-flight streams, close the DB pool. --- ## 10. Testing - No audio files are committed to the repository. A local script generates tiny silent MP3 fixtures (and `.lrc` files) under `build/test-media`; integration tests skip if fixtures are absent. - Ktor integration tests (`ktor-server-test-host`): - token and password auth, `enc:` decoding, wrong credentials → code 40 - deterministic IDs and normalization - user visibility: user A cannot see or stream user B's music; both see long-form - `Range` request → `206 Partial Content` with exact bytes - exact `size` / `duration` / `bitRate` / `suffix` / `contentType` fields - browsing flow: `getArtists` → `getArtist` → `getAlbum` → `stream` - `search3` with Unicode and wildcards - scrobble/star/rating/bookmark isolation between users - playlist ownership and public visibility - transcoding: `maxBitRate` produces MP3, `timeOffset` seeks (skipped when `ffmpeg` is unavailable) --- ## 11. Implementation Order Verify each step with `./gradlew test` and/or `curl`: - [x] 1. **Setup & DB:** `build.gradle.kts`, `AppConfig.kt`, `LibraryConfig.kt`, `UsersConfig.kt`, `DatabaseFactory.kt` (WAL + Flyway), `Tables.kt`, `V1__init.sql`. - [x] 2. **Scanner & covers:** `IdGenerator.kt`, `Mp3TagExtractor.kt`, `CoverArtService.kt`, `MediaScanner.kt` (delta + orphan cleanup + startup scan when empty). - [x] 3. **Ktor core & auth:** `PartialContent`, content negotiation (`ignoreUnknownKeys`, `encodeDefaults`), `SubsonicAuth`, response wrapper, health endpoint. - [ ] 4. **Browsing & media:** system, browsing, genre and media routes (`stream`, `download`, `getCoverArt`). - [ ] 5. **Transcoding:** `FfmpegTranscoder.kt`, `maxBitRate`/`format`/`timeOffset`, extension declaration. - [ ] 6. **Interaction & playlists:** `getAlbumList2`, `getRandomSongs`, `getStarred2`, `search3`, `scrobble`, `star`/`unstar`, `setRating`, bookmarks, playlists. - [ ] 7. **Packaging:** multi-stage Dockerfile (with ffmpeg), Helm chart, Gitea Actions workflow. - [ ] 8. **Tests:** integration suite as described above, plus a `curl` smoke script. --- ## 12. Open Items / Assumptions 1. **Gitea registry path:** image assumed to be `gitea.tap-tap.win/tap-tap/audiomanager` (lowercased repo `TapTap/AudioManager`). 2. **Vault layout:** the chart expects a secret with a `users.yaml` key. Exact Vault path/agent template is deployment-side and not part of the app. 3. **Per-user music roots:** Vault/config must contain one folder entry per user root (e.g. `/mnt/media/music/`); there is no implicit path convention. 4. **hostPath without pinning:** requires `/mnt/media/music` and `/mnt/media/longform` to exist on every node that can schedule the pod. Add a `nodeSelector` later if that changes. 5. **Long-form modelling:** audiobooks/podcasts are albums/tracks in long-form folders; no RSS ingestion or chapter model. 6. **No XML:** clients that insist on XML are unsupported. 7. **No user-management API:** user changes are applied on restart after the Vault secret/config is updated. 8. **Backups** are manual and documented; no backup endpoint.