async_wallpaper

Android wallpaper plugin for Flutter with support for:

  • static wallpaper from URL or file path
  • home, lock, or both targets
  • live wallpaper from local video file
  • opening Android wallpaper chooser
  • wallpaper rotation with interval, charging, and time-of-day triggers

Demo

Example Demo Example App Screenshot
Example Demo Example App Screenshot

Version 3.1.0 highlights

  • Flutter baseline: 3.41.4
  • Android tooling: AGP 8.11.1, Gradle 8.14, Kotlin plugin 2.2.20, Java 17
  • Android minSdk raised to 24
  • Android host code migrated from Java to Kotlin
  • Rotation API support: start, stop, status, and rotate-now
  • Rotation triggers: interval, charging connected, and time-of-day active hours
  • Rotation playlist supports mixed URL and file sources with local caching

Requirements

  • Flutter >=3.41.4
  • Dart >=3.9.0 <4.0.0
  • Android minSdk 24

Installation

dependencies:
  async_wallpaper: ^3.1.0

Usage

import 'package:async_wallpaper/async_wallpaper.dart';

Set wallpaper from URL

final WallpaperResult result = await AsyncWallpaper.setWallpaper(
  const WallpaperRequest(
    target: WallpaperTarget.both,
    sourceType: WallpaperSourceType.url,
    source: 'https://example.com/wallpaper.jpg',
    goToHome: true,
  ),
);

if (!result.isSuccess) {
  debugPrint('Wallpaper failed: ${result.error?.message}');
}

Set wallpaper from file

final WallpaperResult result = await AsyncWallpaper.setWallpaper(
  WallpaperRequest(
    target: WallpaperTarget.home,
    sourceType: WallpaperSourceType.file,
    source: '/storage/emulated/0/Download/wallpaper.jpg',
  ),
);

Set live wallpaper

final WallpaperResult result = await AsyncWallpaper.setLiveWallpaper(
  const LiveWallpaperRequest(
    filePath: '/storage/emulated/0/Download/live.mp4',
    goToHome: false,
  ),
);

Open wallpaper chooser

await AsyncWallpaper.openWallpaperChooser();

Start wallpaper rotation (Android only)

final WallpaperResult result = await AsyncWallpaper.startWallpaperRotation(
  const WallpaperRotationRequest(
    sources: <WallpaperRotationSource>[
      WallpaperRotationSource(
        sourceType: WallpaperSourceType.url,
        source: 'https://example.com/wallpaper1.jpg',
      ),
      WallpaperRotationSource(
        sourceType: WallpaperSourceType.file,
        source: '/storage/emulated/0/Download/wallpaper2.jpg',
      ),
    ],
    target: WallpaperTarget.both,
    intervalMinutes: 60,
    order: WallpaperRotationOrder.shuffle,
    triggers: <WallpaperRotationTrigger>{
      WallpaperRotationTrigger.interval,
      WallpaperRotationTrigger.charging,
      WallpaperRotationTrigger.timeOfDay,
    },
    activeHoursStart: 6,
    activeHoursEnd: 23,
  ),
);

Notes:

  • Minimum interval is 15 minutes.
  • URL entries are cached locally before rotation starts.
  • Rotation runs from local files only.
  • Charging trigger rotates when power is connected.
  • Time-of-day trigger rotates only between activeHoursStart and activeHoursEnd.

Rotation controls

await AsyncWallpaper.rotateWallpaperNow();
await AsyncWallpaper.getWallpaperRotationStatus();
await AsyncWallpaper.stopWallpaperRotation();

Material You support check

final MaterialYouSupport support = await AsyncWallpaper.checkMaterialYouSupport();

Migration from 2.x

  • HOME_SCREEN, LOCK_SCREEN, BOTH_SCREENS are replaced by WallpaperTarget enum.
  • previous bool-based setter methods are replaced with typed request APIs.
  • internal toasts were removed; handle UX messaging in your app.

Bugs and Feature Requests

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR.

License

MIT

Libraries

async_wallpaper
Flutter API for applying Android wallpapers asynchronously.
pigeon_impl_api