Martin Bauer
83d16e0058
Search was still stalling for seconds a keystroke. A trace across five keystrokes said the renderer main thread was blocked for 9.4 s in a single task with *zero* V8 samples inside it - no JavaScript ran at all. What ran instead, on the worker pool during those same 9.4 s: ImageDecodeTask 7.6 s, RasterTask 1.7 s, and only 229 ms of actual "Decode Image". The main thread was waiting on cover bytes, not computing anything. Two causes, and the first one was mine. The stale-while-revalidate handler added earlier today made every cover do a Cache Storage read *plus* a network fetch *plus* a cache write, all serialised through one worker thread. Measured with Network.setBypassServiceWorker: worst keystroke 5580 ms through the worker against 461 ms without it. So covers no longer go through the worker at all. That costs nothing here: this worker only registers on localhost or over HTTPS, which on this setup is the kiosk on the device itself, where the backend is the same machine and a cache lookup is strictly more work than asking for the file. The shell caching, which is what makes it installable, stays. The second is that decode cost goes with pixel count, and 640 px was headroom for a tablet at devicePixelRatio 2 that nobody had asked for. A browse grid paints a card 132 px wide; the largest any screen asks for is 340. At 384 px, typing "conni" over 343 albums, keydown to painted, three runs: before 3735, 270, 5580, 88, 57 ms after 873, 75, 17, 24, 26 ms `shrink_cover` never scales art up, so dropping the limit cannot be applied by re-reading the cache - only by going back to the original art. _INDEX_VERSION 6 does that: the index is discarded and every album is scanned again through store_cover. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Musik Delphin — the web front-end
Browse the whole music collection and play any of it from a browser: the six figurines are only five of the twenty-odd albums on the shelf, and everything else was previously unreachable without swapping files around on disk.
Built from ../claude-design/Dolphin Beats.dc.html, which is a finished interaction and
visual spec rather than a sketch. The keyboard model, the layout, the colours and the
German copy are ported from it; what changed is that a real player sits behind it.
Running it
The backend serves the API. Either of these will do - --simulate needs no audio device
and no libVLC at all, which makes it the easier one to develop against:
cd ../python-backend
python -m musicmouse --config ./config.yml --no-hardware # real audio
python -m musicmouse --config ./config.yml --simulate # fake player
Then:
npm install
npm run dev # http://localhost:5173, /api and the websocket proxied to :8080
For the device, npm run build writes dist/, and general.web.static_dir in
config.yml points at it so one process serves both.
Checks
npm run test # vitest over src/lib
npx tsc --noEmit # strict, noUncheckedIndexedAccess
Only the pure modules are tested - the search, the keyboard machine and the time formatting. That is where the behaviour lives; the components are mostly layout.
src/lib/search.ts builds its normalized search keys once per library payload
(buildSearchIndex) rather than per keystroke. It matters more than it sounds: a real
collection is 343 albums and 4969 tracks, and normalize() does a Unicode NFD
decomposition, so track search used to mean five thousand of those before a single
comparison - 4 ms per keystroke on a laptop, and this runs on a Pi. The same build also
partitions albums by shelf and pre-sorts each shelf's categories, which App and
BrowseView were otherwise deriving separately from the same data.
How it is put together
The split that matters: what is playing comes from the backend, what you are
looking at lives in the browser. The mockup kept both in one state object, but a real
player has other front-ends - the buttons on the mouse, a figurine on the reader, Home
Assistant - and this UI has to follow them rather than assume it is in charge. So
isPlaying, volume, the position and the current album all arrive over the websocket,
and only search / mode / filter / category / selIndex / view / openAlbumId / showHelp
are local.
| Path | What it is |
|---|---|
src/lib/keyboard.ts |
The key map, as a pure function from a keypress to a list of actions. Testable without a DOM. |
src/lib/search.ts |
Filtering and the three-level browse hierarchy. The whole library is in memory, so this is instant - see the note on buildSearchIndex below. |
src/lib/lowPower.ts |
The ?pi=1 profile: what gets cheaper, and by how much. |
src/lib/covers.ts |
Generated cover art from the album's three colours, and the book-spine treatment. |
src/hooks/usePlayerState.ts |
The websocket, with reconnect-and-reseed. |
src/hooks/usePlaybackClock.ts |
Interpolates the 2 Hz position onto animation frames. |
src/components/ |
Layout only. |
src/api/types.ts mirrors musicmouse/services/web/schemas.py; the two are hand-kept in
step.
Keyboard
The device is meant to be driven from a keyboard, so every screen is reachable without a
pointer. F1 shows the same list in-app.
| Key | |
|---|---|
SPACE |
play / pause |
CTRL+H / CTRL+L |
previous / next track |
CTRL+J / CTRL+K |
quieter / louder |
SHIFT+← / SHIFT+→ |
seek 15 s |
A-Z, 0-9 |
search albums as you type |
? |
switch to searching individual tracks |
TAB |
cycle all / music / audiobooks |
← ↑ ↓ → |
move the selection while browsing; transport and volume while playing |
ENTER |
play the selection |
ESC |
back out one layer at a time |
/ |
back to browsing |
F1 |
this list |
SHIFT+arrows is the one addition to the mockup: plain arrows were already taken, and
seeking is the one thing a real player can do that the mockup could not.
The Raspberry Pi profile
?pi=1 loads the same app with nothing on screen animating itself. It exists for
musicdolphin - a Pi 4 driving a 1920x1080 kiosk screen.
| Full | ?pi=1 |
|
|---|---|---|
| Ambient canvas (gradient + bubbles) | on | not rendered |
| Decorative CSS loops, view transitions | on | off |
| Typing game bubbles, next-key pulse | on | off |
| Typing game pets | swimming | placed, held still |
backdrop-filter on cards and list rows |
on | off |
backdrop-filter on panels |
on | on |
| Progress-bar re-renders | every animation frame | 10 per second |
Two of those rows are worth knowing the reasons for, because both are the opposite of what they look like.
The panel blur stays on. Dropping it measured five times worse on the device -
118% of a core against 25%. backdrop-filter is what promotes each glass panel to its
own compositing layer; without it the panels and everything under them collapse into
one layer that repaints wholesale. The card blur goes because that is a different
problem: three hundred of them in one grid, not one per panel.
The canvas goes away rather than getting cheaper. Half resolution and 30 fps took
it from 53.5% of a core to 25.0%, and 25% was still not good enough to use. A
requestAnimationFrame loop repainting the viewport is a floor you cannot get under
while it runs at all. .stage keeps its own static CSS gradient, so there is still a
sea behind everything - it just no longer moves or follows the track.
AMBIENCE_QUALITY in src/lib/lowPower.ts is kept accurate for whoever turns the
canvas back on.
The flag is read once at module load from the URL and nowhere else - no persistence, no
auto-detection. That is what makes "is this the profile or the hardware?" answerable by
editing the address bar. The kiosk gets it from pi_kiosk_url in the ansible repo.
Parent mode
?parentMode=1 opens a settings panel - volume limits, the rotary step, button
brightness, and a button to re-read the library. Saving writes the device's
config.yml.
It is hidden from the child, not protected from them: there is no authentication on the
endpoints behind it. See ../python-backend/README.md.
Installing it on a phone
It is a PWA: public/manifest.webmanifest, icons generated from the mascot, and a small
service worker in public/sw.js. On iOS, Share → Zum Home-Bildschirm; it then opens
full-screen with no Safari chrome, because iOS reads the apple-mobile-web-app-* meta
tags in index.html rather than the manifest.
Two things worth knowing:
- The service worker only registers over HTTPS or on
localhost. Athttp://<mouse>:8080on the LAN, iOS will still install the icon and run it standalone - that part is the meta tags - but there is no offline caching. Put the mouse behind a TLS-terminating proxy if you want that. - The worker deliberately caches very little: the app shell, the font and cover art.
Not
/api/state, not the library, not anything else live. A player that shows stale state is worse than one that says it cannot reach the mouse.
Nunito is self-hosted in public/fonts/ (one variable file per subset, ~74 kB) rather
than pulled from Google. The mouse may have no internet, and a cached shell rendering in
a fallback face looks broken.
Not implemented
The mockup's second page, "Mein Zimmer" (Hue lights, a roller shutter and scenes), is not built. Nothing here depends on it.