lum_splash_video/docs/troubleshooting.rst

=======================
Troubleshooting Guide
=======================

Black Screen Issues
===================

If you're seeing a black screen with no errors:

1. Run the Diagnostic Tool
---------------------------

.. code-block:: bash

   cd example
   flutter run -t lib/diagnostic_main.dart

This will test MediaKit installation and show detailed logging in the console.

2. Check Console Output
------------------------

Look for these messages in your console/terminal:

✅ **Good signs:**

.. code-block:: text

   ✓ SplashVideo: MediaKit initialized and first frame deferred
   SplashVideoPlayer: Starting initialization...
     ✓ Player created
     ✓ VideoController created
     ✓ Media created, opening...
     ✓ Media opened
     ✓ Video initialized with duration: 0:00:05.000000
     ▶ Starting playback

❌ **Problem signs:**

.. code-block:: text

   ✗ MediaKit test failed: ...
   ✗ Player error: ...
   ✗ Initialization failed: ...

3. Verify Dependencies
-----------------------

Make sure your ``pubspec.yaml`` includes the platform-specific libraries:

.. code-block:: yaml

   dependencies:
     media_kit: ^1.2.6
     media_kit_video: ^2.0.1
     
     # Platform-specific video libraries (add all platforms you support)
     media_kit_libs_android_video: any      # Android
     media_kit_libs_ios_video: any          # iOS  
     media_kit_libs_macos_video: any        # macOS
     media_kit_libs_windows_video: any      # Windows
     media_kit_libs_linux: any              # Linux

4. Verify Asset Configuration
------------------------------

In ``pubspec.yaml``:

.. code-block:: yaml

   flutter:
     assets:
       - assets/videos/     # or your video folder

Verify the video file exists at the path you're using:

.. code-block:: dart

   AssetSource('assets/videos/splash.mp4')  // Must match actual file path

5. Check MediaKit Initialization
---------------------------------

In your ``main.dart``:

.. code-block:: dart

   void main() {
     WidgetsFlutterBinding.ensureInitialized();
     SplashVideoPage.initialize();  // This handles MediaKit initialization
     runApp(const MyApp());
   }

6. Test MediaKit Programmatically
----------------------------------

.. code-block:: dart

   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
     
     // Test MediaKit before running app
     final isWorking = await SplashVideoPage.testMediaKit();
     if (!isWorking) {
       debugPrint('MediaKit is not working!');
       // Handle error...
     }
     
     SplashVideoPage.initialize();
     runApp(const MyApp());
   }

7. Clean and Rebuild
---------------------

.. code-block:: bash

   flutter clean
   flutter pub get
   flutter run

8. Platform-Specific Issues
----------------------------

Android
^^^^^^^

- Minimum SDK version must be 21+
- Check ``android/app/build.gradle``:

.. code-block:: gradle

   minSdkVersion 21

iOS
^^^

- Minimum iOS version must be 13.0+
- Check ``ios/Podfile``:

.. code-block:: ruby

   platform :ios, '13.0'

macOS
^^^^^

- Minimum macOS version must be 10.15+
- Check ``macos/Podfile``:

.. code-block:: ruby

   platform :osx, '10.15'

Windows
^^^^^^^

- Visual Studio 2022 or later required
- Windows 10 1809+ required

Linux
^^^^^

- GStreamer and related libraries required
- Install:

.. code-block:: bash

   sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

9. Video Format Issues
----------------------

MediaKit supports most video formats, but for best compatibility use:

- **Container:** MP4
- **Video codec:** H.264
- **Audio codec:** AAC

Test with a known working video:

.. code-block:: bash

   # Download a test video
   curl -o assets/test.mp4 https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4

10. Enable Error Callbacks
---------------------------

Always implement error handling during development:

.. code-block:: dart

   SplashVideoPage(
     source: AssetSource('assets/videos/splash.mp4'),
     onVideoError: (error) {
       debugPrint('Video Error: $error');
       // Show error to user or navigate away
     },
     nextScreen: const HomeScreen(),
   )

11. Check Player State
----------------------

Add a callback to monitor player initialization:

.. code-block:: dart

   SplashVideoPage(
     source: AssetSource('assets/videos/splash.mp4'),
     videoConfig: VideoConfig(
       onPlayerInitialized: (player) {
         debugPrint('Player initialized!');
         debugPrint('Can play: ${player.state.playing}');
         debugPrint('Duration: ${player.state.duration}');
       },
     ),
     nextScreen: const HomeScreen(),
   )

Getting Help
============

If you're still experiencing issues:

1. **Run the diagnostic tool** and share the console output
2. **Check the example app** - does it work?
3. **Share your setup:**

   - Flutter version (``flutter --version``)
   - Platform (Android/iOS/macOS/Windows/Linux)
   - Video file details (format, size, location)
   - Your ``pubspec.yaml`` dependencies
   - Console error messages

4. **Open an issue** with all the above information

Common Error Messages
=====================

"Failed to initialize video"
-----------------------------

- MediaKit not initialized - make sure you call ``SplashVideoPage.initialize()``
- Missing platform libraries - check dependencies

"URL can't be null when playing a remote video"
------------------------------------------------

- Invalid NetworkFileSource URL
- Check URL format and network connectivity

"Unable to parse URI"
---------------------

- Malformed URL in NetworkFileSource
- Verify URL is valid

Player stays black but no errors
---------------------------------

- Video codec not supported - try H.264/MP4
- Asset path incorrect - verify in pubspec.yaml and file system
- Platform library missing - check all media_kit_libs_* dependencies
- Run diagnostic tool for detailed information