jellytau/UXFlows.md

# JellyTau UX Flows & Screen Transitions

This document describes the expected user experience flows, screen transitions, and navigation patterns in JellyTau.

---

## 1. Core Navigation Structure

### 1.1 Navigation System

JellyTau uses a unified navigation system with a bottom navigation bar visible on all platforms (mobile and desktop) and additional header navigation for desktop.

**Bottom Navigation Bar (All Platforms - DR-045, UR-039):**

The bottom navigation bar is the primary navigation and is **always visible** on all platforms (mobile and desktop) except when:
- Full-screen video player is active
- User is on the login screen

**Bottom Nav Structure:**
```
┌─────────────────────────────────────────┐
│    [Home]  [Library]  [Search]         │
└─────────────────────────────────────────┘
```

**Routes:**
- **Home** → `/` (home page with carousels and featured content)
- **Library** → `/library` (library selector showing all libraries)
- **Search** → `/search` (dedicated search page)

**Note:** Available on both mobile and desktop for consistent navigation access.

**Header Navigation (Desktop):**

On desktop (md breakpoint and above), the header contains:
- Logo (links to `/library`)
- Navigation links: Home, Library, Downloads, Settings
- Search bar (inline)
- User menu: Username, Downloads icon, Logout button

**Mobile Navigation:**

On mobile, the header contains:
- Logo
- Three-dot overflow menu button (Android-style)
- Overflow menu includes:
  - Downloads
  - Settings
  - Sign out

**Access Points Summary:**
- **Downloads** → Desktop: nav link + icon; Mobile: overflow menu
- **Settings** → Desktop: nav link; Mobile: overflow menu

---

## 2. Initial App Launch Flow

### 2.1 First-Time Launch

```mermaid
flowchart TB
    Launch[App Launch] --> CheckAuth{Stored<br/>Credentials?}
    CheckAuth -->|No| LoginScreen[Login Screen<br/>/login]
    CheckAuth -->|Yes| AutoLogin[Auto-login]

    LoginScreen --> EnterURL[Enter Server URL]
    EnterURL --> EnterCreds[Enter Username/Password]
    EnterCreds --> LoginSuccess{Success?}
    LoginSuccess -->|No| LoginError[Show Error]
    LoginError --> EnterCreds
    LoginSuccess -->|Yes| StoreToken[Store Token in Keyring]

    AutoLogin --> TokenValid{Token Valid?}
    TokenValid -->|No| LoginScreen
    TokenValid -->|Yes| HomePage

    StoreToken --> HomePage[Home Page<br/>/]
```

**Screens:**
1. **Login Screen** (`/login`)
   - Server URL input
   - Username input
   - Password input
   - "Remember me" checkbox (default: on)
   - Login button
   - No header, no bottom nav

2. **Home Page** (`/`)
   - Default landing page after successful login
   - Shows featured content, carousels, continue watching
   - No MiniPlayer visible (nothing playing yet)
   - Bottom nav: Home tab active
   - Header with navigation links

### 2.2 Subsequent Launches

```mermaid
flowchart TB
    Launch[App Launch] --> LoadAuth[Load Stored Token]
    LoadAuth --> Validate{Token Valid?}
    Validate -->|Yes| RestoreState[Restore Last Screen]
    Validate -->|No| LoginScreen[Login Screen<br/>/login]

    RestoreState --> CheckPlayer{Was Player<br/>Active?}
    CheckPlayer -->|Yes| ShowMiniPlayer[Show MiniPlayer<br/>at bottom]
    CheckPlayer -->|No| HideMiniPlayer[No MiniPlayer]

    ShowMiniPlayer --> LastScreen[Last Active Screen<br/>with MiniPlayer]
    HideMiniPlayer --> HomePage[Home Page<br/>/]
```

**State Restoration:**
- Last viewed screen (route) is restored (defaults to `/` if none)
- If audio was playing, MiniPlayer appears at bottom
- Playback state is NOT automatically resumed (user must press play)
- Queue is restored if it existed

---

## 3. Audio Playback Flows

### 3.1 Starting Audio Playback

