🎬 Video Thumb Kit

Fast, cross-platform video thumbnail generation for Flutter.

Turn a video file, URL, or raw byte array into a crisp thumbnail — as a file or in memory — with a few lines of Dart.

pub package license Example

📚 Table of contents

✨ 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.

Libraries

enum
video_thumb_kit
video_thumb_kit_method_channel
video_thumb_kit_mobile_platform
video_thumb_kit_platform_interface
video_thumb_kit_web