lum_splash_video/readme.rst

============
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``:

.. code-block:: yaml

   dependencies:
     splash_video: ^0.0.1
     media_kit: ^1.2.6
     media_kit_video: ^2.0.1
     
     # Platform-specific video libraries
     media_kit_libs_android_video: any
     media_kit_libs_ios_video: any
     media_kit_libs_macos_video: any
     media_kit_libs_windows_video: any
     media_kit_libs_linux: any

Quick Start
===========

1. Initialize in main()
-----------------------

.. code-block:: dart

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

   void main() {
     WidgetsFlutterBinding.ensureInitialized();
     
     // Initialize SplashVideo (handles MediaKit and defers first frame)
     SplashVideo.initialize();
     
     runApp(MyApp());
   }

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

.. code-block:: 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:

.. code-block:: dart

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

Manual Control
--------------

Use a callback for custom logic after video completes:

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: dart

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

Custom Configuration
--------------------

.. code-block:: 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.

.. list-table::
   :header-rows: 1
   :widths: 20 25 10 45

   * - 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.

.. code-block:: 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.

.. code-block:: 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
------------

.. code-block:: 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
--------------

.. code-block:: dart

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

Lifecycle Methods
=================

.. code-block:: dart

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

   // Resume Flutter rendering
   SplashVideo.resume();

Platform Support
================

.. list-table::
   :header-rows: 1

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

License
=======

MIT License - see LICENSE file for details.