Files
hyprland-headless-stream-pl…/tests/unit/test_wayland_capture.py
T
Hermenix 7190960120 capture: encode JPEG in-process too, so the live stream keeps working
PNG-only was a real defect, not a nice-to-have: `hhstream_live.server` serves
`multipart/x-mixed-replace` with `image/jpeg` parts and its own capture default is
`grim -c -t jpeg -q 80 -`, so switching this backend on would have broken video
streaming while looking faster in a benchmark.

JPEG now goes through libjpeg-turbo by ctypes, using its `TJPF_BGRX` input format
-- which is exactly the compositor's B, G, R, X memory order, so the frame goes
into the encoder with no copy and no colour conversion. Measured on this VM
against the real compositor, the deployment's own settings (Virtual-1, 1280x720,
jpeg q80, 200 frames each, two runs):

                        p50 ms   fps    our CPU   compositor CPU
    in-process           76.2   13.1     2.1 ms      51.5 ms
    grim -c -t jpeg     137.0    7.3     0.5 ms      80.2 ms
                                                          (second run: 84/144,
                                                           55.1/79.8 -> 1.71x)

So ~1.7-1.8x the frame rate and ~1.5x less of the compositor's CPU, with frames
of the same order (188 KB against grim's 222 KB). PNG stays available through the
stdlib for a deployment that would rather not carry the library.

Both segfault-class traps from the spike are handled and documented: every
argtype is declared (an undeclared pitch is a crash, not a wrong number), and
`*jpegBuf` is reset to NULL after `tjFree` (turbojpeg reads a non-NULL pointer as
a caller buffer, so the next frame would write into freed memory). The decoder is
here because a lossy codec can only be tested by round-tripping pixels -- the new
suite encodes solid blocks whose channels differ enough that a swap is
unmistakable, and includes a padded stride.

Packaging: libjpeg-turbo is reached through ctypes, so nothing links it and the
path must reach the loader -- the console scripts get a wrapper with it on
LD_LIBRARY_PATH, and the unit check exports it too. A missing library is reported
at startup rather than once per frame: a server that is up but can never produce
a frame is worse than one that refuses to start.

Verified end to end: server with `--capture wayland:Virtual-1 --format jpeg`,
client Hello `image/jpeg`, three frames read, each magic `ffd8`.
2026-10-11 22:58:28 +00:00

170 lines
6.4 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", 80)
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", 80) is None
def test_jpeg_is_what_the_backend_uses_when_jpeg_is_asked_for():
"""The live viewer serves image/jpeg parts, so this is the format that has to
work -- a PNG-only backend would break video streaming."""
backend = _build_capture_backend("wayland", "jpeg", 80)
assert isinstance(backend, WaylandCapture)
assert (backend.codec, backend.quality) == ("jpeg", 80)
def test_png_never_needs_the_jpeg_library(monkeypatch):
"""A deployment that chose png must not require libjpeg-turbo on the box."""
import hhstream.jpeg as jpeg
def explode(*_args, **_kwargs):
raise jpeg.JPEGError("no libjpeg-turbo anywhere")
monkeypatch.setattr(jpeg, "TurboJPEG", explode)
backend = _build_capture_backend("wayland", "png", 80)
assert isinstance(backend, WaylandCapture)
assert backend.codec == "png"
def test_a_missing_jpeg_library_refuses_to_start_rather_than_never_serving(monkeypatch, caplog):
"""A server that is up but can never produce a frame is worse than one that
refuses to start: its socket still accepts connections."""
import hhstream.jpeg as jpeg
def explode(*_args, **_kwargs):
raise jpeg.JPEGError("no libjpeg-turbo anywhere")
monkeypatch.setattr(jpeg, "TurboJPEG", explode)
assert _build_capture_backend("wayland", "jpeg", 80) is None
assert "cannot capture as jpeg" 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_quality_defaults_to_match_the_command_backend():
"""`grim -q 80` is what the deployment used, so a swap must not change it."""
args = build_parser().parse_args(["--capture", "wayland"])
assert args.capture_quality == 80
@pytest.mark.parametrize("bad", ["0", "101", "-5"])
def test_an_impossible_quality_is_refused(bad):
with pytest.raises(SystemExit):
build_parser().parse_args(["--capture-quality", bad])
def test_no_backend_flag_still_means_the_command_backend():
args = build_parser().parse_args(["--socket", "/tmp/x.sock"])
assert args.capture is None