# Runbook — build and validation commands

Reusable validation steps for this repository. Run the relevant ones before
considering a change complete.

## Build and test

```sh
meson setup build          # once
meson compile -C build
meson test -C build --print-errorlogs
```

## Memory and correctness checks (codec changes)

Run the codec round-trip test under valgrind after touching the encoder or
decoder:

```sh
valgrind --leak-check=full --errors-for-leak-kinds=definite \
    build/tests/test_codec_roundtrip
```

Expected: no "definitely lost" bytes and no "Invalid read/write" errors.
FFmpeg may keep some "still reachable" allocations at exit; that is normal.

This check caught two real defects in the Phase 2 decoder: a per-packet
payload leak and an unpadded extradata buffer over-read. Keep using it.

## Capture smoke test (Phase 3, manual)

Requires a running desktop session with `xdg-desktop-portal` and a backend
that implements the ScreenCast portal (e.g. Hyprland, GNOME, KDE). The
portal shows an interactive source picker, so this cannot run unattended.

```sh
meson compile -C build                       # builds tools/capture_smoke
./build/tools/capture_smoke 10 out.h264      # captures 10 frames
ffprobe -v error -show_entries stream=codec_name,width,height out.h264
```

Expected: the tool prints the negotiated resolution/format/stride and
writes a non-empty file; `ffprobe` reports `codec_name=h264` and the correct
width/height. The encoder prepends its Annex-B SPS/PPS extradata so the
file is a self-contained elementary stream.

If you see `impl_ext_end_proxy called from wrong context` warnings, a
PipeWire proxy operation ran without the thread-loop lock — all pw
calls that send messages (connect, stream, core) must happen under
`pw_thread_loop_lock`.

## LAN discovery and signaling (Phase 6)

Two machines on the same LAN (mDNS via avahi-daemon, which must be running
on both):

```sh
screencast --receive                # machine A: announce + window
screencast --send                   # machine B: discovers A, negotiates, streams
screencast --discover               # list receivers on the LAN
```

`--send` without `--peer` requires exactly one discovered receiver. Use
`--peer HOST[:PORT]` to target a receiver directly (signaling port defaults
to 5005), e.g. `--peer 192.168.178.20`.

Operational note: never `kill -9` a running receiver — a SIGKILLed process
cannot withdraw its mDNS registration, and avahi-daemon then keeps broken
records for that service name until they expire (~75 min), making resolution
time out for every peer. If that happens, `systemctl restart avahi-daemon`
clears it. Always stop screencast with Ctrl-C (SIGTERM).

## Receiver as a systemd service (autostart)

`scripts/install-receiver.sh` installs and enables
`screencast-receiver.service` (see `systemd/screencast-receiver.service`).
It starts at boot after the network and avahi-daemon, and restarts on
failure. On a headless console SDL renders via KMSDRM; on a desktop
autologin, edit `/etc/systemd/system/screencast-receiver.service` and
uncomment the Environment lines for `XDG_RUNTIME_DIR`/`WAYLAND_DISPLAY`.

```sh
systemctl status  screencast-receiver          # is it running?
journalctl -u screencast-receiver -f           # follow logs
sudo systemctl stop screencast-receiver        # graceful; withdraws mDNS
sudo systemctl disable --now screencast-receiver  # turn autostart off
```

Verified behavior: `systemctl stop` results in a clean exit (success,
no restart) and the mDNS announcement is withdrawn — senders stop finding
the receiver immediately.

## Sender / receiver loopback (Phase 5, manual)

Two terminals on the same desktop session:

```sh
./build/src/app/screencast --receive        # terminal 1: window appears
./build/src/app/screencast --send           # terminal 2: portal source picker
```

Expected: the receiver window shows the captured desktop in near real time.
If the receiver starts after the sender, a few `non-existing PPS` decode
errors are normal until the next keyframe arrives (the GOP is ~0.4s);
video should appear within a second. Stop either side with Ctrl-C.
Optional flags: `--port`, `--peer HOST[:PORT]`, `--bitrate KBPS`,
`--target window`.

Notes: the encoder runs a VBV that caps keyframe bursts to roughly two
frame periods of bytes, and the receiver requests a 4MB UDP receive
buffer (clamped by `net.core.rmem_max`). For very high `--bitrate`
values, raise `net.core.rmem_max` on the receiver machine.

The headless equivalent runs as part of `meson test` (`udp loopback` test):
synthetic frames → encode → packetize → localhost UDP → depacketize →
decode, no portal or window involved.

## Formatting

```sh
find include src tests -type f \( -name '*.cpp' -o -name '*.h' \) \
    -exec clang-format --dry-run --Werror {} +
```