dtourolle/jellytau
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
jellytau/UXFlows.md

32 KiB
Raw Permalink Blame History

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

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

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.