Aerial - A free and open-source macOS Screen Saver

Troubleshooting

Are you using Little Snitch or another firewall ?

Aerial requires network access (at least once, after that it can work offline) for it to work, and default Little Snitch settings may impair some or all of it's features. Furthermore, while you may be used to Little Snitch asking you to allow or deny a network connexion, they don't seem to do this for screen savers.

Usually, downloading videos will be ok with default settings, but you may see issues with :

Community videos: Those videos are hosted on GitHub. You need to explicitely allow access to raw.githubusercontent.com for Aerial to work properly. For Catalina, you'll need to create the following rule :

More information regarding this issue and other issues with Community Videos can be found here.

Please note you may also need to create the same rule for https://aerialscreensaver.github.io/

Weather : Aerial uses Yahoo Weather's API, and requires access to it. You may need to explicitely create the following rule to get it working:

If you want to use "Color icons", you will need to setup this additional rule:

In Catalina, Aerial (like all third party screensavers) is hosted by legacyScreenSaver.appex. In older macOS versions, it can be hosted either by System Preferences (for the preference pane) or ScreenSaverEngine.app when running fullscreen.

macOS Catalina/Big Sur specific issues

The sandboxing restrictions make it impossible, as far as I understand, for a screensaver file to auto-update itself, as Aerial did in the past through Sparkle. To overcome this, we made a separate Aerial Companion app to bring you auto updates. If you follow the download link on this site, this is what you'll get. You can find more information on our install page.

Custom videos location : In Catalina, while it's possible to add videos that are stored in your user's Documents or Downloads folder, these files will not playback when Aerial is running as a screensaver. This is a sandboxing restriction, we recommend that you place your videos in a "less protected" folder such as /Users/Shared/.

Settings aren't saved : Some users (using MDM management software and/or Homebrew) seem to have run into an issue where macOS Catalina didn't create the folder where Aerial saves its preferences. You may need to create this folder manually : ~/Library/Containers/com.apple.ScreenSaver.Engine.legacyScreenSaver/Data/Library/Preferences/ByHost/

Some current (or wanted/upcoming) features that require specific privileges are no longer working/impossible because of restrictions, this includes `Right arrow key to skip`. Sorry about that one, I hope I'll be able to bring it back at some point.

Issues on macOS 10.14 and earlier

If you enable Weather, or Adapting videos showed based on time, you may encounter, when exiting the screen saver, this nagging panel that doesn't disappear despite clicking Allow :

If that is the case, you can fix it following these instructions :

Open System Preferences and go into Security & Privacy:

Then click on the `Privacy` tab and in order, click the green, orange and red circles :

This will allow Aerial to use your location to calculate sunset and sunrise times, and if you enabled it, provide your current weather conditions.

Very common issues/macOS bugs

"You cannot use the Aerial screen saver with this version of macOS." error, or you don't see a preview and the prefererences button is greyed out: Select Aerial, close `System Preferences` with Aerial still selected, re-open System Preferences and Aerial should now work. This is a known bug with Swift screen savers in macOS/OS X reported (a long time ago...) to Apple as rdar://25569037.

Some videos may not download, or you are seeing an error with "A server with the specified hostname could not be found.". This may be an issue with Content Caching in macOS, please check this link for more details and how to fix it.

Screensaver hangs at start once a day or so, or unable to quit screensaver. Users of third party firewalls like Little Snitch have reported that it may interact by either blocking by default or popping a window while Aerial tries to connect (for update or download purposes). Please read the section on top about Little Snitch.

"This app is damaged and can't be opened, you should move it to the trash" when double-clicking the `Aerial.saver` file: Please see the [installation notes](Installation.md), this is a GateKeeper issue.

