reels_video_player 1.0.0

A high-performance Flutter package for TikTok/Reels vertical video feeds with background pre-caching, session rotation, and 100% customizable UI.

reels_video_player

A high-performance, sound null-safe Flutter package for building vertical short-video feeds (TikTok and Instagram Reels style). Features dynamic sliding-window pre-caching via a local HTTP proxy, offline cold-start session persistence with randomized video rotation, 55 percent scroll visibility playback switching, press-and-hold 2X fast-forward speed, multi-tap rewind and fast-forward seeking, poster frame overlays, and a 100 percent customizable UI layer.

Features

• Local HTTP Cache Proxy: Routes video playback through a local localhost HTTP proxy (127.0.0.1) using http_cache_stream with custom browser User-Agent headers for seamless streaming and persistent disk caching.
• Customizable Sliding Window Memory Pool: Maintains an active memory window [current_index - preCacheBefore ... current_index + preCacheAfter]. Developers can set preCacheAfter to 5, 10, or any number to pre-cache upcoming video streams while automatically disposing off-screen video controllers.
• 55 Percent Viewport Visibility Switching: Tracks vertical scroll notifications in real-time, automatically pausing off-screen videos and activating playback only when the target reel reaches 55 percent or more of the screen viewport.
• 2X Speed Press and Hold Playback: Pressing and holding anywhere on the video screen instantly accelerates playback to 2.0X speed with a top animated badge display, automatically restoring 1.0X speed upon release.
• Multi-Tap Rewind and Fast-Forward Seeking: Double-tapping or multi-tapping on the left half rewinds 5s, 10s, 15s, or 20s with animated left ripple indicators. Double-tapping or multi-tapping on the right half fast-forwards 5s, 10s, 15s, or 20s with right ripple indicators. Single tap toggles play/pause.
• Interactive Bottom Progress Bar Scrubber: Includes ReelsProgressBar with bright played track, buffered track, draggable dot knob, 36px touch zone, real-time ValueListenableBuilder updates, and full progressBarBuilder customizability.
• Cold-Start Session Persistence and Rotation: Persists cached video metadata across app sessions. On cold startup, randomized stored videos provide immediate offline playback before appending live network feed items.
• Universal Format Resilience: Supports MP4, WebM, MKV, M3U8/HLS, MOV, and M4V native formats with automatic direct network URL fallback handling.
• 100 Percent UI Customizability: Decoupled playback state engine exposing 7 customizable builder callbacks (itemBuilder, overlayBuilder, controlsBuilder, thumbnailBuilder, loadingBuilder, errorBuilder, progressBarBuilder) alongside default out-of-the-box UI components.

---

Platform Configuration

Because the package uses a local HTTP proxy server running on 127.0.0.1 for caching and streaming, you must configure cleartext HTTP permissions for Android and iOS/macOS.

Android Setup

1. Create a file named network_security_config.xml in your Android project at android/app/src/main/res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">127.0.0.1</domain>
        <domain includeSubdomains="true">localhost</domain>
    </domain-config>
</network-security-config>

2. Reference this configuration in android/app/src/main/AndroidManifest.xml under the <application> tag:

<application
    android:name="${applicationName}"
    android:icon="@mipmap/ic_launcher"
    android:label="your_app_name"
    android:networkSecurityConfig="@xml/network_security_config">
</application>

iOS / macOS Setup

Add the NSAppTransportSecurity dictionary to your ios/Runner/Info.plist and macos/Runner/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

---

Installation

Add reels_video_player to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  reels_video_player: ^1.0.0

Then run:

flutter pub get

---

Usage

1. Initialization

Initialize ReelsCacheManager in your application's main() function prior to invoking runApp():

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await ReelsCacheManager.init();
  runApp(const MyApp());
}

2. Basic ReelsViewer Integration with Customizable Pre-Caching

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

class ReelsPage extends StatelessWidget {
  const ReelsPage({super.key});

  final List<ReelsVideoItem> videos = const [
    ReelsVideoItem(
      id: 'v1',
      videoUrl: 'https://flutter.github.io/assets-for-api-docs/assets/videos/bee.mp4',
      thumbnailUrl: 'https://images.unsplash.com/photo-1518709268805-4e9042af9f23?w=800',
    ),
    ReelsVideoItem(
      id: 'v2',
      videoUrl: 'https://flutter.github.io/assets-for-api-docs/assets/videos/butterfly.mp4',
      thumbnailUrl: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=800',
    ),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ReelsViewer(
        videos: videos,
        preCacheBefore: 1,
        preCacheAfter: 5,
        enableSessionRotation: true,
        maxPersistedSessionVideos: 10,
        onPageChanged: (index) {
          debugPrint('Page changed to $index');
        },
      ),
    );
  }
}

3. Custom Overlay and Progress Bar Builder Example

ReelsViewer(
  videos: videos,
  progressBarBuilder: (context, controller) {
    return ReelsProgressBar(
      controller: controller,
      playedColor: Colors.redAccent,
      bufferedColor: Colors.white38,
      backgroundColor: Colors.white12,
      barHeight: 4.0,
      allowScrubbing: true,
    );
  },
  overlayBuilder: (context, controller, item) {
    final metadata = item.metadata ?? {};
    return Positioned(
      left: 16,
      bottom: 40,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            metadata['author'] ?? '@user',
            style: const TextStyle(color: Colors.white, fontWeight: FontWeight.bold),
          ),
          const SizedBox(height: 8),
          Text(
            metadata['caption'] ?? '',
            style: const TextStyle(color: Colors.white70),
          ),
        ],
      ),
    );
  },
)

---

API Reference

ReelsViewer Parameters

Parameter	Type	Default	Description
videos	List<ReelsVideoItem>	Required	List of video items to display in the vertical feed.
preCacheBefore	int	1	Number of previous videos retained in active memory.
preCacheAfter	int	3	Number of upcoming videos pre-buffered in background streams.
enableSessionRotation	bool	true	Enables randomized cold-start offline video rotation.
maxPersistedSessionVideos	int	15	Maximum number of cached session videos retained on disk.
onPageChanged	ValueChanged<int>?	null	Callback fired when visible video page changes.
itemBuilder	Widget Function(...)	null	Custom video container surface builder.
overlayBuilder	Widget Function(...)	null	Custom social metrics and captions overlay builder.
controlsBuilder	Widget Function(...)	null	Custom play/pause controls overlay builder.
thumbnailBuilder	Widget Function(...)	null	Custom poster frame thumbnail widget builder.
loadingBuilder	Widget Function(...)	null	Custom loading indicator widget builder.
errorBuilder	Widget Function(...)	null	Custom error message display widget builder.
progressBarBuilder	Widget Function(...)	null	Custom timeline progress bar scrubber widget builder.

ReelsVideoItem Properties

Property	Type	Description
id	String	Unique identifier for the video item.
videoUrl	String	Remote stream URL or local file path for playback.
thumbnailUrl	String?	Optional poster frame image URL or local path.
localFilePath	String?	Optional local file path for saved offline videos.
metadata	Map<String, dynamic>?	Optional key-value pairs for metadata (author, likes, caption).

---

License

This project is licensed under the MIT License - see the LICENSE file for details.