kami
81 lines
5.0 KiB
Markdown
81 lines
5.0 KiB
Markdown
# music — frontend spec
|
|
|
|
React (vite). Dark theme by default, blue accent. Web UI is v1; backend is API-first so a mobile app can reuse the same endpoints later.
|
|
|
|
## Theme
|
|
- **Dark by default.** Blue accent (`--accent: #2D7FF9` or similar; pick one and define tints like kdrive's accent system).
|
|
- Reuse the design-token approach from kdrive (CSS vars, Geist font). This is a distinct app with its own palette but shared visual language.
|
|
- Animations: tasteful — now-playing bar slide-up, queue/lyrics panel slide-in, album art crossfade on track change, subtle hover/press states, progress bar smoothing, shuffle/loop button state transitions.
|
|
|
|
## Layout
|
|
- **Left sidebar**: nav (Artists / Albums / Songs / Favorites / Recently played / Vibe), profile/avatar (opens settings modal).
|
|
- **Main**: list/grid views per section.
|
|
- **Bottom now-playing bar** (persistent): cover thumb, title, artist + feats, prev / play-pause / next, volume slider, shuffle toggle, loop toggle (off → all → one), progress/seek bar, lyrics button, queue button.
|
|
|
|
## Views
|
|
### Artists
|
|
- List/grid of artists (image if enriched, else monogram). Click → artist page: header (image, name, genres), albums, all tracks.
|
|
|
|
### Albums
|
|
- Grid of album covers (sort: name / year / artist). Click → album page: cover, title, artist, year, ordered tracklist, play / shuffle album.
|
|
|
|
### Songs
|
|
- Virtualized list (library can be large): title, artist, album, duration, play count, favorite toggle. Sort by title/artist/added/plays. Fuzzy search box.
|
|
|
|
### Favorites / Recently played
|
|
- Favorites: from `/api/favorites`. Recently played: from `/api/history`.
|
|
|
|
### Vibe
|
|
- "Start a vibe" from current track / an artist / a genre. Calls `/api/vibe`. Shows the mixed queue; recommendation candidates are visually tagged subtly (small dot/"suggested") but interleaved, not grouped.
|
|
|
|
## Player controls (now-playing bar)
|
|
- **Global shuffle button** (prominent, maybe in topbar or sidebar too): one tap → `GET /api/shuffle/all` → loads entire library shuffled as queue, starts playing. The headline feature.
|
|
- **Prev / Play-Pause / Next**.
|
|
- **Loop toggle**: cycles off → loop-all (current queue/album) → loop-one (single track). Distinct icons per state.
|
|
- **Volume slider**.
|
|
- **Seek bar**: draggable, shows elapsed/total.
|
|
- **Cover + title + artist + feats**: feats rendered subtly after artist (e.g. "Artist · feat. X, Y").
|
|
- **Lyrics button**: opens lyrics panel.
|
|
- **Queue button**: opens queue panel.
|
|
|
|
## Playback engine (client)
|
|
- Web Audio / `<audio>` with `/api/stream/{id}` (range-enabled).
|
|
- Playback modes from prefs:
|
|
- **basic**: sequential.
|
|
- **gapless**: preload next track, start without silence (dual audio elements or Web Audio buffering).
|
|
- **crossfade**: fade out current / fade in next over `crossfade_ms`.
|
|
- **interstitial**: play the configured interstitial track between every song (the gag mode).
|
|
- Log plays to `POST /api/history` with `completed` once threshold reached (≥50% or final 10s).
|
|
|
|
## Lyrics panel
|
|
- Slide-in panel. Calls `/api/lyrics/{track_id}`.
|
|
- **Synced** (LRC): auto-scroll, highlight active line, tap a line to seek.
|
|
- Falls back to plain text or "no lyrics found".
|
|
- Provider chain handled server-side (Musixmatch → LRCLIB), frontend just renders.
|
|
|
|
## Queue panel
|
|
- Slide-in. Shows **prev tracks** (history within session) and **next tracks** (upcoming).
|
|
- Reorder (drag), remove, jump-to.
|
|
- Queue resets on session end (no persistence — per the decision).
|
|
|
|
## Favorites / dislike
|
|
- Heart toggle on tracks/now-playing → `POST /api/favorite/{id}`.
|
|
- **Dislike** control (e.g. thumbs-down in now-playing context menu) → `POST /api/dislike/{id}`. Track hides immediately. A toast confirms.
|
|
- When a dislike reminder fires (server sweep), the app surfaces a toast: *"You disliked '<track>' — deleting in 24h. Undo?"* with an Undo action calling `DELETE /api/dislike/{id}`. (Also delivered via ntfy out-of-app.)
|
|
|
|
## Settings modal (avatar click)
|
|
- **Appearance**: theme (dark default, allow light), blue accent + maybe a couple alt accents.
|
|
- **Playback**: mode (basic/gapless/crossfade/interstitial), crossfade ms (when crossfade), interstitial track picker (when interstitial).
|
|
- **Recommendations**: enable/disable vibe acquisition, max candidates (read-only display of the cap), Last.fm key field, MusicBrainz UA.
|
|
- **Library**: reindex button (`POST /api/library/reindex`), enrich button (`POST /api/enrich`).
|
|
- Persist via `/api/prefs`.
|
|
|
|
## Search
|
|
- Global fuzzy search (topbar) → `/api/search`, grouped results: Artists / Albums / Songs. Handles Cyrillic/mixed scripts (display original, match normalized).
|
|
|
|
## API-first note
|
|
- All state lives behind the documented endpoints so a future mobile client reuses them. No frontend-only business logic that the API can't reproduce. Keep auth simple for v1 (WG-gated, like the rest); leave room for token auth later for mobile over the tunnel.
|
|
|
|
## Deploy
|
|
- Same pattern as kdrive: vite build → served by the FastAPI app (or its own static mount). nginx vhost via the panel: `music.kvmx.ru` (replaces the swingmusic/navidrome entry) → `http://localhost:<port>`.
|