📢 What's New in v0.1.1 #

🐛 Critical Bug Fix: Fixed WebView platform implementation issue
✅ Now Production Ready: Works perfectly on Android, iOS, Web, and Desktop
🚀 Better Platform Support: Improved initialization for all platforms

See full changelog →

✨ Why Simple YouTube Player? #

🎯 Zero Configuration - Works out of the box with sensible defaults
🚀 Lightweight - Minimal dependencies, maximum performance
🎨 Customizable - Full control over size, autoplay, controls, and more
🔗 Flexible URLs - Supports all YouTube URL formats automatically
📱 Responsive - Perfect for any screen size
🎮 Controller Support - Advanced control when you need it
⚡ Fast Loading - Optimized for quick video loading
🛡️ Error Handling - Graceful error messages built-in
🌍 Cross-Platform - Works on iOS, Android, Web, and Desktop
✅ Production Ready - v0.1.1 is stable and tested

📦 Installation #

Add simple_youtube_player to your pubspec.yaml:

dependencies:
  simple_youtube_player: ^0.1.1

Then install it:

flutter pub get

That's it! You're ready to go 🎉

🚀 Quick Start #

The simplest possible usage:

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

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Simple YouTube Player')),
        body: Center(
          child: SimpleYoutubePlayer(
            url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
            width: 350,
            height: 220,
          ),
        ),
      ),
    );
  }
}

That's literally all you need! 🎊

💡 Usage Examples #

🎬 Basic Video Player #

Perfect for simple video embedding:

SimpleYoutubePlayer(
  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  width: 300,
  height: 200,
)

⚙️ Customized Player #

Full control over player behavior:

SimpleYoutubePlayer(
  url: 'https://youtu.be/jNQXAC9IVRw',
  width: 400,
  height: 250,
  autoPlay: true,        // Start playing automatically
  mute: true,            // Start muted (recommended with autoPlay)
  loop: true,            // Loop the video infinitely
  showControls: true,    // Show YouTube player controls
)

🎮 With Controller #

For advanced control and state monitoring:

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

class AdvancedPlayerScreen extends StatefulWidget {
  @override
  _AdvancedPlayerScreenState createState() => _AdvancedPlayerScreenState();
}

class _AdvancedPlayerScreenState extends State<AdvancedPlayerScreen> {
  final _controller = SimpleYoutubePlayerController();

  @override
  void initState() {
    super.initState();
    
    // Monitor player state changes
    _controller.addListener(() {
      setState(() {}); // Rebuild UI when state changes
      
      if (_controller.error != null) {
        print('Error: ${_controller.error}');
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Advanced Player')),
      body: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          SimpleYoutubePlayer(
            url: 'https://www.youtube.com/watch?v=VIDEO_ID',
            width: 350,
            height: 220,
            controller: _controller,
          ),
          SizedBox(height: 20),
          // Show loading indicator
          if (_controller.isLoading)
            CircularProgressIndicator(),
          // Show error if any
          if (_controller.error != null)
            Text(
              'Error: ${_controller.error}',
              style: TextStyle(color: Colors.red),
            ),
        ],
      ),
    );
  }

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

📱 Responsive Player #

Adapts to any screen size with perfect aspect ratio:

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

class ResponsivePlayerScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Responsive Player')),
      body: Center(
        child: LayoutBuilder(
          builder: (context, constraints) {
            // Calculate responsive dimensions
            double width = constraints.maxWidth * 0.9;
            double height = width * 9 / 16; // 16:9 aspect ratio
            
            return SimpleYoutubePlayer(
              url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
              width: width,
              height: height,
            );
          },
        ),
      ),
    );
  }
}

📜 Video List #

Display multiple videos in a scrollable list:

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