Chrome complains that "This download is uncommon and potentilally malicious" on very fresh releases. Google seems to flag very recent files as "uncommon" and may block the download (more info on Google's site here. After a few hours/days, this warning will disappear. This problem only applies to zip downloads and not to the new Companion app.

Can't use Aerial as a login screen saver: As far as we know, using 3rd party screen savers before login is no longer possible on modern versions of macOS (probably and rightly so for security reasons). More about this here.

Videos are stuttering: There are thread general causes of stuttering:

Streaming: We heavily recommend you cache your videos instead of streaming. Streaming performance may cause stuttering or hanging as this is not something that's officially supported by the servers. Starting with version 2.0.0, streaming has been removed from Aerial to avoid those issues.

HDR playback: Playback of HDR videos may cause random stuttering on some Macs, this issue has been reported on Macs with AMD graphics, and 2015 and earlier Macs with Intel graphics. 4K playback may also cause stuttering on some machines, like MacBook Air.

Background tasks: MacOS may start some background tasks while the screensaver is running (usually after a set amount of time, like 5 minutes). `mediaanalysisd` is known to cause issues on some machines with integrated graphics. You can find more information on how to disable it here.

About custom videos

After playing a video, Aerial is stuck on the last frame for a while and does not go to the next video : Please check that your video contains correct duration information. Some export tools may generate incorrect video files and Aerial will not be able to properly detect the end of the file. To fix your files, you will need to "remux" them using a tool such as Handbrake or MP4Box.

About video caching

Change cache location : Starting with Catalina, and because of the sandboxing limitations introduced with macOS 10.15, Aerial will use two distinct folders. Because of the sandbox, Aerial can **only** write inside the sandbox. You can however still specify a secondary cache location, this is what the cache location is about. This is a read-only folder where you can move your videos if you wish. You need to do this manually, changing the cache location will not move your videos as Aerial cannot write outside the sandbox. Please note that locations outside the main disk (including networked and external drives) are not allowed. This, again, is a macOS 10.15 limitation that we can't workaround.

Videos keeps disappearing, Aerial may not restart once in a while: Aerial stores all it's data in a Cache folder. This cache may get deleted by some third party software trying to free disk space. If you use such a "Cleaning" tool, we recommend you set a manual folder location in the Cache tab of Aerial. For example, you can create an Aerial folder in your User folder, and point to it. This will ensure Aerial files don't get deleted.

Black screen: If you are behind a firewall (Like Little Snitch or Hands Off!) try creating exceptions for Aerial to allow it access to Apple's servers. Be sure the applications ScreenSaverEngine.app and System Preferences.app are not being blocked access to *.phobos.apple.com, *.phobos.apple.com.edgesuite.net and sylvan.apple.com. If that isn't an option, please look at the Offline mode documentation.

Bugs related to old versions

*Tip : you can see the version number in the bottom right corner of the preference panel. If you don't see a version number, your version is SEVERELY outdated (1.2 or below)!*

"Done" button doesn't close Aerial: Please update to latest available version, this is a bug on Mojave with very old versions of Aerial (1.2 and below).

Not seeing extended descriptions: Make sure you have version 1.4.2 or above.

Can't type into text fields with macOS High Sierra/Video corruption issue on High Sierra: Please make sure you have at least version 1.4.5.

Aerial logs you out of your user account everytime it starts: This looks like a new bug with macOS 10.14.5 beta 18F108f (similar to the Video corruption issue on High Sierra above), possibly only for Macs with Intel graphics. Please update to Aerial 1.5.0. More information here : https://github.com/JohnCoates/Aerial/issues/738

Misc.

Brightness control does not control external displays: Aerial uses the brightness API from macOS to change the brightness of your screens. As of version 1.5.0, this does not allow us to control the brightness of external screens.

High CPU usage/fan spinning all of a sudden: If you correctly configured the preferred video format [according to your Mac](HardwareDecoding.md) and still experience high CPU usage/fan spinning all of a sudden, please look for the cause with Activity Monitor, you may see a com.apple.photos.ImageConversionService responsible for this CPU load. This is the iCloud Photos process, you can find more about what it does here and how to pause it.