Omahub
← All plugins
M

Omarchy Aerials

by Mark Allen

Apple TV-style 4K aerials as live Hyprland wallpaper, with a bar control and settings panel.

GitHub

Security review

Potentially dangerous behavior detected · 3 findings

Deterministic scan — not a security guarantee

High
Risk level
High
Analyzed commit
2e6c24f
Scanned
1 month ago
  • high destructive_filesystem uninstall.sh:11

    Filesystem operation targeting an environment-variable path.

    rm -f "${HOME}/.local/bin/omarchy-aerials"
  • medium package_manager …/workflows/ci.yml:21

    System-wide Python package installation (not --user).

    pip install --no-deps .
  • Docs external_hosts README.md:44

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/markoalleno/omarchy-aerials.git

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
2e6c24f
Reviewed
1 month ago

The plugin is a legitimate wallpaper service: it downloads Apple aerial videos, plays them via mpvpaper, and provides a bar widget/settings UI. The deterministic scan's high finding is a false positive: uninstall.sh's `rm -f "${HOME}/.local/bin/omarchy-aerials"` only removes the PATH wrapper the plugin itself created, and the Python uninstaller runs first. The other findings are documentation/CI noise: the README's `git clone` is an install instruction, and the CI `pip install --no-deps .` runs in a throwaway GitHub Actions container, not on a user's system.

  • Service.qml runs install.sh --cli on every load, which rewrites ~/.local/bin/omarchy-aerials; this is expected behavior for the plugin's PATH wrapper but is worth noting.
  • The plugin downloads and plays content from Apple's CDN; network access is scoped to *.apple.com with HTTPS, redirect, and size checks, so risk is low.
  • The bundled Apple root CA is pinned for catalog downloads; this is intentional for verifying Apple's CDN but means the plugin trusts that bundled certificate.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/markoalleno/omarchy-aerials --enable
Appearance #Hyprland #bar #media

Omarchy Aerials

<p align="center"> <a href="docs/assets/omarchy-aerials-preview.mp4"> <img src="docs/assets/omarchy-aerials-preview.gif" alt="Omarchy Aerials — Apple TV aerials as a live Hyprland wallpaper" width="720"> </a> <br> <sub>Korea and Japan Night, looping on the desktop. <a href="docs/assets/omarchy-aerials-preview.mp4">Watch the 1080p clip</a>.</sub> </p>

Apple TV-style 4K aerials as live wallpaper on Omarchy. Hardware-decoded, per-monitor, with a bar widget, a Super+Alt+A menu, and a settings panel to pick named films from Apple's catalog.

This is a new project, written from scratch for Omarchy / Hyprland / Wayland. It is not a fork of Aerial for macOS. Same public Apple catalog, same films — different codebase, different OS, built around Omarchy instead of ScreenSaverKit.

Install · Remove · Controls · Not a fork

Why this exists

Aerial is the macOS app that made Apple’s Earth-from-orbit films a desktop fixture. Omarchy Aerials is the Linux rewrite of that idea, aimed at one environment:

  • Omarchy-native controls — bar widget, Super+Alt+A, an Aerials row in the Omarchy menu
  • Hyprland wallpaper — mpvpaper on the background layer, VAAPI/Vulkan decode, one process per monitor
  • Tiling-aware — auto-pauses a display when windows cover ≥90% of it
  • No daemon zoo — Python stdlib (GTK only for settings), XDG dirs, the Omarchy shell plugin service

Install

Omarchy / Arch. Needs mpv, mpvpaper, and Python 3.9+. mpvpaper is not bundled; install it first.

As an Omarchy plugin (recommended):

omarchy pkg aur add mpvpaper    # or: yay -S mpvpaper
omarchy plugin add https://github.com/markoalleno/omarchy-aerials.git --enable
omarchy-aerials settings        # pick named films, then download
omarchy-aerials start

omarchy plugin add --enable clones this repository into ~/.config/omarchy/plugins/io.github.markoalleno.aerials/, enables the bar widget and wallpaper service, and asks which bar section to use (default: right). The service writes a PATH wrapper to ~/.local/bin/omarchy-aerials. It does not edit Hyprland bindings or Omarchy menu config.

Or from a clone:

