ClyoWallpaper

Automated wallpaper changer and layout editor for Android, syncing with self-hosted ClyoCloud.

ClyoWallpaper is an Android utility designed to turn your self-hosted ClyoCloud instance into a wallpaper engine. It connects to your server to retrieve playlists or full libraries of image assets, then automatically rotates them on your Home screen, Lock screen, or both. It features a crop-and-pan editor to preview and position wallpapers for any display aspect ratio.

Features

Auto-Cycling Wallpaper Service: A persistent foreground service (WallpaperCycleService) with WakeLock support that changes your wallpaper at scheduled intervals (e.g., 15m, 30m, 1h).
Crop and Pan Editor: Drag, pinch, scale, and reposition images to fit your screen aspect ratio. Arrangement coordinates are saved locally per wallpaper.
Sync Source Customization: Cycle through your entire ClyoCloud wallpaper collection, or build a custom local playlist.
Interactive Widget: A home screen widget displaying the current wallpaper name, next up wallpaper, and a button to trigger a manual refresh cycle.
Multi-Destination Support: Set wallpapers target home screen, lock screen, or both simultaneously.
Performance: Leverages WorkManager background jobs and caching to manage battery life and memory usage.

Tech Stack and Architecture

ClyoWallpaper uses native Android service patterns:

graph TD
    Widget[App Widget Provider] -->|Trigger Refresh| Service[WallpaperCycleService]
    Work[WorkManager CycleWorker] -->|Schedule Trigger| Service
    Service -->|Download Bitmap| Net[Network Sync / HTTP]
    Net -->|Fetch Wallpaper| Cloud[ClyoCloud Server]
    Service -->|Load Matrix / Crop| Crop[Crop & Pan Engine]
    Crop -->|Apply| WP[WallpaperManager API]

Component	Technology / API	Purpose
User Interface	Jetpack Compose	Configuration screens, login portal, and crop-and-pan canvas.
Service Layer	Foreground Service & WakeLocks	Handles networking and wallpaper application when the CPU enters standby.
Scheduler	WorkManager & Handlers	Manages execution intervals and schedules future rotations.
System Interface	WallpaperManager API	Applies cropped bitmaps directly to the system Home and Lock screens.
Widget Integration	AppWidgetProvider	Powers the interactive home screen widget with text updates.

Getting Started

Prerequisites

Android Studio (Koala or newer recommended)
Android SDK (API Level 24+ supported, API 34 target)
ClyoCloud Server: A running instance of ClyoCloud containing wallpapers.

Pre-built APKs

For automatically built APKs from the OneDev workflow, download the latest artifacts directly:

Latest APK Artifacts

Build and Install from Source

Clone the Repository:

git clone <repository-url>
cd ClyoWallpaper

Open in Android Studio:
- Select File > Open and choose the ClyoWallpaper directory.
- Sync Gradle dependencies.
Run the Application:
- Compile and deploy to your phone or emulator.
- Log in with your server IP/Domain and credentials (supports 2FA).
- Create a playlist, adjust wallpaper layouts in the editor, and turn on the auto-cycle switch.

Documentation

Detailed architectural details and setup configurations can be found in the project documentation: