Video Player - Documentation

1. Overview

The Video Player View in SonicSyncSail provides a dedicated, fluid experience for playing locally stored videos. It supports two primary layers of playback interaction:

• Mini Video Player — lightweight, collapsible, always-on-top for quick browsing
• Fullscreen Video Player — immersive playback with advanced controls and gestures

Users can load videos directly from the Music Vault → Video List. When a video is selected, the app switches to Video Mode, replacing the Music Mini Player with the Mini Video Player. From there, users can tap the mini player to transition into a full cinematic view.

2. Accessing the Video Player

Videos are accessed from a dedicated Video List inside the Music Vault. This list displays all available videos detected on the user's device. Selecting any item immediately:

• Switches app to Video Mode
• Replaces the Music Mini Player with the Mini Video Player
• Starts video playback in the in-app mini player

Playback begins instantly, ensuring the user never needs to leave the current browsing context.

3. Mini Video Player

The Mini Video Player floats at the top of the UI, replacing the Mini Music Player whenever a video is active.

3.1 Display Elements

• Video thumbnail preview
• Video title
• Play/Pause button
• Progress bar (compact)

3.2 Behavior

• Tapping anywhere expands to Fullscreen Video Player
• Visible only when video is actively loaded
• Persists across app screens
• Auto-hides when playback is stopped or video is cleared

4. Transition to Fullscreen

Expanding the mini player triggers a smooth UI transition into a fullscreen cinematic experience. This transition includes:

• Scaling video preview to full screen
• Dimming background UI
• Revealing playback controls
• Animating the system into immersive mode (if supported)

5. Full Video Player UI & Controls

The Full Video Player provides comprehensive playback tools through both on-screen buttons and gesture-based interactions.

5.1 Playback Controls

• Play / Pause Button
• Mute / Unmute toggle
• Progress Bar with scrubbing
• Start and End Timestamps
• Auto-hide controls after inactivity

5.2 Video Scaling Modes

A dedicated overlay dialog allows precise control over how the video fits the screen. Available modes:

• FIT — Entire video visible without cropping
• FILL — Fills screen; cropping may occur
• RATIO_16_9 — Force 16:9 layout
• RATIO_4_3 — Force 4:3 layout
• ORIGINAL — Video’s true aspect ratio
• AUTO — Smart choice based on screen orientation

5.3 Gesture Controls

5.3.1 Double Tap

• Left side → seek backward 30 seconds
• Right side → seek forward 30 seconds

5.3.2 Long Press

• Temporarily increases playback speed to 2×
• Reverts to normal speed on release

5.3.3 Vertical Swipes

• Left side → Adjust Volume
• Right side → Adjust Brightness

On-screen overlays provide feedback for volume/brightness levels, seek jumps, and speed boosts.

5.4 Intelligent Keep-Screen-On

• Enabled only during active playback
• Disabled automatically when paused
• Prevents unnecessary battery drain

6. Playback Behavior

• Only one video is loaded at a time
• No auto-play of the next video
• No playback progress saving (no resume)
• Loading a new video immediately replaces the current one
• Switching away from Video Mode pauses playback

7. Edge Cases & Safeguards

• Brightness control requires system permission on some devices
• Mute toggles player volume only—not system volume
• Gestures disabled in locked orientation modes
• Gesture sensitivity capped to prevent accidental long jumps
• Fullscreen disabled during Picture-in-Picture (future behavior)

8. Known Limitations

• No dynamic video queue
• No automatic next-video playback
• No remembering last played video
• No saved playback timestamp
• No subtitle support
• No Picture-in-Picture mode