```mermaid
flowchart TB
    Start[User Action] --> Action{Action Type?}

    Action -->|Click Track| TrackList[TrackList Component]
    Action -->|Click Album| AlbumDetail[Album Detail Page]
    Action -->|Click Play on Album| AlbumPlay[Play Album Button]

    TrackList --> PlayTrack[Play Single Track]
    PlayTrack --> QueueAll[Queue All Filtered Tracks]

    AlbumPlay --> PlayAlbum[Play All Album Tracks]
    PlayAlbum --> QueueAlbum[Queue Album Tracks]

    QueueAll --> InvokePlay[invoke player_play_queue]
    QueueAlbum --> InvokePlay

    InvokePlay --> PlayerStarts[Player State: Playing]
    PlayerStarts --> MiniAppears[MiniPlayer Slides Up<br/>from Bottom]

    MiniAppears --> StayOnPage[User Stays on<br/>Current Screen]
```

**Entry Points for Audio Playback:**
1. **TrackList** (`/library/music/tracks`, `/library/music/albums/[id]`)
   - Click track number → Play track + queue all visible tracks
   - Clicking track #3 in an album → Play track 3, queue tracks 1-10

2. **Album Card** (grid views)
   - Click album → Navigate to album detail
   - Play button on card → Play album immediately

3. **Search Results**
   - Click track → Play track + queue search results
   - Click album → Navigate to album detail

**MiniPlayer Behavior:**
- Slides up from bottom with animation (300ms)
- Height: 64px on mobile, 80px on desktop
- Shows: artwork, title, artist, play/pause, next, favorite
- Stays visible on ALL screens (except video player)
- Click anywhere on MiniPlayer → Navigate to full player

**Track Highlighting:**
When audio is playing, the currently playing track is visually highlighted in track lists and album pages:
- Subtle blue background tint
- Left border accent in Jellyfin blue
- Title text colored in Jellyfin blue
- Desktop: Animated pulsing dots indicator next to title
- Mobile: Play arrow (▶) inline with title
- Highlight updates automatically when skipping to next/previous track

### 3.2 MiniPlayer → Full Player Transition

```mermaid
flowchart TB
    Mini[MiniPlayer Visible] --> UserClick{User Action}

    UserClick -->|Click MiniPlayer| NavFullPlayer[Navigate to<br/>/player/[id]]
    UserClick -->|Swipe Up| SwipeGesture[Swipe Gesture<br/>Planned]

    NavFullPlayer --> FullPlayer[Full Audio Player Screen]
    SwipeGesture --> FullPlayer

    FullPlayer --> ShowControls[Show Full Controls:<br/>- Large artwork<br/>- Progress bar<br/>- Volume slider<br/>- Queue button<br/>- Shuffle/Repeat<br/>- Favorite button]

    ShowControls --> MiniHidden[MiniPlayer Hidden]
```

**Full Player Screen** (`/player/[id]`)
- **Header:** Song title, artist (clickable links to artist/album pages)
- **Artwork:** Large album art (centered, dominant)
- **Progress:** Seek bar with current time / total duration
- **Controls:** Previous, Play/Pause, Next (large touch targets)
- **Secondary Controls:** Shuffle, Repeat mode, Queue, Favorite
- **Volume:** Volume slider
- **Bottom Nav:** Still visible (can navigate away while playing)
- **Back button:** Returns to previous screen, MiniPlayer reappears

### 3.3 Full Player → Back to Browsing

```mermaid
flowchart TB
    FullPlayer[Full Player Screen] --> UserAction{User Action}

    UserAction -->|Back Button / Close| HistoryBack[window.history.back]
    UserAction -->|Bottom Nav Click| NavOther[Navigate to<br/>Other Screen]

    HistoryBack --> PrevScreen[Return to Previous Screen<br/>in Browser History]
    NavOther --> NewScreen[Navigate to New Screen]

    PrevScreen --> MiniReappears[MiniPlayer Slides Up<br/>from Bottom]
    NewScreen --> MiniReappears

    MiniReappears --> PlaybackContinues[Playback Continues<br/>in Background]
```

**Navigation Behavior:**
- **Back Button:** Uses browser history (`window.history.back()`) to return to the previous page
- **Expected behavior:** Returns user to the screen they were on before opening full player
- **Example:** User browsing album → clicks track → full player opens → clicks back → returns to album

