dreamio/docs/native-player-ux-audit.md

Native Player UX Baseline Audit

Date: 2026-05-26 21:49 EDT
Issue: dreamio-ee1

Scope

This audit covers the current VLC-backed native playback experience before Liquid Glass and broader UX changes. The primary implementation is Dreamio/NativePlayerViewController.swift, backed by Dreamio/NativePlaybackBackend.swift and Dreamio/VLCNativePlaybackBackend.swift.

Current Experience Summary

Dreamio presents native playback as a full-screen black video surface with a compact bottom control tray, a top-right close button, a loading spinner, and a simple centered failure label. Controls are built directly in UIKit and are intentionally lightweight.

Current user-facing controls:

• Top-right close button.
• Bottom compact blur-backed tray capped at 430 points wide.
• Elapsed time, scrubber, and remaining time row.
• Audio menu button.
• 15-second jump back.
• Play/pause.
• 15-second jump forward.
• Captions menu button with subtitle delay controls.
• Tap anywhere on the playback surface to reveal or hide controls.
• Auto-hide while playing after 3 seconds.

Existing Strengths

• Minimal interruption: The player is full-screen and hides chrome while playback is active.
• Compact controls: Recent work reduced the overlay footprint so video content stays dominant.
• Core playback affordances exist: Play/pause, seeking, jump controls, elapsed/remaining time, audio tracks, captions, and subtitle delay are present.
• Backend-aware disabling: Seek and jump controls disable when VLC reports a non-seekable stream.
• Track menus are cached: Audio and captions menus avoid unnecessary rebuilds through signature values.
• Subtitle handoff exists: The native player can receive subtitle candidates from the Stremio Web bridge and attach them through the backend.
• Safe-area aware: Close and controls are anchored to safe-area guides.

Current UX Gaps

Visual Treatment

• The control surface uses UIBlurEffect(style: .systemUltraThinMaterialDark) plus manual tint/border styling, not iOS 26 Liquid Glass.
• Buttons are individual translucent wells rather than an intentional grouped glass system.
• There is no bottom readability scrim; bright video frames could reduce time label and icon contrast.
• Loading and failure states are plain compared with the rest of the player chrome.

Touch Targets and Hierarchy

• Secondary controls are 36×36 points, below Apple’s recommended 44×44 point minimum target.
• The play/pause button is only 42×42 points, so the primary action is not dominant enough.
• Audio and captions have the same visual weight as transport controls even when unavailable or secondary.
• Disabled captions do not currently mirror the explicit alpha treatment used by audio.

Scrubbing

• The scrubber has a compact thumb and row, but no preview/target time bubble.
• During scrubbing, the elapsed label updates, but the user does not get a larger focused scrubbing affordance.
• There is no haptic feedback on scrub begin/end or jump actions.

Gestures

• Single tap toggles controls, but no richer playback gestures exist.
• There is no double-tap left/right jump behavior.
• There is no center tap play/pause behavior separate from chrome visibility.
• Gesture conflict handling will need care because tap.cancelsTouchesInView = false currently allows control touches to pass through.

Auto-Hide

• Controls hide after 3 seconds while playing, which can feel short for subtitle/audio menu interactions or careful scrubbing.
• The auto-hide timer only checks backend.isPlaying; future changes should explicitly protect menu presentation, scrubbing, loading, paused, and failure states.

Loading and Failure

• Startup loading is only a white UIActivityIndicatorView over black.
• Failure is a plain text label with no retry, close action, or debug affordance.
• The 20-second startup timeout is useful, but the user receives little guidance after it fires.

Accessibility

• Buttons have accessibility labels, but no accessibility hints.
• The scrubber has no dynamic accessibility value describing elapsed and remaining time.
• Jump actions are not exposed as custom accessibility actions on the player surface.
• Motion preferences are not checked before animations.
• Dynamic Type behavior for the compact controls has not been explicitly protected.

Device Adaptation

• The bottom tray is capped at 430 points, which is good for phones but underuses iPad/large landscape space.
• Button sizing and row spacing are fixed; orientation-specific density has not been tuned.
• The supported orientations allow all but upside down, so landscape crowding should be part of validation.

Implementation Constraints

• NativePlaybackBackend currently exposes no thumbnail/preview frames, so scrub previews should begin as a time bubble rather than video thumbnails.
• The backend exposes seekability, duration, position, audio tracks, subtitle tracks, and subtitle delay, which is enough for richer controls without backend changes.
• The app must preserve compatibility with builds where MobileVLCKit is unavailable through the existing fallback backend behavior.
• Liquid Glass APIs should be gated with iOS availability checks and keep the current blur/material implementation as fallback.
• Multiple glass controls should be grouped with container effects where possible to avoid expensive standalone glass rendering.

Recommended Next Implementation Slice

Start with a low-risk visual and ergonomics pass:

1. Add iOS 26 Liquid Glass availability-gated styling for the main controls tray and interactive buttons, preserving the current blur fallback.
2. Increase button targets to at least 44×44 points and make play/pause 54–58 points.
3. Add a subtle bottom gradient scrim behind controls for contrast.
4. Extend auto-hide timing from 3 seconds to about 4.5 seconds and prevent hiding while scrubbing.
5. Add missing accessibility hints and scrubber accessibility value.

Defer until the second implementation slice:

• Scrubber target time bubble.
• Double-tap jump gestures.
• Center tap play/pause behavior.
• Glass-backed loading and failure cards with retry.
• iPad-specific wider layout.

Validation Targets for Future Changes

• Build the workspace with Xcode command-line tools.
• Test seekable and non-seekable streams.
• Test streams with one audio track, multiple audio tracks, no captions, embedded captions, and external captions.
• Verify controls remain usable in portrait and landscape.
• Verify VoiceOver labels, hints, and scrubber values.
• Verify older iOS fallback styling still works when Liquid Glass is unavailable.