Files
hyprland-headless-stream-pl…/nix/package.nix
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

84 lines
3.5 KiB
Nix

{
lib,
libjpeg_turbo,
python3,
...
}:
python3.pkgs.buildPythonApplication {
pname = "hhstream";
version = "0.1.0";
pyproject = true;
src = ../.;
build-system = [ python3.pkgs.setuptools ];
# `hhstream-pointer` is a Wayland client, so it needs libwayland's
# marshalling; and it resolves keysym names against the XKB layout it
# uploads, so it needs xkbcommon.
#
# Neither protocol XML is a build input: both generated modules are vendored
# under src/hhstream_pointer/_protocol, so a checkout builds without a code
# generator. See that package's docstring for why, and
# hhstream_pointer._protocol.regenerate for how to refresh them -- including
# the note that virtual-keyboard-unstable-v1.xml is not in wayland-protocols
# or wlr-protocols in this nixpkgs and comes from pkgs.hyprland.src.
dependencies = [ python3.pkgs.pywayland python3.pkgs.xkbcommon libjpeg_turbo ];
# The in-process jpeg encoder reaches libjpeg-turbo through `ctypes`, so the
# library has to be *findable at run time*, which a propagated build input
# alone does not achieve: nothing links it, so nothing puts its directory on
# LD_LIBRARY_PATH. The wrapper is what makes `ctypes.util.find_library` succeed
# inside the unit -- and it is the same library grim already links, so the
# frames stay byte-compatible with the existing stream.
makeWrapperArgs = [
"--prefix LD_LIBRARY_PATH : ${lib.makeLibraryPath [ libjpeg_turbo ]}"
];
# Unit tests are wired up in the flake's `checks` so they can run without
# installing the package; see docs/CONTRACT.md.
doCheck = false;
# Cheap proof that the vendored protocols still bind against this pywayland:
# importing each runs the scanner-generated `_gen_c()` for its interfaces.
pythonImportsCheck = [
"hhstream_pointer.ops"
"hhstream_pointer.keymap"
"hhstream_pointer._protocol.wlr_virtual_pointer_unstable_v1"
"hhstream_pointer._protocol.virtual_keyboard_unstable_v1"
# The web app: importing the server pulls in the router, the publisher and
# the pages.
"hhstream_live.server"
# The capture backend and its vendored protocol bindings: importing the
# backend runs the scanner-generated `_gen_c()` for wl_shm, wl_output and
# zwlr-screencopy-manager-v1, which is the same cheap proof the pointer
# driver gets above.
"hhstream.wayland_capture"
"hhstream._protocol.wlr_screencopy_unstable_v1"
"hhstream.jpeg"
];
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
# wordlist lazily -- so a wheel that dropped `wordlist.txt` would sail past it
# and fail at the first `enable` instead. Read the list for real, against the
# installed tree, and mint a phrase so the generator and its validator are
# proven on the same words. `doCheck = false` (the suite runs in the flake's
# `checks`), so this is the only place the packaged data is exercised.
postFixup = ''
echo "checking the installed wordlist..."
PYTHONPATH="$out/${python3.sitePackages}:$PYTHONPATH" ${python3.interpreter} -c '
import hhstream_live.phrase as phrase
count = len(phrase.words())
assert count > 7000, f"wordlist has only {count} words; is wordlist.txt installed?"
assert phrase.validate(phrase.generate())
print(f"wordlist ok: {count} words, ~{phrase.entropy_bits():.1f} bits a phrase")
'
'';
meta = {
description = "Publish a headless Hyprland session's frames on a Unix socket";
license = lib.licenses.mit;
mainProgram = "hhstream-server";
};
}