docs: replace ambiguous Unicode characters in README with ASCII
This commit is contained in:
1 parent
37a5728d6c
commit
405fd07fb3
1 file changed
+55
-55
@@ -1,4 +1,4 @@
|
||||
# MusicManager — Self-hosted OpenSubsonic Server (Kotlin / Ktor)
|
||||
# MusicManager - Self-hosted OpenSubsonic Server (Kotlin / Ktor)
|
||||
|
||||
## How to use
|
||||
|
||||
@@ -25,7 +25,7 @@ mkdir -p media/music media/longform
|
||||
library:
|
||||
folders:
|
||||
- id: 1
|
||||
name: "Alice — Music"
|
||||
name: "Alice - Music"
|
||||
type: music
|
||||
path: /absolute/path/to/music/alice
|
||||
- id: 10
|
||||
@@ -54,7 +54,7 @@ users:
|
||||
|
||||
- `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.
|
||||
- Passwords live only in this file and in memory. In production the file is provided by Vault (see Section 6.2); `config/users.yaml` is git-ignored.
|
||||
|
||||
### 4. Start the server
|
||||
|
||||
@@ -70,7 +70,7 @@ Or build and run the fat JAR:
|
||||
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`.
|
||||
The server listens on `http://localhost:8080`. Override with `PORT`, `DATA_DIR`, `LIBRARY_CONFIG`, `USERS_FILE` and `FFMPEG_PATH` (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.
|
||||
|
||||
@@ -93,7 +93,7 @@ For quick manual testing you can pass the password in plaintext instead: `&p=cha
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -178,38 +178,38 @@ Build a lightweight, self-hosted **OpenSubsonic-compatible music server** in **K
|
||||
|
||||
```text
|
||||
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
|
||||
│ ├── Repositories.kt # CRUD & queries for artists, albums, songs, playlists
|
||||
│ └── 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
|
||||
|-- 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
|
||||
| |-- Repositories.kt # CRUD & queries for artists, albums, songs, playlists
|
||||
| `-- 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
|
||||
```
|
||||
|
||||
---
|
||||
@@ -258,11 +258,11 @@ Albums are grouped by the `ALBUM_ARTIST` tag. Fallbacks: `ARTIST` tag, then pare
|
||||
|
||||
Every song object must include:
|
||||
|
||||
- `size: Long` — exact byte size
|
||||
- `duration: Int` — seconds
|
||||
- `bitRate: Int` — kbps
|
||||
- `suffix: String` — `"mp3"`
|
||||
- `contentType: String` — `"audio/mpeg"`
|
||||
- `size: Long` - exact byte size
|
||||
- `duration: Int` - seconds
|
||||
- `bitRate: Int` - kbps
|
||||
- `suffix: String` - `"mp3"`
|
||||
- `contentType: String` - `"audio/mpeg"`
|
||||
|
||||
Symfonium verifies downloaded bytes against `size` after each offline download.
|
||||
|
||||
@@ -458,11 +458,11 @@ All timestamps are ISO 8601 in UTC.
|
||||
library:
|
||||
folders:
|
||||
- id: 1
|
||||
name: "Alice — Music"
|
||||
name: "Alice - Music"
|
||||
type: music
|
||||
path: /mnt/media/music/alice
|
||||
- id: 2
|
||||
name: "Bob — Music"
|
||||
name: "Bob - Music"
|
||||
type: music
|
||||
path: /mnt/media/music/bob
|
||||
- id: 10
|
||||
@@ -473,7 +473,7 @@ library:
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
```yaml
|
||||
users:
|
||||
@@ -529,8 +529,8 @@ All endpoints live under `/rest/{endpoint}` and `/rest/{endpoint}.view`.
|
||||
For every `/rest/*` call (except an optional health check):
|
||||
|
||||
- `u` must match a configured user.
|
||||
- Token auth: `t` and `s` present → verify `t.equals(md5(password + s), ignoreCase = true)`.
|
||||
- Password auth: `p` present → if `p` starts with `enc:`, hex-decode it; compare to the password.
|
||||
- Token auth: `t` and `s` present -> verify `t.equals(md5(password + s), ignoreCase = true)`.
|
||||
- Password auth: `p` present -> if `p` starts with `enc:`, 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.
|
||||
@@ -551,7 +551,7 @@ For every `/rest/*` call (except an optional health check):
|
||||
- `getArtist(id)`: artist details plus all visible albums.
|
||||
- `getAlbum(id)`: album details plus visible songs, sorted by `discNumber`, `trackNumber`.
|
||||
- `getSong(id)`: single song, only if visible to the caller.
|
||||
- `search3(query, …Count, …Offset)`: case-insensitive substring search over normalized `search_text` using `LIKE` with escaped wildcards. Empty `query` returns paginated results; `query="*"` returns everything visible.
|
||||
- `search3(query, ...Count, ...Offset)`: case-insensitive substring search over normalized `search_text` using `LIKE` with escaped wildcards. Empty `query` returns 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.
|
||||
@@ -567,7 +567,7 @@ For every `/rest/*` call (except an optional health check):
|
||||
- direct play via `call.respondFile` (PartialContent handles `Range`);
|
||||
- otherwise stream ffmpeg MP3 output with chunked transfer;
|
||||
- set `Content-Type` from the actual response.
|
||||
- `download(id)`: original file with `Content-Disposition: attachment; filename*=UTF-8''…` (RFC 5987 for non-ASCII names).
|
||||
- `download(id)`: original file with `Content-Disposition: attachment; filename*=UTF-8''...` (RFC 5987 for non-ASCII names).
|
||||
- `getCoverArt(id, size)`: serve `DATA_DIR/covers/{albumId}.jpg`; if `size` is given, resize proportionally with Thumbnailator and cache as `{albumId}_{size}.jpg`. Validate `size` (`1..2048`).
|
||||
- `getLyricsBySongId(id)`: read embedded ID3 lyrics or a sibling `.lrc` file; return the OpenSubsonic `lyricsList` format.
|
||||
|
||||
@@ -575,7 +575,7 @@ For every `/rest/*` call (except an optional health check):
|
||||
|
||||
- `scrobble(id, time, submission)`: per user; `submission=true` (default) increments `play_count` and sets `last_played_at`.
|
||||
- `star(id, albumId, artistId)` / `unstar(...)`: per user.
|
||||
- `setRating(id, rating)`: per user, 1–5; `0` clears.
|
||||
- `setRating(id, rating)`: per user, 1-5; `0` clears.
|
||||
- `getBookmarks` / `createBookmark(id, position)` / `deleteBookmark(id)`: per user; `position` is milliseconds.
|
||||
- `getPlaylists`: the caller's playlists plus all public ones.
|
||||
- `getPlaylist(id)`: if public or owned by the caller.
|
||||
@@ -599,7 +599,7 @@ No `createUser` / `updateUser` / `deleteUser` endpoints: config/Vault is the sou
|
||||
- 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.
|
||||
Cover extraction order: embedded APIC frame -> `cover.jpg`/`folder.jpg`/`front.jpg` next to the file -> album directory -> none.
|
||||
|
||||
---
|
||||
|
||||
@@ -607,7 +607,7 @@ Cover extraction order: embedded APIC frame → `cover.jpg`/`folder.jpg`/`front.
|
||||
|
||||
### 9.1 Image
|
||||
|
||||
- Multi-stage Dockerfile: Gradle build → `eclipse-temurin:21-jre-alpine` with `ffmpeg` installed.
|
||||
- Multi-stage Dockerfile: Gradle build -> `eclipse-temurin:21-jre-alpine` with `ffmpeg` installed.
|
||||
- Runtime flags: `-XX:+UseSerialGC -Xmx256m` (adjustable via Helm).
|
||||
- Non-root user (UID 10001), read-only root filesystem, `/tmp` as `emptyDir`, `/data` as PVC.
|
||||
- Image: `gitea.tap-tap.win/tap-tap/audiomanager:<tag>` (registry paths must be lowercase).
|
||||
@@ -641,12 +641,12 @@ The server fails its readiness probe if a configured root path is missing or unr
|
||||
|
||||
- No audio files are committed to the repository. A local script generates tiny silent MP3 fixtures (and `.lrc` files) under `build/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
|
||||
- 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
|
||||
- `Range` request → `206 Partial Content` with exact bytes
|
||||
- `Range` request -> `206 Partial Content` with exact bytes
|
||||
- exact `size` / `duration` / `bitRate` / `suffix` / `contentType` fields
|
||||
- browsing flow: `getArtists` → `getArtist` → `getAlbum` → `stream`
|
||||
- browsing flow: `getArtists` -> `getArtist` -> `getAlbum` -> `stream`
|
||||
- `search3` with Unicode and wildcards
|
||||
- scrobble/star/rating/bookmark isolation between users
|
||||
- playlist ownership and public visibility
|
||||
|
||||
Reference in new issue
Block a user