flutter_smart_video_player 1.0.0

A fully customizable YouTube video player using WebView and IFrame API. Works seamlessly inside dynamic UI rendering systems.

flutter_smart_video_player

A production-ready, fully customizable YouTube video player Flutter package built on WebView + YouTube IFrame API. Designed for dynamic UI rendering systems.

---

✨ Features

• 🎬 YouTube playback from any standard YouTube URL
• 📺 Flutter-controlled fullscreen (landscape lock, smooth transition)
• 🎮 Custom controls — play/pause, seek bar, time labels, fullscreen toggle
• 🔄 Dynamic rendering safe — survives rebuilds, no unnecessary restarts
• 📋 Multiple instances — isolated controllers, no WebView conflicts
• 🎛️ External controller API — programmatically control playback
• 🔧 Custom controls builder — replace the default UI entirely
• ⚡ Lifecycle aware — pauses on app background/dispose
• ❌ Graceful error handling — invalid URLs, unavailable videos

---

🚀 Installation

Add to your pubspec.yaml:

dependencies:
  flutter_smart_video_player: ^1.0.0

Android setup

In android/app/src/main/AndroidManifest.xml, add inside <application>:

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

Also ensure minSdkVersion is at least 19 in android/app/build.gradle.

iOS setup

In ios/Runner/Info.plist, add:

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

---

📖 Usage

Basic — just a URL

import 'package:flutter_smart_video_player/flutter_smart_video_player.dart';

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

Supports all YouTube URL formats:

• 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
• Raw VIDEO_ID (11 chars)

---

With configuration

SmartVideoPlayer(
  url: 'https://youtu.be/dQw4w9WgXcQ',
  config: const SmartVideoConfig(
    autoPlay: true,
    showControls: true,
    aspectRatio: 16 / 9,
    backgroundColor: Colors.black,
    allowFullscreen: true,
  ),
)

---

With external controller

final controller = SmartVideoController();

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

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

// Control from anywhere:
controller.play();
controller.pause();
controller.seekTo(const Duration(seconds: 30));

---

React to state changes

ValueListenableBuilder<SmartVideoState>(
  valueListenable: controller,
  builder: (context, state, _) {
    return Text('${state.positionLabel} / ${state.durationLabel}');
  },
)

---

Custom controls UI

SmartVideoPlayer(
  url: url,
  config: const SmartVideoConfig(showControls: false),
  customControlsBuilder: (context, controller, state) {
    return MyCustomControls(controller: controller, state: state);
  },
)

---

Dynamic rendering system (your use case)

Widget buildComponent(Map<String, dynamic> item) {
  switch (item['type']) {
    case 'ytVideo':
      return SmartVideoPlayer(url: item['data']);
    case 'text':
      return Text(item['data']);
    // ...other types
  }
}

---

🎛️ API Reference

SmartVideoPlayer

Parameter	Type	Default	Description
url	String	required	YouTube URL
controller	SmartVideoController?	auto	External controller
config	SmartVideoConfig	default	Player configuration
customControlsBuilder	Widget Function(...)?	null	Custom controls overlay

---

SmartVideoConfig

Property	Type	Default	Description
autoPlay	bool	false	Auto-start on ready
showControls	bool	true	Show built-in controls
backgroundColor	Color	Colors.black	BG behind WebView
aspectRatio	double	16/9	Player container ratio
allowFullscreen	bool	true	Enable fullscreen button
showAnnotations	bool	false	YouTube annotations
showRelatedVideos	bool	false	Related videos on end

---

SmartVideoController

Method	Description
play()	Start/resume playback
pause()	Pause playback
seekTo(Duration)	Jump to position
enterFullscreen()	Enter fullscreen
exitFullscreen()	Exit fullscreen
dispose()	Cleanup resources

---

SmartVideoState

Property	Type	Description
isPlaying	bool	Currently playing
isReady	bool	Player initialized
isBuffering	bool	Currently buffering
isFullscreen	bool	In fullscreen mode
position	Duration	Current position
duration	Duration	Total duration
progress	double	Progress 0.0–1.0
positionLabel	String	mm:ss position
durationLabel	String	mm:ss duration
error	String?	Error message or null

---

🏗 Architecture

lib/
├── flutter_smart_video_player.dart    # Public exports
└── src/
    ├── controller/
    │   └── smart_video_controller.dart   # ValueNotifier controller + JS bridge
    ├── models/
    │   ├── smart_video_state.dart        # Immutable state object
    │   └── smart_video_config.dart       # Configuration options
    ├── js/
    │   └── player_html.dart             # YouTube IFrame HTML+JS builder
    ├── view/
    │   └── smart_video_view.dart        # InAppWebView + JS handler registration
    ├── player/
    │   └── flutter_smart_video_player.dart      # Public widget (composes all layers)
    ├── fullscreen/
    │   └── fullscreen_page.dart         # Fullscreen navigator page
    ├── widgets/
    │   └── controls.dart               # Default controls overlay UI
    └── utils/
        └── youtube_parser.dart         # YouTube URL → video ID parser

---

🔧 How It Works

1. URL Parsing: YoutubeParser extracts the video ID from any YouTube URL format
2. HTML Generation: PlayerHtml builds a self-contained HTML page embedding the YouTube IFrame API
3. WebView: SmartVideoView hosts the WebView, loads the HTML, and registers JS message handlers
4. JS Bridge: Events from the IFrame (onReady, onStateChange, onProgress, onError) are sent to Flutter via flutter_inappwebview.callHandler()
5. Controller: SmartVideoController exposes state via ValueNotifier and dispatches JS commands back to the WebView
6. Fullscreen: Uses Navigator.push() to a dedicated page, reusing the same controller — no video restart

---

🧪 Testing

flutter test

---

📋 Manual Testing Checklist

• ❌ Android real device — play/pause/seek
• ❌ iOS real device — play/pause/seek
• ❌ Fullscreen enter/exit (portrait restore)
• ❌ Back button in fullscreen
• ❌ Multiple players on same screen
• ❌ Scroll list — players don't restart
• ❌ Dynamic rebuild — players survive
• ❌ Invalid URL — error shown gracefully
• ❌ Private video — error shown gracefully
• ❌ App background — video pauses

---

📦 Publishing

dart pub publish --dry-run   # Check for issues
dart pub publish             # Publish to pub.dev

---

📄 License

MIT — see LICENSE