class VideoListScreen extends StatelessWidget {
  final List<Map<String, String>> videos = [
    {
      'title': 'Amazing Video 1',
      'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    },
    {
      'title': 'Cool Tutorial',
      'url': 'https://youtu.be/jNQXAC9IVRw',
    },
    {
      'title': 'Must Watch',
      'url': 'https://www.youtube.com/watch?v=9bZkp7q19f0',
    },
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Video Playlist')),
      body: ListView.builder(
        padding: EdgeInsets.all(16),
        itemCount: videos.length,
        itemBuilder: (context, index) {
          return Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text(
                videos[index]['title']!,
                style: TextStyle(
                  fontSize: 18,
                  fontWeight: FontWeight.bold,
                ),
              ),
              SizedBox(height: 8),
              SimpleYoutubePlayer(
                url: videos[index]['url']!,
                width: MediaQuery.of(context).size.width - 32,
                height: 200,
              ),
              SizedBox(height: 24),
            ],
          );
        },
      ),
    );
  }
}

🎨 Styled Player #

Add beautiful styling around your player:

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

class StyledPlayerScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.grey[900],
      appBar: AppBar(
        title: Text('Styled Player'),
        backgroundColor: Colors.black,
      ),
      body: Center(
        child: Container(
          margin: EdgeInsets.all(16),
          decoration: BoxDecoration(
            color: Colors.black,
            borderRadius: BorderRadius.circular(16),
            boxShadow: [
              BoxShadow(
                color: Colors.blue.withOpacity(0.3),
                blurRadius: 20,
                spreadRadius: 5,
                offset: Offset(0, 10),
              ),
            ],
          ),
          padding: EdgeInsets.all(8),
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              SimpleYoutubePlayer(
                url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
                width: 350,
                height: 220,
              ),
              SizedBox(height: 16),
              Text(
                'Featured Video',
                style: TextStyle(
                  color: Colors.white,
                  fontSize: 20,
                  fontWeight: FontWeight.bold,
                ),
              ),
              SizedBox(height: 8),
              Text(
                'Watch this amazing content',
                style: TextStyle(
                  color: Colors.grey[400],
                  fontSize: 14,
                ),
              ),
              SizedBox(height: 8),
            ],
          ),
        ),
      ),
    );
  }
}

🎭 Background Video #

Full-screen background video effect:

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

class BackgroundVideoScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // Background video
          Positioned.fill(
            child: SimpleYoutubePlayer(
              url: 'https://www.youtube.com/watch?v=VIDEO_ID',
              width: MediaQuery.of(context).size.width,
              height: MediaQuery.of(context).size.height,
              autoPlay: true,
              mute: true,
              loop: true,
              showControls: false,
            ),
          ),
          // Overlay content
          Positioned.fill(
            child: Container(
              color: Colors.black.withOpacity(0.5),
              child: Center(
                child: Column(
                  mainAxisAlignment: MainAxisAlignment.center,
                  children: [
                    Text(
                      'Welcome',
                      style: TextStyle(
                        color: Colors.white,
                        fontSize: 48,
                        fontWeight: FontWeight.bold,
                      ),
                    ),
                    SizedBox(height: 16),
                    ElevatedButton(
                      onPressed: () {},
                      child: Text('Get Started'),
                    ),
                  ],
                ),
              ),
            ),
          ),
        ],
      ),
    );
  }
}

🔗 Supported URL Formats #

The package automatically recognizes all YouTube URL formats:

Just paste any YouTube URL and it works! 🎯

📋 Parameters #

Complete reference of all available parameters:

🎮 Controller API #

For advanced control and monitoring, use SimpleYoutubePlayerController:

Properties #

final controller = SimpleYoutubePlayerController();

// Check player state
bool isPlaying = controller.isPlaying;    // Is video currently playing?
bool isLoading = controller.isLoading;    // Is video still loading?
String? error = controller.error;         // Error message if any

Methods #

// Listen to state changes
controller.addListener(() {
  print('Player state changed!');
  print('Loading: ${controller.isLoading}');
  print('Error: ${controller.error}');
});