**Key UX Principles:**
- **Playback Never Stops:** Navigating away from player does NOT stop playback
- **MiniPlayer Persistence:** MiniPlayer visible on ALL screens (except video/login)
- **Queue Preserved:** Current queue remains intact
- **State Restoration:** Returning to full player shows same state (position, volume, etc.)
- **Natural Navigation:** Back button behaves as expected (returns to previous page, not just closes modal)

---

## 4. Video Playback Flows

### 4.1 Starting Video Playback

```mermaid
flowchart TB
    Start[User Action] --> Action{Action Type?}

    Action -->|Click Movie| MovieDetail[Movie Detail Page]
    Action -->|Click Episode| EpisodeClick[Episode Click]
    Action -->|Click Play Button| PlayButton[Play Button]

    MovieDetail --> PlayMovie[Play Movie Button]
    EpisodeClick --> PlayEpisode[Play Episode]

    PlayMovie --> CheckResume{Resume<br/>Position?}
    PlayEpisode --> CheckResume

    CheckResume -->|Yes, >30s| ShowDialog[Resume Dialog]
    CheckResume -->|No| DirectPlay[Start from Beginning]

    ShowDialog --> UserChoice{User Choice}
    UserChoice -->|Resume| ResumePlay[Start at Saved Position]
    UserChoice -->|Start Over| DirectPlay

    ResumePlay --> FullscreenVideo[Fullscreen Video Player<br/>/player/[id]]
    DirectPlay --> FullscreenVideo

    FullscreenVideo --> HideUI[Hide All UI:<br/>- No Bottom Nav<br/>- No MiniPlayer<br/>- Fullscreen only]
```

**Resume Dialog:**
```
┌─────────────────────────────────────────┐
│  Continue Watching?                     │
│                                         │
│  [Movie Title]                          │
│  Resume from 12:34 / 1:45:00           │
│                                         │
│  [Start from Beginning]  [Resume]      │
└─────────────────────────────────────────┘
```

### 4.2 Video Player Screen (IR-003, IR-004, UR-003)

**Initial State (First 3 seconds):**
- Controls visible overlay
- Top bar: Back button, title
- Bottom bar: Play/Pause, seek bar, time, settings (subtitles, audio track)
- Center: Large play/pause button

**After 3 Seconds (Idle):**
- All controls fade out (500ms animation)
- Fullscreen video only
- System UI hidden (status bar, nav bar)

**User Interaction:**
- **Tap screen:** Controls reappear for 3 seconds
- **Double tap left side:** Rewind 10 seconds (shows animated feedback with "-10" indicator)
- **Double tap right side:** Forward 10 seconds (shows animated feedback with "+10" indicator)
- **Swipe up/down on left side:** Adjust brightness (0.3-1.7x, shows brightness indicator with progress bar)
- **Swipe up/down on right side:** Adjust volume (0-100%, shows volume indicator with progress bar)
- **Keyboard arrows:** ← rewind 10s, → forward 10s (desktop/external keyboard)
- **Keyboard space/K:** Toggle play/pause
- **Keyboard F:** Toggle fullscreen
- **Pinch:** Zoom (planned)

### 4.3 Exiting Video Player

```mermaid
flowchart TB
    VideoPlaying[Video Playing] --> UserAction{User Action}

    UserAction -->|Back Button| StopVideo[Stop Playback]
    UserAction -->|Home Button| Background[App to Background]
    UserAction -->|Video Ends| VideoEnd[Playback Ended]

    StopVideo --> SaveProgress[Save Progress<br/>to Local DB + Server]
    VideoEnd --> SaveComplete[Mark as Watched<br/>Save Progress]
    Background --> PauseVideo[Pause Video]

    SaveProgress --> ExitFullscreen[Exit Fullscreen]
    SaveComplete --> AutoNext{Next Episode<br/>Available?}

    AutoNext -->|Yes| ShowCountdown[Show Countdown<br/>Next in 5s...]
    AutoNext -->|No| ExitFullscreen

    ShowCountdown --> UserCancel{User Cancels?}
    UserCancel -->|Yes| ExitFullscreen
    UserCancel -->|No, timeout| PlayNext[Play Next Episode]

    ExitFullscreen --> RestoreUI[Restore UI:<br/>- Bottom Nav<br/>- Previous Screen]

    PlayNext --> VideoPlaying

    PauseVideo --> ShowNotification[Show Notification:<br/>Tap to Resume]
```

