v_video_compressor 1.0.0

v_video_compressor: ^1.0.0 copied to clipboard

🚀 Major Release Features #

This is the first stable release of the V Video Compressor Flutter plugin, providing professional-grade video compression with comprehensive features for production apps.

Core Video Compression

• High-Quality Video Compression: Multiple quality presets (High 1080p, Medium 720p, Low 480p, Very Low 360p, Ultra Low 240p)
• Real-Time Progress Tracking: Smooth progress updates with hybrid time/file-size estimation algorithm
• Advanced Compression Options: 20+ customizable parameters including bitrate, resolution, codecs, effects
• Batch Processing: Sequential compression of multiple videos with overall progress tracking
• Compression Estimation: Accurate file size predictions before actual compression
• Cancellation Support: Cancel operations anytime with automatic cleanup

Video Thumbnail Generation

• Single & Batch Thumbnails: Extract thumbnails at specific timestamps from video files
• Format Support: JPEG and PNG output with quality control
• Automatic Scaling: Aspect ratio preservation with custom width/height constraints
• Efficient Processing: Optimized batch generation to minimize video file access

Advanced Configuration System

• Quality Presets: Easy-to-use presets for common use cases
• Custom Resolution: Set exact width/height with validation
• Codec Selection: H.264 (compatibility) and H.265 (efficiency) support
• Audio Control: Custom bitrate, sample rate, channels, or complete removal
• Video Effects: Brightness, contrast, saturation adjustments
• Trimming & Rotation: Cut video segments and rotate orientation
• Encoding Optimization: CRF, two-pass encoding, hardware acceleration

Professional Logging & Debugging

• Comprehensive Logging: Full operation tracking with structured logs
• Error Context: Detailed error information with stack traces for issue reporting
• Performance Metrics: Timing information for all operations
• Debug Information: Method calls, parameters, and results logging

📱 Platform Support #

Platform	Status	Notes
Android	✅ Full Support	API 21+ (Android 5.0+)
iOS	✅ Full Support	iOS 11.0+

🔧 API Reference #

Core Compression Methods

// Get video information
Future<VVideoInfo?> getVideoInfo(String videoPath);

// Estimate compression size
Future<VVideoCompressionEstimate?> getCompressionEstimate(
  String videoPath, VVideoCompressQuality quality, {VVideoAdvancedConfig? advanced}
);

// Compress single video with progress
Future<VVideoCompressionResult?> compressVideo(
  String videoPath, VVideoCompressionConfig config, {Function(double)? onProgress}
);

// Batch compress videos
Future<List<VVideoCompressionResult>> compressVideos(
  List<String> videoPaths, VVideoCompressionConfig config,
  {Function(double, int, int)? onProgress}
);

// Control operations
Future<void> cancelCompression();
Future<bool> isCompressing();

Thumbnail Generation

// Single thumbnail
Future<VVideoThumbnailResult?> getVideoThumbnail(
  String videoPath, VVideoThumbnailConfig config
);

// Multiple thumbnails
Future<List<VVideoThumbnailResult>> getVideoThumbnails(
  String videoPath, List<VVideoThumbnailConfig> configs
);

Resource Management

// Complete cleanup
Future<void> cleanup();

// Selective cleanup
Future<void> cleanupFiles({
  bool deleteThumbnails = true,
  bool deleteCompressedVideos = false,
  bool clearCache = true,
});

🎯 Quality Levels #

Quality	Resolution	Bitrate Range	Use Case
High	1080p HD	8-12 Mbps	Professional quality
Medium	720p	4-6 Mbps	Balanced quality/size
Low	480p	1-3 Mbps	Social media sharing
Very Low	360p	0.5-1.5 Mbps	Messaging apps
Ultra Low	240p	0.2-0.8 Mbps	Maximum compression

⚡ Performance Optimizations #

• Hybrid Progress Algorithm: Combines time-based and file-size monitoring for accurate progress
• Memory Management: Automatic cleanup prevents memory leaks
• Hardware Acceleration: GPU encoding when available on device
• Background Processing: Non-blocking operations with proper lifecycle management
• Efficient Batching: Sequential processing prevents resource conflicts

🔒 Error Handling & Recovery #

• Graceful Degradation: Continue operation when individual videos fail
• Input Validation: Comprehensive validation of all parameters
• Resource Cleanup: Automatic cleanup on errors or cancellation
• Detailed Logging: Full error context for debugging and issue reporting

📚 Documentation #

• Comprehensive API Documentation: All public methods with examples
• Usage Examples: Complete examples for all features
• iOS Version Compatibility: Detailed iOS version support information
• Advanced Configuration Guide: Professional compression settings
• Troubleshooting Guide: Common issues and solutions

