# hyprtile-wallpaperd(1)

## NAME

**hyprtile-wallpaperd** - nativer HyprTile-Wallpaper-Dienst für Hyprland/Wayland

## SYNOPSIS

```sh
hyprtile-wallpaperd --image /pfad/zum/wallpaper.png [--mode cover|contain|stretch|center] [--pidfile PFAD]
```

Normalerweise wird `hyprtile-wallpaperd` nicht manuell gestartet. Wenn das Wallpaper-Feature in `config.json` aktiviert ist, startet `hyprtile` den Dienst automatisch beim Programmstart.

## BESCHREIBUNG

`hyprtile-wallpaperd` setzt ein statisches Bild als Desktop-Hintergrund über Wayland Layer-Shell. Der Dienst legt sich auf den Background-Layer des Compositors und erzeugt pro Monitor eine eigene Layer-Surface. Dadurch ersetzt er typische externe Wallpaper-Tools für diesen einfachen Anwendungsfall.

Das Bild wird über FFmpeg/LibAV geladen. Dadurch funktionieren übliche Bildformate wie PNG, JPEG und WebP, abhängig davon, welche Decoder auf dem System verfügbar sind.

## CONFIG.JSON

Das Feature wird in der HyprTile-Config gesteuert:

```json
{
  "wallpaper": 1,
  "wallpaper_file": "/home/deinuser/Bilder/wallpaper.png",
  "wallpaper_mode": "cover"
}
```

### wallpaper

Aktiviert oder deaktiviert den Wallpaper-Dienst.

- `0` = aus
- `1` = an

Alias: `wallpaper_enabled`

### wallpaper_file

Absoluter oder relativer Pfad zum Bild, das als Hintergrund verwendet werden soll.

Empfohlen ist ein absoluter Pfad, zum Beispiel:

```json
"wallpaper_file": "/home/alex/Bilder/wallpaper.webp"
```

Alias: `wallpaper_path`

Wenn `wallpaper` aktiv ist, aber `wallpaper_file` leer ist oder auf keine existierende Datei zeigt, startet HyprTile den Dienst nicht und schreibt eine Warnung ins Log.

### wallpaper_mode

Legt fest, wie das Bild auf die Monitorfläche skaliert wird.

| Modus | Verhalten |
|---|---|
| `cover` | Füllt den kompletten Monitor aus. Das Bild kann seitlich oder oben/unten beschnitten werden. Das ist der empfohlene Standard. |
| `contain` | Zeigt das komplette Bild ohne Beschnitt. Es können schwarze Ränder entstehen. |
| `stretch` | Streckt das Bild exakt auf Monitorgröße. Das kann das Seitenverhältnis verzerren. |
| `center` | Zeichnet das Bild unskaliert mittig. Zu große Bilder werden beschnitten, zu kleine Bilder bekommen Ränder. |

## AUTOSTART DURCH HYPRTILE

Beim Start prüft `hyprtile`:

1. Ist `wallpaper` aktiviert?
2. Ist `wallpaper_file` gesetzt?
3. Existiert die Bilddatei?
4. Läuft bereits ein Dienst laut `~/.hyprtile/wallpaperd.pid`?
5. Liegt `hyprtile-wallpaperd` neben der `hyprtile`-Binary?

Nur wenn alles passt und noch kein Dienst läuft, wird `hyprtile-wallpaperd` automatisch gestartet.

Die Binary sollte daher im selben Verzeichnis liegen wie `hyprtile`, zum Beispiel:

```text
/usr/bin/hyprtile
/usr/bin/hyprtile-wallpaperd
```

oder im lokalen Build-Verzeichnis:

```text
./hyprtile
./hyprtile-wallpaperd
```

## MANUELLER START

Zum Testen kann der Dienst direkt gestartet werden:

```sh
./hyprtile-wallpaperd --image ~/Bilder/wallpaper.png --mode cover --pidfile ~/.hyprtile/wallpaperd.pid
```

Ohne `--pidfile` läuft der Dienst ebenfalls, aber HyprTile kann dann nicht sauber erkennen, ob bereits eine Instanz aktiv ist.

## BEENDEN / NEU LADEN

