summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorChristopher Warner <cwarner@kernelcode.com>2026-10-13 15:07:53 -0400
committerChristopher Warner <cwarner@kernelcode.com>2026-10-13 15:07:53 -0400
commit6f3426c481f03f5beeed9171b3280f0070798844 (patch)
treec2cfb41a3a8f17919aa40d76ccf032546165ab75 /README.md
parentead35d75893dcbc34a97beb165a2d46f7741bfc8 (diff)
downloadaerial-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.md137
1 files changed, 116 insertions, 21 deletions
diff --git a/README.md b/README.md
index fc71976..ecc39ee 100644
--- a/README.md
+++ b/README.md
@@ -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.