Now Playing Screen - Documentation

1. Overview

The Now Playing Screen is the central music playback interface in SonicSyncSail. It provides complete playback control, dynamic UI transitions, and mode-specific functionality that adapts to the type of media being played—whether it is offline music, streaming radio, or a PulseSync emotional mix.

Users begin with a Mini Collapsible Player displayed at the top of all app screens. Upon tapping it, a smooth animated transition expands the player into a full-screen experience where all controls, artwork, mode buttons, progress bars, queue controls, and mode-specific tools become visible.

2. Mini Player (Collapsed Player)

The Mini Player appears persistently at the top of the app, floating above all UI screens. It provides essential playback information and quick controls without disrupting browsing.

2.1 Displayed Elements

• Current song title
• Artist name
• Mini album art thumbnail
• Play/Pause button
• Tap area that triggers full player transition

2.2 Behavior

• Permanently visible unless playback is fully stopped
• Expands into the full Now Playing screen with a single tap
• Adapts to current mode: Music, Radio, or Sync

3. Transition to Full Now Playing Screen

When the user taps the Mini Player, an animated transition expands the UI into a dedicated full-screen player. This transition:

• Fades in background artwork
• Displays mode controls at the top
• Animates the progress bar into full width
• Reveals mode-specific controls
• Shows queue/segment controls (depending on mode)

4. Mode Selection Controls

At the top of the full player sits a three-button Mode Selection Group. Tapping a mode instantly updates all visible controls.

Available Modes

• Music Mode — standard offline/local music playback
• Radio Mode — internet radio streaming playback
• Sync Mode — PulseSync emotional mix playback

Each mode changes the controls, layout, and available buttons shown on screen.

5. Music Mode

Music Mode represents the classic playback experience for locally stored audio files. It includes all queue and navigation tools expected in a full-featured music player.

5.1 Available Controls

• Playback progress bar
• Play / Pause
• Play Next
• Play Previous
• Queue Controls:
  • Repeat One
  • Repeat All
  • Shuffle
  • No Repeat
• Up Next button (opens queue)
• Song Title & Artist

5.2 Behavior

• Progress bar scrubbing enabled
• Queue advances according to repeat/shuffle mode
• Album art displays full resolution

6. Radio Mode

Radio Mode is designed for internet radio streaming. Controls are simplified compared to Music Mode. An internet connection is required.

6.1 Modified Controls

• Queue controls are removed
• A dedicated Sync Mode Button appears to allow instant switch into PulseSync

6.2 Behavior

• No seek/progress scrubbing (streaming content)
• Sync button allows Buffer refresh to sync the playback with the chosen radio station server

7. Sync Mode

Sync Mode displays the emotional PulseSync mix created using the Pulse Mixer and Pulse Editor. This mode introduces the unique Segment Graph UI.

7.1 Segment Graph

A horizontal graph showing all Pulse Segments in the current mix. Each point represents a segment boundary.

7.1.1 Interactions

• Tapping a point instantly skips playback to that segment
• Points are color-coded by emotion or intensity
• Progress indicator moves across the graph in real time

7.2 Available Controls

• Play/Pause
• Skip to next segment
• Skip to previous segment
• Segment graph scrubbing
• Pulse Mixer button (opens Pulse mixer)

7.3 Behavior

• Progress bar replaced by segment graph
• Playback respects PulseMixer logic
• Crossfades and beatmatching occur between segments

8. Common Controls

8.1 Sleep Timer

A universal button allowing the user to schedule playback shutdown.

8.2 Album Art Interaction

• Tap to toggle artwork size modes
• Long press for metadata shortcuts
• Displays dynamic blurred background

8.3 Animation & UX Behavior

• Artwork color extraction for dynamic UI tinting
• Smooth fade between modes
• Playback state animations

9. Behavioral Flow & Interaction Logic

• Mini Player always transitions upward into Full Player
• Mode buttons hot-swap UI instantly without stopping playback
• Each mode updates controls, not the underlying MediaSession
• Playback engine is consistent across modes except Radio Mode
• Returning to previous screen collapses to Mini Player

10. Edge Cases & Safeguards

• No progress bar on Radio Mode
• Segment graph only in Sync Mode
• Mini Player hidden when no media is active

11. Known Limitations

• No waveform scrubbing in Music Mode
• No DSP energy graph in Sync Mode UI
• Album art extraction depends on file tag quality