**Auto-Next Overlay:**
```
┌─────────────────────────────────────────┐
│                                         │
│         [Episode Thumbnail]             │
│                                         │
│  Next: S01E02 - Episode Title          │
│  Starting in 5 seconds...              │
│                                         │
│  [Cancel]              [Play Now]      │
└─────────────────────────────────────────┘
```

---

## 5. Music Library Navigation Flows

### 5.1 Music Category Landing Page

```mermaid
flowchart TB
    LibraryHome[Library Home<br/>/library] --> ClickMusic[Click Music Library]

    ClickMusic --> MusicLanding[Music Landing Page<br/>/library/music]

    MusicLanding --> ShowCategories[Show Category Cards:<br/>- Tracks<br/>- Artists<br/>- Albums<br/>- Playlists<br/>- Genres]

    ShowCategories --> UserClick{User Clicks Category}

    UserClick -->|Tracks| TracksPage[All Tracks Page<br/>/library/music/tracks]
    UserClick -->|Artists| ArtistsPage[Artists Grid<br/>/library/music/artists]
    UserClick -->|Albums| AlbumsPage[Albums Grid<br/>/library/music/albums]
    UserClick -->|Playlists| PlaylistsPage[Playlists Grid<br/>/library/music/playlists]
    UserClick -->|Genres| GenresPage[Genres Browser<br/>/library/music/genres]
```

**Category Cards:**
```
┌─────────────────────────────────────────┐
│  ┌──────┐  ┌──────┐  ┌──────┐          │
│  │ 🎵  │  │ 👤  │  │ 💿  │          │
│  │Track│  │Artist│  │Album│          │
│  └──────┘  └──────┘  └──────┘          │
│  ┌──────┐  ┌──────┐                    │
│  │ 📝  │  │ 🎭  │                    │
│  │List │  │Genre│                    │
│  └──────┘  └──────┘                    │
└─────────────────────────────────────────┘
```

### 5.2 Albums View Flow

```mermaid
flowchart TB
    AlbumsGrid[Albums Grid<br/>FORCED Grid View] --> UserAction{User Action}

    UserAction -->|Click Album| AlbumDetail[Album Detail Page<br/>/library/[albumId]]
    UserAction -->|Click Play on Card| PlayAlbum[Play Album Immediately]

    AlbumDetail --> ShowAlbum[Show Album:<br/>- Album Art<br/>- Title, Artist<br/>- Track List<br/>- Download Button<br/>- Favorite Button]

    ShowAlbum --> TrackAction{User Action}

    TrackAction -->|Click Track| PlayTrack[Play Track + Queue Album]
    TrackAction -->|Click Artist| NavArtist[Navigate to Artist Page]
    TrackAction -->|Download Album| DownloadFlow[Download Flow]
    TrackAction -->|Back Button| BackToGrid[Return to Albums Grid]
```

**Album Detail Layout:**
```
┌─────────────────────────────────────────┐
│  [←]              [♡] [⬇]               │
│                                         │
│      ┌────────────────────┐             │
│      │                    │             │
│      │   Album Artwork    │             │
│      │                    │             │
│      └────────────────────┘             │
│                                         │
│  Album Title                            │
│  Artist Name (clickable)                │
│  2024 • 12 tracks • 45:23              │
│                                         │
│  [▶ Play]  [🔀 Shuffle]                │
│                                         │
│  ─────────────────────────────────────  │
│  1  Track Title               3:45     │
│  2  Track Title               4:12     │
│  3  Track Title               3:28     │
│  ...                                    │
└─────────────────────────────────────────┘
```

### 5.3 Artist Navigation