Der Dienst lädt das Bild aktuell beim Start. Wenn du das Wallpaper änderst, beende den Dienst und starte HyprTile erneut oder starte den Dienst manuell neu.

```sh
kill "$(cat ~/.hyprtile/wallpaperd.pid)"
```

Danach HyprTile erneut starten.

## OPTIONEN

### --image PFAD

Pfad zum Wallpaper-Bild. Diese Option ist erforderlich.

### --mode MODUS

Skalierungsmodus. Erlaubt sind:

```text
cover, contain, stretch, center
```

Standard ist `cover`.


### --scale FAKTOR

Muss direkt auf einen `--shader`/`--frag`-Pass folgen und setzt dessen interne Renderauflösung. Erlaubt sind Werte von `0.10` bis `1.0`. Beispiel:

```sh
hyprtile-wallpaperd --shader heavy.frag --scale 0.5 --shader final.frag --scale 1.0
```

`0.5` rendert den betreffenden Pass mit halber Breite und Höhe, also nur einem Viertel der Fragmente. Das ist besonders für Raymarch-, Blur- und volumetrische Wallpaper-Shader wichtig. Der nächste Pass kann wieder in höherer Auflösung laufen; Texturen werden dabei linear skaliert.

### --pidfile PFAD

Schreibt die Prozess-ID in die angegebene Datei und nutzt zusätzlich einen Lock, damit nicht versehentlich mehrere Instanzen parallel gestartet werden.

## BUILD

Das Tool wird über den normalen HyprTile-`Makefile`-Build mitgebaut.

```sh
make
```

Erwartetes Ergebnis:

```text
hyprtile
hyprtile-wallpaperd
```

## ABHÄNGIGKEITEN

Zusätzlich zu den bestehenden HyprTile-Abhängigkeiten benötigt das Wallpaper-Feature die Wayland-Client-Development-Headers und die bereits genutzten FFmpeg/LibAV-Bibliotheken.

Typische Paketnamen, je nach Distribution:

```text
wayland-devel / libwayland-dev
ffmpeg-devel / libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
```

Außerdem muss der Compositor `wlr-layer-shell` anbieten. Hyprland tut das.

## TROUBLESHOOTING

### Es erscheint kein Wallpaper

Prüfen:

```sh
grep wallpaper ~/.hyprtile/config.json
ls -l /pfad/zum/wallpaper.png
pgrep -a hyprtile-wallpaperd
```

Häufige Ursachen:

- `wallpaper` steht noch auf `0`
- `wallpaper_file` ist leer
- der Pfad ist falsch
- `hyprtile-wallpaperd` liegt nicht neben der `hyprtile`-Binary
- der Dienst läuft bereits mit einem alten Bild

### Das Bild wirkt verzerrt

`wallpaper_mode` steht vermutlich auf `stretch`. Für normale Wallpaper ist meistens `cover` richtig.

### Ich sehe schwarze Balken

Das ist bei `contain` und `center` normal. Nutze `cover`, wenn der gesamte Bildschirm gefüllt werden soll.

### Mehrere Monitore

Der Dienst erzeugt pro Wayland-Output eine eigene Hintergrundfläche. Dasselbe Wallpaper wird auf jedem Monitor passend zum jeweiligen Modus gezeichnet.

## BEISPIELE

Vollflächiges Wallpaper ohne sichtbare Ränder:

```json
"wallpaper": 1,
"wallpaper_file": "/home/alex/Bilder/neon-city.webp",
"wallpaper_mode": "cover"
```

Komplettes Bild ohne Beschnitt:

```json
"wallpaper": 1,
"wallpaper_file": "/home/alex/Bilder/poster.png",
"wallpaper_mode": "contain"
```

Pixel-Art unskaliert mittig:

```json
"wallpaper": 1,
"wallpaper_file": "/home/alex/Bilder/pixelart.png",
"wallpaper_mode": "center"
```

## EXIT STATUS

- `0` = normal beendet
- `1` = Startfehler, fehlende Argumente, Bild konnte nicht geladen werden oder Wayland/Layer-Shell nicht verfügbar

## SEE ALSO

`hyprtile(1)`, `Hyprland`, `wlr-layer-shell`, `wayland-client`, `ffmpeg`
