1# Screen capture
2
3NeferWL supports `zwlr_screencopy_manager_v1` (used by `grim`) and `ext_image_copy_capture_manager_v1` (used by recorders).
4
5- A red indicator shows on screen while something is captured.
6- Only allowed executables may capture. See [the allowlist](#the-allowlist).
7- Sandboxed apps (Flatpak) must go through the [portal](#portals).
8
9## Sources
10
11With ext-image-copy-capture, a client can capture an output, a window, a workspace (even off screen, without bars) or a region of an output. The workspace and region sources use the NeferWL protocol in `internal/adapters/wayland/imagecapture/`.
12
13- Captures are 8-bit sRGB. HDR content is tone-mapped.
14- The cursor is never included.
15- GPUs without Vulkan sync-file export (such as lavapipe) cannot capture.
16- `neferwl_capture_exclusion_manager_v1` lets a recorder keep its own HUD out of its frames.
17
18## The indicator
19
20A 2-pixel red border surrounds the captured output, region or workspace. A captured window adds a small red square in the top-right corner of its output. No client can turn it off, and it never appears in the captured image.
21
22A screenshot flashes the indicator for one second; a recording keeps it on.
23
24## The allowlist
25
26By default, these executables may capture:
27
28```text
29/usr/bin/grim
30/usr/bin/nefercap
31/usr/lib/xdg-desktop-portal-gnome
32/usr/libexec/xdg-desktop-portal-gnome
33```
34
35The list also gates the D-Bus callers of the screen-sharing service (see Portals): a caller whose executable is not listed gets `AccessDenied`.
36
37To change it, create `/etc/neferwl/capture-allow`. It **replaces** the built-in list, so keep the entries you still need:
38
39```sh
40sudo install -Dm644 /usr/share/doc/neferwl/capture-allow.example /etc/neferwl/capture-allow
41sudoedit /etc/neferwl/capture-allow
42```
43
44```text
45# one absolute executable path per line
46/usr/bin/grim
47/usr/bin/nefercap
48/usr/lib/xdg-desktop-portal-gnome
49/opt/tools/bin/recorder
50```
51
52- List the real file, as `/proc/<pid>/exe` shows it: `/usr/bin/python3.12`, not a `python3` symlink. No globs.
53- A line with only `*` lets every client capture.
54- Changes apply without a restart.
55- The file and every directory above it must be owned by root, not writable by group or others, and not symlinks.
56- If the file is invalid or unsafe, nobody may capture. The log says why.
57- Refused clients are logged as `capture refused`, with the pid and path.
58- Client checks need Linux 6.5 or later. On older kernels, nobody may capture unless the list is `*`.
59
60Never list an interpreter (`python`, `bash`, `node`): every script it runs could capture. Avoid listing files you own: any program running as you could replace them.
61
62The allowlist stops unknown programs, not a program running as you that drives a listed one. The indicator still shows.
63
64## Portals
65
66NeferWL serves the GNOME ScreenCast, DisplayConfig, Introspect and Screenshot D-Bus interfaces, so `xdg-desktop-portal-gnome` provides screen sharing and screenshots.
67
68- **Screen sharing** in browsers and apps: install `xdg-desktop-portal-gnome` and run PipeWire. The portal dialog lists monitors and windows with their titles; the stream is a PipeWire video node. Without PipeWire, the ScreenCast interface is not offered.
69- **Screenshots** through the portal, interactive or not: install [nefercap](https://github.com/bnema/nefercap), which writes the PNG.
70- A cast keeps the indicator on until it ends. It ends when the session locks, the output or window goes away, the client stops it or disconnects, or NeferWL loses the D-Bus connection. When the receiving program stops reading, the stream pauses (no frames are rendered) and the cast stays open for the next reader, as in GNOME.
71- Unsupported: area and virtual casts, and the "Select area" and "Window" choices of the screenshot dialog.
72
73The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the gnome portal.
74
75The D-Bus interfaces are served on the session bus when NeferWL runs on a hardware session. With `--backend=headless`, pass `-dbus` to serve them. Names already owned (by a GNOME session) are skipped.
76
77Screenshots through the portal are taken without asking, for any program running as you whose executable is on the allowlist. The indicator still flashes.