Martin Bauer
4428357e13
Each fix to the home-screen app's layout on iOS broke something else, and they
all traced back to black-translucent: it runs the page under the clock, so any
top-anchored control without its own inset sat behind it (the play view's back
button), and since iOS 26 it sizes the app one status bar short with a strip at
the bottom that CSS cannot paint (WebKit 301108). The status bar is opaque now
("black"), the page starts below it, and lib/fullHeight.ts - the JS workaround
for the short viewport - is gone with the CSS that depended on it.
viewport-fit=cover stays, so everything against a screen edge now adds that
edge's inset from shared --safe-* variables: the corner back button, the
remote-assign button, the assign toast, the tool buttons and the tab rail did
not before. The rules are written down under "Layout on phones" in the README.
On a phone held sideways the mini player and the tabs share one row instead of
taking half the screen.
Home-screen installs read the status-bar tag once: remove and re-add the app.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
197 lines
9.6 KiB
Markdown
197 lines
9.6 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
cd ../python-backend
|
|
python -m musicmouse --config ./config.yml --no-hardware # real audio
|
|
python -m musicmouse --config ./config.yml --simulate # fake player
|
|
```
|
|
|
|
Then:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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`.** At
|
|
`http://<mouse>:8080` on 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.
|
|
|
|
## Layout on phones
|
|
|
|
Phones (`usePhoneLayout`: narrow, or short landscape on touch) get the touch layout in
|
|
`components/mobile/`; tablets and the kiosk keep the keyboard one. The home-screen app
|
|
on iOS has caught every shortcut taken here, so these are the rules - follow them rather
|
|
than patching one element at a time:
|
|
|
|
- **The status bar is opaque** (`apple-mobile-web-app-status-bar-style: black`). The page
|
|
starts below it, so nothing can end up under the clock. `black-translucent` looks
|
|
nicer, but it ran the page behind the status bar, and since iOS 26 it also sizes the
|
|
app one status bar short, leaving a strip at the bottom that CSS cannot paint
|
|
([WebKit 301108](https://bugs.webkit.org/show_bug.cgi?id=301108)). The workarounds for
|
|
that (`100lvh`, measuring `screen` in JS) each broke something else. Installed apps
|
|
read this tag once: after changing it, remove the app and add it again.
|
|
- **`viewport-fit=cover` stays**, so the sea fills the rounded corners and the home
|
|
indicator area, which means:
|
|
- **Anything placed against a screen edge adds that edge's inset**: `--safe-top`,
|
|
`--safe-right`, `--safe-bottom` and `--safe-left` in `app.css`, always the variables
|
|
and never a bare `env()`. That covers `top`/`bottom`/`left`/`right` offsets of
|
|
positioned elements, and the padding of bars and scroll containers that reach the
|
|
edge. Scrolling content clears what floats over it (`--m-dock-clearance`). The top
|
|
inset is 0 with the opaque status bar, but stays in the formulas for Safari tabs and
|
|
landscape.
|
|
- **The stage is pinned, not sized**: `position: fixed; inset: 0` on phones, with the sea
|
|
colour on `html`/`body` so any gap would show sea, not white. No viewport-height unit
|
|
is trusted in the home-screen app.
|
|
- **The keyboard is measured, not assumed**: iOS slides it over the page without resizing
|
|
anything, so the dock is raised by `visualViewport` (`useKeyboardInset`) and drops its
|
|
home-indicator padding while the keyboard is up
|
|
([safe-area-inset-bottom does not update for the keyboard](https://webventures.rejh.nl/blog/2025/safe-area-inset-bottom-does-not-update/)).
|
|
|
|
## Not implemented
|
|
|
|
The mockup's second page, "Mein Zimmer" (Hue lights, a roller shutter and scenes), is
|
|
not built. Nothing here depends on it.
|