fegger
7be8d59d07
Add mDNS/DNS-SD discovery and JSON session negotiation so two peers on a LAN connect without hard-coded addresses. - Discovery (Avahi threaded-poll client): the receiver announces _screencast._tcp with its signaling port; senders browse and resolve peers. Strict lock ordering (poll lock before state mutex) keeps the callbacks deadlock-free; name collisions rename via avahi_alternative_service_name. - Signaling: one JSON object per newline-terminated TCP line. The receiver hosts a server (port 5005) and answers session offers with its RTP port; senders connect, offer, and stream to the negotiated endpoint. WebSocket was deferred: no WS library is installed, the skill permits plain TCP, and the wire format is transport-agnostic. - Dual-stack transports: this machine resolves its own services over IPv6, so getaddrinfo now runs AF_UNSPEC and listeners bind IPv6 with IPV6_V6ONLY=0 (IPv4 fallback), covering UDP and TCP alike. The signaling client shutdown now uses shutdown() so a reader blocked in recv() cannot hang the join (a plain close() does not wake it). - CLI: --discover lists receivers (deduped to one entry per host); --send auto-disovers when exactly one receiver is found; --peer targets a receiver directly; --signaling-port overrides the default. Validation: meson test 5/5 (new signaling round-trip test), valgrind clean. End-to-end over loopback: --discover finds the announced receiver, a probe negotiated a session and streamed 60 frames over both IPv4 and IPv6, and the receiver reported stream started. mDNS resolution was verified against avahi-browse as an independent reference.
103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
# 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).
|
|
|
|
## 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 {} +
|
|
``` |