Flutter Awesome Reels #

A powerful and feature-rich Flutter package for creating Instagram/TikTok-like video reels with advanced streaming support including HLS, DASH, and MP4 formats.

Features #

🎥 Video Streaming Support #

• HLS (HTTP Live Streaming) - Adaptive bitrate streaming with excellent iOS support
• DASH (Dynamic Adaptive Streaming) - High-quality streaming with broad compatibility
• MP4 - Standard video format with universal support
• Auto-format selection - Intelligent format selection based on platform and network conditions
• Fallback support - Automatic fallback to alternative formats if primary format fails

📱 Platform Optimized #

• iOS: Optimized for HLS streaming
• Android: Optimized for DASH streaming
• Web: Universal MP4 support
• Hardware acceleration support
• Picture-in-Picture mode

⚡ Performance Features #

• Adaptive bitrate streaming for optimal quality based on network conditions
• Intelligent caching with configurable cache size and duration
• Video preloading for smooth playback experience
• Memory management with automatic controller cleanup
• Low latency streaming support for live content

🎨 UI/UX Features #

• Instagram-like interface with familiar gestures
• Customizable progress indicators
• Shimmer loading effects
• Error handling with retry functionality
• Play/pause animations
• Double-tap to like with heart animation
• Long press to pause

🔧 Advanced Configuration #

• Streaming quality control (bitrate limits, resolution)
• Subtitle and audio track selection
• DRM support for protected content
• Network timeout and retry configuration
• Custom error and loading widgets

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_awesome_reels: ^1.0.0

Then run:

flutter pub get

Quick Start #

Basic Usage #

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

class MyReelsPage extends StatefulWidget {
  @override
  _MyReelsPageState createState() => _MyReelsPageState();
}

class _MyReelsPageState extends State<MyReelsPage> {
  late ReelController _controller;

