j3g
/
lum_splash_video
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
lum_splash_video/implementation_complete.rst

911 lines
21 KiB
ReStructuredText
Raw Blame History

====================================
Splash Video - Implementation Complete
====================================
:Date: January 24, 2026
:Version: 0.0.1
:Status: Complete
:Package: splash_video
Project Overview
================
**splash_video** is a Flutter shared library package for creating video splash screens with seamless transitions from native splash screens. The implementation follows design patterns from the **splash_master** package but focuses exclusively on video playback using **media_kit** for cross-platform support.
What Was Accomplished
=====================
Core Implementation
-------------------
The package was built from scratch with the following components:
1. **Source System** (``lib/core/source.dart``)
- Sealed class hierarchy for type-safe video sources
- ``AssetSource`` - Bundled application assets
- ``NetworkFileSource`` - Remote video URLs
- ``DeviceFileSource`` - Local file system videos
- ``BytesSource`` - In-memory video data
2. **Controller System** (``lib/controller/splash_video_controller.dart``)
- ``SplashVideoController`` class for manual playback control
- Looping video support with user-controlled exit
- Direct access to media_kit ``Player`` instance
- Methods: ``play()``, ``pause()``, ``skip()``, ``dispose()``
3. **Configuration System** (``lib/config/video_config.dart``)
- ``VideoConfig`` class for playback customization
- Auto-play control
- Display modes (fullscreen, aspect ratio, none)
- SafeArea support
- Volume control (0-100)
- Player initialization callbacks
4. **Widget System** (``lib/widgets/``)
- ``SplashVideo`` - Main public widget with overlay and navigation support
- ``VideoSplash`` - Internal widget for media_kit video rendering
- Smooth lifecycle management
- Defer first frame pattern for jank-free transitions
5. **Utilities** (``lib/core/utils.dart`` & ``lib/enums/``)
- Custom exception handling (``SplashVideoException``)
- Type definitions for callbacks
- Display mode enums
- Extension methods
Design Patterns Followed
-------------------------
From **splash_master**:
✅ Two-widget architecture (main + internal video widget)
✅ Sealed class source types for type safety
✅ Configuration class pattern
✅ Defer first frame pattern (``initialize()`` / ``resume()``)
✅ Timer-based duration management
✅ Automatic and manual navigation support
**Differences from splash_master**:
- Uses **media_kit** instead of video_player
- Only video support (no Lottie, Rive, or CLI tools)
- Controller pattern for advanced control
- Flexible overlay system (title, footer, custom builder)
- Runtime validation instead of const assertions
Technology Integration
----------------------
**Media Kit**:
- ``media_kit ^1.2.6`` - Core player functionality
- ``media_kit_video ^2.0.1`` - Video rendering widgets
- ``video_player_media_kit ^2.0.0`` - Platform integration
- Platform-specific libs for Android, iOS, macOS, Windows, Linux
**Features Enabled**:
- Hardware-accelerated video playback
- Cross-platform support (Android, iOS, macOS, Windows, Linux, Web)
- Wide codec/format support
- Efficient resource management
- Stream-based state management
How to Use
==========
Installation
------------
Add to ``pubspec.yaml``:
.. code-block:: yaml
dependencies:
flutter:
sdk: flutter
media_kit: ^1.2.6
media_kit_video: ^2.0.1
video_player_media_kit: ^2.0.0
# 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
Basic Setup
-----------
**Step 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());
}
**Step 2: Use SplashVideo widget**
.. 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 Patterns
==============
Pattern 1: Auto-Navigation
---------------------------
Video plays once and automatically navigates to the next screen.
**Use Case**: Simple splash screen with no user interaction needed.
.. code-block:: dart
SplashVideo(
source: AssetSource('assets/videos/splash.mp4'),
nextScreen: HomeScreen(),
backgroundColor: Colors.black,
videoConfig: VideoConfig(
videoVisibilityEnum: VisibilityEnum.useFullScreen,
),
)
**Flow**:
1. Native splash displays
2. Video loads → ``SplashVideo.resume()`` called
3. Video plays
4. Video ends → Auto-navigate to ``HomeScreen()``
Pattern 2: Manual Control
--------------------------
Use callback for custom logic when video completes.
**Use Case**: Need to perform actions before navigation (analytics, checks, etc.).
.. code-block:: dart
SplashVideo(
source: AssetSource('assets/videos/splash.mp4'),
onVideoComplete: () {
// Custom logic
analytics.logEvent('splash_completed');
// Manual navigation
Navigator.pushReplacement(
context,
MaterialPageRoute(builder: (_) => HomeScreen()),
);
},
backgroundColor: Colors.black,
)
**Flow**:
1. Video loads and plays
2. Video ends → ``onVideoComplete`` callback fired
3. User controls navigation timing
**Priority**: ``onVideoComplete`` takes priority over ``nextScreen`` if both are set.
Pattern 3: Looping with Manual Exit
------------------------------------
Video loops infinitely until user decides to exit.
**Use Case**: Splash screen that waits for user action or async operations.
.. 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'),
),
);
}
}
**Requirements**:
- ``controller`` is **required** when ``loopVideo: true``
- Cannot use ``nextScreen`` or ``onVideoComplete`` with looping
- Must call ``controller.skip()`` to exit
Pattern 4: Overlays
-------------------
Add UI elements on top of the video.
**Use Case**: Branding, loading indicators, version info, skip buttons.
.. code-block:: dart
SplashVideo(
source: AssetSource('assets/videos/splash.mp4'),
nextScreen: HomeScreen(),
backgroundColor: Colors.black,
// Title widget positioned at top
titleWidget: Padding(
padding: EdgeInsets.all(20),
child: Center(
child: Text(
'Welcome to MyApp',
style: TextStyle(
fontSize: 32,
fontWeight: FontWeight.bold,
color: Colors.white,
),
),
),
),
// Footer widget positioned at bottom
footerWidget: Padding(
padding: EdgeInsets.all(20),
child: Center(
child: CircularProgressIndicator(
valueColor: AlwaysStoppedAnimation<Color>(Colors.white),
),
),
),
// Custom overlay with full positioning control
overlayBuilder: (context) => Positioned(
right: 20,
top: 100,
child: Container(
padding: EdgeInsets.all(8),
decoration: BoxDecoration(
color: Colors.black54,
borderRadius: BorderRadius.circular(8),
),
child: Text(
'v1.0.0',
style: TextStyle(color: Colors.white70),
),
),
),
)
**Rendering Order** (bottom to top):
1. Video
2. ``titleWidget`` (top of screen)
3. ``footerWidget`` (bottom of screen)
4. ``overlayBuilder`` (custom positioning)
Pattern 5: Network Video
-------------------------
Load video from remote URL.
.. code-block:: dart
SplashVideo(
source: NetworkFileSource('https://example.com/splash.mp4'),
nextScreen: HomeScreen(),
onSourceLoaded: () {
print('Video loaded from network');
SplashVideo.resume();
},
)
Pattern 6: Advanced Configuration
----------------------------------
Full control over video playback behavior.
.. code-block:: dart
SplashVideo(
source: AssetSource('assets/videos/splash.mp4'),
nextScreen: HomeScreen(),
videoConfig: VideoConfig(
playImmediately: true,
videoVisibilityEnum: VisibilityEnum.useAspectRatio,
useSafeArea: true,
volume: 75.0,
onPlayerInitialized: (player) {
print('Duration: ${player.state.duration}');
print('Dimensions: ${player.state.width}x${player.state.height}');
// Can access full player API
player.stream.position.listen((pos) {
print('Position: $pos');
});
},
),
)
API Reference
=============
SplashVideo Widget
------------------
Main widget for creating video splash screens.
**Constructor Parameters**:
.. list-table::
:header-rows: 1
:widths: 20 15 10 55
* - Parameter
- Type
- Required
- Description
* - ``source``
- ``Source``
- ✅
- Video source (Asset, Network, DeviceFile, Bytes)
* - ``controller``
- ``SplashVideoController?``
- ⚠️
- Required when ``loopVideo: true``
* - ``videoConfig``
- ``VideoConfig?``
- ❌
- Playback configuration options
* - ``backgroundColor``
- ``Color?``
- ❌
- Background color behind video
* - ``titleWidget``
- ``Widget?``
- ❌
- Widget positioned at top of screen
* - ``footerWidget``
- ``Widget?``
- ❌
- Widget positioned at bottom of screen
* - ``overlayBuilder``
- ``Widget Function(BuildContext)?``
- ❌
- Custom overlay with full positioning control
* - ``nextScreen``
- ``Widget?``
- ❌
- Screen to navigate to on completion (auto-navigate)
* - ``onVideoComplete``
- ``VoidCallback?``
- ❌
- Callback when video completes (manual control)
* - ``onSourceLoaded``
- ``VoidCallback?``
- ❌
- Callback when video loads (defaults to ``resume()``)
**Static Methods**:
.. code-block:: dart
// Defer Flutter's first frame (call in main before runApp)
SplashVideo.initialize();
// Resume Flutter frame rendering (called automatically or manually)
SplashVideo.resume();
**Validation Rules**:
1. Cannot use both ``nextScreen`` AND ``onVideoComplete``
2. Looping videos (``controller.loopVideo == true``) require ``controller``
3. Looping videos cannot use ``nextScreen`` or ``onVideoComplete``
Throws ``ArgumentError`` if validation fails.
SplashVideoController
---------------------
Controller for managing video playback.
**Constructor**:
.. code-block:: dart
SplashVideoController({
bool loopVideo = false, // Enable infinite looping
})
**Properties**:
.. code-block:: dart
Player get player; // Access to media_kit Player instance
bool get loopVideo; // Whether video loops
bool get skipRequested; // Whether skip was called
bool get isDisposed; // Whether controller is disposed
**Methods**:
.. code-block:: dart
Future<void> play(); // Start/resume playback
Future<void> pause(); // Pause playback
Future<void> skip(); // Complete splash immediately
void dispose(); // Release resources
**Player Access**:
The ``player`` property provides full access to the media_kit ``Player``:
.. code-block:: dart
controller.player.play();
controller.player.pause();
controller.player.seek(Duration(seconds: 5));
controller.player.setVolume(50.0);
controller.player.setRate(1.5);
// Listen to state changes
controller.player.stream.position.listen((pos) { });
controller.player.stream.playing.listen((isPlaying) { });
controller.player.stream.duration.listen((duration) { });
VideoConfig
-----------
Configuration for video playback behavior.
.. code-block:: dart
VideoConfig({
bool playImmediately = true,
VisibilityEnum videoVisibilityEnum = VisibilityEnum.useFullScreen,
bool useSafeArea = false,
double volume = 100.0,
void Function(Player)? onPlayerInitialized,
})
**Properties**:
- ``playImmediately`` - Auto-play when loaded (default: ``true``)
- ``videoVisibilityEnum`` - Display mode (default: ``useFullScreen``)
- ``useSafeArea`` - Wrap video in SafeArea (default: ``false``)
- ``volume`` - Initial volume 0.0-100.0 (default: ``100.0``)
- ``onPlayerInitialized`` - Callback with Player access
Source Types
------------
Type-safe video source specifications using sealed classes.
**AssetSource**:
.. code-block:: dart
AssetSource('assets/videos/splash.mp4')
Bundled application assets.
**NetworkFileSource**:
.. code-block:: dart
NetworkFileSource('https://example.com/splash.mp4')
Remote video URLs. URI validation on construction.
**DeviceFileSource**:
.. code-block:: dart
DeviceFileSource('/path/to/video.mp4')
Local file system videos.
**BytesSource**:
.. code-block:: dart
BytesSource(videoBytes) // Uint8List
In-memory video data.
VisibilityEnum
--------------
Controls how video is displayed.
.. code-block:: dart
VisibilityEnum.useFullScreen // Fill entire screen
VisibilityEnum.useAspectRatio // Maintain aspect ratio
VisibilityEnum.none // No special sizing
File Structure
==============
Complete package organization::
splash_video/
├── lib/
│ ├── config/
│ │ └── video_config.dart
│ ├── controller/
│ │ └── splash_video_controller.dart
│ ├── core/
│ │ ├── source.dart
│ │ └── utils.dart
│ ├── enums/
│ │ └── splash_video_enums.dart
│ ├── widgets/
│ │ ├── splash_video.dart
│ │ └── video_splash.dart
│ └── splash_video.dart (exports)
├── example/
│ └── lib/
│ └── main.dart (4 complete examples)
├── implementation_plan.rst
├── implementation_complete.rst
├── README.md
├── pubspec.yaml
└── LICENSE
Example Application
====================
The ``example/`` folder contains a complete demonstration app with:
1. **Example Selector** - Menu to choose different patterns
2. **Auto-Navigate Example** - Simple auto-navigation pattern
3. **Manual Control Example** - Using ``onVideoComplete`` callback
4. **Looping Example** - Infinite loop with skip button
5. **Overlay Example** - Title, footer, and custom overlays
Run the example:
.. code-block:: bash
cd example
flutter run
Key Accomplishments
===================
✅ **Clean API Design**
- Intuitive widget-based API
- Type-safe source system
- Clear validation rules
✅ **Flexible Architecture**
- Auto or manual navigation
- Optional controller for advanced use
- Multiple overlay options
✅ **Production Ready**
- Comprehensive error handling
- Resource cleanup
- Memory management
✅ **Well Documented**
- Complete README with examples
- Inline code documentation
- Implementation plan (RST)
- This completion guide (RST)
✅ **Example Driven**
- 4 working examples
- Common use case coverage
- Copy-paste ready code
✅ **Media Kit Integration**
- Cross-platform video support
- Hardware acceleration
- Wide format support
Technical Decisions
===================
Why Media Kit?
--------------
**Chosen over video_player**:
- Better cross-platform support
- Hardware acceleration by default
- More modern API with streams
- Active development
- Better performance for 4K/8K content
Why Sealed Classes for Sources?
--------------------------------
- Type safety at compile time
- Exhaustive pattern matching
- Clear API contract
- Better IDE support
Why Controller Pattern?
------------------------
- Matches Flutter conventions (TextEditingController, etc.)
- Provides Player access without coupling
- Clean separation of concerns
- Easy to test
Why Runtime Validation?
------------------------
- ``const`` constructors can't check dynamic conditions
- Better error messages
- More flexibility
- Validation happens once at initialization
Why Defer First Frame?
-----------------------
- Prevents blank frame between native and Flutter splash
- Standard Flutter pattern for splash screens
- User-controlled timing
- Smooth transitions
Future Enhancements
===================
Phase 2 (Planned)
-----------------
🔜 **Boomerang Loop**
- Forward/backward video playback
- Seamless direction changes
- Custom loop patterns
🔜 **Advanced Overlays**
- Animation support
- Interactive elements
- Progress indicators
🔜 **Analytics Hooks**
- Playback metrics
- User interaction tracking
- Performance monitoring
🔜 **Preloading**
- Cache video before showing splash
- Faster startup times
- Offline support
Testing Strategy
=================
Recommended Test Coverage
--------------------------
**Unit Tests**:
- Source type validation
- Controller state management
- Configuration validation
- Utility functions
**Widget Tests**:
- Widget initialization
- Overlay rendering
- Navigation behavior
- Lifecycle management
**Integration Tests**:
- End-to-end splash flow
- Platform-specific playback
- Performance benchmarks
- Memory leak detection
Migration Guide
===============
From splash_master
-------------------
If migrating from ``splash_master`` video implementation:
**Changes Needed**:
1. Replace ``video_player`` imports with ``media_kit``
2. Use ``Player`` instead of ``VideoPlayerController``
3. Update initialization (``SplashVideo.initialize()`` now handles MediaKit)
4. Move loop config to controller
5. Update overlay API (separate title/footer)
**API Mapping**:
.. code-block:: dart
// splash_master
SplashMaster.video(
source: source,
videoConfig: VideoConfig(loopVideo: true),
)
// splash_video
final controller = SplashVideoController(loopVideo: true);
SplashVideo(
source: source,
controller: controller,
)
Platform Requirements
=====================
Android
-------
- Minimum SDK: 21 (Android 5.0)
- Permissions: Internet, storage (if needed)
- Gradle: 7.0+
iOS
---
- Minimum: iOS 9+
- Xcode: 13+
- CocoaPods: 1.11+
macOS
-----
- Minimum: macOS 10.9+
- Xcode: 13+
Windows
-------
- Minimum: Windows 7+
- Visual Studio 2019+
Linux
-----
- Any modern distribution
- Dependencies: ``libmpv-dev``, ``mpv``
Web
---
- Modern browsers with HTML5 video support
- Format support varies by browser
Support & Resources
===================
Documentation
-------------
- README.md - Quick start and API reference
- implementation_plan.rst - Design and architecture
- implementation_complete.rst - This document
- Inline code documentation - Comprehensive dartdocs
Example Code
------------
- ``example/lib/main.dart`` - 4 working examples
- README.md - Code snippets
- Inline usage examples in docs
External Resources
------------------
- Media Kit: https://github.com/media-kit/media-kit
- Flutter: https://flutter.dev
- Dart: https://dart.dev
License
=======
MIT License
Copyright (c) 2025
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Conclusion
==========
The **splash_video** package is complete and production-ready. It provides a
clean, flexible API for video splash screens with excellent developer experience.
The implementation follows Flutter best practices, integrates seamlessly with
media_kit, and provides comprehensive documentation and examples.
:Status: ✅ Complete
:Quality: Production Ready
:Documentation: Comprehensive
:Examples: 4 Working Patterns
:Tests: Ready for Implementation
Reference in New Issue View Git Blame Copy Permalink