Aura

The definitive live wallpaper engine for COSMIC Desktop.

(With experimental support for GNOME & Wayland)

Transform your COSMIC and Wayland workspace (including Niri) with fluid animated backgrounds, dynamic desktop color matching, and zero lag when gaming.

⚡ Quick Install (One Command)

curl -fsSL https://raw.githubusercontent.com/antwny/aura/main/install.sh | bash

Bundled video engine included. Compatible with Pop!_OS, CachyOS, Arch Linux, Fedora, and any distribution running COSMIC Desktop or Wayland layer-shell compositors (such as Niri, Hyprland, Sway), with experimental support for GNOME.

Prerequisites for video playback & thumbnails:

• Arch / CachyOS: sudo pacman -S --needed mpv ffmpeg
• Pop!_OS / Ubuntu / Debian: sudo apt install -y libmpv2 ffmpeg
• Fedora: sudo dnf install -y mpv-libs ffmpeg-free
• openSUSE: sudo zypper install -y mpv ffmpeg

_{Live recording: COSMIC Desktop • Wayland Layer-Shell • Seamless MPV IPC Engine — click to play}

---

✨ Features at a Glance

• Native Rust & Wayland Layer-Shell: Smooth 60 FPS rendering with zero compositor tearing.
• Smart Auto-Pause (0% CPU / 0% GPU): Instantly halts video playback when windows cover the desktop or when launching fullscreen games.
• Online Catalogs: Browse and download thousands of curated live and static wallpapers (MotionBGS 4K/1080p, Wallhaven UHD, Bing Daily, DenverCoder1).
• Dynamic Desktop Auto-Theming: Automatically extracts color palettes from your wallpaper to theme COSMIC window borders, accents, and controls.
• Multi-Monitor Studio: Set independent wallpapers, scaling modes (Fit, Fill, Stretch), and arrangements per screen with live hotplug support.
• Quick Switcher HUD: Floating heads-up display overlay summonable from anywhere with a global shortcut.

---

⚡ Quick Switcher HUD

Summon a floating overlay anywhere on your desktop with aura switcher:

• 3 Visual Styles:
  • Honeycomb HUD: Geometric pointy-topped hexagon matrix with smooth camera lerp, hover expansion, and edge panning.
  • Cinematic HUD: Tilted parallelogram cards with 3D perspective and ambient halo glow.
  • Classic Dock: Minimalist dock bar with interactive hover pop-out and slide momentum.
• Cursor Awareness: Spawns directly on the monitor where your mouse pointer is located.
• Fluid Navigation: Arrow keys, WASD, mouse scroll, edge hover, and 1-click wallpaper apply.
• In-HUD Shortcuts: Space to Pause/Resume, F for Favorites, Esc to dismiss.

---

🎨 Dynamic Auto-Theming

• Harmonized Accents: Shifts desktop accent colors to match wallpaper hues.
• WCAG Contrast: Automatically verifies legible text contrast.
• Auto Dark / Light: Adapts palette luminance according to the active background.

---

🎮 Smart Auto-Pause: 0% GPU & CPU in Games

• Window Occlusion: Pauses playback when any application window covers the desktop.
• Fullscreen Games: Frees 100% of GPU and CPU resources for maximum gaming FPS.
• Battery Saver: Automatically halts video playback when unplugged to preserve laptop battery.
• Audio Control: Built-in volume slider and instant mute toggle.

---

🖥️ GNOME Desktop Support (Wayland) — Experimental

Aura includes experimental support for GNOME on Wayland:

• Automatic Detection: Aura detects XDG_CURRENT_DESKTOP=GNOME and selects the appropriate backend automatically (override with AURA_BACKEND=gnome|mpvpaper).
• Static Wallpapers: Applied natively via GSettings (org.gnome.desktop.background).
• Live Video Wallpapers: Powered by the Hanabi GNOME Shell extension (gnome-ext-hanabi). Aura communicates with Hanabi over D-Bus for synchronized playback, volume, and scaling controls.
• Interactive HUD: Runs via borderless toplevel windows (note: background may appear opaque/dark due to Mutter's lack of the Wayland layer-shell protocol).
• Icon Fallback: Automatically falls back to Adwaita icons on systems where the Cosmic icon theme is not installed.

---

⌨️ Shortcuts & CLI

Action	Command	Recommended Shortcut
Quick Switcher HUD	aura switcher	Super + Alt + W
Next Wallpaper	aura next	Super + W
Previous Wallpaper	aura prev	Super + Shift + W
Pause / Resume (0% GPU)	aura toggle-pause	Super + P
Apply Video Directly	aura apply <file>	File manager integration
Stop Wallpaper	aura stop	Terminal / script
System Status	aura status	Terminal health check

---

🚀 Installation

One-Line Installer (Recommended)

curl -fsSL https://raw.githubusercontent.com/antwny/aura/main/install.sh | bash

Precompiled Release Package

Download aura-v1.7.1-x86_64-linux.tar.gz from GitHub Releases:

tar -xzf aura-v1.7.1-x86_64-linux.tar.gz
cd aura-v1.7.1-x86_64-linux
./install.sh

Build from Source

git clone https://github.com/antwny/aura.git
cd aura
cargo build --release
install -m 755 target/release/aura ~/.local/bin/aura

---

📊 Performance Benchmarks

Tested on Linux / COSMIC Desktop (AMD Ryzen 5 4500U, Radeon Graphics, Wayland Layer-Shell):

Benchmark	Aura (Rust)	Legacy Python/GTK Tools	Advantage
Cold Startup Time	< 20 ms	~1,120 ms	56x faster
Idle CPU (Paused / Occluded)	0.00%	3.5% - 8.0%	Zero battery drain
GPU Usage When Paused	0.0%	4.0% - 10.0%	100% GPU for games
Desktop UI Framerate	60+ FPS	24 - 45 FPS	Silky smooth

---

Acknowledgments & License

Aura is Free & Open Source software licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for details.

Inspirations & references: Papyrus and skwd-wall.

• Community: @antwny on YouTube • @antw-ny on Reddit
• Support the project with a star on GitHub ⭐ or donate via PayPal.