docs(capture): document screen sharing through the GNOME portal
- commit
- 3d397874432d4371facc2466309e616221bd1641
- author
- brice · · 2026-10-14 20:37 UTC
- committer
- brice · · 2026-10-14 21:39 UTC
- parent
- 0cdc34e
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
3 files · +17 -9
M README.md +1 -1
| @@ -113,7 +113,7 @@ sudo apt install ./neferwl_<version>_amd64.deb | |||
| 113 | 113 | Optional tools: | |
| 114 | 114 | ||
| 115 | 115 | ```sh | |
| 116 | - | sudo apt install foot fuzzel xdg-desktop-portal-gtk xdg-desktop-portal-wlr | |
| 116 | + | sudo apt install foot fuzzel xdg-desktop-portal-gtk xdg-desktop-portal-gnome | |
| 117 | 117 | ``` | |
| 118 | 118 | ||
| 119 | 119 | X11 apps need [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) 0.7 or later, which you may have to build. The package is tested on Ubuntu 24.04 and 26.04; Debian with the same library packages should work but is untested. | |
| @@ -113,7 +113,7 @@ sudo apt install ./neferwl_<version>_amd64.deb | |||||
| 113 | Optional tools: | 113 | Optional tools: | ||
| 114 | 114 | ||||
| 115 | ```sh | 115 | ```sh | ||
| 116 | - | sudo apt install foot fuzzel xdg-desktop-portal-gtk xdg-desktop-portal-wlr | 116 | + | sudo apt install foot fuzzel xdg-desktop-portal-gtk xdg-desktop-portal-gnome |
| 117 | ``` | 117 | ``` | ||
| 118 | 118 | ||||
| 119 | X11 apps need [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) 0.7 or later, which you may have to build. The package is tested on Ubuntu 24.04 and 26.04; Debian with the same library packages should work but is untested. | 119 | X11 apps need [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) 0.7 or later, which you may have to build. The package is tested on Ubuntu 24.04 and 26.04; Debian with the same library packages should work but is untested. | ||
M docs/capture.md +15 -7
| @@ -28,10 +28,12 @@ By default, these executables may capture: | |||
| 28 | 28 | ```text | |
| 29 | 29 | /usr/bin/grim | |
| 30 | 30 | /usr/bin/nefercap | |
| 31 | - | /usr/lib/xdg-desktop-portal-wlr | |
| 32 | - | /usr/libexec/xdg-desktop-portal-wlr | |
| 31 | + | /usr/lib/xdg-desktop-portal-gnome | |
| 32 | + | /usr/libexec/xdg-desktop-portal-gnome | |
| 33 | 33 | ``` | |
| 34 | 34 | ||
| 35 | + | The list also gates the D-Bus callers of the screen-sharing service (see Portals): a caller whose executable is not listed gets `AccessDenied`. | |
| 36 | + | ||
| 35 | 37 | To change it, create `/etc/neferwl/capture-allow`. It **replaces** the built-in list, so keep the entries you still need: | |
| 36 | 38 | ||
| 37 | 39 | ```sh | |
| @@ -43,7 +45,7 @@ sudoedit /etc/neferwl/capture-allow | |||
| 43 | 45 | # one absolute executable path per line | |
| 44 | 46 | /usr/bin/grim | |
| 45 | 47 | /usr/bin/nefercap | |
| 46 | - | /usr/lib/xdg-desktop-portal-wlr | |
| 48 | + | /usr/lib/xdg-desktop-portal-gnome | |
| 47 | 49 | /opt/tools/bin/recorder | |
| 48 | 50 | ``` | |
| 49 | 51 | ||
| @@ -61,9 +63,15 @@ The allowlist stops unknown programs, not a program running as you that drives a | |||
| 61 | 63 | ||
| 62 | 64 | ## Portals | |
| 63 | 65 | ||
| 64 | - | - **Screen sharing** in browsers and apps: install `xdg-desktop-portal-wlr`. | |
| 65 | - | - **Screenshots and recordings:** install [nefercap](https://github.com/bnema/nefercap). | |
| 66 | + | NeferWL 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, or the client disconnects. | |
| 71 | + | - Unsupported: area and virtual casts, and the "Select area" and "Window" choices of the screenshot dialog. | |
| 72 | + | ||
| 73 | + | The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the gnome portal. | |
| 66 | 74 | ||
| 67 | - | The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the wlr portal. NeferWL has no window picker: set `chooser_type` and `chooser_cmd` in the wlr portal config to use slurp, wofi or bemenu (see `man xdg-desktop-portal-wlr`). | |
| 75 | + | The 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. | |
| 68 | 76 | ||
| 69 | - | The wlr portal takes screenshots without asking, for any program running as you. The indicator still flashes. | |
| 77 | + | Screenshots through the portal are taken without asking, for any program running as you whose executable is on the allowlist. The indicator still flashes. | |
| @@ -28,10 +28,12 @@ By default, these executables may capture: | |||||
| 28 | ```text | 28 | ```text | ||
| 29 | /usr/bin/grim | 29 | /usr/bin/grim | ||
| 30 | /usr/bin/nefercap | 30 | /usr/bin/nefercap | ||
| 31 | - | /usr/lib/xdg-desktop-portal-wlr | 31 | + | /usr/lib/xdg-desktop-portal-gnome |
| 32 | - | /usr/libexec/xdg-desktop-portal-wlr | 32 | + | /usr/libexec/xdg-desktop-portal-gnome |
| 33 | ``` | 33 | ``` | ||
| 34 | 34 | ||||
| 35 | + | The list also gates the D-Bus callers of the screen-sharing service (see Portals): a caller whose executable is not listed gets `AccessDenied`. | |||
| 36 | + | ||||
| 35 | To change it, create `/etc/neferwl/capture-allow`. It **replaces** the built-in list, so keep the entries you still need: | 37 | To change it, create `/etc/neferwl/capture-allow`. It **replaces** the built-in list, so keep the entries you still need: | ||
| 36 | 38 | ||||
| 37 | ```sh | 39 | ```sh | ||
| @@ -43,7 +45,7 @@ sudoedit /etc/neferwl/capture-allow | |||||
| 43 | # one absolute executable path per line | 45 | # one absolute executable path per line | ||
| 44 | /usr/bin/grim | 46 | /usr/bin/grim | ||
| 45 | /usr/bin/nefercap | 47 | /usr/bin/nefercap | ||
| 46 | - | /usr/lib/xdg-desktop-portal-wlr | 48 | + | /usr/lib/xdg-desktop-portal-gnome |
| 47 | /opt/tools/bin/recorder | 49 | /opt/tools/bin/recorder | ||
| 48 | ``` | 50 | ``` | ||
| 49 | 51 | ||||
| @@ -61,9 +63,15 @@ The allowlist stops unknown programs, not a program running as you that drives a | |||||
| 61 | 63 | ||||
| 62 | ## Portals | 64 | ## Portals | ||
| 63 | 65 | ||||
| 64 | - | - **Screen sharing** in browsers and apps: install `xdg-desktop-portal-wlr`. | 66 | + | NeferWL serves the GNOME ScreenCast, DisplayConfig, Introspect and Screenshot D-Bus interfaces, so `xdg-desktop-portal-gnome` provides screen sharing and screenshots. |
| 65 | - | - **Screenshots and recordings:** install [nefercap](https://github.com/bnema/nefercap). | 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, or the client disconnects. | |||
| 71 | + | - Unsupported: area and virtual casts, and the "Select area" and "Window" choices of the screenshot dialog. | |||
| 72 | + | ||||
| 73 | + | The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the gnome portal. | |||
| 66 | 74 | ||||
| 67 | - | The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the wlr portal. NeferWL has no window picker: set `chooser_type` and `chooser_cmd` in the wlr portal config to use slurp, wofi or bemenu (see `man xdg-desktop-portal-wlr`). | 75 | + | The 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. |
| 68 | 76 | ||||
| 69 | - | The wlr portal takes screenshots without asking, for any program running as you. The indicator still flashes. | 77 | + | Screenshots through the portal are taken without asking, for any program running as you whose executable is on the allowlist. The indicator still flashes. |
M docs/desktop.md +1 -1
| @@ -64,7 +64,7 @@ Use an external locker such as swaylock or hyprlock. See [Session locking](sessi | |||
| 64 | 64 | ||
| 65 | 65 | ## Screen capture | |
| 66 | 66 | ||
| 67 | - | nefercap, `grim` and screen sharing through `xdg-desktop-portal-wlr` work out of the box. Other tools must be added to the allowlist. See [Screen capture](capture.md). | |
| 67 | + | nefercap, `grim` and screen sharing through `xdg-desktop-portal-gnome` work out of the box. Other tools must be added to the allowlist. See [Screen capture](capture.md). | |
| 68 | 68 | ||
| 69 | 69 | ## Idle and screen off | |
| 70 | 70 | ||
| @@ -64,7 +64,7 @@ Use an external locker such as swaylock or hyprlock. See [Session locking](sessi | |||||
| 64 | 64 | ||||
| 65 | ## Screen capture | 65 | ## Screen capture | ||
| 66 | 66 | ||||
| 67 | - | nefercap, `grim` and screen sharing through `xdg-desktop-portal-wlr` work out of the box. Other tools must be added to the allowlist. See [Screen capture](capture.md). | 67 | + | nefercap, `grim` and screen sharing through `xdg-desktop-portal-gnome` work out of the box. Other tools must be added to the allowlist. See [Screen capture](capture.md). |
| 68 | 68 | ||||
| 69 | ## Idle and screen off | 69 | ## Idle and screen off | ||
| 70 | 70 | ||||