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

## Formatting

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