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 ## 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