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
|
## How to use
|
||||||
|
|
||||||
@@ -25,7 +25,7 @@ mkdir -p media/music media/longform
|
|||||||
library:
|
library:
|
||||||
folders:
|
folders:
|
||||||
- id: 1
|
- id: 1
|
||||||
name: "Alice — Music"
|
name: "Alice - Music"
|
||||||
type: music
|
type: music
|
||||||
path: /absolute/path/to/music/alice
|
path: /absolute/path/to/music/alice
|
||||||
- id: 10
|
- id: 10
|
||||||
@@ -54,7 +54,7 @@ users:
|
|||||||
|
|
||||||
- `folders` lists the *music* folder IDs the user may see; long-form folders are added automatically.
|
- `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.
|
- 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
|
### 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
|
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.
|
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.
|
1. Add a new **Subsonic** server.
|
||||||
2. URL: `http://<host>:8080` (or `https://subsonic.tap-tap.win` when deployed).
|
2. URL: `http://<host>:8080` (or `https://subsonic.tap-tap.win` when deployed).
|
||||||
3. Username and password from `users.yaml`.
|
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
|
### 7. Verify it works
|
||||||
|
|
||||||
@@ -178,38 +178,38 @@ Build a lightweight, self-hosted **OpenSubsonic-compatible music server** in **K
|
|||||||
|
|
||||||
```text
|
```text
|
||||||
src/main/kotlin/win/taptap/musicmanager/
|
src/main/kotlin/win/taptap/musicmanager/
|
||||||
├── Application.kt # Ktor entry point, plugins, graceful shutdown
|
|-- Application.kt # Ktor entry point, plugins, graceful shutdown
|
||||||
├── config/
|
|-- config/
|
||||||
│ ├── AppConfig.kt # Port, data dir, ffmpeg path, env overrides
|
| |-- AppConfig.kt # Port, data dir, ffmpeg path, env overrides
|
||||||
│ ├── LibraryConfig.kt # Music folders and their type/path
|
| |-- LibraryConfig.kt # Music folders and their type/path
|
||||||
│ └── UsersConfig.kt # Users, admins and folder assignments
|
| `-- UsersConfig.kt # Users, admins and folder assignments
|
||||||
├── db/
|
|-- db/
|
||||||
│ ├── DatabaseFactory.kt # SQLite init, PRAGMA journal_mode=WAL, Flyway
|
| |-- DatabaseFactory.kt # SQLite init, PRAGMA journal_mode=WAL, Flyway
|
||||||
│ ├── Tables.kt # Exposed table definitions
|
| |-- Tables.kt # Exposed table definitions
|
||||||
│ ├── Repositories.kt # CRUD & queries for artists, albums, songs, playlists
|
| |-- Repositories.kt # CRUD & queries for artists, albums, songs, playlists
|
||||||
│ └── migrations/ # Flyway SQL (V1__init.sql, ...)
|
| `-- migrations/ # Flyway SQL (V1__init.sql, ...)
|
||||||
├── scanner/
|
|-- scanner/
|
||||||
│ ├── MediaScanner.kt # Recursive scan, delta updates, orphan cleanup
|
| |-- MediaScanner.kt # Recursive scan, delta updates, orphan cleanup
|
||||||
│ ├── Mp3TagExtractor.kt # jaudiotagger wrapper (tags, path fallback, duration, bitrate)
|
| |-- Mp3TagExtractor.kt # jaudiotagger wrapper (tags, path fallback, duration, bitrate)
|
||||||
│ └── CoverArtService.kt # Cover extraction from tags/folders, disk cache, resizing
|
| `-- CoverArtService.kt # Cover extraction from tags/folders, disk cache, resizing
|
||||||
├── subsonic/
|
|-- subsonic/
|
||||||
│ ├── SubsonicAuth.kt # Token (u, t, s) and password (p, enc:) auth
|
| |-- SubsonicAuth.kt # Token (u, t, s) and password (p, enc:) auth
|
||||||
│ ├── SubsonicResponse.kt # JSON envelope & error codes
|
| |-- SubsonicResponse.kt # JSON envelope & error codes
|
||||||
│ ├── models/ # kotlinx.serialization DTOs
|
| |-- models/ # kotlinx.serialization DTOs
|
||||||
│ │ ├── SystemModels.kt
|
| | |-- SystemModels.kt
|
||||||
│ │ ├── BrowsingModels.kt
|
| | |-- BrowsingModels.kt
|
||||||
│ │ ├── MediaModels.kt
|
| | |-- MediaModels.kt
|
||||||
│ │ └── PlaylistModels.kt
|
| | `-- PlaylistModels.kt
|
||||||
│ └── routes/ # /rest/{endpoint} and /rest/{endpoint}.view
|
| `-- routes/ # /rest/{endpoint} and /rest/{endpoint}.view
|
||||||
│ ├── SystemRoutes.kt # ping, getLicense, extensions, startScan, getScanStatus
|
| |-- SystemRoutes.kt # ping, getLicense, extensions, startScan, getScanStatus
|
||||||
│ ├── BrowsingRoutes.kt # indexes, artists, album, song, search3, lists, genres
|
| |-- BrowsingRoutes.kt # indexes, artists, album, song, search3, lists, genres
|
||||||
│ ├── MediaRoutes.kt # stream, download, getCoverArt, lyrics
|
| |-- MediaRoutes.kt # stream, download, getCoverArt, lyrics
|
||||||
│ ├── InteractionRoutes.kt # scrobble, star/unstar, setRating, getStarred2
|
| |-- InteractionRoutes.kt # scrobble, star/unstar, setRating, getStarred2
|
||||||
│ └── PlaylistRoutes.kt # playlists and playlist songs
|
| `-- PlaylistRoutes.kt # playlists and playlist songs
|
||||||
├── transcoding/
|
|-- transcoding/
|
||||||
│ └── FfmpegTranscoder.kt # MP3 transcoding with maxBitRate and timeOffset
|
| `-- FfmpegTranscoder.kt # MP3 transcoding with maxBitRate and timeOffset
|
||||||
└── util/
|
`-- util/
|
||||||
└── IdGenerator.kt # Deterministic SHA-256 IDs
|
`-- 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:
|
Every song object must include:
|
||||||
|
|
||||||
- `size: Long` — exact byte size
|
- `size: Long` - exact byte size
|
||||||
- `duration: Int` — seconds
|
- `duration: Int` - seconds
|
||||||
- `bitRate: Int` — kbps
|
- `bitRate: Int` - kbps
|
||||||
- `suffix: String` — `"mp3"`
|
- `suffix: String` - `"mp3"`
|
||||||
- `contentType: String` — `"audio/mpeg"`
|
- `contentType: String` - `"audio/mpeg"`
|
||||||
|
|
||||||
Symfonium verifies downloaded bytes against `size` after each offline download.
|
Symfonium verifies downloaded bytes against `size` after each offline download.
|
||||||
|
|
||||||
@@ -458,11 +458,11 @@ All timestamps are ISO 8601 in UTC.
|
|||||||
library:
|
library:
|
||||||
folders:
|
folders:
|
||||||
- id: 1
|
- id: 1
|
||||||
name: "Alice — Music"
|
name: "Alice - Music"
|
||||||
type: music
|
type: music
|
||||||
path: /mnt/media/music/alice
|
path: /mnt/media/music/alice
|
||||||
- id: 2
|
- id: 2
|
||||||
name: "Bob — Music"
|
name: "Bob - Music"
|
||||||
type: music
|
type: music
|
||||||
path: /mnt/media/music/bob
|
path: /mnt/media/music/bob
|
||||||
- id: 10
|
- id: 10
|
||||||
@@ -473,7 +473,7 @@ library:
|
|||||||
|
|
||||||
### 6.2 `users.yaml` (Vault-managed Secret)
|
### 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
|
```yaml
|
||||||
users:
|
users:
|
||||||
@@ -529,8 +529,8 @@ All endpoints live under `/rest/{endpoint}` and `/rest/{endpoint}.view`.
|
|||||||
For every `/rest/*` call (except an optional health check):
|
For every `/rest/*` call (except an optional health check):
|
||||||
|
|
||||||
- `u` must match a configured user.
|
- `u` must match a configured user.
|
||||||
- Token auth: `t` and `s` present → verify `t.equals(md5(password + s), ignoreCase = true)`.
|
- 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.
|
- Password auth: `p` present -> if `p` starts with `enc:`, hex-decode it; compare to the password.
|
||||||
- Comparisons use constant-time equality.
|
- Comparisons use constant-time equality.
|
||||||
- On failure: HTTP 200 with a Subsonic error (`code = 40`).
|
- 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.
|
- 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.
|
- `getArtist(id)`: artist details plus all visible albums.
|
||||||
- `getAlbum(id)`: album details plus visible songs, sorted by `discNumber`, `trackNumber`.
|
- `getAlbum(id)`: album details plus visible songs, sorted by `discNumber`, `trackNumber`.
|
||||||
- `getSong(id)`: single song, only if visible to the caller.
|
- `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.
|
- `getGenres`: distinct genres from visible songs.
|
||||||
- `getSongsByGenre(genre, count, offset)`: paginated visible songs in a genre.
|
- `getSongsByGenre(genre, count, offset)`: paginated visible songs in a genre.
|
||||||
- `getStarred2`: the caller's starred artists, albums and songs for the home screen.
|
- `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`);
|
- direct play via `call.respondFile` (PartialContent handles `Range`);
|
||||||
- otherwise stream ffmpeg MP3 output with chunked transfer;
|
- otherwise stream ffmpeg MP3 output with chunked transfer;
|
||||||
- set `Content-Type` from the actual response.
|
- 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`).
|
- `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.
|
- `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`.
|
- `scrobble(id, time, submission)`: per user; `submission=true` (default) increments `play_count` and sets `last_played_at`.
|
||||||
- `star(id, albumId, artistId)` / `unstar(...)`: per user.
|
- `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.
|
- `getBookmarks` / `createBookmark(id, position)` / `deleteBookmark(id)`: per user; `position` is milliseconds.
|
||||||
- `getPlaylists`: the caller's playlists plus all public ones.
|
- `getPlaylists`: the caller's playlists plus all public ones.
|
||||||
- `getPlaylist(id)`: if public or owned by the caller.
|
- `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.
|
- 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).
|
- 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
|
### 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).
|
- Runtime flags: `-XX:+UseSerialGC -Xmx256m` (adjustable via Helm).
|
||||||
- Non-root user (UID 10001), read-only root filesystem, `/tmp` as `emptyDir`, `/data` as PVC.
|
- 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).
|
- 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.
|
- 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`):
|
- 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
|
- deterministic IDs and normalization
|
||||||
- user visibility: user A cannot see or stream user B's music; both see long-form
|
- 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
|
- exact `size` / `duration` / `bitRate` / `suffix` / `contentType` fields
|
||||||
- browsing flow: `getArtists` → `getArtist` → `getAlbum` → `stream`
|
- browsing flow: `getArtists` -> `getArtist` -> `getAlbum` -> `stream`
|
||||||
- `search3` with Unicode and wildcards
|
- `search3` with Unicode and wildcards
|
||||||
- scrobble/star/rating/bookmark isolation between users
|
- scrobble/star/rating/bookmark isolation between users
|
||||||
- playlist ownership and public visibility
|
- playlist ownership and public visibility
|
||||||
|
|||||||
Reference in new issue
Block a user