Dynamic Wallpaper Creator documentation

MuGen Wallpaper supports both video and web dynamic wallpaper. Creator can choose the right type for their needs.

Table of content

Dynamic wallpaper package file structure
How to import dynamic wallpaper
Web Wallpaper developer guide

Dynamic wallpaper package file structure

You need to prepare a zip file that contains certain files.

Video wallpaper package

Option 1: Only a video file is enough. Thumbnail will be generated by the app automatically.

Option 2: Create a zip file that contins the following files in the root level of zip file:

video file
wallpaper-info.json (optional)
thumbnail image

Web wallpaper package

Create a zip file that contins the following files in the root level of zip file:

video file
wallpaper-info.json (optional)
thumbnail image

wallpaper-info.json

The app will load the information from this file automatically. If the file is missing, you just need to enter the information in the app.

These are the description of the fields: Make sure you choose the correct type (video or web). Declare extra native integrations, such as weather data, through the requestService array.

Fields	value	description
title	String	the title of the wallpaper.
description	String	the description of the wallpaper.
type	web or video	Make sure you choose the correct type (video or web).
version	x.x.x	Scematic versioning. e.g. 1.0.1 each version must be higher version than the last one
thumbFilePath	filename	The file name of the thumbnail file. It can be gif, jpg or png. GIF can be animated. The file must be in the root level of the zip file.
entrypoint	filename	For video wallpaper, it is the video filename. For web wallpaper, it is the html filename. The file must be in the root level of the zip file.
requestService	string list	An optional field. An array of native services your wallpaper needs. Set to `["weather"]` to receive OpenWeatherMap updates (see Weather service section).

An example:

{
  "title": "Blue sky with Clouds",
  "description": "Created by MUGEN Wallpaper as a demonstration to show system utilization and different views in different screens. Github: https://github.com/dreaminghk/mugenwallpaper-demo2",
  "type": "web",
  "version": "1.0.0",
  "thumbFilePath": "thumbnail.gif",
  "entrypoint": "demo.html",
  "requestService": ["weather"]
}

How to import dynamic wallpaper?

In the app → Manage Wallpaper → Your Wallpaper, Click the + button to create a new wallpaper. Then choose the package to import or drag the file to the app.

Web Wallpaper developer guide

What is Web Wallpaper?

Web Wallpaper is build as a website. You can use any technology like HTML, CSS and JavaScript to craft your own Web Wallpaper. To handle 3D rendering and GPU acceleration, three.js and WebGL enable you to create stunning effects and animations. With these tools, you can build and customize your interactive and responsive web wallpaper.

To give you access to system information, MuGen Wallpaper inject the system utilization like CPU, RAM, Disk and network usage to the Web Wallpaper as event with a 1 second interval. Screen Index is also injected to let Web Wallpaper distingulish the order of monitor. As a Wallpaper Designer, you can add logic based on the screen index and show different content on different screen.

More details explanation of the usage of the api are in the README.md of MuGen Wallpaper - Demo2

Integration example

Some examples are created to illustrate how to create Web Wallpaper. The detail API is documented in the demo2 listed below.

How to debug web wallpaper

The app enabled debug feature of the webview. When the web wallpaper is being displayed, open Safari → Develop → You macbook name then you should see the html that MuGen Wallpaper is running. Click on the html and the safari developer tool will popup. Javascript console, web inspector and network inspector should help you debug any problem.

Weather service and OpenWeatherMap updates

To consume live weather data you must opt in via requestService. Set "requestService": ["weather"] in wallpaper-info.json (or enable the “Use Weather service” checkbox in the importer UI). Only wallpapers that opt in receive updates.

Event: WeatherUpdateEvent dispatched with window.dispatchEvent(new CustomEvent('WeatherUpdateEvent', { detail })).
Frequency: About every 10 minutes while the wallpaper runs (pauses during sleep/screensaver or after 429 throttling responses). All values use OpenWeatherMap metric units.
Location source: The macOS host uses Core Location to fetch an approximate location before calling OpenWeatherMap.
Payload: detail is a JSON object with status, optional reason, provider, and weatherUpdate containing currentWeather and forcast (intentional spelling) blocks that mirror the raw OpenWeatherMap API responses.
Status values: success, failed, skipped, location_service_denied. Reasons such as throttled, connection_fail, authorization_failed, or api_key_not_setup describe failures.

Example handler:

window.addEventListener('WeatherUpdateEvent', event => {
  const payload = event.detail;
  if (payload.status === 'success') {
    renderWeather(payload.weatherUpdate.currentWeather, payload.weatherUpdate.forcast);
  } else {
    handleWeatherError(payload.status, payload.reason);
  }
});

Use cached data or graceful fallbacks when the status is not success, and debounce UI updates if the wallpaper renders continuously.

Limitations

MuGen Wallpaper do not pass mouse click event to the Web Wallpaper. Mouse coordination are essential for interactive wallpaper, therefore MuGen Wallpaper simulate the mouse location and inject it to the Web Wallpaper. The coordinate reporting may have some latency or results in in-precise coordination.

MuGen Wallpaper start a very simple web server to serve the resources for Wallpaper. The app restrict web wallpaper to access local resources only which means you are not allowed to call external API directly.