```mermaid
flowchart TB
    ArtistsGrid[Artists Grid] --> ClickArtist[Click Artist]

    ClickArtist --> ArtistPage[Artist Detail Page<br/>/library/artist/[id]]

    ArtistPage --> ShowContent[Show Artist Content:<br/>- Artist Photo<br/>- Biography<br/>- Albums Grid<br/>- Top Tracks<br/>- Similar Artists]

    ShowContent --> UserAction{User Action}

    UserAction -->|Click Album| AlbumDetail[Album Detail Page]
    UserAction -->|Play Top Tracks| PlayArtist[Play Artist Radio]
    UserAction -->|Click Similar Artist| OtherArtist[Other Artist Page]
```

---

## 6. Search Flow

### 6.1 Search Page Navigation

```mermaid
flowchart TB
    BottomNav[Bottom Nav] --> ClickSearch[Click Search Tab]

    ClickSearch --> SearchPage[Search Page<br/>/search]

    SearchPage --> EmptyState{Has Query?}

    EmptyState -->|No| ShowPrompt[Show Empty State:<br/>Search for music,<br/>movies, shows...]
    EmptyState -->|Yes| ShowResults[Show Results Grouped:<br/>- Songs<br/>- Albums<br/>- Artists<br/>- Movies<br/>- Episodes]

    ShowPrompt --> UserTypes[User Types in Search]
    UserTypes --> LiveSearch[Live Search<br/>Debounced 300ms]
    LiveSearch --> ShowResults

    ShowResults --> UserClick{User Clicks Result}

    UserClick -->|Song| PlaySong[Play Song + Queue Results]
    UserClick -->|Album| NavAlbum[Navigate to Album Detail]
    UserClick -->|Artist| NavArtist[Navigate to Artist Page]
    UserClick -->|Movie| NavMovie[Navigate to Movie Detail]
```

**Search Page Layout:**
```
┌─────────────────────────────────────────┐
│  [🔍 Search...]                [✕]     │
│                                         │
│  Songs ────────────────────────────     │
│  ♪ Song Title - Artist         3:45    │
│  ♪ Song Title - Artist         4:12    │
│  See all (23)                          │
│                                         │
│  Albums ───────────────────────────     │
│  [Album Cover] Album Title             │
│  [Album Cover] Album Title             │
│  See all (8)                           │
│                                         │
│  Artists ──────────────────────────     │
│  [Photo] Artist Name                   │
│  See all (5)                           │
└─────────────────────────────────────────┘
```

---

## 7. Download Flows

### 7.1 Initiating Downloads

```mermaid
flowchart TB
    User[User on Album/Track Page] --> ClickDownload[Click Download Button]

    ClickDownload --> CheckType{Download Type?}

    CheckType -->|Single Track| DownloadTrack[Download Single File]
    CheckType -->|Album| DownloadAlbum[Download All Tracks]
    CheckType -->|Artist| ShowOptions[Show Options Dialog]

    ShowOptions --> UserChoice{User Choice}
    UserChoice -->|Discography| DownloadAll[Download All Albums]
    UserChoice -->|Select Albums| AlbumPicker[Album Selection UI]

    DownloadTrack --> QueueDownload[Queue in Download Manager]
    DownloadAlbum --> QueueMultiple[Queue Multiple Files]

    QueueDownload --> ShowProgress[Show Progress Ring<br/>on Download Button]
    QueueMultiple --> ShowProgress

    ShowProgress --> DownloadActive[Download Active:<br/>Button shows % complete]
```

**Download Button States:**
```
States:
1. [⬇] Available     - Gray outline
2. [○ 45%] Downloading - Blue ring progress
3. [✓] Downloaded    - Green checkmark
4. [!] Failed        - Red with retry option
5. [⏸] Paused        - Yellow pause icon
```

### 7.2 Managing Downloads Page