  @override
  void initState() {
    super.initState();
    
    // Create reels with different streaming formats
    final reels = [
      // HLS Stream
      ReelModel.hls(
        id: '1',
        hlsUrl: 'https://example.com/video.m3u8',
        thumbnailUrl: 'https://example.com/thumb1.jpg',
        duration: Duration(minutes: 2),
        user: ReelUser(
          id: 'user1',
          username: 'creator1',
          profilePictureUrl: 'https://example.com/avatar1.jpg',
        ),
        caption: 'Amazing HLS video!',
      ),
      
      // DASH Stream
      ReelModel.dash(
        id: '2',
        dashUrl: 'https://example.com/video.mpd',
        thumbnailUrl: 'https://example.com/thumb2.jpg',
        duration: Duration(minutes: 1, seconds: 30),
        user: ReelUser(
          id: 'user2',
          username: 'creator2',
          profilePictureUrl: 'https://example.com/avatar2.jpg',
        ),
        caption: 'High quality DASH stream!',
      ),
      
      // Standard MP4
      ReelModel.mp4(
        id: '3',
        mp4Url: 'https://example.com/video.mp4',
        thumbnailUrl: 'https://example.com/thumb3.jpg',
        duration: Duration(seconds: 45),
        user: ReelUser(
          id: 'user3',
          username: 'creator3',
          profilePictureUrl: 'https://example.com/avatar3.jpg',
        ),
        caption: 'Classic MP4 video!',
      ),
    ];
    
    // Configure with streaming support
    final config = ReelConfig(
      enableCaching: true,
      videoPlayerConfig: VideoPlayerConfig(
        useBetterPlayer: true, // Enable for HLS/DASH support
        enableHardwareAcceleration: true,
        streamingConfig: StreamingConfig(
          preferredFormat: PreferredStreamingFormat.auto,
          enableAdaptiveBitrate: true,
          enableFallback: true,
        ),
      ),
    );
    
    _controller = ReelController(
      reels: reels,
      config: config,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ReelViewer(
        controller: _controller,
        onReelChanged: (index) {
          print('Current reel: $index');
        },
        onLike: (reel) {
          print('Liked: ${reel.caption}');
        },
        onComment: (reel) {
          print('Comment on: ${reel.caption}');
        },
        onShare: (reel) {
          print('Share: ${reel.caption}');
        },
      ),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }
}

Advanced Streaming Configuration #

// Create a reel with multiple format support
final multiFormatReel = ReelModel(
  id: 'multi_1',
  videoSource: VideoSource(
    format: VideoFormat.hls, // Primary format
    urls: {
      VideoFormat.hls: 'https://example.com/video.m3u8',
      VideoFormat.dash: 'https://example.com/video.mpd',
      VideoFormat.mp4: 'https://example.com/video.mp4',
    },
  ),
  thumbnailUrl: 'https://example.com/thumb.jpg',
  duration: Duration(minutes: 3),
  user: ReelUser(
    id: 'user1',
    username: 'creator',
    profilePictureUrl: 'https://example.com/avatar.jpg',
  ),
  caption: 'Multi-format video with fallback support',
);

// Advanced streaming configuration
final streamingConfig = StreamingConfig(
  preferredFormat: PreferredStreamingFormat.hls,
  enableAdaptiveBitrate: true,
  enableLowLatency: false,
  maxBitrate: 5000000, // 5 Mbps
  minBitrate: 500000,  // 500 Kbps
  enableSubtitleSelection: true,
  enableAudioTrackSelection: true,
  enableQualitySelection: true,
  enableFallback: true,
  fallbackFormats: [VideoFormat.dash, VideoFormat.mp4],
  networkTimeout: Duration(seconds: 30),
  maxRetryAttempts: 3,
  enableDRM: false,
);

final config = ReelConfig(
  enableCaching: true,
  cacheConfig: CacheConfig(
    maxCacheSize: 500 * 1024 * 1024, // 500MB
    maxCacheAge: Duration(days: 7),
  ),
  videoPlayerConfig: VideoPlayerConfig(
    useBetterPlayer: true,
    enableHardwareAcceleration: true,
    enablePictureInPicture: true,
    streamingConfig: streamingConfig,
  ),
  preloadConfig: PreloadConfig(
    preloadCount: 2,
    preloadRadius: 1,
  ),
);

Streaming Formats #

HLS (HTTP Live Streaming) #

• Best for: iOS devices, adaptive streaming
• Features: Automatic quality adjustment, low latency options
• File extension: .m3u8
• Platform support: Excellent on iOS, good on Android/Web

ReelModel.hls(
  id: 'hls_video',
  hlsUrl: 'https://example.com/playlist.m3u8',
  // ... other properties
);

DASH (Dynamic Adaptive Streaming) #

• Best for: Android devices, high-quality streaming
• Features: Superior compression, wide codec support
• File extension: .mpd
• Platform support: Excellent on Android, good on Web

ReelModel.dash(
  id: 'dash_video',
  dashUrl: 'https://example.com/manifest.mpd',
  // ... other properties
);

MP4 (Standard Video) #

• Best for: Universal compatibility, simple implementation
• Features: Wide support, easy to implement
• File extension: .mp4
• Platform support: Universal

ReelModel.mp4(
  id: 'mp4_video',
  mp4Url: 'https://example.com/video.mp4',
  // ... other properties
);

Configuration Options #

ReelConfig #

StreamingConfig #

VideoPlayerConfig #

Best Practices #

1. Format Selection #

• Use HLS for iOS-first applications
• Use DASH for Android-first applications
• Use Auto for cross-platform applications
• Always provide MP4 fallback for maximum compatibility

2. Performance Optimization #

// Optimal configuration for performance
final config = ReelConfig(
  enableCaching: true,
  cacheConfig: CacheConfig(
    maxCacheSize: 200 * 1024 * 1024, // 200MB
    maxCacheAge: Duration(days: 3),
  ),
  preloadConfig: PreloadConfig(
    preloadCount: 1, // Preload next video only
    preloadRadius: 1,
  ),
  videoPlayerConfig: VideoPlayerConfig(
    useBetterPlayer: true,
    enableHardwareAcceleration: true,
    streamingConfig: StreamingConfig(
      preferredFormat: PreferredStreamingFormat.auto,
      enableAdaptiveBitrate: true,
      maxBitrate: 3000000, // 3 Mbps max
      minBitrate: 500000,  // 500 Kbps min
    ),
  ),
);

3. Error Handling #

ReelViewer(
  controller: _controller,
  errorBuilder: (context, reel, error) {
    return Container(
      color: Colors.black,
      child: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.error, color: Colors.red, size: 48),
            SizedBox(height: 16),
            Text(
              'Failed to load video',
              style: TextStyle(color: Colors.white, fontSize: 16),
            ),
            SizedBox(height: 8),
            ElevatedButton(
              onPressed: () => _controller.retry(),
              child: Text('Retry'),
            ),
          ],
        ),
      ),
    );
  },
);

4. Custom Loading Widget #

ReelViewer(
  controller: _controller,
  loadingBuilder: (context, reel) {
    return Container(
      color: Colors.black,
      child: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            CircularProgressIndicator(color: Colors.white),
            SizedBox(height: 16),
            Text(
              'Loading ${reel.videoFormat.name.toUpperCase()} video...',
              style: TextStyle(color: Colors.white),
            ),
          ],
        ),
      ),
    );
  },
);

Platform-Specific Setup #

iOS #

Add the following to your ios/Runner/Info.plist:

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

Android #

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Dependencies #

This package uses the following dependencies:

• video_player: Standard video playback
• better_player: Advanced streaming support (HLS/DASH)
• connectivity_plus: Network connectivity detection
• visibility_detector: Viewport visibility detection
• get: State management
• dio: HTTP client for caching
• path_provider: File system access
• lottie: Loading animations

Examples #

Check out the example directory for complete implementation examples:

• Basic Usage: Simple reel implementation
• Streaming Example: Advanced streaming with HLS/DASH
• Custom UI: Customized interface and controls
• Performance Optimized: Optimized for large video lists

Contributing #

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License #

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

Changelog #

See CHANGELOG.md for a detailed list of changes and updates.

Support #

If you encounter any issues or have questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue

Acknowledgments #

• Inspired by Instagram and TikTok reel interfaces
• Built with Flutter's powerful video capabilities
• Thanks to the Flutter community for feedback and contributions