video_thumbnail_gen 0.6.2

A production-grade Flutter plugin to generate video thumbnails on Android and iOS. Supports JPEG, PNG, WebP, HEIC, batch extraction, metadata, and custom caching.

video_thumbnail_gen

A production-grade Flutter plugin to generate video thumbnails and get thumbnails from video URLs on Android and iOS.
Easily convert video to image, extract YouTube video thumbnails natively, capture video frames, and read video metadata with high performance.

---

📸 Screenshots

Onboarding Screen	Main App Interface	Thumbnail Extraction
Image Settings	Generated Thumbnail & Path	Settings (Alternative View)

---

✨ Features

Feature	Android	iOS
JPEG / PNG / WebP thumbnails	✅	✅
HEIC thumbnails	✅ API 30+	✅ iOS 11+
Batch frame extraction (single codec open)	✅	✅
Video metadata (duration, size, rotation)	✅	✅
In-memory LRU / NSCache	✅	✅
content:// (SAF) URI support	✅	—
HTTP(S) remote video URL	✅	✅
Custom output filename	✅	✅
Swift Package Manager (SPM)	—	✅
Typed error codes	✅	✅

---

📦 Installation

Run this command with Flutter:

flutter pub add video_thumbnail_gen

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

dependencies:
  video_thumbnail_gen: ^0.6.2

---

🚀 Quick Start

import 'package:video_thumbnail_gen/video_thumbnail_gen.dart';

Generate thumbnail in memory

final Uint8List? bytes = await VideoThumbnail.thumbnailData(
  video: '/path/to/video.mp4',
  imageFormat: ImageFormat.JPEG,
  maxWidth: 256,
  quality: 75,
);
// Use with Image.memory(bytes!)

Generate thumbnail as a file

final String? filePath = await VideoThumbnail.thumbnailFile(
  video: 'https://example.com/video.mp4',
  thumbnailPath: (await getTemporaryDirectory()).path,
  imageFormat: ImageFormat.PNG,
  maxHeight: 128,
  quality: 80,
);

Batch frame extraction

final List<Uint8List?> frames = await VideoThumbnail.thumbnailDataList(
  video: '/path/to/video.mp4',
  timesMs: [0, 2000, 5000, 10000], // extract 4 frames
  imageFormat: ImageFormat.JPEG,
  maxWidth: 320,
  quality: 75,
);

Get video metadata

final VideoMetadata? meta = await VideoThumbnail.getVideoMetadata(
  video: '/path/to/video.mp4',
);
print('Duration: ${meta?.durationMs}ms');
print('Size: ${meta?.width}×${meta?.height}');
print('Rotation: ${meta?.rotation}°');
print('MIME: ${meta?.mimeType}');

Clear the in-memory cache

await VideoThumbnail.clearCache();

---

📖 API Reference

VideoThumbnail.thumbnailData

static Future<Uint8List?> thumbnailData({
  required String video,
  Map<String, String>? headers,
  ImageFormat imageFormat = ImageFormat.PNG,
  int maxHeight = 0,    // 0 = original
  int maxWidth  = 0,    // 0 = original
  int timeMs    = 0,    // ms from start
  int quality   = 10,   // 0-100, ignored for PNG
})

VideoThumbnail.thumbnailFile

static Future<String?> thumbnailFile({
  required String video,
  Map<String, String>? headers,
  String? thumbnailPath,           // directory OR full file path
  ImageFormat imageFormat = ImageFormat.PNG,
  int maxHeight = 0,
  int maxWidth  = 0,
  int timeMs    = 0,
  int quality   = 10,
})

VideoThumbnail.thumbnailDataList

static Future<List<Uint8List?>> thumbnailDataList({
  required String video,
  Map<String, String>? headers,
  required List<int> timesMs,
  ImageFormat imageFormat = ImageFormat.JPEG,
  int maxHeight = 0,
  int maxWidth  = 0,
  int quality   = 75,
})

VideoThumbnail.getVideoMetadata

static Future<VideoMetadata?> getVideoMetadata({
  required String video,
  Map<String, String>? headers,
})

Returns a VideoMetadata object:

Field	Type	Description
durationMs	int	Total video duration in milliseconds
width	int	Display width (after rotation)
height	int	Display height (after rotation)
rotation	int	Clockwise rotation: 0, 90, 180, 270
mimeType	String?	Container MIME type, e.g. "video/mp4"

VideoThumbnail.clearCache

static Future<void> clearCache()

Evicts all entries from the native in-memory cache. Call this during low-memory events or when the app moves to background.

---

⚠️ Error Handling

All methods throw ThumbnailException on failure:

try {
  final bytes = await VideoThumbnail.thumbnailData(video: path);
} on ThumbnailException catch (e) {
  switch (e.code) {
    case ThumbnailErrorCode.fileNotFound:
      print('File does not exist: ${e.message}');
    case ThumbnailErrorCode.unsupportedFormat:
      print('Codec not supported: ${e.message}');
    case ThumbnailErrorCode.ioError:
      print('I/O error: ${e.message}');
    default:
      print('Unknown error: ${e.message}');
  }
}

Error Codes

Code	Cause
fileNotFound	File path does not exist
unsupportedFormat	Video codec not supported or frame undecodable
corruptedVideo	Thumbnail could not be generated from the video
ioError	Disk full, permission denied, or write failure
unknown	Unexpected native error

---

🖼️ Supported Image Formats

Enum	Android	iOS	Quality param
ImageFormat.JPEG	✅ All APIs	✅ All	✅
ImageFormat.PNG	✅ All APIs	✅ All	❌ (lossless)
ImageFormat.WEBP	✅ All APIs	✅ (libwebp)	✅
ImageFormat.HEIC	✅ API 30+	✅ iOS 11+	✅

Note: HEIC falls back to JPEG on older OS versions.

---

🍎 iOS: Swift Package Manager (SPM)

A Package.swift manifest is included for SPM integration in Xcode 14+. WebP is only available via CocoaPods; SPM builds fall back to JPEG gracefully.

CocoaPods (default):

pod 'video_thumbnail_gen', :path => '../'

SPM: Add the package URL directly in Xcode → File → Add Package Dependencies.

---

🔍 Keywords & Use Cases

This plugin is designed to support a wide range of video preview and thumbnail extraction use cases, including:

• Flutter video thumbnail generator: Convert any local video file, asset, or remote stream into high-quality preview images.
• Get thumbnail from video URL: Extract and download thumbnails from remote HTTP/HTTPS video links.
• Flutter YouTube thumbnail: Retrieve YouTube video cover images natively via public CDNs with automatic fallback resolutions.
• Video to image in Flutter: Capture video frames as raw bytes (Uint8List) or save them directly as files (JPEG, PNG, WebP, HEIC).
• High-speed frame extraction: Extract multiple video frames at once using batch processing, keeping the native decoder open for efficiency.

---

🤝 Contributing

Issues and pull requests are welcome at github.com/Itsxhadi/video_thumbnail_gen.

---

🏅 Credits & Acknowledgements

This plugin is a fork of the original video_thumbnail package by justsoft, rebranded as video_thumbnail_gen for maintenance and improvements.

The foundational idea, original platform channel design, and initial native implementations are the work of the original author. This fork extends the original with new APIs, a modernised build system, improved error handling, and additional features.

Role	Person
Original Author / Idea	justsoft
Maintainer / Updater	Hadi (Itsxhadi)

---

👤 Author

Hadi

• 📧 [e-mail]
• 🐙 github.com/Itsxhadi

---

📄 License

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