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)
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user