```mermaid
flowchart TB
    User[User] --> NavChoice{Navigation Path}

    NavChoice -->|Desktop| HeaderNav[Header: Click Downloads Link]
    NavChoice -->|Mobile| HeaderIcon[Header: Click Downloads Icon]
    NavChoice -->|Direct| TypeURL[Type /downloads]

    HeaderNav --> DownloadsPage[Downloads Page<br/>/downloads]
    HeaderIcon --> DownloadsPage
    TypeURL --> DownloadsPage

    DownloadsPage --> ShowTabs[Show Tabs:<br/>Active | Completed]

    ShowTabs --> ActiveTab{Active Tab}

    ActiveTab -->|Active| ShowActive[Show Active Downloads:<br/>- Download progress bars<br/>- Pause/Resume buttons<br/>- Cancel buttons]
    ActiveTab -->|Completed| ShowCompleted[Show Completed:<br/>- Downloaded items list<br/>- Delete buttons<br/>- Play buttons]

    ShowActive --> UserAction1{User Action}
    UserAction1 -->|Pause| PauseDownload[Pause Download]
    UserAction1 -->|Cancel| CancelDialog[Show Confirm Dialog]

    ShowCompleted --> UserAction2{User Action}
    UserAction2 -->|Play| PlayOffline[Play from Local File]
    UserAction2 -->|Delete| DeleteDialog[Show Confirm Dialog]
```

**Navigation to Downloads:**
- **Desktop:** Click "Downloads" link in header navigation
- **All screen sizes:** Click download icon (⬇) button in header user menu
- **Direct:** Navigate to `/downloads` route

**Downloads Page Layout:**
```
┌─────────────────────────────────────────┐
│  [←] Downloads                          │
│                                         │
│  [Active (3)] [Completed (12)]         │
│                                         │
│  ─ Downloading ────────────────────     │
│                                         │
│  Album Cover  Album Title               │
│               Artist Name               │
│               [████████░░] 80%          │
│               [⏸ Pause] [✕ Cancel]     │
│                                         │
│  Album Cover  Album Title               │
│               Artist Name               │
│               [██░░░░░░░░] 20%          │
│               [⏸ Pause] [✕ Cancel]     │
│                                         │
│  ─ Queued ─────────────────────────     │
│                                         │
│  Album Cover  Album Title               │
│               Artist Name               │
│               Waiting...                │
└─────────────────────────────────────────┘
```

---

## 8. Settings & Account Flows

### 8.1 Settings Navigation

```mermaid
flowchart TB
    User[User] --> NavChoice{Navigation Path}

    NavChoice -->|Desktop| HeaderSettings[Header: Click Settings Link]
    NavChoice -->|Mobile| OverflowMenu[Click Overflow Menu<br/>→ Settings]
    NavChoice -->|Direct| TypeURL[Navigate to /settings]

    HeaderSettings --> SettingsPage[Settings Page<br/>/settings]
    OverflowMenu --> SettingsPage
    TypeURL --> SettingsPage

    SettingsPage --> ShowSections[Show Sections:<br/>- Account<br/>- Playback<br/>- Downloads<br/>- Appearance<br/>- About]

    ShowSections --> UserClick{User Clicks Section}

    UserClick -->|Account| AccountSettings[Account Settings:<br/>- Server URL<br/>- Username<br/>- Logout button]
    UserClick -->|Playback| PlaybackSettings[Playback Settings:<br/>- Gapless playback<br/>- Volume normalization<br/>- Crossfade duration]
    UserClick -->|Downloads| DownloadSettings[Download Settings:<br/>- Max concurrent<br/>- WiFi only<br/>- Storage location<br/>- Auto-cache next tracks]
    UserClick -->|Appearance| AppearanceSettings[Appearance Settings:<br/>- Dark mode<br/>- Accent color]
```

**Navigation to Settings:**
- **Desktop:** Click "Settings" link in header navigation
- **Mobile:** Click three-dot overflow menu → Select "Settings"
- **Direct:** Navigate to `/settings` route

### 8.2 Logout Flow

```mermaid
flowchart TB
    AnyScreen[Any Screen] --> ClickLogout[Click Logout Button<br/>in Header]

    ClickLogout --> ConfirmDialog[Show Confirmation:<br/>"Log out of [Server]?"]

    ConfirmDialog --> UserConfirm{User Confirms?}

    UserConfirm -->|No| CancelLogout[Cancel - Stay on Current Screen]
    UserConfirm -->|Yes| StopPlayer[Stop Playback]

    StopPlayer --> ClearToken[Delete Token from Keyring]
    ClearToken --> ClearState[Clear App State:<br/>- Player state<br/>- Queue<br/>- Current screen]

    ClearState --> NavLogin[Navigate to Login Screen<br/>/login]

    NavLogin --> ShowLogin[Show Login Screen:<br/>- No Header<br/>- No Bottom Nav<br/>- No MiniPlayer]
```

