# HyprTile Screener – Mini-Info

`hyprtile-screener` ist ein kleines Wayland/Hyprland-Tool zum Aufnehmen des aktuell fokussierten Monitors. Es speichert die Aufnahme als Matroska-Datei (`.mkv`) mit einem freien Video-Codec und kann optional nur einen ausgewählten Bereich aufnehmen.

## Voraussetzungen

Das Tool ist für eine Hyprland-/Wayland-Session gedacht und benötigt zur Laufzeit:

- Hyprland mit `hyprctl`
- Wayland Screencopy Support (`zwlr_screencopy_manager_v1`)
- Wayland Layer Shell für die Bereichsauswahl
- `ffmpeg` zum Schreiben der Matroska-Datei; bevorzugt wird `libsvtav1` (AV1), als Fallback `libvpx-vp9` (VP9)
- optional für Systemton: PulseAudio-kompatibler Zugriff über PipeWire/Pulse und `pactl` zur Default-Sink-Erkennung
- Zugriff auf den fokussierten Monitor über `hyprctl monitors -j`

Codec-Auswahl zur Laufzeit:

- bevorzugt: AV1 über `libsvtav1`
- Fallback: VP9 über `libvpx-vp9`
- Audio mit `--audio`: Opus über `libopus`
- Container: Matroska (`.mkv`)

## Grundverwendung

```bash
hyprtile-screener [optionen]
```

Ohne Optionen startet die Aufnahme mit 12 FPS und läuft, bis sie mit `Ctrl+C` beendet wird.

Die fertige Datei wird standardmäßig hier gespeichert:

```text
~/Videos/Screencasts/HyprTile_Screencast_YYYY-MM-DD_HH-MM-SS.mkv
```

Nach Abschluss gibt das Programm den vollständigen Pfad zur erzeugten Datei aus.

## Optionen

| Option | Beschreibung |
|---|---|
| `-f, --fps FPS` | Aufnahme-FPS. Erlaubt sind Werte von `5` bis `24`. Standard: `12` |
| `-t, --duration SEC` | Aufnahmedauer in Sekunden. Standard: `0`, also aufnehmen bis `Ctrl+C` |
| `-o, --output FILE` | Eigener Ausgabepfad für die Matroska-Datei; muss auf `.mkv` enden |
| `-s, --select` | Vor der Aufnahme einen Bereich mit der Maus auswählen |
| `-c, --cursor` | Mauszeiger in der Aufnahme anzeigen |
| `-d, --delay SEC` | Startverzögerung in Sekunden |
| `-a, --audio` | Nimmt zusätzlich den aktuell hörbaren Systemton auf. Quelle ist automatisch der Monitor des Default-Sinks |
| `--audio-source SRC` | Explizite Pulse/PipeWire-Quelle, z. B. `alsa_output...monitor`. Aktiviert Audio automatisch |
| `-p, --pid-file FILE` | Pfad zur PID-Datei. Standard: `/tmp/hyprtile-screener.pid` |
| `-h, --help` | Hilfe anzeigen |

## Beispiele

### 10 Sekunden mit 24 FPS aufnehmen

```bash
hyprtile-screener --fps 24 --duration 10 --output demo.mkv
```

### Bereich auswählen und Mauszeiger aufnehmen

```bash
hyprtile-screener --fps 12 --select --cursor
```

### Aufnahme nach 3 Sekunden Verzögerung starten

```bash
hyprtile-screener --delay 3 --duration 15
```

### Video mit aktuell hörbarem Systemton aufnehmen

```bash
hyprtile-screener --fps 24 --audio --output demo-mit-ton.mkv
```

Falls eine bestimmte Monitor-Quelle erzwungen werden soll:

```bash
hyprtile-screener --audio-source alsa_output.pci-0000_00_1f.3.analog-stereo.monitor
```

### Aufnahme manuell beenden

```bash
hyprtile-screener
```

Beenden mit:

```bash
Ctrl+C
```

## Bereichsauswahl

Mit `--select` erscheint ein Overlay auf dem fokussierten Monitor. Ziehe mit der linken Maustaste einen Bereich auf. Nach dem Loslassen startet die Aufnahme dieses Bereichs.

Sehr kleine oder abgebrochene Auswahlen werden verworfen.

## PID-Datei

Standardmäßig schreibt das Tool während der Aufnahme seine Prozess-ID nach:

```text
/tmp/hyprtile-screener.pid
```

Das kann praktisch sein, um die Aufnahme aus einem Script oder Hotkey heraus zu stoppen:

```bash
kill "$(cat /tmp/hyprtile-screener.pid)"
```

Nach dem Beenden wird die PID-Datei automatisch entfernt.

## Hinweise

