Files
hyprland-headless-stream-pl…/tests/unit/test_jpeg.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

165 lines
6.0 KiB
Python

"""`hhstream.jpeg`: the libjpeg-turbo binding, checked by round-tripping pixels.
A lossy codec cannot be tested by looking at a file header, so these tests encode a
raster and decode it again through the same library. The raster is chosen to fail
loudly on the two mistakes that matter here: uniformly filled blocks (JPEG
reproduces a solid block almost exactly, so a tolerance of a few counts is honest)
whose channels differ enough that a BGR/RGB mix-up is unmistakable, and a padded
stride, because assuming `width * 4` is the bug grim shipped in 1.5.
This is also the only test of the pixel-format claim the backend rests on:
`TJPF_BGRX` exists precisely so the compositor's B, G, R, X buffer can go into the
encoder unconverted. If that were the wrong format, the decoded block colours come
back swapped and these tests say so.
"""
from __future__ import annotations
import ctypes
import pytest
from hhstream.jpeg import DEFAULT_QUALITY, JPEGError, TurboJPEG
BLOCK = 16
def blocks() -> list[tuple[int, int, int]]:
"""Four colours whose channels differ enough that a swap cannot hide."""
return [(200, 30, 30), (30, 200, 30), (30, 30, 200), (140, 120, 100)]
def as_rgb(colour: tuple[int, int, int]) -> tuple[int, int, int]:
"""`blocks()` writes memory order (B, G, R); assertions read (R, G, B).
Getting these two the wrong way round is indistinguishable from a wrong pixel
format in the encoder -- which is exactly what this file exists to detect, so
the conversion is named rather than done inline.
"""
blue, green, red = colour
return red, green, blue
def colour_at(x: int, y: int, width: int) -> tuple[int, int, int]:
"""The block colour at a pixel, wrapping so any frame size is covered.
One formula for both the raster and the assertions: they used to index the
four colours independently, which ran off the end of the list for anything
bigger than a 2x2 grid of blocks.
"""
column = x // BLOCK
row = y // BLOCK
return blocks()[((row * (width // BLOCK)) + column) % len(blocks())]
def raster(width: int = 64, height: int = 64, stride: int | None = None) -> tuple[bytes, int]:
"""A BGRX frame of solid blocks; returns (bytes, stride)."""
stride = stride if stride is not None else width * 4
out = bytearray()
for y in range(height):
row = bytearray()
for x in range(width):
b, g, r = colour_at(x, y, width)
row += bytes((b, g, r, 0x00))
row += b"\x77" * (stride - width * 4) # padding, if any
out += row
return bytes(out), stride
def address_of(pixels: bytes) -> int:
return ctypes.addressof(ctypes.create_string_buffer(pixels, len(pixels)))
def centre_colour(pixels: bytes, stride: int, x: int, y: int) -> tuple[int, int, int]:
offset = y * stride + x * 4
blue, green, red, _ = pixels[offset:offset + 4]
return red, green, blue
def test_a_frame_round_trips_with_its_channels_in_the_right_place():
enc = TurboJPEG()
try:
pixels, stride = raster()
encoded = enc.compress(address_of(pixels), 64, 64, stride)
width, height, decoded = enc.decompress(encoded)
assert (width, height) == (64, 64)
for column, row in ((0, 0), (1, 0), (2, 0), (0, 1), (3, 3)):
x, y = column * BLOCK + BLOCK // 2, row * BLOCK + BLOCK // 2
want = as_rgb(colour_at(x, y, 64))
got = centre_colour(decoded, width * 4, x, y)
assert got == pytest.approx(want, abs=12), (
f"block ({row}, {column}) came back as {got}, expected ~{want} "
"-- a swapped channel order or a wrong pixel format"
)
# Being close is not enough on its own: assert the channels are
# distinguishable, so a swap could not pass as "close enough".
assert max(want) - min(want) > 24, "pick colours a swap would expose"
finally:
enc.close()
def test_a_padded_stride_is_honoured():
"""The padding bytes are deliberately not black; leaking them changes the
last column of every row."""
enc = TurboJPEG()
try:
pixels, stride = raster(64, 64, stride=64 * 4 + 32)
assert stride != 64 * 4
encoded = enc.compress(address_of(pixels), 64, 64, stride)
_, _, decoded = enc.decompress(encoded)
got = centre_colour(decoded, 64 * 4, 8, 8)
assert got == pytest.approx(as_rgb(colour_at(8, 8, 64)), abs=12), got
finally:
enc.close()
def test_quality_trades_bytes_for_fidelity():
enc = TurboJPEG()
try:
pixels, stride = raster()
small = enc.compress(address_of(pixels), 64, 64, stride, quality=20)
large = enc.compress(address_of(pixels), 64, 64, stride, quality=95)
assert len(small) < len(large)
finally:
enc.close()
def test_the_output_is_really_a_jpeg():
enc = TurboJPEG()
try:
pixels, stride = raster()
encoded = enc.compress(address_of(pixels), 64, 64, stride)
assert encoded.startswith(b"\xff\xd8"), "missing SOI marker"
assert b"\xff\xc0" in encoded, "missing SOF0 marker"
assert encoded.endswith(b"\xff\xd9"), "missing EOI marker"
finally:
enc.close()
def test_the_default_quality_is_the_one_the_capture_command_used():
"""`grim -c -t jpeg -q 80 -` is the deployment's command; a swap must not
silently change the frames' size or quality."""
assert DEFAULT_QUALITY == 80
@pytest.mark.parametrize("quality", [0, -1, 101])
def test_an_impossible_quality_is_refused(quality):
enc = TurboJPEG()
try:
pixels, stride = raster()
with pytest.raises(ValueError, match="1..100"):
enc.compress(address_of(pixels), 64, 64, stride, quality=quality)
finally:
enc.close()
def test_a_library_that_is_not_there_is_a_clear_error_not_a_crash():
with pytest.raises(JPEGError, match="cannot load libjpeg-turbo"):
TurboJPEG(path="/nonexistent/libturbojpeg.so")
def test_close_is_safe_twice():
enc = TurboJPEG()
enc.close()
enc.close()