From 405fd07fb3aebc7698169dbb637ea0539119e4ba Mon Sep 17 00:00:00 2001 From: TapTap Date: Fri, 13 Nov 2026 12:00:13 +0000 Subject: [PATCH] docs: replace ambiguous Unicode characters in README with ASCII --- README | 110 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/README b/README index 97e4dac..5e08784 100644 --- a/README +++ b/README @@ -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://: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:` (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