flutter_wallpaper_plus 1.0.0

Production-grade Flutter plugin for setting image and video (live) wallpapers on Android. Supports assets, files, URLs, caching, thumbnails, and structured error handling.

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.

1.0.0 — 2026-02-18

Changed

• Android live wallpaper service label now inherits the host app label, so the picker shows the app name instead of a hardcoded "Video Wallpaper" label.

Fixed

• Android example app no longer goes black/white after wallpaper apply on OEMs that recreate the activity (e.g., MIUI): MainActivity now reuses a cached FlutterEngine across host activity recreation.
• Android live wallpaper target handling now validates unsupported lock-only requests and improves home behavior by creating a dedicated lock wallpaper snapshot before launching the system picker (best effort, OEM-dependent).
• Android image wallpaper both target now applies OEM fallback (combined flags, then explicit home+lock writes on known restrictive OEMs) and reports manufacturerRestriction when lock updates are blocked.
• Android live wallpaper home-target lock snapshot now uses permission-independent bitmap fallback when direct wallpaper file read is restricted by OEM permission policy.
• Android now fail-fast returns manufacturerRestriction for lock/both targets on known restrictive OEMs (Xiaomi/Redmi/Oppo/Vivo/Realme) to avoid misleading success.

Added

Chooser & UX

• Added FlutterWallpaperPlus.openNativeWallpaperChooser(source: ...) with required WallpaperSource (asset/file/url) to open native chooser flow from explicit media source.
• Added optional goToHome flag across public plugin methods for best-effort app minimization/home navigation behavior.

Image Wallpaper

• Set image wallpaper from Flutter asset, local file, or remote URL
• Target home screen, lock screen, or both
• Memory-efficient streaming via WallpaperManager.setStream()
• Pre-flight checks: isWallpaperSupported, isSetWallpaperAllowed

Video (Live) Wallpaper

• Set video wallpaper using Android's WallpaperService + Media3 ExoPlayer
• Enable/disable audio at runtime
• Seamless looping via Player.REPEAT_MODE_ALL
• Survives app kill (config persisted in SharedPreferences)
• Handles screen rotation without crashing
• Pauses when not visible, resumes on home screen (battery saving)
• Automatic error recovery (seek to start + re-prepare)
• Two-strategy intent launch (direct component → fallback picker)

Thumbnail Generation

• Extract video thumbnails using MediaMetadataRetriever
• 3-level frame extraction fallback strategy
• Proportional scaling to max 480px dimension
• JPEG compression with configurable quality (1–100)
• Optional thumbnail caching for instant subsequent calls
• Explicit Bitmap recycling for memory efficiency

Caching System

• SHA-256 filename hashing for collision-resistant cache keys
• LRU eviction when cache exceeds configurable size limit (default 200 MB)
• Separate directories for media files and thumbnails
• Atomic file writes (temp file + rename) to prevent corruption
• OkHttp for reliable HTTP downloads with timeouts and retries

Error Handling

• Structured WallpaperResult returned from every operation
• WallpaperErrorCode enum with 11 specific error codes
• No exceptions thrown for operational failures
• Input validation at WallpaperSource construction time

Permissions

• Automatic handling across Android 7–14
• SET_WALLPAPER (normal, auto-granted)
• READ_EXTERNAL_STORAGE (API < 33) / READ_MEDIA_* (API 33+)
• App-internal path detection (skips permission check)
• FEATURE_LIVE_WALLPAPER capability check

Toast Customization

• Optional Android Toast notifications
• Custom success and error messages
• showToast flag to disable (handle UI yourself)

Public API

• FlutterWallpaperPlus.setImageWallpaper()
• FlutterWallpaperPlus.setVideoWallpaper()
• FlutterWallpaperPlus.getVideoThumbnail()
• FlutterWallpaperPlus.getTargetSupportPolicy()
• FlutterWallpaperPlus.clearCache()
• FlutterWallpaperPlus.getCacheSize()
• FlutterWallpaperPlus.setMaxCacheSize()