summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorChristopher Warner <cwarner@kernelcode.com>2026-10-13 15:12:17 -0400
committerChristopher Warner <cwarner@kernelcode.com>2026-10-13 15:12:17 -0400
commit2c8f190bf1e1981813cb04b75b80d46fa79263f5 (patch)
treecb18bd0b2fdeac281a63f9f385de34d56eadac51 /README.md
parent32b692b7712cc6dcb7e17701c55abb4c3a664964 (diff)
downloadaerial-screensaver-linux-2c8f190bf1e1981813cb04b75b80d46fa79263f5.tar.gz
aerial-screensaver-linux-2c8f190bf1e1981813cb04b75b80d46fa79263f5.tar.bz2
aerial-screensaver-linux-2c8f190bf1e1981813cb04b75b80d46fa79263f5.tar.xz
aerial-screensaver-linux-2c8f190bf1e1981813cb04b75b80d46fa79263f5.zip
feat: ship video install path for ThinkPad/Intel users
Add install-aerial-videos, LocalSend lite video pack builder, Intel VAAPI preference, and software x265/x264 encode fallbacks so a T480 can install clips via zip or Apple fetch without AMD-specific assumptions. Co-authored-by: Cursor <cursoragent@cursor.com>
Diffstat (limited to 'README.md')
-rw-r--r--README.md118
1 files changed, 60 insertions, 58 deletions
diff --git a/README.md b/README.md
index ecc39ee..a17ac27 100644
--- a/README.md
+++ b/README.md
@@ -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.