Files
hyprland-headless-stream-pl…/tests/unit/test_wayland_capture.py
T
Hermenix a7d9357b43 capture: an in-process Wayland backend, and the measurements that justify it
The frame server could only capture by running a program once per frame
(grim). That works, but ~95% of a grim frame is waiting -- fork, connect,
handshake, round trip -- not encoding, and grim makes the compositor import
a *new* shared-memory buffer for every single frame.

This adds `--capture wayland[:OUTPUT]`: one long-lived zwlr-screencopy-v1
client per server, with one shm buffer reused for the whole run, capturing
inside the process. Measured here at 1280x720 (spike capture-speed, 200
frames; live re-check on Virtual-1, 60 frames):

    grim (subprocess)    117.3 ms/frame   8.1 fps   compositor 116.4 ms
    grim-rs (Rust crate) 124.6 ms/frame   7.5 fps   compositor 123.1 ms
    this backend          78.0 ms/frame  13.9 fps   compositor  67.5 ms

    live, PNG both sides: this 128.5 ms/frame against grim's 389.3 ms (3.0x)

Three findings, each of which shaped the code:

* The win is buffer reuse, not language. grim and grim-rs both hand the
  compositor a fresh buffer per frame, which is why their compositor CPU is
  nearly double ours. The per-frame allocate-copy-swizzle that grim-rs pays
  was measured in isolation at 2.4 ms of *client* time; the rest of its
  deficit lands inside the compositor.
* ext-image-copy-capture-v1 is no faster (78.0 vs 77.7 ms) and its
  create_frame path appears in a Hyprland segfault stack, so this keeps the
  deprecated protocol grim uses. The switch is one constant when that crash
  is fixed.
* PNG only, deliberately: PNG is the one encoding this package produces
  without a dependency, so --format jpeg is refused rather than publishing a
  Hello whose MIME type the frames do not have. A PNG frame is ~2.1 MB
  against ~120 KB for JPEG q80, which is why the command backend stays the
  default and why a libjpeg-turbo encoder (1.7 ms/frame, measured) is the
  obvious follow-up.

The timeout is the load-bearing part of the client: pywayland only reads
events from read()/dispatch(block=True), neither of which takes a timeout,
and the server captures in a worker thread where SIGALRM is unavailable. It
therefore polls the display fd itself, so a compositor that stops answering
produces a CaptureError instead of a capture thread that never returns.

The protocol bindings are vendored under src/hhstream/_protocol/ exactly the
way hhstream_pointer already vendors its two, with regenerate.py recording
where each XML came from. No new dependency: pywayland was already required
by the input driver.

Contract: the new server flag and the two new module options are documented
in docs/CONTRACT.md, and docs/ARCHITECTURE.md's prediction that a native
screencopy client would be "a swap rather than a rewrite" is now the record
of what the swap cost.

