video_snapshot_generator #

A Flutter package for generating video snapshots and thumbnails with custom dimensions and quality settings. This package provides a simple and efficient way to generate thumbnails from video files in Flutter applications.

Features #

• 🎬 Extract frames from video files at specific time positions
• 📏 Customizable frame dimensions (width and height)
• 🎨 Quality control settings (1-100)
• ⏰ Extract frames at specific time positions
• 🖼️ Multiple output formats (JPEG, PNG, WebP)
• 📱 Cross-platform support (Android, iOS)
• 🔒 Automatic permission handling
• ⚡ Efficient frame extraction
• 🧪 Comprehensive error handling
• 🔄 Extract multiple frames at different time positions
• 📁 Custom output path support
• 🎯 Precise time-based extraction

Getting Started #

Installation #

Add this dependency to your pubspec.yaml file:

dependencies:
  video_snapshot_generator: ^0.0.1

Then run:

flutter pub get

Platform Setup #

Android

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

For Android 13+ (API level 33+), you may also need:

<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>

iOS

No additional setup required for iOS.

Web

No additional setup required for web.

Desktop

No additional setup required for desktop platforms.

Usage #

Basic Usage #

import 'package:video_snapshot_generator/video_snapshot_generator.dart';

// Generate a thumbnail with default settings
final result = await VideoSnapshotGenerator.generateThumbnail(
  videoPath: '/path/to/video.mp4',
);

print('Frame saved at: ${result.path}');
print('Dimensions: ${result.width}x${result.height}');
print('File size: ${result.dataSize} bytes');

Advanced Usage #

import 'package:video_snapshot_generator/video_snapshot_generator.dart';

// Generate a thumbnail with custom settings
final result = await VideoSnapshotGenerator.generateThumbnail(
  videoPath: '/path/to/video.mp4',
  options: ThumbnailOptions(
    width: 640,
    height: 480,
    quality: 90,
    timeMs: 5000, // Generate at 5 seconds
    format: ThumbnailFormat.png,
  ),
);

// Extract multiple frames at different time positions
final results = await VideoSnapshotGenerator.generateMultipleThumbnails(
  videoPath: '/path/to/video.mp4',
  timePositions: [0, 5000, 10000, 15000], // 0s, 5s, 10s, 15s
  options: ThumbnailOptions(
    width: 320,
    height: 240,
    quality: 75,
  ),
);

ThumbnailOptions #

The ThumbnailOptions class allows you to customize the frame extraction:

ThumbnailResult #

The ThumbnailResult class contains information about the extracted frame:

ThumbnailFormat #

Supported output formats:

• ThumbnailFormat.jpeg - JPEG format (default)
• ThumbnailFormat.png - PNG format
• ThumbnailFormat.webP - WebP format

Error Handling #

The package throws ThumbnailException when frame extraction fails:

try {
  final result = await VideoSnapshotGenerator.generateThumbnail(
    videoPath: '/path/to/video.mp4',
  );
} on ThumbnailException catch (e) {
  print('Frame extraction failed: ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}

Common Error Scenarios #

• File not found: The specified video file doesn't exist
• Permission denied: Storage permissions are not granted
• Invalid parameters: Width, height, quality, or time values are out of range
• Unsupported format: The video format is not supported
• Insufficient storage: Not enough storage space for the frame

Platform Support #

Performance Considerations #

• Memory usage: Large video files may consume significant memory during processing
• Processing time: Frame extraction time depends on video size and complexity
• Storage: Extracted frames are stored temporarily by default
• Quality vs. Size: Higher quality settings result in larger file sizes

Best Practices #

1. Request permissions early: Request storage permissions before attempting to extract frames
2. Handle errors gracefully: Always wrap frame extraction in try-catch blocks
3. Use appropriate dimensions: Choose dimensions that balance quality and performance
4. Clean up files: Remove temporary frames when they're no longer needed
5. Validate input: Ensure video paths exist and parameters are within valid ranges

Example #

Check out the example/ directory for a complete Flutter application demonstrating how to use this package. The example app includes:

• Video file selection
• Customizable frame extraction options
• Real-time preview
• Multiple frame extraction
• Error handling
• Modern Material 3 UI

Testing #

The package includes comprehensive test coverage:

# Run unit tests
flutter test

# Run integration tests
flutter test test/integration_test.dart

# Generate test coverage report
flutter test --coverage

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request. Before contributing, please ensure:

1. All tests pass
2. Code follows the project's style guidelines
3. New features include appropriate tests
4. Documentation is updated

Development Setup #

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License #

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

Dependencies #

This package depends on:

• video_thumbnail: Core video frame extraction functionality
• path_provider: File system path management
• permission_handler: Cross-platform permission handling

Support #

If you encounter any issues or have questions, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information

Changelog #

See CHANGELOG.md for a detailed list of changes and version history.

Roadmap #

Future versions may include:

• Video metadata extraction
• Batch processing capabilities
• Custom frame shapes
• Advanced filtering options
• Performance optimizations
• Additional output formats

Acknowledgments #

• video_thumbnail package for core functionality
• path_provider for file system access
• permission_handler for permission management
• Flutter team for the excellent framework