nextav/docs/active/media-streaming-root/PLAYER_AUTO_LAUNCH_FEATURE.md

External Video Player Auto-Launch Feature Implementation

Overview

Successfully implemented a seamless auto-launch system for external video players, allowing users to configure preferences once and automatically launch videos without manual selection each time.

Features Implemented

1. Player Preferences Management (/src/lib/player-preferences.ts)

• localStorage-based storage for user preferences
• Cross-component state management with custom events
• Default configurations with safe fallbacks
• Platform-specific player detection

Key preferences:

• preferredPlayer: User's chosen video player (null = manual selection)
• autoLaunch: Enable/disable automatic launching
• confirmBeforeLaunch: Show confirmation dialog before auto-launch
• rememberChoice: Offer to remember manual selections

2. Enhanced LocalPlayerLauncher (/src/components/local-player-launcher.tsx)

• Auto-launch detection on component mount
• Confirmation dialogs for auto-launch (when enabled)
• Smart preference learning from manual selections
• Fallback to manual selection when no preferences set

New workflow:

1. Component loads → Check user preferences
2. If auto-launch enabled → Show confirmation or launch directly
3. If manual selection → Show traditional player selection
4. After manual selection → Offer to remember choice

3. Settings Page Integration (/src/app/settings/page.tsx)

• Dedicated Video Player section with modern toggle switches
• Real-time preference updates with immediate feedback
• Platform-aware player list showing only compatible players
• Current configuration display for transparency
• Reset to defaults functionality

Settings UI includes:

• Auto Launch toggle
• Preferred Player selection (with manual option)
• Confirmation toggle
• Remember Choice toggle
• Current status display

User Experience Flow

First Time Use

1. User clicks on .ts (or other external format) video
2. LocalPlayerLauncher shows traditional selection dialog
3. User selects preferred player (e.g., VLC)
4. System asks: "Remember VLC as preferred player?"
5. If yes, asks: "Auto-launch videos with VLC in future?"
6. Preferences saved for subsequent videos

Subsequent Uses (Auto-Launch Enabled)

1. User clicks on external format video
2. System shows: "Launch VLC?" confirmation dialog
3. User clicks "Launch VLC" → Video opens immediately
4. OR clicks "Choose Manually" → Shows full selection dialog

Subsequent Uses (Auto-Launch Disabled)

1. User clicks on external format video
2. System immediately launches preferred player
3. No confirmation needed

Technical Implementation

Storage Architecture

interface PlayerPreferences {
  preferredPlayer: string | null;    // Player ID or null for manual
  autoLaunch: boolean;              // Enable auto-launch
  confirmBeforeLaunch: boolean;     // Show confirmation dialog
  rememberChoice: boolean;          // Offer to remember selections
}

Auto-Launch Logic

const autoLaunchCheck = shouldAutoLaunch();
if (autoLaunchCheck.autoLaunch && autoLaunchCheck.playerId) {
  if (autoLaunchCheck.needsConfirmation) {
    setShowingAutoLaunchConfirm(true);
  } else {
    handlePlayerLaunch(autoLaunchCheck.playerId, true);
  }
}

Settings Integration

• Real-time preference updates using localStorage
• Custom event system for cross-component synchronization
• Platform detection for showing relevant players only
• Visual feedback with toggle switches and status display

Benefits

User Experience

• ✅ One-time setup → Seamless future use
• ✅ Configurable experience → Users choose their level of automation
• ✅ Smart defaults → Safe, non-intrusive initial behavior
• ✅ Clear settings → Easy to modify preferences later

Technical

• ✅ Lightweight implementation → localStorage-based, no server calls
• ✅ Cross-platform compatibility → Detects available players per OS
• ✅ Backwards compatible → Manual selection still available
• ✅ Event-driven updates → Real-time preference synchronization

Configuration Options

Users can now configure:

1. Auto Launch: Toggle automatic video launching
2. Preferred Player: Choose default player or manual selection
3. Confirmation: Require confirmation before auto-launch
4. Learning: Allow system to learn from manual choices

Files Modified

1. Created: /src/lib/player-preferences.ts - Preference management system
2. Enhanced: /src/components/local-player-launcher.tsx - Auto-launch support
3. Enhanced: /src/app/settings/page.tsx - Settings UI integration

Future Enhancements

Potential improvements:

• Player installation detection - Verify players are actually installed
• Custom player paths - Allow users to specify player locations
• Per-format preferences - Different players for different video formats
• Keyboard shortcuts - Quick launch hotkeys

The implementation provides a perfect balance between automation and user control, making the external video player experience as seamless as possible while maintaining flexibility for different user preferences.