docs: add how-to-use guide to the README
This commit is contained in:
1 parent
643ee42f09
commit
37a5728d6c
1 file changed
+122
@@ -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
|
||||||
|
|||||||
Reference in new issue
Block a user