- Die Aufnahme erfolgt vom aktuell fokussierten Hyprland-Monitor.
- Die Ausgabe ist Matroska (`.mkv`). Video wird bevorzugt als AV1 über `libsvtav1` geschrieben; fehlt dieser Encoder, wird VP9 über `libvpx-vp9` verwendet. Bei `--audio` wird Opus über `libopus` verwendet.
- FPS-Werte unter `5` oder über `24` werden abgelehnt.
- Negative Werte für Dauer oder Delay sind nicht erlaubt.

## Häufige Probleme

### `cannot determine focused Hyprland monitor via hyprctl monitors -j`

Hyprland oder `hyprctl` ist nicht verfügbar, oder der fokussierte Monitor konnte nicht ausgelesen werden.

### `required Wayland globals missing`

Die aktuelle Wayland-Session stellt die nötigen Protokolle nicht bereit. Das Tool benötigt mindestens `wl_shm`, `wl_compositor` und `zwlr_screencopy_manager_v1`.

### `ffmpeg failed`

`ffmpeg` fehlt, ist nicht ausführbar oder konnte die Matroska-Datei nicht schreiben. Für Video muss `libsvtav1` oder `libvpx-vp9` verfügbar sein; bei `--audio` zusätzlich `libopus`. Prüfe außerdem, ob der Ausgabeordner existiert und beschreibbar ist. Bei `--audio` zusätzlich prüfen, ob PipeWire/Pulse läuft und ob `pactl get-default-sink` eine gültige Ausgabe liefert.

## Kurzfassung

```bash
# Standardaufnahme bis Ctrl+C
hyprtile-screener

# 10 Sekunden aufnehmen
hyprtile-screener -t 10

# Bereich auswählen, Cursor anzeigen, eigene Datei schreiben
hyprtile-screener -s -c -o demo.mkv

# Video inklusive Systemton aufnehmen
hyprtile-screener --audio -o demo-mit-ton.mkv
```


# Integraion in hyprland
so kann man es in hyprland.conf integrieren:

## Videoaufnahme via print
bind = SHIFT , Print, exec, ~/.local/bin/hyprtile-record-toggle



und ~/.local/bin/hyprtile-record-toggle sollte so aussehen:
```bash
#!/bin/sh

BIN="$HOME/neue_projekte/hyprtile-screener/hyprtile-screener"
PIDFILE="/tmp/hyprtile-screener.pid"
OUTDIR="$HOME/Videos/Screencasts"

mkdir -p "$OUTDIR"

if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; then
    kill -INT "$(cat "$PIDFILE")"
    exit 0
fi

"$BIN" \
    --fps 24 \
    --cursor \
    --pid-file "$PIDFILE" \
    --output "$OUTDIR/recording_$(date +%Y-%m-%d_%H-%M-%S).mkv" &

```
### Hinweis zu Audio-Aufnahmen

Bei `--audio` wird ffmpeg nach dem Schließen des Video-Streams länger sauber auslaufen gelassen, damit Opus-Pakete und die Matroska-Datei sauber finalisiert werden können. Außerdem hält der Recorder den Videostream konstant auf der gewünschten FPS-Zahl, indem bei Lastspitzen der letzte Frame dupliziert wird, statt die Aufnahmezeit zu verkürzen.

## Debugging timing/audio recordings

If a recording is shorter than the real recording time, run with `--debug`:

```bash
./hyprtile-screener --fps 24 --audio --debug --output demo-debug.mkv 2> screener-debug.log
```

The debug log prints the ffmpeg command, wall-clock recording time, captured frame count, duplicated frame count, final frame count, expected frame count, and ffmpeg exit status.

This build pads the final frame up to the actual stop time before closing ffmpeg stdin. This is necessary because ffmpeg receives rawvideo over stdin without per-frame timestamps; the video duration is therefore calculated from `frames / fps`.

## Debug-/Audio-Fix v4

Bei Aufnahmen mit `--audio` wird `ffmpeg` nun in eine eigene Prozessgruppe gesetzt. Dadurch bekommt `ffmpeg` beim Stoppen per Ctrl+C nicht mehr gleichzeitig das Terminal-Signal ab, während der Recorder noch versucht, stdin sauber zu schließen und die Matroska-Datei zu finalisieren. Der Recorder steuert das Beenden von `ffmpeg` danach selbst.

Der Debug-Log enthält zusätzlich die PID des Recorders, die PID von `ffmpeg` sowie das empfangene Stop-Signal:

```bash
hyprtile-screener --fps 24 --audio --debug --output demo.mkv 2> screener-debug.log
```

Eine typische Stop-Zeile sieht nun so aus:

```text
hyprtile-screener debug: frames: captured=... duplicated=... total=... expected=... elapsed=... video=... stop_signal=yes stop_signal_num=2 stop_signal_name=SIGINT
```

Falls `ffmpeg` nach sauberem Video-EOF wegen des live laufenden Audio-Inputs kontrolliert per SIGINT gestoppt werden muss, wird der dabei übliche ffmpeg-Exitcode 255 nicht mehr als harter Fehler behandelt.
