Add native ScreenCast portal with PipeWire monitor streams

2026-09-28 07:54:22 +01:00
1 parent cb512eece9
commit e7d92280d6
@@ -13,7 +13,7 @@ desktop instead of direct access to the graphics device.

 Build with **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config, and the
 native development libraries below. The installer builds Ferese, its shell,
-Settings, command-line tools, and locker together. It does not install system
+Settings, command-line tools, locker, and ScreenCast portal together. It does not install system
 packages or enable services for you.

 ### Fedora
@@ -22,7 +22,8 @@ packages or enable services for you.
 sudo dnf install git curl gcc gcc-c++ make cmake pkgconf-pkg-config \
  wayland-devel libxkbcommon-devel libinput-devel systemd-devel libseat-devel \
  mesa-libgbm-devel mesa-libEGL-devel libdrm-devel fontconfig-devel \
-  freetype-devel expat-devel dbus-daemon dbus-tools desktop-file-utils foot pam
+  freetype-devel expat-devel dbus-daemon dbus-tools desktop-file-utils foot pam \
+  clang clang-devel pipewire-devel pipewire wireplumber xdg-desktop-portal xdg-desktop-portal-gtk
 ```

 ### Arch Linux
@@ -30,7 +31,8 @@ sudo dnf install git curl gcc gcc-c++ make cmake pkgconf-pkg-config \
 ```sh
 sudo pacman -S --needed base-devel git curl cmake pkgconf wayland libxkbcommon \
  libinput systemd seatd mesa libdrm fontconfig freetype2 expat dbus \
-  desktop-file-utils foot pam
+  desktop-file-utils foot pam clang pipewire libpipewire wireplumber \
+  xdg-desktop-portal xdg-desktop-portal-gtk
 ```

 ### Debian and Ubuntu
@@ -40,7 +42,9 @@ sudo apt update
 sudo apt install build-essential git curl cmake pkg-config libwayland-dev \
  libxkbcommon-dev libinput-dev libudev-dev libseat-dev libgbm-dev libegl-dev \
  libdrm-dev libfontconfig1-dev libfreetype-dev libexpat1-dev dbus-bin \
-  dbus-user-session desktop-file-utils foot libpam0g
+  dbus-user-session desktop-file-utils foot libpam0g clang libclang-dev \
+  libpipewire-0.3-dev libspa-0.2-dev pipewire wireplumber \
+  xdg-desktop-portal xdg-desktop-portal-gtk
 ```

 These are package recipes, not a claim that every distribution release has been
@@ -86,7 +90,9 @@ The installer adds:
 - Versioned releases under `/usr/local/lib/ferese/releases/`, with `current` and
  `previous` links for upgrades and rollback.
 - Commands under `/usr/local/bin/`, including `ferese-session`, `ferese-settings`,
-  `feresectl`, `ferese-lock`, and `ferese-screenshot`.
+  `feresectl`, `ferese-lock`, `ferese-screenshot`, and
+  `xdg-desktop-portal-ferese`.
+- D-Bus activation and Ferese-specific ScreenCast portal registration.
 - A Wayland session entry at `/usr/share/wayland-sessions/ferese.desktop`.
 - A Settings application entry, icons, the default wallpaper, and an example config.
 - `/etc/pam.d/ferese-lock`, using your distribution's authentication stack.
@@ -203,7 +209,7 @@ To preview a source build before installing, run these commands from the checkou
 inside an existing Wayland desktop:

 ```sh
-cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
+cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock -p xdg-desktop-portal-ferese
 target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
  target/release/ferese-shell
 ```
@@ -245,7 +251,7 @@ Installer options:

 `--dry-run` prints the planned commands. `--offline` requires dependencies to be
 cached already. `--skip-build` installs the binaries already in `target/release/`;
-use it only after building all five components from the intended revision.
+use it only after building all six components from the intended revision.
 Run `./scripts/install.sh --help` for all options.

 ## Logout and recovery