git clone https://github.com/markoalleno/omarchy-aerials.git
cd omarchy-aerials
./install.sh
omarchy-aerials settings
omarchy-aerials start

./install.sh checks for mpvpaper and installs the PATH wrapper. Optional keybind, Omarchy menu row, and systemd user service:

./install.sh --desktop

Open Settings from the bar widget, tray, menu, or omarchy-aerials settings. Check the aerials you want by name and click Download checked. sync only fetches that list — it no longer grabs a random 100.

omarchy-aerials catalog
omarchy-aerials sync --name "Korea and Japan Night" --name Hawaii
omarchy-aerials sync --count 0          # every catalog item (opt-in)

Remove

Plugin install — run the uninstaller from the plugin folder first (Omarchy has no remove hook), then remove the plugin:

~/.config/omarchy/plugins/io.github.markoalleno.aerials/uninstall.sh
omarchy plugin remove io.github.markoalleno.aerials

Clone install:

./uninstall.sh

That stops playback, removes the PATH wrapper, and removes any keybind, menu row, and user service this project added. Cached films stay under ~/.cache/omarchy-aerials unless you pass --purge. mpvpaper is left installed.

Controls
Bar widget Left-click the 󰔎 icon for Next / Previous / Pause / Settings. Middle-click skips. Right-click opens settings.
Menu Super+Alt+A after ./install.sh --desktop, or omarchy-aerials menu
Settings Named catalog, quality, cycle, decode, cache — omarchy-aerials settings
Next / Previous Skip through the cache
Pause / Start Freeze or resume the current film
Select Pick any cached aerial by name
Frequency 1 / 5 / 10 / 15 / 30 / 60 minutes
Favorites Save the current shot, or play only favorites

Optional keybind, if you did not use --desktop:

-- ~/.config/hypr/bindings.lua
o.bind("SUPER + ALT + A", "Aerials", "omarchy-aerials menu")

What you get

  • 4K SDR preferred, 4K HDR fallback, 1080p if that’s all there is
  • Named downloads from the Apple TV archive (no random 100)
  • Randomized wallpaper per monitor from the films you actually cached
  • Location filter (--location Hawaii) and favorites
  • Atomic downloads, Apple Root CA bundled so Linux can verify the CDN
  • omarchy-aerials status for cache size and player state

Config lives at ~/.config/omarchy-aerials/config.toml:

quality = '4k-sdr'        # 4k-sdr, 4k-hdr, or 1080p
cache_count = 100         # only used with `sync --count`
max_cache_gb = 0          # 0 = unlimited
cycle_minutes = 15
per_monitor = true
auto_pause = true
covered_threshold = 0.9
hardware_decode = 'auto-safe'
source = 'apple-tvos26'
location = ''
wanted = ['009BA758-7060-4479-8EE8-FB9B40C8FB97']

Commands

omarchy-aerials settings
omarchy-aerials catalog [query] [--refresh]
omarchy-aerials sync [--name NAME] [--id ID] [--count N] [--refresh]
omarchy-aerials next | previous | start | pause | resume | stop
omarchy-aerials select [--id ID]
omarchy-aerials frequency [1|5|10|15|30|60]
omarchy-aerials favorite
omarchy-aerials menu | tray | daemon [--no-tray] | status | config
omarchy-aerials install | uninstall [--purge]

Dependencies

Package Why
mpv Decode backend used by mpvpaper
mpvpaper Plays the film on the Hyprland background layer
Python 3.9+ Catalog, cache, daemon, settings
GTK 3 + Ayatana AppIndicator Optional tray; settings panel uses GTK 3

Not a fork

Aerial for macOS is a Swift app + ScreenSaver extension. Omarchy Aerials does not share that repository, that language, or that runtime.

It reimplements the same job on Omarchy: fetch Apple’s public Aerial catalog, cache the films, play them as wallpaper. Catalog URL discovery follows what the macOS project documented; the player, cache, tray, and desktop integration are original.

On a Mac, use Aerial. On Omarchy, use this.

License and credits

MIT. Unofficial. Not affiliated with Apple.

Videos are downloaded from URLs in Apple’s Aerial catalog and remain subject to Apple’s terms. The README preview is a short clip of Korea and Japan Night from that catalog.

Catalog endpoint discovery is informed by Aerial.