1. Overview

Tune Vault is SonicSyncSail's unified library surface for browsing and managing the user's media collection. It presents horizontally swipeable sections (Songs, Albums, Artists, Genres, Videos, Playlists) in a single top-level pager. Each section is optimized for quick discovery, immediate playback, and bulk management through a focused multi-select mode.

2. Top-level UI & Swipable Pager

The Tune Vault screen uses a horizontal pager at the top that exposes the following tabs (order may be customized): Songs, Albums, Artists, Genres, Videos, Playlists.

Pager behavior

• Horizontal swipe to change the visible content area. Tab headers remain visible for direct navigation.
• Each page is independently scrollable vertically and supports lazy loading for performance.
• Pager state is preserved during navigation and when returning to Tune Vault from other parts of the app.

Top bar controls

• Resync button — triggers an immediate quick library scan (see Resync section).
• Search field — scoped to the entire library .
• Sort / Filter dropdown — per-page options (e.g., sort by title/date/artist).

3. Resync / Quick Library Scan

The top bar Resync action performs an immediate quick scan that reconciles the app's metadata with Android MediaStore. The scan is designed to be quick and non-blocking.

Resync flow

1. User taps Resync.
2. UI shows an inline progress indicator (non-blocking toast or top bar loader).
3. Background worker queries MediaStore for additions, deletions, and metadata updates.
4. Room database and UI lists are updated incrementally; visible list items refresh as changes are applied.
5. Upon completion, a success or conflict summary is shown (e.g., 12 new tracks, 2 deleted).

Notes

• Resync has quick and full modes. Quick mode checks timestamps and simple diffs; full scan re-reads file-level metadata and regenerates caches.
• Permission checks run before scanning—if required permissions are missing, the user is prompted elegantly.

4. Item Types & Details Pages

Each item type in Tune Vault has a dedicated representation and a details page:

Songs

Song list items include album art, title, artist, duration, and overflow menu. Tapping a song starts playback. Long-press enters multi-select mode.

Albums

Album items show artwork, album title, artist, and track count. Tapping opens the Album Details page listing all songs for that album in a vertically scrollable list.

Artists

Artist items provide a header card with artist art (if available) and a list of albums or top tracks within the Artist Details page.

Genres

Genre items present genre name and sample artwork. The Genre Details page lists all tracks assigned to that genre.

Videos

Video items show thumbnail, title, duration. Opening the details page displays video-specific playback and sharing options.

Playlists

Playlists can be local or user-created. The Playlist Details page lists songs in order. Play actions respect the playlist's ordering and queue mode.

5. Playback Behavior from Lists

Tapping a song

When a user taps a song item on any list:

• Playback begins immediately using the currently selected queue mode (no repeat / repeat one / repeat all / shuffle).
• The global player (mini-player) updates and may transition to the full Now Playing screen depending on user action.
• If the tapped song belongs to a list with a natural ordering (e.g., album or playlist), the queue is constructed from that source starting at the tapped index.

Queue construction rules

• Songs page: queue = current songs page list (filtered & sorted), starting at tapped index.
• Album/Playlist/Artist/Genre details: queue = items in the details page ordered as displayed.
• Videos: uses the video queue controller with video-specific playback semantics.

Up Next & Context

"Up Next" displays the remaining queue entries and supports reordering, removing, or sending items to the Pulse Editor / PulseVault where applicable.

6. Multi-select Mode & Batch Operations

Long-press on any item (song, album entry, artist track, genre item, playlist item) activates the per-screen multi-select mode. Only one screen may be in multi-select at a time.

Multi-select UI

• Top action bar replaces the normal top bar while in multi-select mode.
• Controls include: Select All toggle, Play, Add to, Share, Hide, and a counter of selected items.
• Exit multi-select via back arrow or by back navigation .

Actions & Semantics

Play

Creates a playback queue from selected items (order follows current list sort). For playlist/album contexts, respects local ordering where applicable.

Add to

Shows a destination picker (Playlists, Queue, Custom Collections). When adding large numbers, the operation runs in a background batch with progress feedback.

Share

Exports URIs via Intent.ACTION_SEND_MULTIPLE. For files that cannot be accessed directly, creates temporary share URIs via FileProvider.

Hide

Marks items as hidden in Room DB (soft-delete). Hidden items can be restored from Hidden view.

Limits & Constraints

• Multi-select is scoped to the active screen only (e.g., selecting songs on Songs page won't affect Albums screen).
• Selection count cap can be enforced to limit memory / operation size (configurable, e.g., 1000 items).
• Long-running batch operations present a progress UI and optionally notifications when running in the background.

7. Accessibility & Keyboard / External Controls

• All list items provide descriptive accessibility labels including title, artist, duration, and actionable hints.
• Keyboard navigation supports item focus, selection via space/enter, and multi-select toggling with standard modifiers.
• External controllers (Bluetooth media buttons) map to global playback actions and do not conflict with selection gestures.

8. Data Flow & Persistence

Tune Vault uses a layered model:

1. MediaStore — authoritative source for device media files.
2. Room DB — mirrors and augments MediaStore with app-only metadata (hidden flag, user-created playlists, Pulse segment references).
3. UI cache — in-memory views and waveform previews for performance.

Sync mechanics

On Resync or on content change notifications (ContentResolver observers), the background scanner reconciles MediaStore → Room DB → UI increments, minimizing full reloads.

9. Edge Cases & Safeguards

• Missing permissions: UI shows an explanatory placeholder and call-to-action to request required permissions.
• Read-only files: Edit or hide actions are disabled and show contextual explanations.
• Large libraries: Use incremental loading, batching, and virtualization to keep UI responsive.
• Conflicting metadata: Provide a simple merge UI when duplicate media entries are detected.
• Out-of-sync MediaStore: Allow user-triggered full rescan and provide conflict resolution tools.

10. Implementation Notes & UI Examples

Suggested components

• Pager — accessible, swipeable with visible tab bar.
• List virtualization — for long lists (recycler / virtual-scroller).
• Local selection store — ephemeral selection state per screen for multi-select.
• Batch operation queue — for background add/share operations.

UX patterns

1. Show immediate feedback for Resync (progress + quick summary).
2. Keep multi-select persistent across rotation and minor navigation while remaining scoped to the active screen.
3. Prevent destructive bulk deletes—require a confirmation dialog and display estimated impact.