enricobuehler
8926d82a80
The FlowBoxChild draws the hover/selection highlight AROUND the card (it wraps it with its own padding ring), so its default corner radius ran visibly tighter than the card's 12px inside it. The host grids now scope a 15px radius onto their children — card radius + the ring — so the highlight's corners run concentric with the card's. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
103 lines
4.9 KiB
Markdown
103 lines
4.9 KiB
Markdown
---
|
||
title: Hyprland
|
||
description: Configure a punktfunk host on a Hyprland session — headless output via hyprctl, capture via xdg-desktop-portal-hyprland.
|
||
---
|
||
|
||
Hyprland is a **first-class backend.** The host adds a per-client headless output at the client's
|
||
exact mode with `hyprctl`, captures it through the **xdg-desktop-portal-hyprland (xdph)** ScreenCast
|
||
portal (zero-copy dmabuf), and injects input via the wlroots virtual pointer/keyboard protocols —
|
||
which Hyprland still implements even after dropping wlroots in v0.42.
|
||
|
||
This is a distinct backend from [Sway / wlroots](/docs/sway): Hyprland has its own IPC (`hyprctl`)
|
||
and its own portal (xdph), so it is auto-detected and driven separately.
|
||
|
||
This page assumes the package is already installed — see [Arch](/docs/arch), [Ubuntu](/docs/ubuntu),
|
||
or [Fedora](/docs/fedora).
|
||
|
||
> New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
|
||
> the machine, so keep it on a trusted LAN or VPN and require pairing.
|
||
|
||
## host.env
|
||
|
||
The host auto-detects a Hyprland session, so you usually need nothing here. To force the backend, set
|
||
these in `~/.config/punktfunk/host.env`:
|
||
|
||
```ini
|
||
PUNKTFUNK_COMPOSITOR=hyprland
|
||
PUNKTFUNK_INPUT_BACKEND=wlr
|
||
PUNKTFUNK_VIDEO_SOURCE=virtual
|
||
# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
|
||
```
|
||
|
||
See [Configuration](/docs/configuration) for the full reference.
|
||
|
||
## How it works
|
||
|
||
- **Video** — the host runs `hyprctl output create headless PF-1` and applies a monitor rule for the
|
||
client's exact mode. Outputs are **named**, so there's no before/after diffing. The rule uses
|
||
`hyprctl keyword monitor …` (the hyprlang config manager — the default on every release, 0.55
|
||
included) and falls back to the Lua `hyprctl eval 'hl.monitor{…}'` only if you've opted into the
|
||
Lua config manager. The host confirms the output actually adopted the mode before streaming.
|
||
- **Capture** — it captures that output through the **xdg-desktop-portal-hyprland (xdph)** ScreenCast
|
||
portal. To pick the output without a GUI on a headless host, the host writes a managed
|
||
`~/.config/hypr/xdph.conf` pointing xdph's `custom_picker_binary` at a small shim that selects the
|
||
new output automatically — no interactive picker dialog to answer.
|
||
- **Input** — mouse and keyboard are injected via the wlroots **virtual pointer** and **virtual
|
||
keyboard** protocols (Hyprland kept them). Gamepads and audio are compositor-independent.
|
||
|
||
For how long the virtual output lives, and extend-vs-exclusive topology, see
|
||
[Virtual displays](/docs/virtual-displays).
|
||
|
||
## Requirements
|
||
|
||
- A running Hyprland session (the `hyprctl`/xdph contracts are verified on **0.55.4**; older
|
||
releases share the same `hyprctl` surface).
|
||
- **xdg-desktop-portal-hyprland (xdph)** installed and running — the host captures through its
|
||
ScreenCast portal, and steers its custom picker. Without it there is no video.
|
||
- The ScreenCast interface routed to xdph — see `scripts/headless/portals.conf` (a `[Hyprland]`
|
||
section pins `org.freedesktop.impl.portal.ScreenCast=hyprland`).
|
||
|
||
## Troubleshooting: black / no video (headless output at 0×0)
|
||
|
||
A headless output only gets a framebuffer once the compositor can allocate one. On some GPU/driver
|
||
combinations (notably NVIDIA, and in nested test setups) that GBM/dmabuf allocation fails and the
|
||
output stays `0×0` — you'll see `GBM: Failed to allocate a GBM buffer: bo null` in the Hyprland log
|
||
(cf. [Sunshine #4197](https://github.com/LizardByte/Sunshine/issues/4197)). The host detects this
|
||
and fails the session with a clear error rather than streaming a blank surface. If you hit it,
|
||
capture the Hyprland log (`hyprctl` instance dir → `hyprland.log`) and check your GPU's GBM support;
|
||
running Hyprland as a real session (not nested) is the supported configuration.
|
||
|
||
## Permission system
|
||
|
||
Hyprland's permission system (`ecosystem.enforce_permissions`, 0.49+, **off by default**) can deny
|
||
direct screencopy and virtual-input clients — and denial is **silent**: capture goes to *black
|
||
frames* and input is *dropped*, with no error. If you've enabled it, grant the host explicitly in
|
||
your Hyprland config:
|
||
|
||
```ini
|
||
ecosystem {
|
||
enforce_permissions = true
|
||
}
|
||
|
||
permission = /usr/bin/punktfunk-host, screencopy, allow
|
||
permission = /usr/bin/punktfunk-host, virtual-pointer, allow
|
||
permission = /usr/bin/punktfunk-host, virtual-keyboard, allow
|
||
```
|
||
|
||
The host logs a warning at startup when it detects enforcement is on. (Adjust the binary path to
|
||
where your package installed `punktfunk-host`.)
|
||
|
||
## Start the host
|
||
|
||
With the backend selected, start the host from **inside your Hyprland session**:
|
||
|
||
```sh
|
||
systemctl --user enable --now punktfunk-host
|
||
journalctl --user -u punktfunk-host -f
|
||
```
|
||
|
||
## Bring up the console and pair
|
||
|
||
Enable the web console, read its login password, and arm PIN pairing — see
|
||
[The Web Console](/docs/web-console). Then [connect a client](/docs/clients).
|