// Don't forget to dispose!
controller.dispose();

🌟 Best Practices #

✅ DO: #

// Use mute with autoPlay for better UX
SimpleYoutubePlayer(
  url: 'https://youtube.com/watch?v=...',
  autoPlay: true,
  mute: true,  // ✅ Good practice
)

// Dispose controllers
@override
void dispose() {
  _controller.dispose();  // ✅ Prevents memory leaks
  super.dispose();
}

// Handle errors gracefully
controller.addListener(() {
  if (controller.error != null) {
    // Show user-friendly message
  }
});

❌ DON'T: #

// Don't autoplay with sound (annoying for users)
SimpleYoutubePlayer(
  autoPlay: true,
  mute: false,  // ❌ Bad UX
)

// Don't forget controller cleanup
// ❌ Memory leak!

// Don't use extremely large dimensions
SimpleYoutubePlayer(
  width: 10000,  // ❌ Performance issue
  height: 10000,
)

🎨 Customization Tips #

Perfect 16:9 Aspect Ratio #

double width = 400;
double height = width * 9 / 16;  // = 225

SimpleYoutubePlayer(
  url: url,
  width: width,
  height: height,
)

Dynamic Sizing Based on Screen #

double screenWidth = MediaQuery.of(context).size.width;
double playerWidth = screenWidth * 0.9;  // 90% of screen
double playerHeight = playerWidth * 9 / 16;

Card-Style Player #

Card(
  elevation: 8,
  shape: RoundedRectangleBorder(
    borderRadius: BorderRadius.circular(12),
  ),
  child: ClipRRect(
    borderRadius: BorderRadius.circular(12),
    child: SimpleYoutubePlayer(
      url: url,
      width: 300,
      height: 200,
    ),
  ),
)

🌍 Platform Support #

⚠️ Important Notes #

• 📡 Internet Required: Videos require active internet connection
• 🔒 Embed Restrictions: Some videos may have embedding disabled by uploader
• 🎬 YouTube Terms: Respects YouTube's Terms of Service
• 🔄 WebView Based: Uses webview_flutter internally for reliability

🐛 Troubleshooting #

Video Not Loading? #

1. Check URL: Ensure the URL is valid and video exists
2. Check Internet: Verify internet connection is active
3. Check Embedding: Some videos can't be embedded (error will show)
4. Update Package: Make sure you're using v0.1.1 or higher

Still Using v0.0.1? #

⚠️ Version 0.0.1 has a critical bug! Please upgrade to v0.1.1:

# Update pubspec.yaml
dependencies:
  simple_youtube_player: ^0.1.1

# Get update
flutter pub get

📱 Live Demo #

Check out the /example folder for a complete demo app featuring:

• Basic player usage
• Advanced controller features
• Responsive layouts
• Multiple videos in list
• Styled player examples
• All configuration options

Run the example:

cd example
flutter run

🤝 Contributing #

Contributions are welcome! Here's how you can help:

1. 🐛 Report Bugs: Open an issue with reproduction steps
2. 💡 Suggest Features: Share your ideas in issues
3. 🔧 Submit PRs: Fork, code, and submit pull requests
4. 📖 Improve Docs: Help make documentation better
5. ⭐ Star the Repo: Show your support!

See CONTRIBUTING.md for detailed guidelines.

📄 License #

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

TL;DR: Free to use, modify, and distribute. Commercial use allowed. 🎉

🙏 Credits #

• Built with ❤️ for the Flutter community
• Powered by webview_flutter
• Inspired by the need for simplicity in video embedding

💬 Support & Feedback #

• 📦 Package: pub.flutter-io.cn/packages/simple_youtube_player
• 💻 Repository: GitHub
• 🐛 Issues: GitHub Issues
• 📝 Changelog: CHANGELOG.md
• ⭐ Like it?: Give us a star on GitHub!