---

📚 Table of contents

• ✨ Features
• 📱 Platform support
• 📦 Installation
• 🚀 Quick start
• 🧰 API reference
• 🪟 Windows notes
• 💡 Example use cases
• 🤝 Contributing
• ⭐ Support this project

---

✨ Features

• 🖼️ Generate thumbnails from video files or raw byte arrays
• 🎨 Multiple image formats — PNG, JPG, and WebP
• 📐 Fully customizable size, quality, and timestamp
• ⚡ Native platform implementations for optimal performance
• 💾 Get a thumbnail back as a file path or an in-memory Uint8List

📱 Platform support

Platform	thumbnailFile	thumbnailData	thumbnailDataWeb
🤖 Android	✅	✅	⛔️
🍎 iOS	✅	✅	⛔️
🖥️ macOS	✅	✅	⛔️
🪟 Windows	✅	✅	⛔️
🌐 Web	⛔️	⛔️	✅

iOS / macOS: iOS and macOS share a single native implementation under darwin/, integrable via either CocoaPods or Swift Package Manager. Minimum versions: iOS 13.0+, macOS 10.15+.

📦 Installation

Add video_thumb_kit to your pubspec.yaml:

dependencies:
  video_thumb_kit: ^0.0.1

Then fetch it:

flutter pub get

🚀 Quick start

1️⃣ Generate a thumbnail file

import 'package:video_thumb_kit/video_thumb_kit.dart';

Future<void> main() async {
  final videoPath = 'path/to/video.mp4';
  final thumbnailPath = 'path/to/thumbnail.png';

  final result = await VideoThumbKit.thumbnailFile(
    video: videoPath,
    thumbnailPath: thumbnailPath,
    imageFormat: ImageFormat.png,
    maxHeight: 100,
    maxWidth: 100,
    timeMs: 1000,
    quality: 10,
  );

  if (result != null) {
    print('✅ Thumbnail generated: $result');
  } else {
    print('❌ Failed to generate thumbnail');
  }
}

2️⃣ Generate thumbnail bytes from a video byte array (Web only)

import 'package:video_thumb_kit/video_thumb_kit.dart';

Future<void> main() async {
  final videoBytes = Uint8List.fromList([/* video byte array */]);

  final result = await VideoThumbKit.thumbnailDataWeb(
    videoBytes: videoBytes,
    quality: 100,
  );

  if (result != null) {
    print('✅ Thumbnail generated: ${result.lengthInBytes} bytes');
  } else {
    print('❌ Failed to generate thumbnail');
  }
}

🧰 API reference

VideoThumbKit.thumbnailFile(...)

Generates a thumbnail from a video file and saves it to disk. Returns the path to the generated file, or null on failure.

Parameter	Type	Default	Description
video	String	required	Path to the source video file
headers	Map<String, String>?	null	Optional headers sent with the request
thumbnailPath	String?	null	Where to save the thumbnail (auto-generated if omitted)
imageFormat	ImageFormat	ImageFormat.png	Output image format
maxHeight	int	0 (unbounded)	Maximum thumbnail height
maxWidth	int	0 (unbounded)	Maximum thumbnail width
timeMs	int	0	Timestamp in the video to capture, in milliseconds
quality	int	10	Output image quality

VideoThumbKit.thumbnailData(...)

Same as above, but returns the thumbnail as a Uint8List instead of writing to disk. Accepts the same parameters (minus thumbnailPath).

VideoThumbKit.thumbnailDataWeb(...)

Generates a thumbnail from a raw video byte array — Web only. Returns a Uint8List, or null on failure.

Parameter	Type	Default	Description
videoBytes	Uint8List	required	The source video as a byte array
quality	num	100	Output image quality

🪟 Windows notes

• Thumbnail extraction uses Media Foundation; image encoding uses WIC
• ImageFormat.webp currently falls back to PNG for compatibility
• If thumbnailPath is omitted, output is written to the OS temp directory

💡 Example use cases

• 🎞️ Thumbnails for video playback screens
• 🖼️ Building a video gallery grid
• 📤 Sharing video previews on social media

See the full example app for a complete, runnable demo.

🤝 Contributing

Contributions are welcome! Fork the repository, make your changes, and submit a pull request. 🙌

⭐ Support this project

If video_thumb_kit helped you ship faster, consider starring the repo — it genuinely helps! Found a bug? Open an issue and we'll take a look.