Frontend¶
A React 18 + TypeScript app built with Vite (amp/frontend/), shown in the Tauri window. It also
runs in a normal browser for development (npm run dev, port 1420).
| Page | Topic |
|---|---|
| Player | PlayerBar, the load sequence, the segment bar, persistence, prefetch, errors |
| Tauri shell | the Rust side: backend process, sign-in window, permissions, CSP |
Startup¶
// main.tsx: the backend's port is only known once Tauri answers
initBackend().then(() => {
ReactDOM.createRoot(root).render(<BrowserRouter><App /></BrowserRouter>);
});
initBackend() (sidecar.ts) calls the Tauri command backend_info and sets api.ts's base
URL to http://127.0.0.1:<port> before the first render, so no component ever calls the
wrong port. Outside Tauri it keeps the default http://127.0.0.1:8000.
App.tsx then renders the sidebar (navigation, session badge, cache use, backend status), the
routes, the QueuePanel and the always-visible PlayerBar, and loads the liked songs once signed in.
| Route | Page | Data |
|---|---|---|
/now-playing |
NowPlaying |
the store: current song, following the queue; ?uid= pins a queue item (queue menu "Display song info") |
/ |
Search |
GET /api/search, results in SongList |
/library |
Library |
GET /api/user/likes; SignInPrompt when signed out or on 401 |
/playlists |
Playlists |
GET /api/user/playlists as cards; same sign-in prompt |
/playlists/:id |
PlaylistDetail |
GET /api/playlist/{id} |
/albums/:id |
AlbumDetail |
GET /api/album/{id}; reached through albumNav.goToAlbum (GET /api/song/{id}/album first: songs don't carry their album ID) |
/queues, /queues/:id |
SavedQueues, SavedQueueDetail |
/api/queues |
/auth |
Auth |
status, webview sign-in, Advanced (paste, Firefox) |
/history |
History |
GET /api/history by period, grouped by day; reloads on the amp:history window event |
/settings |
Settings |
settings.ts (localStorage, no API) |
/logs |
Logs |
backend output (Tauri events), /api/stream/logs, /api/logs relay |
/developer |
Developer |
/api/health, /playback-state, /now-playing, /cache-info, /chunks every 2 s; API tester (rawRequest) |
Modules¶
| File | Role |
|---|---|
api.ts |
typed fetch wrapper. Base URL (setBaseUrl), optional Bearer token, ApiError with HTTP status and backend code, a hook for 401s from /api/user/*. All response types live here |
sidecar.ts |
the backend client (it never spawns anything): initBackend(), health poll every 1 s, backend-log / backend-status events, the replayed backend_logs ring, restart() → restart_backend |
state.ts |
the queue and playback store (below) |
authSession.ts |
shared sign-in status: 60 s poll, refresh on 401, badge labels |
tauri_auth.ts |
youtubeLogin() → Tauri command youtube_login; mightBeTauri() |
player/ |
pure helpers covered by vitest: errors.ts, persistence.ts, prefetch.ts, keyboard.ts (space bar), fade.ts (fade gain, crossfadeDue), normalize.ts (loudness → gain), history.ts (listening tracker). OS media controls are wired in PlayerBar.tsx through navigator.mediaSession (metadata, playback state, action handlers calling the player bar's own handlers; position comes from the <audio> element) |
settings.ts |
theme, accent, crossfade, normalization: amp.settings.v1 in localStorage, validated by parseSettings, applied to <html> (data-theme, --accent, --on-accent) when the module loads, so before the first render |
likes.ts, savedQueues.ts, ui.ts |
liked songs store; saved queue list and actions; toasts and dialogs |
player/queue.ts |
the pure queue model |
components/ |
PlayerBar, QueuePanel, SongList (click = play with the list as queue), SongMenu, CollectionHeader, Cover, Icon, LikeButton, UiLayer, SignInPrompt |
State: state.ts¶
Crossfade, normalization and history live in the store
Crossfade: PlayerBar owns two <audio> elements. When the active one reaches its last
fadeSec seconds (crossfadeDue) and the queue has a next song (not repeat-one), the store
ends the play as finished, moves to the next song with playToken === crossfadeToken, and
ignores the old element until PlayerBar loads the next song on the spare element and calls
store.handOver(next). The old element becomes the fading one and plays its end; Next,
Previous, a jump, Pause, Stop or an emptied queue call stopFading() and cut it.
Each element's volume is volume × fadeGain(its position, its duration, fadeSec) × normalization
gain of its song, refreshed every 50 ms while something plays or fades.
One backend session: the new song's /play takes the session (buffer-ahead, position
reports, OBS widget, OS media controls all move to it at the start of the overlap). The fading
song keeps streaming over its open /audio request; anything not yet on disk is fetched by
the request itself (ensure_segment), and buffer-ahead had already downloaded ~30 s past the
playhead, so the last ≤ 10 s are normally cached. The backend needs no change.
Normalization: GET /api/song/{id}/loudness once per song (at load, in parallel with
/play, and at prefetch); the load waits up to 1 s for it so the song starts at the right
volume. Gain min(1, 10^((-6 − loudnessDb) / 20)) (normalize.ts).
Why YouTube's value rather than Web Audio: a MediaElementAudioSourceNode on the stream needs
CORS on /audio (otherwise the output is silent) and would route every sample through the
audio graph; a compressor changes the dynamics instead of the level; measuring loudness
ourselves needs the whole song before it plays. YouTube already measures every track and
sends it with the player response. Its values for released music sit around −5…+2 dB, so
YouTube's own rule (only turn down above 0 dB) would hardly change anything; AMP aims at −6 dB
instead. The element's volume can't exceed 1, so songs quieter than −6 dB are not boosted.
History: HistoryTracker gets every timeupdate; only forward steps under 2 s count, so
seeks don't. A new playToken ends the play as skipped, ended as finished, Stop or an
emptied queue as stopped. Plays under 5 s are dropped. The play in progress is saved to
amp.history.pending.v1 every 5 s and sent as closed on the next start.
The queue belongs to the frontend; the backend only stores named copies (/api/queues).
player/queue.ts is a pure model: items with a uid (the same song can be queued twice), the
current index, shuffle (reorders items, original remembers the order to restore) and repeat.
StateStore applies it to the audio element and adds playback fields; useQueueState() reads it
and components call store.playList, playNext, addToQueue, moveItem, removeItem, jumpTo,
next, previous... directly.
playToken goes up whenever the current song must (re)load, and PlayerBar watches it. A restored
queue stays at token 0, so it waits for the play button. Selecting the song already loaded keeps
its position.
previous()restarts the current song after 3 s of play, else goes back one.- The store owns the
<audio>element'sendedlistener (→next(false)), and a 2 s timer that readsaudio.currentTimeand reports it toPOST /api/stream/position. The next song is prefetched fromtimeupdate.
Polling rules¶
Every timer that calls the API has an in-flight guard: if the previous call hasn't returned, the tick is skipped. Otherwise a slow backend accumulates overlapping requests.
| Poll | Interval |
|---|---|
/api/health (sidecar) |
1 s |
/api/stream/{id}/chunks (segment bar) |
500 ms while a song is loaded |
/api/stream/cache-info |
5 s |
/api/auth/status |
60 s |
/api/stream/logs, /api/logs (Logs page) |
2 s while the page is open |
| position report | 2 s while playing |
Scripts¶
| Command | Does |
|---|---|
npm run dev |
Vite dev server on :1420 |
npm run build |
tsc type check + production bundle in dist/ |
npm test |
vitest (pure helpers) |
npm run tauri dev / npx tauri build |
desktop app / installers (Tauri shell) |