Flutter Wallpaper Plus #

Production-grade Flutter plugin for setting image and video (live) wallpapers on Android.

• Set wallpaper from asset, file, or URL
• Use typed results and structured error codes
• Generate and cache video thumbnails
• Manage cache with size limits + LRU eviction
• Handle OEM target limitations with getTargetSupportPolicy()
• Fixed: Now works on Xiaomi/Redmi/Oppo/Vivo/Realme devices with sequential writes

Support #

If you find this plugin useful, please consider supporting development:

Table of Contents #

• Platform Support
• Installation
• Android Permissions
• Quick Start
• API Reference
• Target Behavior and OEM Limitations
• Real Device Results
• FAQ
• Architecture
• Roadmap
• License

Platform Support #

• Flutter: >=3.3.0
• Dart: ^3.11.0
• Platform: Android only
• Android API: 24+

Installation #

Add the package:

dependencies:
  flutter_wallpaper_plus: ^1.0.2

Install dependencies:

flutter pub get

Android Permissions #

Permissions are declared by the plugin manifest:

<uses-permission android:name="android.permission.SET_WALLPAPER" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<uses-permission
    android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

Permission notes:

• SET_WALLPAPER, INTERNET, and ACCESS_NETWORK_STATE are normal permissions (auto-granted).
• Storage permissions are only needed for WallpaperSource.file(...) when reading outside app-internal storage.
• WallpaperSource.asset(...) and WallpaperSource.url(...) do not require storage read permission.

Quick Start #

Import once:

import 'package:flutter_wallpaper_plus/flutter_wallpaper_plus.dart';

Set Image Wallpaper #

final result = await FlutterWallpaperPlus.setImageWallpaper(
  source: WallpaperSource.url('https://example.com/wallpaper.jpg'),
  target: WallpaperTarget.home,
);

if (result.success) {
  print('Applied: ${result.message}');
} else {
  print('Failed: ${result.errorCode.name} - ${result.message}');
}

Set Video (Live) Wallpaper #

final result = await FlutterWallpaperPlus.setVideoWallpaper(
  source: WallpaperSource.url('https://example.com/live.mp4'),
  target: WallpaperTarget.home,
  enableAudio: false,
  loop: true,
  goToHome: false,
);

Notes:

• Android opens the system live wallpaper chooser and user confirmation is required.
• WallpaperTarget.lock is not supported for live video wallpaper (WallpaperErrorCode.unsupported).
• Live wallpaper service runs independently after apply (survives app process death).
• Selected live wallpaper video is persisted in app-internal storage so it remains available even after cache cleanup.

Open Native Wallpaper Chooser #

final result = await FlutterWallpaperPlus.openNativeWallpaperChooser(
  source: WallpaperSource.url('https://example.com/wallpaper.jpg'),
  goToHome: true, // optional best-effort: minimize app before chooser
);

source is required and supports:

• WallpaperSource.asset(...)
• WallpaperSource.file(...)
• WallpaperSource.url(...)

Source path/URL must be non-empty.

Get Device Target Support Policy #

Use this before rendering target options in UI:

final policy = await FlutterWallpaperPlus.getTargetSupportPolicy();

if (!policy.allowImageBoth) {
  // Disable "Image -> Both" action in UI
}

Generate Video Thumbnail #

final bytes = await FlutterWallpaperPlus.getVideoThumbnail(
  source: WallpaperSource.url('https://example.com/video.mp4'),
  quality: 50,
  cache: true,
);

if (bytes != null) {
  // Example: Image.memory(bytes)
}

Cache Management #

final size = await FlutterWallpaperPlus.getCacheSize();
print('Cache bytes: $size');

await FlutterWallpaperPlus.setMaxCacheSize(100 * 1024 * 1024); // 100 MB

final clearResult = await FlutterWallpaperPlus.clearCache();
print(clearResult.message);

API Reference #

FlutterWallpaperPlus #

WallpaperSource #

WallpaperTarget #

WallpaperResult #

WallpaperErrorCode #

• none
• sourceNotFound
• downloadFailed
• unsupported
• permissionDenied
• applyFailed
• videoError
• thumbnailFailed
• cacheFailed
• manufacturerRestriction
• unknown

Target Behavior and OEM Limitations #

This section is important for product behavior and user expectations.

Live Wallpaper Targeting Rules #

• Live wallpaper always uses Android's native chooser flow.
• WallpaperTarget.lock for live video is unsupported on public Android APIs.
• Final behavior for live wallpapers can still be altered by OEM system apps/policies.

Known OEM Restrictions #

On some OEM ROMs (commonly Xiaomi/Redmi/Oppo/Vivo/Realme), lock-screen wallpaper behavior may be controlled by system policy (carousel/slideshow/theme engines). In these environments:

• Third-party apps may not reliably force lock wallpaper persistence.
• Lock/both behavior can diverge from what user selected in the system UI.
• Similar behavior is likely on other heavily customized OEM ROMs with lock-screen themes/carousel features.

v1.0.2 Fix: The plugin now uses sequential writes with 500ms delay between home and lock screen wallpaper sets, matching the working approach from async_wallpaper. This significantly improves reliability on restrictive OEMs. The plugin no longer blocks lock/both targets - it attempts them and relies on the sequential write approach for success.

Real Device Results #

Observed behavior from real testing (as of February 24, 2026):

v1.0.2 Update: The sequential write approach (500ms delay between home and lock) fixes the previous failures on Oppo and Redmi devices.

Recommended App-Side UX #

• Query getTargetSupportPolicy() before showing target options.
• Disable unreliable target choices in your UI.
• Prefer home target by default on restrictive OEMs.
• Explain to users when device policy may override lock-screen wallpaper behavior.

FAQ #

Does video wallpaper keep playing if the app is closed? #

Yes. Playback is hosted in WallpaperService and is independent from your Flutter UI process.

Why does video wallpaper open a system screen? #

Android requires user confirmation for live wallpaper selection.

Why does "Home only" sometimes affect lock screen? #

Some OEMs mirror lock/home wallpaper behavior unless lock wallpaper is independently controlled by the ROM.

Why does lock wallpaper revert after a few seconds on some devices? #

Some ROM features (for example lock-screen slideshow/carousel) can override third-party lock wallpaper shortly after apply.

What formats are supported? #

• Video: device codec support via MediaCodec/ExoPlayer (MP4 H.264 recommended for best compatibility)
• Image: device-supported bitmap formats (JPEG/PNG/WebP/BMP, etc.)

Architecture #

Flutter (Dart API)
  -> MethodChannel (com.flutterwallpaperplus/methods)
    -> Kotlin plugin layer
      -> ImageWallpaperManager
      -> VideoWallpaperService + ExoPlayer
      -> ThumbnailGenerator
      -> SourceResolver
      -> CacheManager (LRU)
      -> PermissionHelper

Roadmap #

Planned next additions:

• Expand OEM policy coverage and reliability hints for more manufacturers
• Add more end-to-end integration testing across Android OEM variants

License #

MIT. See LICENSE.