From 37a5728d6cc9093493205400a682f43bb3583363 Mon Sep 17 00:00:00 2001 From: TapTap Date: Fri, 13 Nov 2026 11:55:38 +0000 Subject: [PATCH] docs: add how-to-use guide to the README --- README | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/README b/README index bbd6df8..97e4dac 100644 --- a/README +++ b/README @@ -1,5 +1,125 @@ # 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-shell` from this repository, which provides JDK 21, Gradle, ffmpeg and sqlite) +- `ffmpeg` on `PATH` (used for transcoding; direct play works without it) +- An MP3 library on disk, laid out as `Artist/Album/Track.mp3` if tags are missing + +### 2. Configure the library + +Copy the example config and edit the folder paths: + +```bash +cp config/library.example.yaml config/library.yaml +mkdir -p media/music media/longform +``` + +`config/library.yaml` defines every root the server indexes: + +```yaml +library: + folders: + - id: 1 + name: "Alice — Music" + type: music + path: /absolute/path/to/music/alice + - id: 10 + name: "Audiobooks & Podcasts" + type: longform + path: /absolute/path/to/longform +``` + +- `type: music` roots are assigned per user; `type: longform` roots are shared with every user. +- `id` must 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. + +### 3. Configure users + +```bash +cp config/users.example.yaml config/users.yaml +``` + +```yaml +users: + - name: alice + password: "change-me" + admin: true + folders: [1] +``` + +- `folders` lists 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 §6.2); `config/users.yaml` is git-ignored. + +### 4. Start the server + +```bash +nix-shell # optional: provides the toolchain +./gradlew run +``` + +Or build and run the fat JAR: + +```bash +./gradlew shadowJar +java -jar build/libs/musicmanager-0.1.0-all.jar +``` + +The server listens on `http://localhost:8080`. Override with `PORT`, `DATA_DIR`, `LIBRARY_CONFIG`, `USERS_FILE` and `FFMPEG_PATH` (see §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: + +```bash +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:` if it contains special characters). + +### 6. Connect a client (Symfonium) + +1. Add a new **Subsonic** server. +2. URL: `http://:8080` (or `https://subsonic.tap-tap.win` when deployed). +3. Username and password from `users.yaml`. +4. 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 + +```bash +# 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=" +``` + +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+C` or `SIGTERM`); in-flight streams are allowed to finish. +- Back up `DATA_DIR` (SQLite database + `covers/`) while stopped, or use `sqlite3 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**. @@ -385,6 +505,8 @@ users: ### 6.4 Local development +See [How to use](#how-to-use) for the full setup. In short: + ```bash cp config/library.example.yaml config/library.yaml cp config/users.example.yaml config/users.yaml