Where it works
goome picks the backend itself. GOOME_BACKEND=x11 (or wayland, gnome, portal, test) forces one, and then it fails instead of falling back.
| Where | Overlay | Screen grab | Global hotkeys |
|---|---|---|---|
| sway, Hyprland, river, wayfire, labwc, niri | layer-shell | wlr-screencopy | control fifo |
| KDE Plasma 6, COSMIC | layer-shell | portal (asks once) | control fifo |
| GNOME (Wayland) | XWayland window | Mutter ScreenCast, no popup | control fifo |
| Cinnamon and other Wayland | XWayland window | portal (asks once) | control fifo |
| Any X11 desktop (XFCE, KDE X11, MATE, i3, openbox...) | X11 window | X11 | yes |
| Windows 10 / 11 | layered windows | GDI | yes |
| macOS 14+ | NSPanel | ScreenCaptureKit | yes, with Accessibility on |
No system wide key grabs on Wayland, see Hotkeys and the control fifo.
What CI actually ran
The table says what each backend is meant to do. What a scripted CI run has checked, on machines with no GPU and no person (Compare has the full tables):
- X11: 11 of 11 window managers pass (i3, openbox, fluxbox, icewm, metacity, marco, xfwm4 with and without picom, mutter, kwin, and none). Hotkeys and screen grabs are checked there too
- Wayland: sway (wlr-screencopy, grabs compared with grim, control fifo), labwc and mutter pass on Ubuntu and Arch, wayfire on Arch, kwin 5.27 on Ubuntu through the portal. Hyprland, river and niri never started in the harness, and COSMIC and Cinnamon were not tried, so those rows are what the code is written for, not something I saw run. weston and cage only half passed, see Compare
- GNOME grabs:
tests/gnome.shin c-goome checks Mutter ScreenCast and the portal path against a headless gnome-shell and a fake portal, but it is not part of the CI workflow. The overlay on GNOME is in CI, the "no popup" grab is not - Windows: the runner is Windows Server 2025, not a 10 or 11 desktop. Layered windows, UI Automation, GDI grabs and hotkeys pass there
- macOS: the runners are macOS 15 and 26, nothing ran on 14. The runners cant record the screen, so CI only checks that a grab comes back "not allowed" instead of hanging, ScreenCaptureKit never gave a picture. Global hotkeys were not tried on a Mac either
goome_caps(g) says what actually works where you are, goome_backend_name(g) which backend you got. Java has g.can(Goome.CAP_HOTKEYS) and g.backendName().
The caps
| Cap | Means |
|---|---|
GOOME_CAP_CAPTURE |
goome_capture works |
GOOME_CAP_GLOBAL_POINTER |
goome_pointer knows where the mouse is everywhere, also outside your hits |
GOOME_CAP_HOTKEYS |
goome_hotkey works |
GOOME_CAP_HIDE_SELF |
hide_self really keeps your overlay out of grabs |
GOOME_CAP_KEYBOARD |
goome_keyboard can take the keyboard |
GOOME_CAP_WINDOW 0.2 |
window mode works here |
GOOME_CAP_CLIPBOARD 0.2 |
the clipboard functions reach the real clipboard |
GOOME_CAP_CURSOR 0.2 |
goome_cursor changes the real cursor |
GOOME_CAP_GRAB 0.3 |
goome_grab gets a real pointer grab, see Taking input from the game |
How it picks on Linux
- X11 session (
XDG_SESSION_TYPE=x11, orDISPLAYset withoutWAYLAND_DISPLAY): x11. - No Wayland display either: gives up with
GOOME_ENODISPLAY. - GNOME on Wayland: x11 overlay on XWayland with mutter capture, then the portal, then no capture.
- layer-shell + wlr-screencopy (sway, Hyprland, river, wayfire, labwc, niri).
- layer-shell + portal (KDE, COSMIC).
- x11 on XWayland + portal (Cinnamon and anything else without layer-shell).
- An overlay with no capture. Drawing works, grabs return
GOOME_ENOTSUP.
Any GOOME_TEST_* env var switches to the test backend.
Window mode 0.2 skips gnome and portal, they only do overlays. On GNOME Wayland with DISPLAY set it goes through XWayland for real window decorations. Offscreen mode doesnt use any of this.
macOS permissions
Grabs need Screen Recording, hotkeys need Accessibility. macOS gives those to whatever app started your program, so from a terminal or IDE its that app in System Settings, not yours. A real .app bundle asks for itself. goome has to run on the main thread on Mac.
Old systems
Linux builds are meant to work back to glibc 2.34. CI doesnt run on that old a glibc, it checks with objdump that the binaries dont use any symbol newer than 2.34. libwayland, libX11, xkbcommon, gio, gstreamer and fontconfig all load at runtime, if one is missing goome picks something else. Nothing to install to build the C library except a C compiler.