media_picker_guard 0.0.1-beta.1

Validates media file size, duration, and format before upload with friendly error messages. Prevents server rejections and improves user experience.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.0.1-beta.1 - 2024-12-19

🎉 Initial Release - Beta

This is the first beta release of Media Picker Guard, a comprehensive Flutter package for validating media files before upload.

✨ Added

Core Features

• File Size Validation: Set minimum and maximum file size limits with human-readable error messages
• Duration Validation: Validate video and audio duration constraints (with placeholder implementation)
• Format Validation: Restrict file extensions and MIME types with comprehensive format detection
• File Access Validation: Check file accessibility and basic corruption detection
• Custom Error Messages: Fully customizable, user-friendly error messages

Pre-built Configurations

• MediaPickerGuard.imageUploadConfig() - Optimized for image uploads (profile pictures, galleries)
• MediaPickerGuard.videoUploadConfig() - Configured for video uploads (social media, content)
• MediaPickerGuard.audioUploadConfig() - Set up for audio uploads (podcasts, music)
• MediaPickerGuard.documentUploadConfig() - Ready for document uploads (PDFs, office docs)

Validation Methods

• validateFile() - Comprehensive file validation with detailed results
• validateFiles() - Batch validation for multiple files
• isFileValid() - Quick boolean validation check for performance
• getFileInfo() - Extract detailed file information without validation

Error Handling

• Friendly Error Messages: User-readable error descriptions
• Error Context: Additional metadata for debugging and logging
• Multiple Error Support: Handle multiple validation failures simultaneously
• Custom Error Messages: Override default messages with localized versions

File Type Support

• Images: JPG, JPEG, PNG, GIF, WebP, BMP, SVG
• Videos: MP4, MOV, AVI, MKV, WMV, FLV, WebM
• Audio: MP3, WAV, AAC, OGG, FLAC, M4A
• Documents: PDF, DOC, DOCX, TXT, RTF, XLS, XLSX, PPT, PPTX

Platform Support

• ✅ Android: Full functionality
• ✅ iOS: Full functionality
• ✅ Web: Full functionality
• ✅ Desktop: Full functionality (Windows, macOS, Linux)

🏗️ Architecture

Core Classes

• MediaPickerGuard - Main validation class with static methods
• MediaValidationConfig - Configuration class for validation rules
• MediaValidationResult - Result object with validation status and errors
• MediaValidationError - Detailed error information with context
• MediaType - Enum for different media types (Image, Video, Audio, Document, Any)
• ValidationErrorType - Enum for different error types

Validators

• SizeValidator - Handles file size validation with MB/KB formatting
• FormatValidator - Manages file extension and MIME type validation
• DurationValidator - Validates media duration (placeholder implementation)

🧪 Testing & Quality

Test Coverage

• 26 Comprehensive Tests: Full coverage of all major functionality
• Unit Tests: Individual component testing
• Integration Tests: End-to-end validation scenarios
• Error Handling Tests: Edge cases and error conditions
• Performance Tests: Quick validation and batch processing

Code Quality

• Flutter Lints: Passes all recommended linting rules
• Type Safety: Full Dart type safety with null safety
• Documentation: Comprehensive API documentation and examples
• Clean Architecture: Well-organized, maintainable code structure

📚 Documentation & Examples

Documentation

• Comprehensive README: Usage examples, API reference, common patterns
• API Documentation: Detailed method and class documentation
• Error Reference: Complete error type documentation with user messages

Interactive Example App

• Complete Flutter App: Fully functional example with beautiful UI
• Multiple Validation Types: Switch between different validation configurations
• Real-time Testing: Pick files and see validation results immediately
• File Information Display: Shows detailed file metadata
• Error Demonstration: Visual feedback for validation failures

Code Examples

• Quick Start: Simple usage examples for immediate implementation
• Advanced Patterns: Complex validation scenarios and error handling
• Custom Configurations: How to create custom validation rules
• Batch Processing: Multiple file validation examples

🔧 Dependencies

Runtime Dependencies

• flutter: SDK dependency for Flutter framework
• path: ^1.9.0 - File path manipulation utilities
• mime: ^1.0.4 - MIME type detection and validation

Development Dependencies

• flutter_test: Testing framework for unit and widget tests
• flutter_lints: ^5.0.0 - Dart linting rules for code quality

📋 Known Limitations (Beta)

• Duration Validation: Currently uses placeholder implementation based on file size estimation
  • Real duration validation requires platform-specific media libraries
  • Future versions will include proper media duration detection
• File Integrity: Basic corruption detection only
  • Advanced integrity checking planned for future releases
• Image Dimensions: Not yet supported (planned for future versions)
• Video Resolution: Not yet supported (planned for future versions)

🔮 Roadmap

Planned features for upcoming releases:

• ❌ Real media duration detection using platform channels
• ❌ Image dimension validation (width/height constraints)
• ❌ Video resolution validation
• ❌ Audio quality/bitrate validation
• ❌ Advanced file integrity checking
• ❌ Cloud storage integration helpers
• ❌ Batch processing with progress callbacks
• ❌ Content-based validation (AI/ML integration)

📦 Package Information

• Package Name: media_picker_guard
• Version: 0.0.1-beta.1
• Minimum SDK: Dart ^3.8.1, Flutter ">=1.17.0"
• License: MIT
• Repository: https://github.com/waqas/media_picker_guard

🤝 Contributing

This is a beta release and we welcome feedback, bug reports, and contributions!

• Report issues on GitHub
• Submit feature requests
• Contribute code improvements
• Help improve documentation

---

Note: This is a beta release intended for testing and feedback. While the core functionality is stable, the API may change based on community feedback before the 1.0.0 release.