docs: add how-to-use guide to the README

This commit is contained in:
TapTap committed 2026-11-13 11:55:38 +00:00
1 parent 643ee42f09
commit 37a5728d6c
1 file changed
+122
+122
View File
@@ -1,5 +1,125 @@
# MusicManager — Self-hosted OpenSubsonic Server (Kotlin / Ktor) # 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:<hex>` if it contains special characters).
### 6. Connect a client (Symfonium)
1. Add a new **Subsonic** server.
2. URL: `http://<host>: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=<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+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 ## 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**. 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 ### 6.4 Local development
See [How to use](#how-to-use) for the full setup. In short:
```bash ```bash
cp config/library.example.yaml config/library.yaml cp config/library.example.yaml config/library.yaml
cp config/users.example.yaml config/users.yaml cp config/users.example.yaml config/users.yaml