jar_video_player

A modern, reels-ready, customizable network video player for Flutter.

jar_video_player is built for real-world performance. It provides automatic lifecycle handling, route awareness, visibility-based playback control, and optimized support for vertical reel-style feeds like Instagram or TikTok.

https://github.com/user-attachments/assets/f1f8e44a-3425-4870-aa0e-35beab325ad8

✨ Features

🎥 Network video playback
🔁 Reels mode (auto play/pause based on visibility)
🔄 Route-aware auto pause
📱 App lifecycle handling (background/foreground safety)
🎛 External controller support
⚡ Optimized for PageView reels
🧠 Safe async initialization (prevents ghost audio issues)
🧹 Proper resource disposal to prevent memory leaks

📦 Installation

Add the dependency to your pubspec.yaml:

dependencies:
  jar_video_player: ^0.1.5

Then run:

flutter pub get

🚀 Some important permissions



<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>


<!-- Internet (required for downloading video) -->
<uses-permission android:name="android.permission.INTERNET"/>

<!-- Android 13+ (API 33+) -->
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>

<!-- Android 12 and below -->
<uses-permission
    android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

🚀 Overlay Jar Video Player

import 'package:flutter/material.dart';
import 'package:jar_video_player/jar_video_player.dart';

final controller = JarVideoPlayerController();



///
// this must be true 
// for downloading and sharing the video with or without overlay 
// downloadWithOverlay: true,
///
JarVideoPlayerOverlay(
        url: videoUrl,
        aspectRatio: 9 / 16,
        reelsMode: true,

        ///top overlay widget
        // topStripe: Container(
        //   color: Colors.green,
        //   width: double.infinity,
        //   height: 50,
        //   child: Text("Hello leaders", style: TextStyle(fontSize: 37)),
        // ),

        /// this is bottom overlay
        downloadWithOverlay: true,
        bottomStripe: Container(
          color: Colors.red,
          width: double.infinity,
          height: 70,
          child: Text("Hello Sagar"),
        ),


        /// if you want custom downlaod or share functions
        // onDownload: () {},
        // onShare: () {},

        ///if you want reel mode, controller is not necessary
        // controller: ctrl,

      ),
    );

///types of Overlay Animations
enum OverlayAnimationType {
  none, /// defauls to 'top left' 

  // Basic
  topToCenter,
  rightToCenter,
  leftToCenter,
  bottomToCenter,
  leftToRight,
  rightToLeft,

  // Diagonal
  diagonalTopLeftToBottomRight,
  diagonalTopRightToBottomLeft,
  diagonalBottomLeftToTopRight,
  diagonalBottomRightToTopLeft,
}

🎬 Reels Mode

Reels mode automatically plays the video when it becomes visible and pauses it when it goes out of view.

JarVideoPlayer(
  controller: controller,
  url: videoUrl,
  reelsMode: true,
);

Recommended Usage with PageView

PageView.builder(
  scrollDirection: Axis.vertical,
  itemCount: videoList.length,
  itemBuilder: (context, index) {
    final controller = JarVideoPlayerController();

    return JarVideoPlayer(
      controller: controller,
      url: videoList[index],
      reelsMode: true,
    );
  },
);

🎛 Controller API

You can control playback manually using the controller:

controller.play();
controller.pause();
controller.seekTo(Duration(seconds: 10));
controller.dispose();

🔄 Lifecycle & Route Handling

jar_video_player automatically:

Pauses when navigating to a new route
Pauses when app goes to background
Resumes safely when returning
Prevents audio leaks during fast scroll

🧩 Best Practices

Dispose controllers properly when no longer needed.
Use reelsMode: true inside PageView for best performance.
Avoid initializing multiple heavy videos simultaneously on low-end devices.

📚 Example

A complete working example is available inside the example/ folder of this package.

🛠 Requirements

Flutter 3.10+
Dart >=3.0.0 <4.0.0

📝 License

MIT License

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 the Software.