summaryrefslogtreecommitdiff
path: root/README.md
blob: ecc39ee6a8bec663e980f2f669d4d28c206a84b0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# 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.

> This package is the **player + tooling**. Apple’s video assets are not redistributed here — download them yourself (helper included).

## 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

## Requirements

| 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.