The Gitea registry rejects kaniko pushes from job containers with 401 reqPackageAccess even though the same credentials work from a normal machine, so the image job could never go green. Drop the image job; CI now only runs unit tests, the smoke test and the Helm chart lint. Add scripts/release.sh, which builds and pushes the image from a trusted machine and can optionally apply the users secret and run helm upgrade.
32 KiB
MusicManager - Self-hosted OpenSubsonic Server (Kotlin / Ktor)
How to use
This is the short version. The detailed design and endpoint reference follow in the sections below.
1. Prerequisites
- JVM 21 (or
nix-shellfrom this repository, which provides JDK 21, Gradle, ffmpeg and sqlite) ffmpegonPATH(used for transcoding; direct play works without it)- An MP3 library on disk, laid out as
Artist/Album/Track.mp3if tags are missing
2. Configure the library
Create the local config and media directories:
./gradlew setupLocal
This copies config/library.example.yaml to config/library.yaml (only when it does not exist), copies config/users.example.yaml to config/users.yaml and creates media/music plus media/longform. Both local config files are git-ignored, so git pull never touches them.
config/library.yaml defines every root the server indexes:
library:
folders:
- id: 1
name: "Music"
type: music
path: ./media/music
- id: 10
name: "Audiobooks & Podcasts"
type: longform
path: ./media/longform
The example file already uses these relative paths, so no edit is needed for local development. Relative paths are resolved from the working directory (./gradlew run uses the project root). For deployment, replace them with absolute paths such as /mnt/media/music/alice (see Section 6.1).
type: musicroots are assigned per user;type: longformroots are shared with every user.idmust be stable and unique (integers). It is part of song IDs, so do not renumber it after a scan.- Paths must exist and be readable, otherwise the server refuses to start with a clear error naming the folder.
3. Configure users
./gradlew setupLocal already created it. To recreate it manually:
cp config/users.example.yaml config/users.yaml
users:
- name: alice
password: "change-me"
admin: true
folders: [1]
folderslists the music folder IDs the user may see; long-form folders are added automatically.- At least one admin is needed to trigger scans.
- Passwords live only in this file and in memory. In production the file is provided by Vault (see Section 6.2);
config/users.yamlis git-ignored.
4. Start the server
nix-shell # optional: provides the toolchain
./gradlew run
Or build and run the fat JAR:
./gradlew shadowJar
java -jar build/libs/musicmanager-0.1.0-all.jar
The server listens on http://localhost:8080. Open http://localhost:8080/ui for the built-in test client (log in with a user from users.yaml). Override with PORT, DATA_DIR, LIBRARY_CONFIG, USERS_FILE, FFMPEG_PATH and WEB_UI (see Section 6.3). The SQLite database and cover cache are written to ./data.
On first start, the server scans automatically because the database is empty. After that, scans are manual.
5. Trigger a scan
Use an admin account. Token auth is what real clients use:
SALT=abc123
TOKEN=$(printf '%s%s' 'change-me' "$SALT" | md5sum | cut -d' ' -f1)
curl -s "http://localhost:8080/rest/startScan?u=alice&t=$TOKEN&s=$SALT&v=1.16.1&c=curl&f=json"
curl -s "http://localhost:8080/rest/getScanStatus?u=alice&t=$TOKEN&s=$SALT&v=1.16.1&c=curl&f=json"
For quick manual testing you can pass the password in plaintext instead: &p=change-me (use p=enc:<hex> if it contains special characters).
6. Connect a client (Symfonium)
For a quick browser check, open http://localhost:8080/ui and log in with a user from users.yaml. It lists folders, albums and songs and can play streams; it is a debugging aid, not a full music client.
For a real client:
- Add a new Subsonic server.
- URL:
http://<host>:8080(orhttps://subsonic.tap-tap.winwhen deployed). - Username and password from
users.yaml. - Let Symfonium sync. Music and long-form appear as separate music folders - select the one you want so the two content types never mix.
7. Verify it works
# health (no auth)
curl -s http://localhost:8080/health
# list the folders this user can see
curl -s "http://localhost:8080/rest/getMusicFolders?u=alice&t=$TOKEN&s=$SALT&v=1.16.1&c=curl&f=json"
# search and stream the first result
curl -s "http://localhost:8080/rest/search3?u=alice&t=$TOKEN&s=$SALT&v=1.16.1&c=curl&f=json&query=*&songCount=1"
curl -o track.mp3 "http://localhost:8080/rest/stream?u=alice&t=$TOKEN&s=$SALT&v=1.16.1&c=curl&f=json&id=<song-id>"
All responses are JSON (no XML). Errors are returned as HTTP 200 with a Subsonic error.code; HTTP status codes are reserved for transport-level problems.
8. Stop, back up, upgrade
- Stop the process gracefully (
Ctrl+CorSIGTERM); in-flight streams are allowed to finish. - Back up
DATA_DIR(SQLite database +covers/) while stopped, or usesqlite3 data/musicmanager.db ".backup backup.db". - The schema is migrated automatically by Flyway on startup.
- Re-running a scan only reads changed files (delta by mtime + size); IDs stay stable across scans.
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)
- Library indexing: index MP3 files only for now (other extensions are skipped and logged). Tags come first, with the folder layout
Artist/Album/Trackas fallback. Data is persisted in SQLite. - Symfonium sync: implement the OpenSubsonic browsing endpoints so Symfonium can sync the full catalog into its offline-first database.
- 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. - Two content types, never mixed: music and long-form (audiobooks, podcasts, lectures) live in separate music folders. Clients see and select them independently.
- 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.
- Transcoding: optional on-the-fly MP3 transcoding with
maxBitRateandtimeOffsetsupport. - 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-jammy) - Build: Gradle Kotlin DSL (
build.gradle.kts), ShadowJar fat JAR - Web: Ktor Server (Netty)
ktor-server-core,ktor-server-nettyktor-server-content-negotiation+ktor-serialization-kotlinx-jsonktor-server-partial-content(HTTPRange/206)ktor-server-status-pages,ktor-server-call-logging,ktor-server-auto-head-response
- Database: SQLite in
WALmode + JetBrains Exposed (exposed-core,exposed-dao,exposed-jdbc,exposed-java-time) +sqlite-jdbc+ HikariCP - Migrations: Flyway (
flyway-core) with versioned SQL undersrc/main/resources/db/migration - Audio metadata:
net.jthink:jaudiotagger(MP3/ID3 only for the MVP) - Covers:
net.coobird:thumbnailatorfor on-the-fly resizing - Transcoding:
ffmpegbinary 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 tests, local release script for image pushes
3. Project Structure
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
| |-- LibraryRepository.kt # Visibility-scoped browsing, feeds, genres, search
| |-- UserStateRepository.kt # Play counts, stars, ratings, bookmarks
| |-- PlaylistRepository.kt # Playlist CRUD and visibility
| |-- MediaRepository.kt # Scanner persistence and aggregate rebuilds
| `-- 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:
- Unicode NFC
- Trim and collapse internal whitespace
- 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.
albumshave 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_idin API responses means the album artist; track credits are exposed viadisplayArtist/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.
getMusicFoldersreturns the caller's assigned music folders plus the shared long-form folders.- Songs store
folder_id;music_foldersis 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 sizeduration: Int- secondsbitRate: Int- kbpssuffix: 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.queryParametersandcall.receiveParameters()(POSTapplication/x-www-form-urlencoded). - Declare the
formPostOpenSubsonic 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:
{
"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
streamacceptsmaxBitRate(kbps),formatandtimeOffset(seconds).- Direct play when no transcode is requested or when the source bitrate is already
<= maxBitRate. - Transcoding target is always MP3 (
libmp3lame). A requestedformatother thanmp3falls back to MP3. timeOffsetis implemented withffmpeg -ss, declared as thetranscodeOffsetOpenSubsonic extension.- Transcoded responses are chunked and do not support byte
Range. Seeking usestimeOffset. downloadalways returns the original file, never a transcode.- Direct-play responses support
Range/206via thePartialContentplugin.
5. Database Schema (SQLite)
Identity and folder tables are synced from config at startup; passwords are never stored in SQLite.
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)
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.
users:
- name: alice
password: "<from-vault>"
admin: true
folders: [1]
- name: bob
password: "<from-vault>"
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). usersandmusic_folderstables are reconciled on startup; removed users/folders are deleted with their per-user state or orphaned songs.- If
users.yamlis 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 |
WEB_UI |
true |
Serve the built-in test client at /ui |
6.4 Local development
See How to use for the full setup. In short:
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):
umust match a configured user.- Token auth:
tandspresent -> verifyt.equals(md5(password + s), ignoreCase = true). - Password auth:
ppresent -> ifpstarts withenc:, 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: emptysubsonic-responsewithstatus: "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}}.getUser(username): returns roles and visible folder IDs; users may only query themselves, admins may query anyone.getUsers: admin only; lists all configured users.
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[]}]), includinglastModifiedandignoredArticles.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 bydiscNumber,trackNumber.getSong(id): single song, only if visible to the caller.search3(query, ...Count, ...Offset): case-insensitive substring search over normalizedsearch_textusingLIKEwith escaped wildcards. Emptyqueryreturns 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 handlesRange); - otherwise stream ffmpeg MP3 output with chunked transfer;
- set
Content-Typefrom the actual response.
- direct play via
download(id): original file withContent-Disposition: attachment; filename*=UTF-8''...(RFC 5987 for non-ASCII names).getCoverArt(id, size): serveDATA_DIR/covers/{albumId}.jpg; ifsizeis given, resize proportionally with Thumbnailator and cache as{albumId}_{size}.jpg. Validatesize(1..2048).getLyricsBySongId(id): read embedded ID3 lyrics or a sibling.lrcfile; return the OpenSubsoniclyricsListformat.
7.6 Interaction, bookmarks & playlists
scrobble(id, time, submission): per user;submission=true(default) incrementsplay_countand setslast_played_at.star(id, albumId, artistId)/unstar(...): per user.setRating(id, rating): per user, 1-5;0clears.getBookmarks/createBookmark(id, position)/deleteBookmark(id): per user;positionis 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.getMusicDirectory(id): folder IDs return their albums as directories; album IDs return their songs. Used by folder-browsing clients.savePlayQueue/getPlayQueue(and the*ByIndexvariants): per-user queue kept in memory.jukeboxControl(action=status)returns a stopped status; other jukebox actions report that jukebox is unsupported.getInternetRadioStationsreturns an empty list; radio mutation endpoints report that radio is unsupported.
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
songstable is empty; otherwise rely onstartScan. - One scan at a time; a second
startScanreturns 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 -> glibc-based
eclipse-temurin:21-jre-jammywithffmpeginstalled (Alpine/musl is unsupported by sqlite-jdbc's bundled native library). - Runtime flags:
-XX:+UseSerialGC -Xmx256m(adjustable via Helm). - Non-root user (UID 10001), read-only root filesystem,
/tmpasemptyDir,/dataas PVC. - Image:
gitea.tap-tap.win/taptap/audiomanager:<tag>(registry paths must be lowercase). - Images are built and pushed from a trusted machine, not from Gitea Actions;
imagePullSecretis provided by the cluster.
Build and push the image:
docker login gitea.tap-tap.win
scripts/release.sh # tag = git short SHA, pushes :<sha> and :latest
scripts/release.sh --tag v1.0.0 # explicit tag
scripts/release.sh --deploy # also apply the users secret and helm upgrade
.gitea/workflows/ci.yaml only runs the test suite, the smoke script and the Helm
chart lint. Image builds do not run in CI because the Gitea registry rejects
pushes from job containers (401 Unauthorized: reqPackageAccess), while the same
credentials work from a normal machine. Releases therefore stay a deliberate local
step; scripts/release.sh --deploy covers build, push and helm upgrade.
9.2 Helm chart
charts/musicmanager renders:
- image repository/tag and
imagePullSecrets library.foldersinto a ConfigMap (/etc/musicmanager/library.yaml)users.existingSecret+ key (Vault-managed; never put passwords in values)- ingress host
subsonic.tap-tap.win, ingress class and TLS secret /dataPVC (size, storage class)hostPathmounts for music and long-form roots, both read-only- resource requests/limits, non-root security context, probes on
/health - optional
nodeSelector,tolerationsandaffinity
The secret is not created by the chart. Create it from the Vault-managed file:
kubectl create namespace musicmanager
kubectl -n musicmanager create secret generic musicmanager-users \
--from-file=users.yaml=config/users.yaml
helm upgrade --install musicmanager charts/musicmanager \
--namespace musicmanager \
--set image.tag=dev \
--set users.existingSecret=musicmanager-users
Adjust library.folders, media.music.hostPath and media.longform.hostPath for
the cluster. Every schedulable node must expose the same host paths; the chart
deliberately does not pin the pod to a node.
The server exits at startup if a configured root path is missing or unreadable, so the pod will not pass its readiness probe in that case.
9.3 Operations
- Backups: documented manual copy of
DATA_DIR(SQLite DB + covers) while the server is stopped, or viasqlite3 .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
.lrcfiles) underbuild/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
Rangerequest ->206 Partial Contentwith exact bytes- exact
size/duration/bitRate/suffix/contentTypefields - browsing flow:
getArtists->getArtist->getAlbum->stream search3with Unicode and wildcards- scrobble/star/rating/bookmark isolation between users
- playlist ownership and public visibility
- music directory browsing and server-side play queues
- transcoding:
maxBitRateproduces MP3,timeOffsetseeks (skipped whenffmpegis unavailable)
- token and password auth,
Compatibility smoke test
scripts/smoke.sh generates a tagged MP3 with ffmpeg, starts the real server against a temporary library, and checks every endpoint a Subsonic client uses (browsing, feeds, search, stars, ratings, bookmarks, playlists, queues, stream with Range, download and covers). It prints PASS/FAIL per endpoint and exits non-zero on the first failure summary:
nix-shell --run scripts/smoke.sh
# or, with ffmpeg/sqlite/curl installed:
scripts/smoke.sh
The work directory can be passed as the first argument; the server log is kept there for debugging.
11. Implementation Order
Verify each step with ./gradlew test and/or curl:
- 1. Setup & DB:
build.gradle.kts,AppConfig.kt,LibraryConfig.kt,UsersConfig.kt,DatabaseFactory.kt(WAL + Flyway),Tables.kt,V1__init.sql. - 2. Scanner & covers:
IdGenerator.kt,Mp3TagExtractor.kt,CoverArtService.kt,MediaScanner.kt(delta + orphan cleanup + startup scan when empty). - 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
curlsmoke script.
12. Open Items / Assumptions
- Gitea registry path: image is
gitea.tap-tap.win/taptap/audiomanager(lowercased package ownertaptap). - Vault layout: the chart expects a secret with a
users.yamlkey. Exact Vault path/agent template is deployment-side and not part of the app. - Per-user music roots: Vault/config must contain one folder entry per user root (e.g.
/mnt/media/music/<user>); there is no implicit path convention. - hostPath without pinning: requires
/mnt/media/musicand/mnt/media/longformto exist on every node that can schedule the pod. Add anodeSelectorlater if that changes. - Long-form modelling: audiobooks/podcasts are albums/tracks in long-form folders; no RSS ingestion or chapter model.
- No XML: clients that insist on XML are unsupported.
- No user-management API: user changes are applied on restart after the Vault secret/config is updated.
- Backups are manual and documented; no backup endpoint.