🧪 Testing #

• Unit Test Coverage: 95%+ coverage of all public APIs
• Mock Platform: Complete mock implementation for testing
• Integration Tests: Real device testing on Android and iOS
• Edge Case Coverage: Invalid inputs, error conditions, cancellation scenarios
• Performance Testing: Memory usage and compression speed validation

🔨 Development & Maintenance #

• Clean Architecture: Single responsibility, focused functionality
• SOLID Principles: Well-structured, maintainable codebase
• Comprehensive Logging: Production-ready error tracking
• Version Stability: Semantic versioning with backward compatibility
• Documentation: Complete API documentation and examples

🏗️ Architecture Benefits #

Plugin Focus

• ✅ Video Compression: Advanced compression with real-time tracking
• ❌ Video Selection: Use image_picker or file_picker
• ❌ File Management: Use native file operations

Dependencies

dependencies:
  v_video_compressor: ^1.0.0 # Only for compression
  image_picker: ^1.0.7 # For video selection
  file_picker: ^8.0.0 # Alternative file selection
  path_provider: ^2.1.0 # For custom paths (optional)

🎨 Example Usage #

// Basic compression with progress
final result = await compressor.compressVideo(
  videoPath,
  VVideoCompressionConfig.medium(),
  onProgress: (progress) {
    print('Progress: ${(progress * 100).toInt()}%');
  },
);

// Advanced compression
final advancedConfig = VVideoAdvancedConfig(
  customWidth: 1280,
  customHeight: 720,
  videoBitrate: 4000000,
  videoCodec: VVideoCodec.h265,
  removeAudio: false,
  brightness: 0.1,
);

final result = await compressor.compressVideo(
  videoPath,
  VVideoCompressionConfig(
    quality: VVideoCompressQuality.medium,
    advanced: advancedConfig,
  ),
);

// Thumbnail generation
final thumbnail = await compressor.getVideoThumbnail(
  videoPath,
  VVideoThumbnailConfig(
    timeMs: 5000,
    maxWidth: 300,
    maxHeight: 200,
    format: VThumbnailFormat.jpeg,
    quality: 85,
  ),
);

📋 Migration from Pre-Release #

This is the first stable release. If upgrading from development versions:

1. Update pubspec.yaml: v_video_compressor: ^1.0.0
2. Run: flutter pub get
3. Review API: Check method signatures for any breaking changes
4. Test thoroughly: Validate all compression workflows

🐛 Known Issues & Limitations #

• iOS Simulator: Hardware acceleration not available in simulator
• Large Files: Very large files (>4GB) may require additional memory
• Background Processing: iOS may limit background compression time

🔮 Roadmap #

• 1.1.0: Enhanced progress algorithms and additional presets
• 1.2.0: Video filtering and advanced effects
• 1.3.0: Cloud storage integration helpers
• 2.0.0: Breaking changes for improved performance

📄 License #

MIT License - See LICENSE file for details.

🤝 Contributing #

We welcome contributions! Please read our Contributing Guide for details.

📞 Support #

• Issues: GitHub Issues
• Documentation: API Documentation
• Examples: Example App

---

Previous Releases #

Added #

• Video Thumbnail Generation API: Extract thumbnails from video files at specific timestamps

  • getVideoThumbnail(): Generate a single thumbnail from a video
  • getVideoThumbnails(): Generate multiple thumbnails from a video at different timestamps
  • VVideoThumbnailConfig: Configuration for thumbnail generation (time, dimensions, format, quality)
  • VVideoThumbnailResult: Result containing thumbnail path, dimensions, and metadata
  • Support for JPEG and PNG output formats
  • Automatic aspect ratio preservation with custom width/height constraints
  • Android implementation using MediaMetadataRetriever
  • iOS implementation using AVAssetImageGenerator

• Resource Cleanup API: Free up storage space and resources

  • cleanup(): Complete cleanup of all temporary files and resources
  • cleanupFiles(): Selective cleanup with options for:
    • deleteThumbnails: Remove generated thumbnail files
    • deleteCompressedVideos: Optionally remove compressed video files
    • clearCache: Clear temporary cache and free memory
  • Automatic cancellation of ongoing operations during cleanup
  • Cross-platform implementation for Android and iOS

Enhanced #

• Updated plugin description to include thumbnail generation capabilities
• Added comprehensive documentation and examples for thumbnail API
• Enhanced example app with thumbnail generation demo
• Added resource management and cleanup functionality to example app
• Improved memory management with automatic resource cleanup

• Initial development release
• Basic compression functionality
• Android platform support