Spec: Vollbild-Player als persistentes Overlay mit Live-Blur-Übergang
Punkt 2 der HyperOS-Animations-Serie. Bereit zur Freigabe durch Dustin (via Hermes) vor der Umsetzung.
This commit is contained in:
Hermes (Server)
@@ -0,0 +1,200 @@
|
||||
# Vollbild-Player als persistentes Overlay mit Live-Blur-Übergang
|
||||
|
||||
Status: Approved (Dustin, 2026-08-29) — bereit für Implementierungsplan.
|
||||
|
||||
## Kontext
|
||||
|
||||
Punkt 2 aus dem Animations-Bericht zu Xiaomis HyperOS-Design-Sprache
|
||||
(fließende, physikalisch wirkende Bewegung statt starrer, linearer
|
||||
Animation): Der Übergang vom Mini-Player zum Vollbild-Player
|
||||
(`NowPlayingScreen`) soll sich beim Öffnen/Schließen per Wischgeste
|
||||
reaktiv anfühlen — der Hintergrund soll live mit der Zugdistanz des
|
||||
Fingers verschwimmen (Blur), nicht erst nach Abschluss einer festen
|
||||
Animation.
|
||||
|
||||
Heute (`lib/player/mini_player.dart`, `lib/player/now_playing_screen.dart`,
|
||||
`lib/player/wischen.dart`) ist die Wischgeste rein **entscheidungsbasiert**:
|
||||
Der Mini-Player folgt beim Ziehen sichtbar dem Finger (`_versatz` +
|
||||
`AnimatedContainer`/`Matrix4.translationValues`), aber die eigentliche
|
||||
Navigation passiert erst nach `onVerticalDragEnd` als normaler
|
||||
`Navigator.push(MaterialPageRoute(builder: (_) => const NowPlayingScreen()))`.
|
||||
Während des Ziehens existiert `NowPlayingScreen` im Widget-Baum noch gar
|
||||
nicht — es gibt keine live-Verbindung zwischen Zugdistanz und einer
|
||||
Bildschirm-Transition. Dieselbe Route wird an drei weiteren, gestenlosen
|
||||
Stellen per einfachem Tap gepusht: `lib/library/song_list.dart`,
|
||||
`lib/playlists/playlist_detail_screen.dart`,
|
||||
`lib/downloads/server_titel_screen.dart`.
|
||||
|
||||
Zwei Architektur-Ansätze wurden im Brainstorming verglichen (interaktive
|
||||
`PageRoute` mit geteiltem Fortschritts-Notifier vs. persistentes Overlay).
|
||||
Dustin hat sich für das **persistente Overlay** entschieden (Ansatz 2) —
|
||||
näher an der Bauweise nativer Musik-Apps (Spotify/Apple Music), auch wenn
|
||||
der Eingriff größer ist als bei der interaktiven-Route-Variante.
|
||||
|
||||
## Ziel
|
||||
|
||||
`NowPlayingScreen` wird Teil der dauerhaften App-Hülle (`HomeShell`) statt
|
||||
einer über den Navigator gepushten Route. Ein geteilter Fortschritts-Wert
|
||||
(0.0 = eingeklappt/Mini-Player, 1.0 = Vollbild) steuert live:
|
||||
- die Größe/Position des Vollbild-Inhalts (Interpolation Mini-Player-Rechteck
|
||||
→ Vollbild)
|
||||
- die Blur-Intensität des darunterliegenden Tab-Inhalts
|
||||
- das Ein-/Ausblenden des Mini-Players
|
||||
|
||||
Sowohl das Öffnen (Ziehen am Mini-Player, Tap an allen 4 bisherigen
|
||||
Öffnen-Stellen) als auch das Schließen (Ziehen im Vollbild-Player nach
|
||||
unten) sollen sich darüber gleich, live und symmetrisch anfühlen.
|
||||
|
||||
## Nicht-Ziele
|
||||
|
||||
- Keine Änderung an der Wiedergabe-Logik selbst (`playSongs`, `audio_handler.dart`).
|
||||
- Keine Änderung an internen `Navigator.push`-Aufrufen INNERHALB von
|
||||
`NowPlayingScreen` (Warteschlange, Songtext-Sheet) — die bleiben echte
|
||||
Routen/Modals über demselben Navigator.
|
||||
- Keine Änderung an `wischen.dart`s bestehender Entscheidungslogik
|
||||
(`oeffnetVollbildMitStrecke`, `titelWechselMitStrecke`,
|
||||
`wischSchwelle`/`wischStreckeSchwelle`) — die wird unverändert
|
||||
wiederverwendet, nur um einen rein optischen `progress`-Wert ergänzt.
|
||||
- Keine Änderung an Punkt 1 (`EinblendItem`, bereits umgesetzt/gemergt).
|
||||
- Punkte 3–5 des Animations-Berichts (Karaoke-Highlight, Advanced-Blur-
|
||||
Kopplung am Farbverlauf, Equalizer-Visualizer) sind nicht Teil dieses
|
||||
Specs.
|
||||
|
||||
## Entscheidungen (aus dem Brainstorming, mit Dustin abgestimmt)
|
||||
|
||||
| Frage | Entscheidung |
|
||||
|---|---|
|
||||
| Architektur-Ansatz | Persistentes Overlay in `HomeShell` statt interaktiver `PageRoute` |
|
||||
| Tap-Only-Stellen (song_list.dart, playlist_detail_screen.dart, server_titel_screen.dart) | Bekommen denselben Übergang (automatischer `progress` 0→1), nicht nur die Mini-Player-Geste |
|
||||
| Schließgeste im Vollbild-Player | Wird symmetrisch umgebaut — live am Finger, nicht nur Entscheidung bei Loslassen |
|
||||
| Cover-Übergang (bisher `Hero`) | Wird von Hand nachgebaut (Rect-Interpolation über `progress`), da `Hero` nur bei echten Navigator-Transitions feuert |
|
||||
| Android-Zurück-Taste | `PopScope` in `HomeShell`: bei `progress > 0` schließt Zurück den Player statt die Route/App zu verlassen — notwendiger Teil des Designs, keine Alternative |
|
||||
|
||||
## Architektur
|
||||
|
||||
### Neue Komponente: `PlayerExpansionController`
|
||||
|
||||
Datei: `lib/player/player_expansion_controller.dart`. `ChangeNotifier`,
|
||||
lebt in `HomeShell`s `State` (die `TickerProviderStateMixin` bekommt, um
|
||||
als `vsync` für einen internen `AnimationController` zu dienen), bereit-
|
||||
gestellt per `ChangeNotifierProvider.value` oberhalb von `IndexedStack`,
|
||||
`MiniPlayer` und `NowPlayingScreen`.
|
||||
|
||||
Zustand:
|
||||
- `double progress` — 0.0…1.0, rein optisch, öffentlich lesbar.
|
||||
|
||||
Methoden:
|
||||
- `dragBy(double dy)` — während des Ziehens aufgerufen (Mini-Player beim
|
||||
Öffnen, Vollbild-Player beim Schließen, jeweils mit passendem Vorzeichen).
|
||||
Bildet `progress = (aufsummierte Zugstrecke / referenzHoehe).clamp(0, 1)`.
|
||||
`referenzHoehe` ist ein fester Wert (300px) — bewusst **entkoppelt** von
|
||||
der Entscheidungs-Schwelle in `wischen.dart`; er bestimmt nur, wie "weit"
|
||||
sich der optische Übergang bei einer bestimmten Zugstrecke anfühlt.
|
||||
- `dragEnd(double geschwindigkeit, double strecke)` — ruft unverändert
|
||||
`oeffnetVollbildMitStrecke`/die Schließ-Variante auf, um zu entscheiden,
|
||||
ob `progress` zu 1.0 oder 0.0 animiert wird (`AnimationController.fling`
|
||||
mit der Loslass-Geschwindigkeit als Startimpuls, danach `MeloMotion.curve`
|
||||
bis zum jeweiligen Ziel).
|
||||
- `open()` — animiert `progress` 0→1 über `MeloMotion.ruhig(context,
|
||||
MeloMotion.normal)` (Tap-Auslöser, kein Ziehen beteiligt).
|
||||
- `close()` — spiegelbildlich 1→0 (z.B. Zurück-Taste, `X`-artiger Schließen-
|
||||
Button falls später gewünscht).
|
||||
- Reduce-Motion: alle Übergänge über `MeloMotion.ruhig` — bei deaktivierten
|
||||
Animationen springt `progress` sofort auf das Ziel.
|
||||
|
||||
### Widget-Baum in `HomeShell`
|
||||
|
||||
Heute: `Scaffold` mit `body`-Bereich, der `IndexedStack` (5 Tabs) + darunter
|
||||
`MiniPlayer` + `BottomNavigationBar` anordnet. Neu: der `body`-Bereich wird
|
||||
ein `Stack`, von unten nach oben:
|
||||
|
||||
1. `IndexedStack` (Tabs) + `BottomNavigationBar` — unverändert
|
||||
2. `AnimatedBuilder` auf den Controller: nur wenn `progress > 0`, ein
|
||||
`BackdropFilter(filter: ImageFilter.blur(sigmaX: progress * maxSigma,
|
||||
sigmaY: progress * maxSigma))` über Punkt 1 — Widget wird bei
|
||||
`progress == 0` komplett aus dem Baum entfernt (kein Performance-Overhead
|
||||
im Ruhezustand). `maxSigma = 20.0` als Startwert (spürbarer Weichzeichner,
|
||||
ohne die Tab-Umrisse völlig zu verlieren) — im Review/auf echtem Gerät
|
||||
nachjustierbar, siehe „Offene Risiken“.
|
||||
3. `MiniPlayer` — `Opacity(opacity: 1 - progress)`, bei `progress == 1`
|
||||
ebenfalls aus dem Baum entfernt (`IgnorePointer`/Kein Hit-Testing mehr,
|
||||
sonst blockiert eine unsichtbare Leiste Gesten im Vollbild-Player)
|
||||
4. `NowPlayingScreen`-Inhalt — Größe/Position per `Rect.lerp` zwischen dem
|
||||
Mini-Player-Rechteck (volle Breite, `MiniPlayer.hoehe` + Fortschrittsbalken
|
||||
hoch, am unteren Rand über der `BottomNavigationBar`) und dem
|
||||
Vollbild-Rechteck; Detail-Inhalt (Titel, Steuerung, Songtext-Icon etc.)
|
||||
blendet erst ab `progress > 0.3` ein (Crossfade), darunter ist nur das
|
||||
wandernde Cover sichtbar — vermeidet, dass die volle Player-UI in eine
|
||||
72px hohe Box gequetscht wird
|
||||
|
||||
### Cover-Übergang ohne `Hero`
|
||||
|
||||
`_Cover`/`Hero(tag: coverHeldenName, ...)` entfällt an beiden Stellen.
|
||||
Stattdessen: eine neue `_WanderndesCover`-Komponente, die ihr Rechteck
|
||||
(Größe + Position) direkt aus `progress` berechnet (`Rect.lerp` zwischen
|
||||
Mini- und Vollbild-Cover-Rect) und denselben `CoverImage`-Widget-Typ mit
|
||||
interpolierendem `radius` (6 → 16) rendert. Lebt als Teil der `NowPlayingScreen`-
|
||||
Inhalts-Ebene (Punkt 4 oben) — der `MiniPlayer` selbst zeigt kein eigenes
|
||||
Cover mehr, sobald `progress > 0`, um Doppel-Rendering zu vermeiden.
|
||||
|
||||
### Migration der 4 Öffnen-Stellen
|
||||
|
||||
- `lib/library/song_list.dart` (`SongZeile._zeile.onTap`),
|
||||
`lib/playlists/playlist_detail_screen.dart`,
|
||||
`lib/downloads/server_titel_screen.dart`: `Navigator.push(MaterialPageRoute(
|
||||
builder: (_) => const NowPlayingScreen()))` wird durch
|
||||
`context.read<PlayerExpansionController>().open()` ersetzt — nur im
|
||||
Erfolgspfad nach `playSongs(...)`, Fehlerpfad/Snackbar unverändert. Der
|
||||
`NowPlayingScreen`-Import entfällt an diesen 3 Stellen vollständig.
|
||||
- `lib/player/mini_player.dart`: `_oeffne()` ruft `.open()` statt zu pushen;
|
||||
`onVerticalDragUpdate`/`onVerticalDragEnd` rufen `.dragBy()`/`.dragEnd()`
|
||||
statt lokal `_versatz` zu verwalten (die bisherige rein visuelle
|
||||
Mitzieh-Logik der Leiste geht im gemeinsamen `progress`-Wert auf).
|
||||
|
||||
### Zurück-Taste (Android)
|
||||
|
||||
`HomeShell` bekommt ein `PopScope(canPop: controller.progress == 0,
|
||||
onPopInvokedWithResult: (did, _) { if (!did) controller.close(); })` (oder
|
||||
Äquivalent je nach Flutter-Version im Projekt) um den `Scaffold`/`Stack`.
|
||||
Bei offenem oder halb gezogenem Player schließt Zurück den Player; erst bei
|
||||
`progress == 0` verhält sich Zurück wie heute (App verlassen/vorherige
|
||||
Route).
|
||||
|
||||
## Verhaltensänderung (positiv, aber erwähnenswert)
|
||||
|
||||
`_CoverGrundState` (Farbverlauf-Hintergrund aus dem Cover) läuft heute bei
|
||||
jedem Öffnen neu, weil jede Route ein frischer State ist. Als dauerhaftes
|
||||
Overlay bleibt der State über mehrere Öffnen/Schließen-Zyklen hinweg
|
||||
erhalten — die Cover-Farbe ist beim erneuten Öffnen sofort da, kein
|
||||
wiederholtes Bild-Dekodieren pro Öffnen. Reine Verbesserung, aber ein
|
||||
beobachtbarer Unterschied gegenüber heute.
|
||||
|
||||
## Testing
|
||||
|
||||
- **Unit** (`test/player/player_expansion_controller_test.dart`):
|
||||
`dragBy`/`dragEnd`-Übergänge, Clamping auf [0,1], Reduce-Motion-Sofortsprung,
|
||||
`open()`/`close()`-Zielwerte. Entscheidungslogik selbst bleibt in
|
||||
`wischen.dart` und wird dort NICHT erneut getestet (unverändert).
|
||||
- **Widget** (`test/player/home_shell_expansion_test.dart` o.ä.):
|
||||
- Ziehen am Mini-Player erhöht `progress`, Blur-Layer erscheint ab
|
||||
`progress > 0`
|
||||
- Tap aus `song_list.dart` (bzw. Stellvertreter-Widget im Test) ruft
|
||||
`.open()` auf, kein `Navigator.push` mehr
|
||||
- Zurück-Taste bei `progress > 0` schließt den Player statt zu poppen/die
|
||||
App zu verlassen
|
||||
- Ziehen nach unten im Vollbild-Player reduziert `progress` symmetrisch
|
||||
bis zum Schließen
|
||||
- **Cover-Interpolation**: Test, dass `_WanderndesCover` bei
|
||||
`progress = 0 / 0.5 / 1` die erwarteten Rect/Radius-Werte liefert
|
||||
(`Rect.lerp`-Ergebnis direkt prüfbar, kein Golden-Test nötig)
|
||||
|
||||
## Offene Risiken
|
||||
|
||||
- `BackdropFilter` ist in Flutter performance-sensibel (GPU-Kosten pro
|
||||
Frame) — bewusst nur im Baum, wenn `progress > 0`, um Idle-Kosten zu
|
||||
vermeiden; bei sehr low-end Geräten ggf. später Sigma-Obergrenze
|
||||
reduzieren, falls sich das Ziehen ruckelig anfühlt (kein Blocker für die
|
||||
erste Umsetzung, aber im Review beobachten).
|
||||
- `PlayerExpansionController` muss den `mounted`-Zustand von `HomeShell`
|
||||
respektieren (kein `notifyListeners()`/Controller-Zugriff nach `dispose()`)
|
||||
— analog zum bestehenden Muster in `_CoverGrundState`.
|
||||
Reference in New Issue
Block a user