lum_splash_video/README.md

# splash_video

A Flutter package for creating smooth video splash screens using media_kit. Provides seamless transitions from native splash screens to video playback with flexible overlay support and manual controls.

## Features

- ✨ **Smooth Transitions** - Defer first frame pattern prevents jank between native and video splash
- 🎬 **Media Kit Integration** - Cross-platform video playback with hardware acceleration
- 🎮 **Manual Controls** - Full controller access for play, pause, skip operations
- 🔄 **Looping Support** - Infinite video loops with user-controlled exit
- 📱 **Flexible Overlays** - Title, footer, and custom overlay widgets
- 🎯 **Auto-Navigation** - Automatic screen transitions or manual control
- 🎨 **Customizable** - Aspect ratio, fullscreen, volume, and more

## Installation

Add to your `pubspec.yaml`:

```yaml
dependencies:
  splash_video: ^0.0.2

## Quick Start

### 1. Initialize in main()

```dart
import 'package:flutter/material.dart';
import 'package:media_kit/media_kit.dart';
import 'package:splash_video/splash_video.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Required: Initialize media_kit
  SplashVideo.initialize();
  
  runApp(MyApp());
}
```

### 2. Basic Usage (Auto-Navigate)

```dart
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: SplashVideo(
        source: AssetSource('assets/videos/splash.mp4'),
        nextScreen: HomeScreen(),
        backgroundColor: Colors.black,
      ),
    );
  }
}
```

## Usage Examples

### Auto-Navigation

Video plays and automatically navigates to the next screen:

```dart
SplashVideo(
  source: AssetSource('assets/videos/splash.mp4'),
  nextScreen: HomeScreen(),
  backgroundColor: Colors.black,
)
```

### Manual Control

Use a callback for custom logic after video completes:

```dart
SplashVideo(
  source: AssetSource('assets/videos/splash.mp4'),
  onVideoComplete: () {
    // Custom logic
    Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (_) => HomeScreen()),
    );
  },
)
```

### Looping Video with Controller

Create an infinite loop that the user can manually exit:

```dart
class MyScreen extends StatefulWidget {
  @override
  State<MyScreen> createState() => _MyScreenState();
}

class _MyScreenState extends State<MyScreen> {
  late final SplashVideoController controller;

  @override
  void initState() {
    super.initState();
    controller = SplashVideoController(loopVideo: true);
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  void _onSkip() {
    controller.skip();
    Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (_) => HomeScreen()),
    );
  }

  @override
  Widget build(BuildContext context) {
    return SplashVideo(
      source: AssetSource('assets/videos/splash.mp4'),
      controller: controller,
      footerWidget: ElevatedButton(
        onPressed: _onSkip,
        child: Text('Skip'),
      ),
    );
  }
}
```

### With Overlays

Add title, footer, and custom overlays:

```dart
SplashVideo(
  source: AssetSource('assets/videos/splash.mp4'),
  nextScreen: HomeScreen(),
  backgroundColor: Colors.black,
  
  // Title at top
  titleWidget: Padding(
    padding: EdgeInsets.all(20),
    child: Text(
      'Welcome',
      style: TextStyle(fontSize: 32, color: Colors.white),
    ),
  ),
  
  // Footer at bottom
  footerWidget: CircularProgressIndicator(),
  
  // Custom overlay with full control
  overlayBuilder: (context) => Positioned(
    right: 20,
    top: 100,
    child: Text('v1.0.0', style: TextStyle(color: Colors.white)),
  ),
)
```

### Network Video

Load video from URL:

```dart
SplashVideo(
  source: NetworkFileSource('https://example.com/splash.mp4'),
  nextScreen: HomeScreen(),
)
```

### Custom Configuration

```dart
SplashVideo(
  source: AssetSource('assets/videos/splash.mp4'),
  nextScreen: HomeScreen(),
  videoConfig: VideoConfig(
    playImmediately: true,
    videoVisibilityEnum: VisibilityEnum.useAspectRatio,
    useSafeArea: true,
    volume: 50.0,
    onPlayerInitialized: (player) {
      print('Player ready: ${player.state.duration}');
    },
  ),
)
```

## API Reference

### SplashVideo

Main widget for video splash screen.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | `Source` | ✅ | Video source (Asset, Network, DeviceFile, Bytes) |
| `controller` | `SplashVideoController?` | ⚠️ | Required when looping is enabled |
| `videoConfig` | `VideoConfig?` | ❌ | Playback configuration |
| `backgroundColor` | `Color?` | ❌ | Background color behind video |
| `titleWidget` | `Widget?` | ❌ | Widget at top of screen |
| `footerWidget` | `Widget?` | ❌ | Widget at bottom of screen |
| `overlayBuilder` | `Widget Function(BuildContext)?` | ❌ | Custom overlay builder |
| `nextScreen` | `Widget?` | ❌ | Screen to navigate to (auto-navigate) |
| `onVideoComplete` | `VoidCallback?` | ❌ | Callback when video completes (manual control) |
| `onSourceLoaded` | `VoidCallback?` | ❌ | Callback when video loads |

**Validation Rules:**
- Cannot use both `nextScreen` and `onVideoComplete`
- Looping videos require `controller` and cannot use `nextScreen` or `onVideoComplete`

### SplashVideoController

Controls video playback.

```dart
final controller = SplashVideoController(loopVideo: true);

// Access media_kit Player
controller.player.play();
controller.player.pause();
controller.player.seek(Duration(seconds: 5));

// Controller methods
controller.play();
controller.pause();
controller.skip(); // Complete immediately
controller.dispose();
```

### VideoConfig

Configuration for video playback.

```dart
VideoConfig(
  playImmediately: true,                           // Auto-play on load
  videoVisibilityEnum: VisibilityEnum.useFullScreen, // Display mode
  useSafeArea: false,                              // Wrap in SafeArea
  volume: 100.0,                                   // Volume (0-100)
  onPlayerInitialized: (player) { },              // Player callback
)
```

### Source Types

```dart
// Asset bundled with app
AssetSource('assets/videos/splash.mp4')

// Network URL
NetworkFileSource('https://example.com/video.mp4')

// Device file
DeviceFileSource('/path/to/video.mp4')

// Raw bytes
BytesSource(videoBytes)
```

### VisibilityEnum

```dart
VisibilityEnum.useFullScreen   // Fill entire screen
VisibilityEnum.useAspectRatio  // Maintain aspect ratio
VisibilityEnum.none            // No special sizing
```

## Lifecycle Methods

```dart
// Defer first frame (prevents jank)
SplashVideo.initialize();

// Resume Flutter rendering
SplashVideo.resume();
```

## Platform Support

| Platform | Supported |
|----------|-----------|
| Android | ✅ |
| iOS | ✅ |
| macOS | ✅ |
| Windows | ✅ |
| Linux | ✅ |
| Web | ✅ |

## License

MIT License - see LICENSE file for details.