Hello Friends,
if you own a Mac running macOS Mojave or newer, you've surely noticed, there's a Function called "Time-shifting Wallpapers". Wouldn't it be nice, if iOS does have such a Feature with Performance in Mind and being Battery Friendly ? moXen make your Dreams come true and it ships with three great Backgrounds : Mojave, Catalina and Big Sur …
Now it's Time to create our own "Time-shifting Wallpapers", so we can use it on every iPhone, iPod Touch or iPad running iOS 10 and above.
- Introduction
- Requirements
- Creating the Folder
- Building "Contents.json"
- Wallpaper-Time
- On-Device-Test
- Creating a Debian-Package
- Last Words
- Greetings
This Developer Kit allows you to create your own "Time-shifting Wallpapers" ( we call them "Wallpaper-Sets" ), based on the two Algorithms moXen supports : Solar-based ( used in any macOS Wallpaper ) and Time-based ( used in custom Wallpapers; much easier to use ). Booth of them are nearly equal and to being Battery-friendly, we did it without using a Service for getting the Solar Position for your Location.
If we're working with a Path, you'll see an opened Folder-Emoji, following by the Path : 📂 Step 4 ● Time-based
.
If you would like to use this Developer Kit, the first Application you need is a Text Editor ( we're using Coda on macOS, but TextEdit does also the Job ). The second App you need is an Image Editor, like Adobe Photoshop or Pixelmator from the Mac App Store.
If you don't know what a JSON-File is, please read the Wikipedia-Article, and have a Look for the Syntax and Character Encoding.
The last Thing you need is Patience.
This is fairly simple, create a Folder with the Name of your Wallpaper. Please don't use Spaces, these are not supported. The Wallpaper-Set "Cherry Blossom" uses an Underscore, instead Spaces.
Example : 📂 Step 3 ● moXen ● Assets ● Cherry_Blossom
.
Now we can create a File, named Contents.json
, in our created Folder. The first Thing we need to specify is a Title, so open the File in your Text Editor, copy the following Lines and set a Title ( in Difference to the Folder, are Whitespaces allowed ) :
{
"Title": "macOS Mojave"
}
Next, we have to choose one of the two Algorithms, which are supported by moXen :
- Solar-based
This Algorithm is used in all Wallpapers shipped with macOS, it's a little bit complicated, since the Wallpapers consider the Position of the Sun. Currently the Attribute altitude
won't be used in moXen, so we're using only azimuth
. Booth Values are using Degrees, so altitude
allows Values between -179.99 and 179.99 and azimuth
Values between 0 and 359.99.
If you want to learn more about this Algorithm, have a Look at Marcin Czachurski's Article "macOS Mojave dynamic wallpaper" on ITNEXT.
Example : 📂 Step 4 ● Solar-based ● moXen ● Assets ● Mojave ● Contents.json
As you can see, you have to specify solar
as Type.
{
"Type": "solar",
"Mojave":
[
{ "id": "Mojave_01", "altitude": -52.7531813787993, "azimuth": 2.1750965538675473 }
]
}
If you want to use this Algorithm, Casio Computer offers a Website to calculate the Position of the Sun, but consider to think about the Differences for Summer and Winter.
Pro Tip : If you want to go more into the Deep, you can use wallpapper -e
to extract the Metadata from a downloaded Wallpaper to get the Values for altitude
and azimuth
.
- Time-based
This Algorithm is much easier to use. Instead of dealing with Altitude and Azimuth, we're using the Time of Day in Percent. We know a Day has a Total of 86.400 Seconds and if we want to change the Wallpaper at 09:30 AM, we need to do the following Math : (9 * 60 * 60) + (30 * 60) = 34,200. Divided by 86,400, we get a Value of "0.39583˜3". Optionally you can also add Seconds, but it's not necessary.
Let us express this in a Formulae :
$$
((Hours6060)+(Minutes*60)+Seconds)/86400=X
$$
Example : 📂 Step 4 ● Time-based ● moXen ● Assets ● Cherry_Blossom ● Contents.json
As you can see, you have to specify time
as Type.
{
"Type": "time",
"Cherry_Blossom":
[
{ "id": "Cherry_Blossom_01", "time": 0 }
]
}
If you'd chosen one of the Algorithms, copy the Code in your Contents.json
. And replace altitude
, azimuth
and respectively time
with your Values. This is only for one Image, you can ( theoretically ) add up to 86,400 Images. To prevent Performance Issues, we've set a Maximum of 1,440 Images. Every Minute, one Image. Not really useful, but possible. Just add more Images, until your Array of Images looks like the following :
{
"Cherry_Blossom":
[
{ "id": "Cherry_Blossom_01", "time": 0 },
{ "id": "Cherry_Blossom_02", "time": 0.25 },
{ "id": "Cherry_Blossom_03", "time": 0.333333333333333 },
{ "id": "Cherry_Blossom_04", "time": 0.416666666666667 },
{ "id": "Cherry_Blossom_05", "time": 0.708333333333333 },
{ "id": "Cherry_Blossom_06", "time": 0.791666666666667 },
{ "id": "Cherry_Blossom_07", "time": 0.916666666666667 }
]
}
The Value id
holds the Filename. As the same as for the Folder, please don't use Spaces. moXen requires an Index at the End of every Image, as you can see above. Just add a _01
… _n
to your Filename. Additionally, after every Line a Comma is needed, except for the last Line in the Array. This is also necessary for the Values Title
and Type
.
With all the Values, your Contents.json
should look like this :
{
"Title": "Cherry Blossom",
"Type": "time",
"Cherry_Blossom":
[
{ "id": "Cherry_Blossom_01", "time": 0 },
{ "id": "Cherry_Blossom_02", "time": 0.25 },
{ "id": "Cherry_Blossom_03", "time": 0.333333333333333 },
{ "id": "Cherry_Blossom_04", "time": 0.416666666666667 },
{ "id": "Cherry_Blossom_05", "time": 0.708333333333333 },
{ "id": "Cherry_Blossom_06", "time": 0.791666666666667 },
{ "id": "Cherry_Blossom_07", "time": 0.916666666666667 }
]
}
To test your newly created JSON-File, just copy the whole Code into the JSON-Validator provided by FreeFormatter.com.
If everything is fine, the Validator should display the following Messages :
Save your Changes and we can head over to the NextSTEP.
To offer the best Performance and decrease the Size of the Wallpaper-Sets, we've decided, that a Wallpaper-Set can only hold Images for one Display Size. It doesn't help the User, if he needs to download much more Images, which he can't use, because his Device supports only one Display Size.
Example : You don't need Images with 2340 × 1080 Pixels, if your Device has a Display Size of 1334 × 750 Pixels.
Let's have a Look on the Display Sizes, which every Device uses :
iDevice | Display Size in Pixels |
---|---|
iPhone 4S | 960 × 640 |
iPhone 5 | 5S | 5C | SE 1st Gen. | 1136 × 640 |
iPod Touch 5th Gen - 7th Gen | 1136 × 640 |
iPhone 6 | 7 | 8 | SE 2nd Gen. | 1334 × 750 |
iPhone XR | 11 | 1792 × 828 |
iPhone 6+ | 7+ | 8+ | 1920 × 1080 |
iPad 3 | 4 | 5 | 6 | 2048 × 1536 |
iPad Air 1 | 2 | 2048 × 1536 |
iPad mini 2 | 3 | 4 | 5 | 2048 × 1536 |
iPad Pro 9.7-inch | 2048 × 1536 |
iPad 7 | 8 | 2160 × 1620 |
iPad Air 3 | 2224 × 1668 |
iPad Pro 10.5-inch | 2224 × 1668 |
iPhone 12 mini | 2340 × 1080 |
iPad Air 4 | 2360 × 1640 |
iPad Pro 11-inch 1st Gen | 2nd Gen | 2388 × 1668 |
iPhone X | XS | 11 Pro | 2436 × 1125 |
iPhone 12 | 12 Pro | 2532 × 1170 |
iPhone XS Max | 11 Pro Max | 2688 × 1242 |
iPad Pro 12.9-inch 1st Gen - 4th Gen | 2732 × 2048 |
iPhone 12 Pro Max | 2778 × 1242 |
As you can see, a lot of Devices share their Display Size with other Devices, so you can create a Wallpaper-Set for an iPhone 6 and it runs on an iPhone 6S, 7, 8 and on the 1st generation iPhone SE too.
How do you create Images ? It's very simple :
-
Pick a few Images you want to use for your Wallpaper-Set. You can find a lot of Time-shifting Wallpapers at Dynamic Wallpaper Club, depending on your desired Screen Size you’ll need to do some digging around the Gallery, but you have a wide Array of Choices ranging from real-world Photography to Artist Renditions of Video Games, Cityscapes, Animals and more.
Be careful : A lot of Wallpapers are re-uploaded by the Users and they're sometimes looking pixelated and blurred.
Alternatively you can visit Dynwalls, but they're offering only six Wallpapers at the Moment.
-
Open your downloaded Image in Preview.
-
Now select every Image and Drag & Drop them into your created Folder, where also the File
Contents.json
is located.You should now have a lot of Images in your Folder.
-
Rename the Images with the Name you've chosen as
id
inContents.json
. -
Start your Image Editor, open all Images, resize and crop them, so we can use it for our desired Display Size.
Pro Tip : If you're using Photoshop, you can use Batch Processing, but also macOS provides a very good App for this Task : Automator.
-
Save them as PNG.
-
You should now have a Folder with a
Contents.json
and a few Images in it.Example 1 :
📂 Step 5 ● Solar-based ● moXen ● Assets ● Mojave
Example 2 :
📂 Step 5 ● Time-based ● moXen ● Assets ● Cherry_Blossom
It's Time to verify, that our Wallpaper-Set is working. Transfer Contents.json
and the Images in the Folder Developer
on your iPhone, iPad or iPod Touch :
- Homescreen :
/var/mobile/Library/Widgets/Homescreen/moXen/Developer
- Lockscreen :
/var/mobile/Library/Widgets/Lockscreen/moXen/Developer
Now head over in Preferences, select "Xen HTML" and choose between "Lockscreen" and "Homescreen". Select "Background Widgets" and "moXen", tap on the Settings-Icon, choose "Developer Options" and switch on "Developer Mode".
If everything is working, you should now see your running Wallpaper-Set …
The Developer Mode has a Function to run through a Day in 24 Minutes, which means you can see how moXen cycles through the Images of your Wallpaper-Set during a Day …
If everything is working, disable "Developer Mode" and remove all Files from the Folder Developer
.
During this Step, we'll create a Debian-Package, so you can easily share your Wallpaper-Set with the Community.
Pro Tip : If you don't want to publish your Creation and keep it private, place your Folder, containing Contents.json
and the Images in the Folders Assets
:
- Homescreen :
/var/mobile/Library/Widgets/Homescreen/moXen/Assets
- Lockscreen :
/var/mobile/Library/Widgets/Lockscreen/moXen/Assets
Now open a Terminal-App right on your iPhone, iPad or iPod Touch, for Example Prompt 2 or NewTerm 2 and run the Command Line Utility moxen
with the Argument -u
.
What does this Command do ?
Let's have a Look at moxen --help
, which shows the "Help & Usage" :
NAME
moXen -- Simply powerful. On your Mac and also on iOS.
VERSION
2103 ( March 8, 2021 )
SYNOPSIS
moxen [ -u | -l ]
DESCRIPTION
This Command Line Utility allows Developers to update the Backgrounds-Array and list available Wallpaper-Sets.
The Options are as follows:
-u Updates Backgrounds-Array in config.plist; --update is for the non-lazy Ones.
-l Lists Wallpaper-Sets in Assets; --list is for the non-lazy Ones.
-h Displays Help & Usage; --help is for the non-lazy Ones.
NOTES
moxen comes with no Warranty, neither express nor implied. If it blows up your Widgets, eats your Children, or causes you bodily Harm, all you'll get is a little Pity and maybe an Apology.
As you can see : The Command moxen -u
updates the "Background"-Array in the File config.plist
.
Now head over in Preferences, select "Xen HTML" and choose between "Lockscreen" and "Homescreen". Select "Background Widgets" and "moXen", tap on the Settings-Icon, look for your Wallpaper-Set in "Background" and select it.
To create a Debian-Package, we need the Command Line Tools for Xcode, Homebrew and the Packages dpkg
and md5sha1sum
. The following Steps will guide you through the Installation of all these Requirements :
-
Open "Terminal" on your Mac. Homebrew requires the Command Line Tools for Xcode to be installed, so we'll install them first. Copy the following Line into Terminal and hit Enter …
xcode-select --install
-
When the Installation has finished, we're able to install Homebrew. Just paste the following Line and hit Enter.
/bin/bash -c "$(curl -fsSL https://github.com/raw/Homebrew/install/HEAD/install.sh)"
This Step can take up a few Minutes.
-
Now we have to install
dpkg
andmd5sha1sum
, you can do it by pasting the Line in the Terminal ( and hitting Enter again ).brew install dpkg md5sha1sum
Now we've installed all Requirements and we're able to build a Debian-Package from the Command Line. This can be very difficult and to simplify this Step, we built an Automator-Service.
-
Copy the File
Services_CreateDebianPackage.workflow
located in📂 Step 7 ● Tools
. -
Go to the Finder, hit the Menu "Go" and navigate down to "Go to Folder".
Pro Tip : Hit Command+Shift+G from the Desktop or a Finder Window.
-
Paste the following Path into the new appearing Sheet :
~/Library/Services
. -
Paste the previously copied File.
If you're now opening the Context Menu on a Folder, you should see a new Entry, named "Build Debian-Package …".
Let's get started with the major Part of this Step : Every Debian-Package contains a File control
, with Informations about the Package. Navigate to 📂 Step 7
and you'll see a lot of Folders. In Step 5 "Wallpaper-Time", you've chosen a Display Size for you Wallpaper-Set, now pick the corresponding Debian-Folder and copy the Folder of your Wallpaper-Set into the following Folders :
📂 Step 7 ● * ● var ● mobile ● Library ● Widgets ● Homescreen ● moXen ● Assets
or
📂 Step 7 ● * ● var ● mobile ● Library ● Widgets ● Lockscreen ● moXen ● Assets
Replace the *
with a Debian-Folder from the following List …
iDevice | Display Size in Pixels | Debian-Folder |
---|---|---|
iPhone 4S | 960 × 640 | com.xyz. …-2x-iphone |
iPhone 5 | 5S | 5C | SE 1st Gen. | 1136 × 640 | com.xyz. …-568h-2x-iphone |
iPod Touch 5th Gen - 7th Gen | 1136 × 640 | com.xyz. …-568h-2x-iphone |
iPhone 6 | 7 | 8 | SE 2nd Gen. | 1334 × 750 | com.xyz. …-667h-2x-iphone |
iPhone XR | 11 | 1792 × 828 | com.xyz. …-896h-2x-iphone |
iPhone 6+ | 7+ | 8+ | 1920 × 1080 | com.xyz. …-3x-iphone |
iPad 3 | 4 | 5 | 6 | 2048 × 1536 | com.xyz. …-2x-ipad |
iPad Air 1 | 2 | 2048 × 1536 | com.xyz. …-2x-ipad |
iPad mini 2 | 3 | 4 | 5 | 2048 × 1536 | com.xyz. …-2x-ipad |
iPad Pro 9.7-inch | 2048 × 1536 | com.xyz. …-2x-ipad |
iPad 7 | 8 | 2160 × 1620 | com.xyz. …-1080h-2x-ipad |
iPad Air 3 | 2224 × 1668 | com.xyz. …-1112h-2x-ipad |
iPad Pro 10.5-inch | 2224 × 1668 | com.xyz. …-1112h-2x-ipad |
iPhone 12 mini | 2340 x 1080 | com.xyz. …-780h-3x-iphone |
iPad Air 4 | 2360 × 1640 | com.xyz. …-1180h-2x-ipad |
iPad Pro 11-inch 1st Gen | 2nd Gen | 2388 × 1668 | com.xyz. …-1194h-2x-ipad |
iPhone X | XS | 11 Pro | 2436 x 1125 | com.xyz. …-812h-3x-iphone |
iPhone 12 | 12 Pro | 2532 × 1170 | com.xyz. …-844h-3x-iphone |
iPhone XS Max | 11 Pro Max | 2688 × 1242 | com.xyz. …-896h-3x-iphone |
iPad Pro 12.9-inch 1st Gen - 4th Gen | 2732 × 2048 | com.xyz. …-1366h-2x-ipad |
iPhone 12 Pro Max | 2778 × 1242 | com.xyz. …-926h-3x-iphone |
Did you noticed the first Part of the Name of every Debian-Folder ?
Example : com.xyz.moxen.abc
Looks a Bit generic and that's true. Here you can create your own Package-Identifier, by replacing xyz
with your Company Name ( or Nickname, we're using macthemes
) and abc
with the Name of your Wallpaper-Set ( for Example : cherryblossom
). The whole Name of this Folder will be your Package-Identifier. Please don't remove the Part moxen
in the Name, because it prevent "Chaos", especially if you're planing to release more than one Wallpaper-Set with your Company Name ( or Nickname ).
Pro Tip : If you're using the same Wallpaper-Set for Homescreen and Lockscreen, you can reduce the Size of the Debian-Package by using Symbolic Links.
Now let's edit the File control
. Navigate to 📂 Step 7 ● * ● DEBIAN
and open control
in your Text Editor. The File already contain a few Informations and Example Data about the Package …
Package: com.xyz.moxen.abc-667h-2x-iphone
Version: 2009
Section: XenHTML ( Assets )
Name: macOS Mojave ( iPhone 4.7" )
Author: Aeneon <aeneon@avalon-studios.de>
Maintainer: Aeneon <aeneon@avalon-studios.de>
Icon: file:///usr/share/macthemes/sections/xenhtml@2x.png
Pre-Depends: cy+model.iphone, gsc.main-screen-height (= 1334)
Depends: com.macthemes.moxen (>= 2007)
Architecture: iphoneos-arm
Description: macOS Mojave meets "moXen" …
Depiction: https://repo.avalon-studios.de/package.php?id=com.macthemes.moxen.mojave
Let's explain these Fields. If you want more Information about the Fields, have a Look at "Control files and their fields" …
Value | Description |
---|---|
Package | The Identifier of your Package, should have the same Name like your Debian-Folder. |
Version | Yes, here you can set a Version. |
Section | Allows to Group the Wallpaper-Sets in a Package Manager. |
Name | The Name of your Wallpaper-Set, with an Addition for the Display Size. |
Author | Your Name ( and optionally your E-Mail-Address ). |
Maintainer | The Name of the Repo-Maintainer ( and optionally your E-Mail-Address ). |
Icon | Changes the Icon of the Package in a Package Manager. |
Pre-Depends | Contains a List of Pre-Depends, we're using it to detect the Device Model and Display Size. |
Depends | Contains a List of Dependencies, we're using this to install moXen, if it's not already installed. |
Architecture | The Architecture of your Package. |
Description | A short Description of your Wallpaper-Set. |
Depiction | Here you can set a Link to a Webpage, which contains more Information about your Package. |
The Fields Section
, Icon
, Pre-Depends
, Depends
and Architecture
should not be changed, as it contains Values for Core-Functionality of this Package.
Did we forget anything ?
No ?
Then we can create the Debian-Package from our Debian-Folder. Open the Context Menu and select the Service "Build Debian-Package …". A few Moments later, a new Debian-Package appears in Finder.
That's it ! We hope you use the Developer Kit to create some amazing new Wallpaper-Sets for moXen. If you would like to contribute to this Project, let us know.
If you respect our hard Work, you can help us with a small Donation via PayPal.me 😃 …
We would like to thank Matt Clarke ( aka _Matchstic ) for his amazing Work he did and the countless Hours he spend with the Development of Xen HTML.
Thank you.