diff options
| author | Christopher Warner <cwarner@kernelcode.com> | 2026-10-13 15:07:53 -0400 |
|---|---|---|
| committer | Christopher Warner <cwarner@kernelcode.com> | 2026-10-13 15:07:53 -0400 |
| commit | 6f3426c481f03f5beeed9171b3280f0070798844 (patch) | |
| tree | c2cfb41a3a8f17919aa40d76ccf032546165ab75 /README.md | |
| parent | ead35d75893dcbc34a97beb165a2d46f7741bfc8 (diff) | |
| download | aerial-screensaver-linux-6f3426c481f03f5beeed9171b3280f0070798844.tar.gz aerial-screensaver-linux-6f3426c481f03f5beeed9171b3280f0070798844.tar.bz2 aerial-screensaver-linux-6f3426c481f03f5beeed9171b3280f0070798844.tar.xz aerial-screensaver-linux-6f3426c481f03f5beeed9171b3280f0070798844.zip | |
feat: package portable Aerial screensaver for sharing
Add install/uninstall scripts, XDG config, portable VAAPI detection,
fetch-aerial-recent helper, and a LocalSend-ready zip without Apple video assets.
Co-authored-by: Cursor <cursoragent@cursor.com>
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 137 |
1 files changed, 116 insertions, 21 deletions
@@ -1,26 +1,121 @@ -# Aerial Screensaver for Linux +# Aerial Screensaver for Linux (GNOME) -A high-performance, power-efficient Apple Aerial screensaver implementation for Linux, optimized for the Framework 16 and AMD graphics. +Idle screensaver that plays Apple Aerial–style clips with **mpv**, on **every connected monitor**. Designed to be quiet on battery and dual-GPU laptops: AC-only by default, lid-aware, VAAPI decode, low CPU niceness. + +> This package is the **player + tooling**. Apple’s video assets are not redistributed here — download them yourself (helper included). ## Features -- **Power Efficient**: Only runs when connected to AC power. -- **Low Impact**: Runs with `nice 19` priority and `idle` scheduling. -- **Hardware Accelerated**: Uses VA-API on the Integrated GPU to keep the Discrete GPU asleep. -- **Smooth Playback**: Optimized for local 4K HEVC files with frame-dropping logic for 60Hz displays. -- **Systemd Integration**: Runs as a background user service. + +- Starts after idle (default 5 minutes) via GNOME Mutter IdleMonitor +- Fullscreen **one mpv per logical monitor** +- AC-only (optional) and skips / stops when the laptop lid is closed +- VAAPI HEVC playback; lite encoder for 1080p24 library files +- systemd user service ## Requirements -- `mpv` -- `python3` -- `python3-gobject` (for GNOME IdleMonitor access) -- `systemd` - -## Installation -1. Place your Aerial videos in `~/Videos/Screensavers/Aerial`. -2. Copy `aerial-screensaver.py` to `~/.local/bin/aerial-screensaver`. -3. Copy `aerial-screensaver.service` to `~/.config/systemd/user/`. -4. Enable the service: - ```bash - systemctl --user daemon-reload - systemctl --user enable --now aerial-screensaver - ``` + +| Package | Why | +|---|---| +| GNOME (Wayland) | IdleMonitor + DisplayConfig | +| `python3` + PyGObject (`python3-gobject` / `python3-gi`) | Daemon | +| `mpv` | Playback | +| `ffmpeg` (VAAPI HEVC) | Optional encode | +| `aria2c`, `curl`, `jq`/`python3` | Optional fetch helper | +| `systemd --user` | Autostart | + +Fedora / CachyOS example: + +```bash +sudo dnf install mpv ffmpeg python3-gobject aria2 curl +``` + +## Quick install + +```bash +git clone https://git.kernelcode.com/aerial-screensaver-linux +# or unzip the LocalSend archive, then: +cd aerial-screensaver-linux +./install.sh +``` + +`install.sh` installs: + +- `~/.local/bin/aerial-screensaver` +- `~/.local/bin/encode-aerial-lite` +- `~/.local/bin/fetch-aerial-recent` +- `~/.config/systemd/user/aerial-screensaver.service` +- `~/.config/aerial-screensaver/config` + +Enable is done for you. Check: + +```bash +systemctl --user status aerial-screensaver +``` + +## Get videos + +### Option A — fetch recent Apple pack (recommended) + +Tahoe / Sequoia / Sonoma / Cazadero from Apple’s public macOS catalog: + +```bash +fetch-aerial-recent --encode +``` + +Downloads masters, then encodes lite 1080p24 clips into `~/Videos/Screensavers/Aerial`. + +### Option B — your own files + +```bash +mkdir -p ~/Videos/Screensavers/Aerial +# copy .mp4 / .mov / .mkv there +``` + +### Option C — encode masters you already have + +```bash +encode-aerial-lite /path/to/4k-masters +``` + +## Config + +Edit `~/.config/aerial-screensaver/config`: + +```ini +VIDEO_DIR=/home/YOU/Videos/Screensavers/Aerial +IDLE_TIMEOUT_SECONDS=300 +REQUIRE_AC=1 +VAAPI_DEVICE=/dev/dri/by-path/pci-XXXX:XX:XX.X-render +``` + +On dual-GPU machines, set `VAAPI_DEVICE` to the **iGPU** render node so the discrete GPU stays asleep. `install.sh` writes a detected default; override if needed. + +Environment overrides (prefix `AERIAL_`): `AERIAL_VIDEO_DIR`, `AERIAL_IDLE_TIMEOUT_SECONDS`, `AERIAL_VAAPI_DEVICE`, `AERIAL_REQUIRE_AC`. + +## Uninstall + +```bash +./uninstall.sh +``` + +Videos and `~/.config/aerial-screensaver/` are left in place. + +## Sharing + +| Method | What to send | +|---|---| +| **Git** | This repo (no videos) | +| **LocalSend** | `aerial-screensaver-linux.zip` from `dist/` (no videos) | +| **LocalSend + clips** | Also send `~/Videos/Screensavers/Aerial` separately (~1GB lite) | + +Do not commit or publish Apple’s `.mov` masters — fetch them per machine. + +## Tests + +```bash +python3 test_screensaver.py -v +``` + +## License + +MIT (this software only). Aerial video content remains Apple’s. |
