flutter_smart_video_player

A production-ready, fully customizable YouTube video player Flutter package built on WebView + YouTube IFrame API. Designed specifically for stable dynamic UI rendering systems and crash-free seamless fullscreen transitions.

---

✨ Features

• 🎬 YouTube Playback: Play standard videos, live streams, or embedded URLs seamlessly.
• 📱 YouTube Shorts Auto-Detection: Automatically detects Shorts URLs and maps constraints to a native 9:16 layout safely.
• 📺 Zero-Latency Fullscreen: Preserves the underlying WebView via intelligent GlobalKey reparenting to completely prevent Android memory codec ANRs, providing lightning-fast cross-route transitions.
• 🔄 Custom Orientation Tilts: Define precisely how fullscreen operates utilizing SmartVideoTilt (Portrait, Landscape Left, Right, or Auto).
• 🎮 Built-in Smart Controls: Features a dynamic UX/UI overlay with time scrubbers, play/pause bottom bar layouts, and a native rotation toggler while in fullscreen mode.
• 🎛️ External Controller Support: Programmatically control playback anywhere from within your app architecture.
• ❌ Graceful Error Handling: Failsafes and fallback messages for invalid URLs and unavailable videos.

---

🚀 Installation

Add it to your pubspec.yaml:

dependencies:
  flutter_smart_video_player: ^1.0.3

Android setup

In android/app/src/main/AndroidManifest.xml, make sure to add inside your <application> tag:

<application
  android:usesCleartextTraffic="true"
  ...>

Ensure your minSdkVersion is at least 19 inside android/app/build.gradle.

iOS setup

In ios/Runner/Info.plist, inject:

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

---

📖 Usage Guides

Basic Usage

import 'package:flutter_smart_video_player/flutter_smart_video_player.dart';

SmartVideoPlayer(
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
)

The player actively supports all formats, rapidly tracking them down to their core IDs:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/embed/VIDEO_ID
• https://www.youtube.com/shorts/VIDEO_ID

---

YouTube Shorts & Custom Aspect Ratios

By default, standard URLs are scaled dynamically at 16:9, while URLs including /shorts/ are instantly evaluated as 9:16 without needing explicit overrides! However, you can freely override anything:

SmartVideoPlayer(
  url: 'https://www.youtube.com/shorts/5wJVJg0K8K0',
  // Below config will override the auto-detection
  config: const SmartVideoConfig(
    aspectRatio: 1.0, // Force a square 1:1 ratio
    autoPlay: false,
    showControls: true,
    centerPlayButton: true, // Beautiful centered translucent overlay
  ),
)

---

Blurred Letterbox Background (useBlurBackground)

When a video uses a custom aspectRatio (e.g. 1:1), the remaining space on either side normally shows a plain backgroundColor. Enable useBlurBackground to fill those areas with a live blurred thumbnail of the video instead:

SmartVideoPlayer(
  url: 'https://youtu.be/dQw4w9WgXcQ',
  config: const SmartVideoConfig(
    aspectRatio: 1.0,
    centerPlayButton: true,
    useBlurBackground: true, // ✨ Blurred thumbnail fills letterbox areas
  ),
)

Note: Falls back to backgroundColor if the thumbnail cannot be fetched.

---

Muted / Silent Playback (soundOn)

Control whether the player starts with audio enabled. Useful for autoplay scenarios or silent preview lists:

SmartVideoPlayer(
  url: 'https://youtu.be/dQw4w9WgXcQ',
  config: const SmartVideoConfig(
    autoPlay: true,
    soundOn: false, // 🔇 Starts muted
  ),
)

---

Decide how the OS rotates the device when entering fullscreen:

SmartVideoPlayer(
  url: 'https://youtu.be/dQw4w9WgXcQ',
  config: const SmartVideoConfig(
    tilt: SmartVideoTilt.landscape, // Forces the screen to strictly enter landscape
  ),
)

Tip: Setting this to SmartVideoTilt.portrait (which is the default) guarantees that triggering Fullscreen maximizes the widget vertically without annoying the user with forced side-rotating physics. Once in fullscreen, users can then freely press the built-in Rotate icon to manually flip it themselves!

---

Using Controllers Programmatically

final controller = SmartVideoController();

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

// In your widget:
SmartVideoPlayer(
  url: 'https://youtu.be/dQw4w9WgXcQ',
  controller: controller,
)

// Examples of triggering playback securely:
controller.play();
controller.pause();
controller.seekTo(const Duration(seconds: 30));
controller.enterFullscreen();

---

🎛️ API Reference

SmartVideoConfig

Take fine-tuned command over every metric of UX styling and tracking:

Property	Type	Default	Description
tilt	SmartVideoTilt	.portrait	How the UI behaves natively when triggering Fullscreen mode.
centerPlayButton	bool	false	When true, renders a translucent, animated Netflix-style play button exclusively in the center.
aspectRatio	double?	Auto	Overrides default 16:9/9:16 calculations manually.
autoPlay	bool	false	Instruct the embedded IFrame to trigger Play instantly.
showControls	bool	true	Allows overlay visibility interaction.
allowFullscreen	bool	true	Displays the fullscreen toggle securely in the corner.
showAnnotations	bool	false	Whether to stream annoying contextual Youtube popups.
showRelatedVideos	bool	false	Spawns generic video cards when paused or terminated.
backgroundColor	Color	Colors.black	Fills the container box beneath the initial loading state WebView.
useBlurBackground	bool	false	Fills letterbox areas (e.g. for 1:1 aspect ratio) with a blurred thumbnail instead of backgroundColor.
soundOn	bool	true	When false, the player initializes muted — ideal for silent autoplay scenarios.
withoutBNav	bool	false	Pushes the fullscreen page via rootNavigator: true, hiding the app's bottom navigation bar.

---

📄 License

MIT — see LICENSE