Cinematic Video Player

A modern, feature-rich Flutter video player with cinematic UI controls. Provides a production-ready video playback experience with all the features expected from a premium streaming application.

Features

  • 🎬 Beautiful cinematic UI - Clean, modern interface with transparent controls that auto-hide
  • 📱 Cross-platform support - Works on Android, iOS, Web, macOS, and Windows
  • 🎮 Complete playback controls - Play/pause, seek, volume, fullscreen, and playback speed
  • ⏩ 10-second seek - Quick rewind/forward buttons for easy navigation
  • 📊 Progress tracking - Visual progress bar with buffering indicator
  • ⌨️ Keyboard shortcuts - Space (play/pause), M (mute), F (fullscreen), arrow keys (seek)
  • 🖱️ Mouse hover support - Controls automatically appear on mouse movement
  • 🎨 Fully customizable - All colors, sizes, and behaviors can be customized
  • 🎯 Error handling - Graceful error states with retry functionality
  • 📶 Multi-quality support - Built-in architecture for adaptive quality streaming
  • 🔄 Auto-hiding controls - Controls fade out after 3 seconds of inactivity
  • 📐 Responsive design - Works seamlessly on phones, tablets, and desktop

Supported Platforms

Platform Support Notes
Android ✅ Full support
iOS ✅ Full support
Web ✅ Full support
macOS ✅ Full support
Windows ✅ Full support

Supported Formats

  • MP4
  • HLS (where supported by the underlying platform)
  • Network URLs
  • Asset videos
  • Local file videos

Installation

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

dependencies:
  cinematic_video_player: ^1.0.0

Then run:

flutter pub get

Platform Setup

Android

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

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

iOS

If you need to access HTTP videos, add this to your ios/Runner/Info.plist:

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

macOS

Add the network client entitlement to your macOS runner.

Basic Usage

import 'package:cinematic_video_player/cinematic_video_player.dart';

// Create a video player with a network video
CinematicVideoPlayer(
  source: VideoSource.network('https://example.com/video.mp4'),
  autoPlay: false,
  looping: false,
  showControls: true,
  allowFullscreen: true,
  allowPlaybackSpeed: true,
  allowVolume: true,
  aspectRatio: 16 / 9,
  progressIndicatorColor: Colors.red,
  onPlay: () => print('Video started playing'),
  onPause: () => print('Video paused'),
  onCompleted: () => print('Video completed'),
)

Controller Usage

For more control, use the CinematicVideoPlayerController:

late final CinematicVideoPlayerController controller;

@override
void initState() {
  super.initState();
  controller = CinematicVideoPlayerController(
    onPlay: () => print('Playing'),
    onPause: () => print('Paused'),
  );
}

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

// Use in your widget
CinematicVideoPlayer(
  source: VideoSource.network('https://example.com/video.mp4'),
  controller: controller,
)

// Control the player programmatically
controller.play();
controller.pause();
controller.seekTo(Duration(seconds: 30));
controller.setVolume(0.5);
controller.setPlaybackSpeed(1.5);
controller.toggleMute();
controller.enterFullscreen(context);
controller.exitFullscreen(context);
controller.retry(); // Retry after error

Fullscreen Usage

The package handles fullscreen mode automatically across all platforms. On mobile, it enters landscape orientation and hides system overlays. On desktop/web, it uses the platform's fullscreen capabilities.

// Toggle fullscreen programmatically
controller.toggleFullscreen(context);

Playback Speed

Supported playback speeds: 0.25x, 0.5x, 0.75x, 1.0x, 1.25x, 1.5x, 1.75x, 2.0x

Customization

Extensive customization options are available:

CinematicVideoPlayer(
  source: VideoSource.network(url),
  // Behavior customization
  autoPlay: true,
  looping: true,
  controlsAutoHideDuration: Duration(seconds: 5),
  // Visual customization
  backgroundColor: Colors.black,
  controlsBackgroundColor: Colors.black54,
  progressIndicatorColor: Colors.blue,
  playPauseIconColor: Colors.white,
  playPauseIconSize: 64,
  durationTextColor: Colors.white,
  durationTextSize: 14,
  fullscreenIconColor: Colors.white,
  speedTextColor: Colors.white,
  speedTextSize: 14,
  qualityLabel: '4K', // Custom quality label
)

Multi-Quality Videos

For videos with multiple quality options:

final qualities = [
  VideoQuality.quality1080p.copyWith(url: 'https://example.com/1080p.mp4'),
  VideoQuality.quality720p.copyWith(url: 'https://example.com/720p.mp4'),
  VideoQuality.quality480p.copyWith(url: 'https://example.com/480p.mp4'),
];

CinematicVideoPlayer(
  source: VideoSource.networkWithQualities(qualities),
)

Error Handling

The player automatically handles errors and shows a retry button. You can also handle errors programmatically:

CinematicVideoPlayer(
  source: VideoSource.network(url),
  onError: (error) {
    print('Video error: $error');
    // Handle the error
  },
)

// Or via the controller
if (controller.value.hasError) {
  print('Error: ${controller.value.errorMessage}');
  controller.retry();
}

Keyboard Shortcuts (Desktop/Web)

  • Space: Play/Pause
  • M: Mute/Unmute
  • F: Toggle Fullscreen
  • Left Arrow: Seek backward 10 seconds
  • Right Arrow: Seek forward 10 seconds

Example

Check out the example directory for a complete demonstration of all features.

To run the example:

cd example
flutter pub get
flutter run

Platform Limitations

  • HLS streaming support depends on the underlying platform's video player capabilities
  • Some platforms may have restrictions on autoplay policies
  • Windows uses MediaFoundation which supports most common video codecs

Issues and Feedback

Please file issues, feature requests, and bugs in the GitHub repository.

License

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

Libraries

cinematic_video_player
A modern, feature-rich Flutter video player with cinematic UI controls.