Muzei: an Android live wallpaper that rotates art, and an API for building your own source

What Muzei solves, and who it is built for

An Android home screen is mostly icons and widgets, and a static wallpaper sits behind them permanently. Muzei changes that by rotating the background image and then deliberately getting out of the way: the README describes the wallpaper as blurring and dimming artwork so that icons and widgets stay in the spotlight, with a double touch or the Muzei app opening the artwork at full size. The rotation can come from curated art or from the user's own gallery, and the README says Muzei will rotate through favorite photos every few hours. There are two audiences here, and they are different. The first is an Android user who wants a changing home screen without picking a new image by hand. The second is a developer who wants to supply images to that home screen: the README states that Muzei offers a simple API for building your own wallpaper source, and points at the API docs and the Unsplash example source. The repository layout backs this up. Alongside main/, wearable/ and gl-wallpaper/ sit muzei-api/, android-client-common/, example-unsplash/ and four source modules: source-featured-art, source-gallery, source-single and extensions. The project is not only an app. It is a small platform with a published contract for third-party sources.

How the wallpaper source API and the client modules fit together

The split visible in the repository is between the client, the contract and the sources. muzei-api/ holds the API that a wallpaper source compiles against, and android-client-common/ holds code shared by the Android client modules. The main/ module is the phone app; wearable/ and gl-wallpaper/ are separate surfaces that reuse the same client pieces. Sources are their own modules, which is why source-gallery and source-featured-art are siblings of main/ rather than packages inside it. example-unsplash/ is a complete third-party source written against the same API, and it is the module to read if you want to see the intended shape of an integration rather than infer it from the API docs. The api3.4.x release tags (api3.4.0, api3.4.1, api3.4.2) map to that API line, which tells you the versioned surface is the API, not the app. The practical consequence is that a source does not need to know how the wallpaper is rendered or blurred; it supplies images and metadata, and the client handles display. The README does not describe the internal data flow between a source and the renderer beyond the API link, so the API docs at api.muzei.co are the place to confirm what a source must return.

Installing Muzei and running the Unsplash example source

For a phone, the README gives one installation path: the Google Play listing for net.nurik.roman.muzei, linked from the README with the standard Play badge. There is no APK download and no sideloading instructions in the README, so treat Play as the supported route and ignore search results offering a modded APK. For a developer, the route is the repository. Clone it and build with the Gradle wrapper that is checked in at the root. The wrapper is invoked as ./gradlew on Linux and macOS, and gradlew.bat on Windows. The repository does not document a required JDK or Android SDK level in the README, so read build.gradle and gradle.properties before assuming a toolchain. Two files in the root are templates rather than working configuration: local.properties.example and keystore.properties.example. Copy them to local.properties and keystore.properties and fill in your own SDK path and signing values. The example source is a separate module, so the most direct way to see it run is to build and install it on a device or emulator from the repository root: ./gradlew :example-unsplash:installDebug. The README does not state the exact module task name or the application id used by the example, so confirm both in the module's build.gradle before running anything, and expect the example to need network access because Unsplash images are fetched remotely.

Where Muzei is the wrong tool

Muzei is an Android live wallpaper, and nothing in the repository changes that. Searches for a Windows or PC version, an iOS version, or a standalone download have no answer in this material: the README only links Google Play and the API docs, the top-level modules are Android and Wear modules, and there is a web/ directory but no described desktop or iOS product. If your target is a desktop background, Muzei is not it. The second limitation is API stability and maintenance. The three releases listed are api3.4.0 (2020-07-23), api3.4.1 (2022-01-03) and api3.4.2 (2024-06-16). The gaps are measured in years, so a source built against the API should not assume frequent contract changes in either direction: there is little evidence of churn, and equally little evidence of active API evolution. The repository itself is not archived and the last push was on 2026-09-17, but that activity is not the same as a released API change, and the README does not describe a deprecation policy, a support window or a rollback path for a source that breaks. Third, the README is thin on operational detail: it does not document permissions a source must request, offline behavior, or what happens when a source fails to return images. Those gaps matter more for a production source than for a personal one.

Muzei compared with a general wallpaper app or a plain image rotator

The obvious alternative for a user is a wallpaper app that ships a fixed catalog and lets you tap an image to set it. That approach is simpler and involves no API, no source module and no rotation logic, but the image stops changing once you set it. Muzei's difference is the source model: the README frames the app around a rotating feed and an API that lets anyone supply that feed, which is why example-unsplash exists as a first-party demonstration rather than a hidden integration. A second alternative is a tasker-style automation that swaps the wallpaper on a schedule from a folder. That gives full control over timing and files, but it does not provide the blur-and-dim treatment the README describes, and it does not give you a shareable source that other Muzei users can install. The trade-off is the reverse of what people usually assume: Muzei is more work than a static wallpaper and less work than building your own rotation service, and the API is the reason. If you only want one image that never changes, none of this is worth the setup.

Licence, contribution and upgrade cost

Muzei is Apache-2.0, per the LICENSE file in the repository root, and the README does not add any additional terms. That is a permissive licence, which in practice means you can build a wallpaper source, ship it, and keep your own source code closed if you want, provided you meet the licence's notice requirements. This is a description of the licence text, not legal advice; read LICENSE and, if you are redistributing the app or a modified client, take your own counsel. The repository also carries a CODE_OF_CONDUCT.md and a PRIVACY.md, plus a crowdin.yml, which indicates translations are managed through Crowdin. The upgrade cost for a source author is the API version: releases are tagged api3.4.0 through api3.4.2, so pinning to a specific tag and reading the API docs before bumping is the low-risk path. Because the gaps between those tags run from months to years, a source that works today is unlikely to be broken by a rapid series of API changes, but it also means a fix you need may not arrive quickly. Check the release notes for the tag you depend on rather than assuming the main branch and the published artifact match.

Editorial conclusion

Adopt Muzei if you want a live wallpaper on Android that rotates art, or if you are an Android developer building a wallpaper source and want the example-unsplash module as a starting point. Do not adopt it if you need a Windows or iOS wallpaper, or if you expect a maintained API surface: the newest release in the repository is api3.4.2 from 2024-06-16, and the README does not document rollback or a support window. Before writing code against it, read the API docs at api.muzei.co and check whether the published artifact version matches the api3.4.2 tag.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. muzei/muzei on GitHub
3. Project website
4. README
5. Releases