**Logout Button Location:**
- Always visible in header user menu (logout icon)
- Accessible from any authenticated screen

---

## 9. Background & Lock Screen Behavior

### 9.1 Audio Playback in Background (Android)

```mermaid
flowchart TB
    Playing[Audio Playing] --> Background{User Action}

    Background -->|Home Button| AppBackground[App to Background]
    Background -->|Screen Lock| ScreenLock[Screen Locked]

    AppBackground --> ContinuePlay[Playback Continues]
    ScreenLock --> ContinuePlay

    ContinuePlay --> ShowNotification[Show Media Notification:<br/>- Artwork<br/>- Title/Artist<br/>- Play/Pause<br/>- Next/Previous]

    ShowNotification --> LockScreen[Lock Screen Controls:<br/>Media Session Integration]

    LockScreen --> UserInteract{User Interaction}

    UserInteract -->|Tap Notification| OpenApp[Open App to Last Screen<br/>with MiniPlayer]
    UserInteract -->|Lock Screen Controls| SendCommand[Send Command to Player]
    UserInteract -->|BLE Headset Button| HeadsetControl[AVRCP Command]
```

**Notification Layout (Android):**
```
┌─────────────────────────────────────────┐
│  [Artwork] Song Title                   │
│           Artist Name                   │
│           Album Name                    │
│                                         │
│  [⏮]  [⏸]  [⏭]                [✕]      │
└─────────────────────────────────────────┘
```

### 9.2 Video Playback in Background

```mermaid
flowchart TB
    VideoPlaying[Video Playing] --> Background{User Action}

    Background -->|Home Button| AutoPause[Automatically Pause]
    Background -->|Screen Lock| AutoPause

    AutoPause --> SaveProgress[Save Progress]
    SaveProgress --> ShowNotification[Show Paused Notification:<br/>"Tap to Resume"]

    ShowNotification --> UserReturn{User Returns?}

    UserReturn -->|Tap Notification| ResumeVideo[Open App to Video Player]
    UserReturn -->|Later| KeepPaused[Video Remains Paused]

    ResumeVideo --> AskResume[Resume from Saved Position]
```

---

## 10. Error States & Edge Cases

### 10.1 Network Loss During Streaming

```mermaid
flowchart TB
    Streaming[Streaming Audio/Video] --> LoseNetwork[Network Connection Lost]

    LoseNetwork --> CheckLocal{Local Copy<br/>Available?}

    CheckLocal -->|Yes| SwitchLocal[Switch to Local Playback<br/>Seamlessly]
    CheckLocal -->|No| ShowBuffer[Show Buffering Spinner]

    ShowBuffer --> WaitReconnect[Wait for Reconnection<br/>30 second timeout]

    WaitReconnect --> Reconnect{Reconnected?}

    Reconnect -->|Yes| Resume[Resume Streaming]
    Reconnect -->|No| ShowError[Show Error Toast:<br/>"Unable to stream.<br/>Check connection."]

    ShowError --> OfferRetry[Offer Retry Button]
    ShowError --> OfferDownload[Offer "Download for Offline"]
```

### 10.2 Server Unreachable

```mermaid
flowchart TB
    Action[User Action Requires Server] --> TryConnect[Attempt Connection]

    TryConnect --> Timeout{Connection<br/>Timeout?}

    Timeout -->|Yes| ShowError[Show Error:<br/>"Server unreachable"]
    Timeout -->|No| Success[Action Succeeds]

    ShowError --> OfferOptions[Offer Options:<br/>- Retry<br/>- Switch to Offline Mode<br/>- Change Server]
```

### 10.3 Download Failed

```mermaid
flowchart TB
    Downloading[Download in Progress] --> Failure{Failure Type?}

    Failure -->|Network Error| Retry[Auto-retry<br/>with Backoff]
    Failure -->|Disk Full| ShowDiskError[Show Error:<br/>"Not enough storage"]
    Failure -->|Server Error| ShowServerError[Show Error:<br/>"Server error"]

    Retry --> RetryCount{Retry Count<br/>< 3?}
    RetryCount -->|Yes| Downloading
    RetryCount -->|No| Failed[Mark as Failed]

    ShowDiskError --> Failed
    ShowServerError --> Failed

    Failed --> UserAction[Show in Downloads:<br/>with Retry Button]
```

