diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 118 |
1 files changed, 60 insertions, 58 deletions
@@ -1,114 +1,116 @@ # Aerial Screensaver for Linux (GNOME) -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. +Idle screensaver that plays Apple Aerial–style clips with **mpv**, on **every connected monitor**. Quiet defaults: AC-only, 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). +Works on AMD (Framework) and **Intel** laptops (e.g. **ThinkPad T480** / UHD 620). -## Features - -- 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 +> Player + tooling are MIT. Apple’s video assets stay Apple’s — install them with the helpers or the optional LocalSend video pack. ## Requirements | Package | Why | |---|---| | GNOME (Wayland) | IdleMonitor + DisplayConfig | -| `python3` + PyGObject (`python3-gobject` / `python3-gi`) | Daemon | +| `python3` + PyGObject | Daemon | | `mpv` | Playback | -| `ffmpeg` (VAAPI HEVC) | Optional encode | -| `aria2c`, `curl`, `jq`/`python3` | Optional fetch helper | +| `ffmpeg` | Optional encode | +| `aria2c`, `curl`, `unzip` | Optional fetch / video zip | | `systemd --user` | Autostart | -Fedora / CachyOS example: +### Fedora / CachyOS (ThinkPad T480) ```bash -sudo dnf install mpv ffmpeg python3-gobject aria2 curl +sudo dnf install mpv ffmpeg python3-gobject aria2 curl unzip \ + intel-media-driver libva libva-utils ``` -## Quick install +### Debian / Ubuntu ```bash -git clone https://git.kernelcode.com/aerial-screensaver-linux -# or unzip the LocalSend archive, then: -cd aerial-screensaver-linux -./install.sh +sudo apt install mpv ffmpeg python3-gi aria2 curl unzip \ + intel-media-va-driver-non-free ``` -`install.sh` installs: +Verify VAAPI: `vainfo` (should list Intel entrypoints). -- `~/.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: +## Install ```bash -systemctl --user status aerial-screensaver +unzip aerial-screensaver-linux.zip +cd aerial-screensaver-linux +./install.sh ``` -## Get videos +### Get the videos (pick one) -### Option A — fetch recent Apple pack (recommended) - -Tahoe / Sequoia / Sonoma / Cazadero from Apple’s public macOS catalog: +**A. LocalSend video pack (best for T480)** — no multi-GB Apple download / long encode: ```bash -fetch-aerial-recent --encode +./install.sh --videos-zip ~/Downloads/aerial-videos-lite.zip +# or later: +install-aerial-videos --from-zip ~/Downloads/aerial-videos-lite.zip ``` -Downloads masters, then encodes lite 1080p24 clips into `~/Videos/Screensavers/Aerial`. - -### Option B — your own files +**B. Download from Apple + encode on this machine** (slower on T480): ```bash -mkdir -p ~/Videos/Screensavers/Aerial -# copy .mp4 / .mov / .mkv there +./install.sh --fetch-videos +# or later: +install-aerial-videos ``` -### Option C — encode masters you already have +**C. Your own files** — drop `.mp4` / `.mov` / `.mkv` in: -```bash -encode-aerial-lite /path/to/4k-masters +```text +~/Videos/Screensavers/Aerial ``` +## What gets installed + +| Path | Role | +|---|---| +| `~/.local/bin/aerial-screensaver` | Idle daemon | +| `~/.local/bin/install-aerial-videos` | Install / fetch clips | +| `~/.local/bin/fetch-aerial-recent` | Download Apple recent pack | +| `~/.local/bin/encode-aerial-lite` | 1080p24 lite encoder | +| `~/.config/systemd/user/aerial-screensaver.service` | Autostart | +| `~/.config/aerial-screensaver/config` | Settings | +| `~/Videos/Screensavers/Aerial` | Clip library | + ## Config -Edit `~/.config/aerial-screensaver/config`: +`~/.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 +VAAPI_DEVICE=/dev/dri/renderD128 ``` -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. +On hybrid GPUs, leave `VAAPI_DEVICE` on the **iGPU** (Intel on T480, AMD display-class on Framework). `install.sh` auto-detects. -Environment overrides (prefix `AERIAL_`): `AERIAL_VIDEO_DIR`, `AERIAL_IDLE_TIMEOUT_SECONDS`, `AERIAL_VAAPI_DEVICE`, `AERIAL_REQUIRE_AC`. +## Sharing (LocalSend) -## Uninstall +Send **two** files: -```bash -./uninstall.sh -``` +| File | Size | Contents | +|---|---|---| +| `aerial-screensaver-linux.zip` | ~15KB | Code + installer | +| `aerial-videos-lite.zip` | ~1GB | 12 ready-to-play 1080p clips | -Videos and `~/.config/aerial-screensaver/` are left in place. +Recipient: -## Sharing +```bash +unzip aerial-screensaver-linux.zip && cd aerial-screensaver-linux +./install.sh --videos-zip ~/Downloads/aerial-videos-lite.zip +``` -| 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) | +## Uninstall -Do not commit or publish Apple’s `.mov` masters — fetch them per machine. +```bash +./uninstall.sh +``` ## Tests @@ -118,4 +120,4 @@ python3 test_screensaver.py -v ## License -MIT (this software only). Aerial video content remains Apple’s. +MIT for this software. Aerial footage remains Apple’s; we only provide download/install helpers and an optional private LocalSend pack of already-encoded lite clips. |
