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

Libraries

reels_video_player
A high-performance Flutter package for TikTok/Reels vertical video feeds with background pre-caching, cold-start session rotation, format resilience, poster thumbnails, and 100% customizable UI.