docs: replace ambiguous Unicode characters in README with ASCII

This commit is contained in:
TapTap committed 2026-11-13 12:00:13 +00:00
1 parent 37a5728d6c
commit 405fd07fb3
1 file changed
+55 -55
+55 -55
View File
@@ -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