@@ -299,3 +305,9 @@ sudo mv /usr/share/wayland-sessions/ferese.desktop \

 For a command-based greeter, remove Ferese from its session choices using that
 greeter's configuration. Reinstalling restores the desktop session entry.
+
+## Screen sharing and recording
+
+The installer includes Ferese’s native ScreenCast portal. See
+[Screen sharing](screen-sharing.md) for consent, PipeWire setup, supported sources,
+and current recording limitations.
@@ -0,0 +1,78 @@
+# Screen sharing and recording
+
+Ferese includes a ScreenCast portal backend, `xdg-desktop-portal-ferese`.
+Applications use the standard desktop portal to request a display, then receive
+video through PipeWire. A recorder or conferencing application handles encoding,
+saving files, or sending video; those tasks do not run inside the compositor.
+
+## Start sharing
+
+Use a Wayland screen-sharing or recording source in your application. Ferese
+opens a display picker. Select a display and press **Share**. Nothing is selected
+by default. Applications that request multiple displays can share up to four.
+The picker uses your Ferese theme colors, font, and shell corner radius.
+
+A **screen sharing** window remains visible while sharing. Press **Stop sharing**
+or close that window to revoke the session. Closing the requesting application,
+locking Ferese, disconnecting the selected display, or changing its capture size
+also ends sharing. A new request needs fresh consent; selections are not saved.
+Everything visible on a shared display, including notifications, is included.
+
+## Installation
+
+The [standard installer](installation.md) builds and installs the backend, its
+D-Bus activation entry, and a Ferese-specific portal preference file. Install
+`pipewire`, a PipeWire session manager such as `wireplumber`,
+`xdg-desktop-portal`, and `xdg-desktop-portal-gtk` using your distribution's package
+manager. The GTK backend supplies other portal interfaces such as file selection.
+
+Log into a new Ferese session after installation. The session launcher imports
+its Wayland display into the D-Bus activation environment. Nested previews leave
+the host activation environment alone.
+
+Existing custom window rules can float the picker and sharing indicator:
+
+```kdl
+window-rule app-id="dev.ferese.ScreenShare" floating=#true
+```
+
+The packaged example configuration already includes this rule. Existing user
+configuration is preserved during installation.
+
+## Current capabilities
+
+- Monitor capture, one PipeWire stream per selected display, at up to 30 fps.
+- Hidden or embedded pointer, as requested by the application.
+- Bounded frame storage and reusable shared-memory buffers.
+- Cancellation during selection, an explicit stop control, and process cleanup.
+- ScreenCast backend version 3, without persistent or automatic consent.
+
+Window-only sharing, region selection, audio capture, and a built-in recorder
+control in the shell are not implemented yet. Audio can be handled separately by
+the recording application. Video currently uses CPU copies through the
+compositor's shared-memory screencopy path, not DMA-BUF zero-copy. High-resolution
+or multiple-display recording can therefore use significant CPU and memory
+bandwidth. A paused stream checks capture availability once per second so locking
+also ends sessions without an active consumer.
+
+## Troubleshooting
+
+Confirm that `XDG_CURRENT_DESKTOP` contains `Ferese`, PipeWire is running, and
+`FERESE_ENABLE_SCREENCOPY` was not set to `0` before launching the session.
+
+The installed preference is
+`/usr/share/xdg-desktop-portal/ferese-portals.conf`. A user override under
+`~/.config/xdg-desktop-portal/` can take precedence. Its ScreenCast preference
+should name `ferese`:
+
+```ini
+[preferred]
+default=gtk;
+org.freedesktop.impl.portal.ScreenCast=ferese;
+```
+
+If capture dimensions change, stop and start sharing again. Ferese ends the old
+session instead of feeding incorrectly sized frames to the application.
+
+For development, `xdg-desktop-portal-ferese --sources` lists displays available
+on the current `WAYLAND_DISPLAY`. This command does not start a stream.