---

## 11. Platform-Specific UX Patterns

### 11.1 Android-Specific

**Hardware Back Button:**
- **In Full Player:** Return to previous screen, show MiniPlayer
- **In Video Player:** Stop playback, exit fullscreen
- **In Album Detail:** Return to library grid
- **At Library Home:** Exit app (show confirmation)

**System Volume Buttons:**
- **While playing audio:** Adjust playback volume
- **While controlling remote session:** Adjust remote session volume (shows session name in volume panel)
- **In menus:** Adjust system volume (default behavior)

**Share Integration:**
- Long-press album/song → Share menu
- Options: Share with other apps, Copy link

### 11.2 Linux Desktop-Specific

**Keyboard Shortcuts:**
- `Space`: Play/Pause
- `→`: Next track
- `←`: Previous track
- `/`: Focus search
- `Ctrl+Q`: Quit

**Window Behavior:**
- Minimize to tray (playback continues)
- Close window (show confirmation if playing)
- MPRIS integration for desktop media controls

**Mouse Interactions:**
- Hover over MiniPlayer: Show additional controls (volume, queue peek)
- Right-click: Context menu (Add to playlist, Go to artist, Download)

---

## 12. UX Principles Summary

### 12.1 Core Principles

1. **Playback Persistence:**
   - Audio playback never stops unless user explicitly stops it
   - MiniPlayer visible on all screens (except video/login)
   - Queue and position preserved across navigation

2. **Non-Blocking UI:**
   - Downloads happen in background
   - Sync operations never block user interaction
   - Optimistic updates (favorite, progress) with background sync

3. **Offline-First:**
   - Downloaded content works offline
   - Seamless switch between online/offline
   - Progress and preferences saved locally

4. **Progressive Disclosure:**
   - Simple defaults, advanced options hidden
   - Context menus for secondary actions
   - Settings organized by category

5. **Responsive Design:**
   - Mobile-first UI
   - Desktop enhancements (hover states, keyboard shortcuts)
   - Tablet: Grid layouts with more columns

### 12.2 Animation & Transitions

| Transition | Duration | Easing |
|------------|----------|--------|
| MiniPlayer slide up/down | 300ms | ease-out |
| Screen navigation | 200ms | ease-in-out |
| Video controls fade | 500ms | ease-out |
| Download button state change | 150ms | ease-in-out |
| Modal appear | 200ms | ease-out |
| Toast notification | 250ms | ease-in-out |

### 12.3 Touch Targets (Mobile)

| Element | Minimum Size |
|---------|--------------|
| Bottom nav buttons | 48x48 dp |
| List item (track, album) | Full width x 56 dp |
| Player controls | 56x56 dp |
| MiniPlayer | Full width x 64 dp |
| Download button | 40x40 dp |
| Favorite button | 40x40 dp |

---

## 13. Future UX Enhancements

### 13.1 Planned Features

1. **Gesture Navigation:**
   - Swipe up on MiniPlayer → Full player
   - Swipe down on full player → Back to previous screen
   - Swipe between tracks in full player

2. **Queue Management UI (DR-020):**
   - Drag to reorder
   - Swipe to remove
   - Add to queue vs. Play next

3. **Sleep Timer (UR-026):**
   - Accessible from full player menu
   - Presets: 15min, 30min, 1hr, End of track, End of album
   - Countdown visible in MiniPlayer

4. **Home Screen (UR-034):**
   - Hero banner carousel
   - Continue watching/listening
   - Recently added
   - Personalized recommendations

5. **Cast/Remote Control Enhancements:**
   - Picture-in-picture for remote sessions
   - Multi-room audio (play on multiple devices)
   - Handoff (transfer playback to phone from TV)

### 13.2 Accessibility Enhancements

- Screen reader optimization
- High contrast mode
- Larger text option
- Voice control integration
- Haptic feedback for controls

---

This UX flow documentation should be updated as new features are implemented and user feedback is incorporated.