medias_viewer 0.3.2

A powerful and customizable Flutter media viewer for images and videos with zoom, swipe navigation, and video controls.

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.3.2 - 2025-10-06

• Update format and readme

0.3.1 - 2025-10-03

Added

• Video UX Optimizations: Enhanced video playback experience with smart UI controls
  • hideArrowsWhenVideoPlays config option (default: true) - Navigation arrows automatically fade out during video playback and fade back in when paused
  • backButtonPadding config option (default: EdgeInsets.only(top: 16, left: 8)) - Configurable back button positioning to prevent overlap with Chewie's fullscreen button
  • SafeArea wrapper for video controls - Ensures video controls respect device notches and safe areas on all devices

Enhanced

• Smooth animations: Navigation arrows now use AnimatedOpacity with 300ms fade transitions for better UX
• Video state tracking: Implemented callback system to track video playing/paused state
• Better ergonomics: Back button position now customizable to avoid UI element conflicts

Technical

• Video playing state propagates from VideoPlayerController → VideoViewerWidget → MediaViewer
• AnimatedOpacity with IgnorePointer ensures arrows don't interfere with touch events when hidden
• Proper video state listener cleanup in dispose() method

Example

MediaViewer(
  items: [MediaItem.videoUrl('https://example.com/video.mp4')],
  config: MediaViewerConfig(
    // Arrows automatically hide during video playback
    hideArrowsWhenVideoPlays: true,
    
    // Custom back button position to avoid overlap
    backButtonPadding: EdgeInsets.only(top: 20, left: 12),
    
    // Video controls respect SafeArea automatically
    showVideoControls: true,
  ),
);

0.3.0 - 2025-10-03

Added

• Automatic media type detection: New feature to automatically detect whether a media item is an image or video based on file extension
  • New constructors: MediaItem.url(), MediaItem.path(), MediaItem.asset()
  • Simplifies API usage - no need to specify .imageUrl() or .videoUrl() anymore
  • enableAutoDetectMediaType config option (default: false for backward compatibility)
  • Supports common image formats: jpg, jpeg, png, gif, webp, bmp, svg
  • Supports common video formats: mp4, mov, avi, mkv, webm, flv, m4v, wmv
  • Clear error messages when extension is not recognized
  • Case-insensitive extension matching
  • Handles URLs with query parameters and fragments

Technical

• New MediaTypeDetector utility class for extension-based detection
• Comprehensive unit tests for auto-detection (25+ test cases)
• Updated documentation with auto-detection examples and supported formats
• Future-proof design for HTTP Content-Type detection

Example

// Before (explicit type specification)
MediaItem.imageUrl('https://example.com/photo.jpg')
MediaItem.videoUrl('https://example.com/video.mp4')

// After (automatic detection)
MediaItem.url('https://example.com/photo.jpg')  // Detected as image
MediaItem.url('https://example.com/video.mp4')  // Detected as video

0.2.0 - 2025-10-03

Added

• Navigation arrows: Optional left/right arrows for manual navigation between media items
  • Configurable position (center, top, bottom)
  • Customizable color and size
  • showNavigationArrows, navigationArrowsPosition, arrowsColor, arrowsSize config options
• Back button: Optional close button in top-left corner
  • Configurable color
  • showBackButton, backButtonColor config options
• Swipe down to dismiss: Gesture to close the viewer by swiping down
  • Smooth animation with fade-out effect
  • enableDismissOnSwipeDown config option
• SafeArea support: All UI controls now respect device notches and safe areas
• Swipe threshold configuration: swipeToPageThreshold to control horizontal swipe sensitivity

Fixed

• Improved swipe detection: Better distinction between horizontal page swipes and image pan gestures
• Smooth transitions: Eliminated visual glitches when swiping between zoomed images
• Image caching: Better preloading for smoother transitions

Enhanced

• Example app now includes 10 different demos showcasing all features
• Updated tests to cover new functionality (12 tests passing)
• Improved documentation with detailed examples

0.1.0 - 2025-10-03

Added

• Initial release of medias_viewer package
• Image viewer with zoom capabilities (pinch-to-zoom and double-tap)
• Video viewer with playback controls using Chewie
• Swipe navigation between media items using PageView
• Customizable page indicator showing current position (e.g., "1 of 5")
• Support for network URLs, local files, and asset paths
• Configurable appearance (colors, indicator position, styles)
• Hero animations support for images
• Auto-play option for videos
• Loop navigation option
• Fullscreen support for videos
• Cached network images for better performance
• Comprehensive configuration options via MediaViewerConfig
• Complete example app with multiple use cases
• Unit tests for models and core functionality
• Full documentation with API reference
• Multi-platform support (Android, iOS, Web, Desktop)

Features

• Image Support:

  • Zoom with pinch and double-tap gestures
  • Pan zoomed images
  • Network, file, and asset sources
  • Hero animations

• Video Support:

  • Auto-pause when swiping away
  • Playback controls (play, pause, seek)
  • Fullscreen mode
  • Network, file, and asset sources

• Customization:

  • Background colors
  • Indicator position (6 positions available)
  • Custom indicator styles
  • Enable/disable zoom
  • Enable/disable loop
  • Auto-play videos

• Performance:

  • Efficient memory management
  • Proper video controller disposal
  • Network image caching
  • Smooth transitions