Unit suite: 977 passed, 2 skipped, 0 failed (nix build -L .#checks.unit).
The live numbers were taken on this VM against the real compositor.
2026-10-11 20:34:33 +00:00

131 lines
4.9 KiB
Python

"""The in-process capture backend, in the parts that need no compositor.
Everything that needs a real Wayland connection is left to the vm checks
(`checks/vm-hyprland.nix` runs the server against the actual headless
compositor), so what is worth testing here is the behaviour around the edges: the
timeout that stops a frame from hanging forever, the recovery path that makes a
dead compositor reconnectable, and the argv the module and the CLI agree on.
The `_pump` tests are the point of the file. `pywayland` only reads events from
`read()` and `dispatch(block=True)`, neither of which takes a timeout, so a
compositor that stops answering used to mean a capture thread that never returns
-- and a frame server that has silently stopped serving while its socket still
accepts connections. The stub display below is a real pipe fd that never becomes
readable: the test passes only if the deadline is what ends the wait.
"""
from __future__ import annotations
import os
import pytest
from hhstream.capture import CaptureError
from hhstream.server import _build_capture_backend, _join_capture_tokens, build_parser
from hhstream.wayland_capture import WaylandCapture
class _StubDisplay:
"""Just enough `Display` for `_pump`: a fd, and a dispatch that finds nothing."""
def __init__(self, fd: int) -> None:
self._fd = fd
self.reads = 0
def get_fd(self) -> int:
return self._fd
def flush(self) -> None:
return None
def dispatch(self, *, block: bool = False, queue=None) -> int:
return 0
def read(self, *, queue=None) -> None:
# Reached only if select() said the fd was readable; on this pipe it never
# is, so arriving here means the wait was not bounded by the deadline.
self.reads += 1
raise AssertionError("read() called although nothing was readable")
def test_a_frame_that_never_arrives_raises_instead_of_hanging():
capture = WaylandCapture(timeout=0.05)
read_fd, write_fd = os.pipe()
stub = _StubDisplay(read_fd)
capture._display = stub
try:
with pytest.raises(CaptureError, match="timed out"):
capture._pump(lambda: False, "the compositor never sent the frame")
assert stub.reads == 0, "it waited on a readable fd instead of on the clock"
finally:
os.close(read_fd)
os.close(write_fd)
def test_the_pump_returns_immediately_when_it_is_already_done():
"""A queued event must not cost a select() timeout to notice."""
capture = WaylandCapture(timeout=0.05)
read_fd, write_fd = os.pipe()
capture._display = _StubDisplay(read_fd)
try:
capture._pump(lambda: True, "nothing to wait for")
finally:
os.close(read_fd)
os.close(write_fd)
def test_size_is_unknown_until_a_frame_has_actually_been_captured():
"""The Hello must never carry a size that was guessed."""
capture = WaylandCapture()
assert capture.size() == (0, 0)
def test_close_is_safe_twice_and_before_anything_was_opened():
"""`close()` is the recovery path, so it runs on a half-torn-down backend."""
capture = WaylandCapture()
capture.close()
capture.close()
assert capture.size() == (0, 0)
def test_a_timeout_of_zero_or_less_is_refused_at_construction():
with pytest.raises(ValueError, match="positive"):
WaylandCapture(timeout=0)
@pytest.mark.parametrize(
"spec, expected_output",
[("wayland", None), ("wayland:Virtual-1", "Virtual-1"), ("wayland:", None)],
)
def test_the_backend_spec_selects_an_output_without_connecting(spec, expected_output):
"""Constructing the backend must not open a connection -- grab() does."""
backend = _build_capture_backend(spec, "png")
assert isinstance(backend, WaylandCapture)
assert backend.output_name == expected_output
assert backend._display is None, "the connection belongs to grab(), not to __init__"
@pytest.mark.parametrize("spec", ["grim", "wayland:too:many:colons:here", "x11"])
def test_an_unknown_backend_spec_is_refused_rather_than_guessed(spec, caplog):
"""`wayland:a:b` is not an output name, and guessing would capture the wrong
output silently."""
assert _build_capture_backend(spec, "png") is None
def test_jpeg_is_refused_rather_than_advertised_in_the_hello(caplog):
"""The Hello carries the MIME type; publishing jpeg over PNG frames would
mis-decode every frame in every client, so it is refused up front."""
assert _build_capture_backend("wayland", "jpeg") is None
assert "PNG only" in caplog.text
def test_the_backend_flag_survives_the_token_folding_that_capture_tokens_need():
folded = _join_capture_tokens(["--capture", "wayland:Virtual-1", "--fps", "10"])
assert folded == ["--capture=wayland:Virtual-1", "--fps", "10"]
assert build_parser().parse_args(folded).capture == "wayland:Virtual-1"
def test_no_backend_flag_still_means_the_command_backend():
args = build_parser().parse_args(["--socket", "/tmp/x.sock"])
assert args.capture is None