From a88d05a9f2af3c25ae162988feac20ce1f0e6857 Mon Sep 17 00:00:00 2001 From: Samuel Onoja Date: Mon, 28 Sep 2026 07:58:05 +0100 Subject: [PATCH] Document screen sharing across the website and handbook --- README.md | 3 +++ docs/screen-sharing.md | 29 +++++++++++++++++++++++++++++ site/README.md | 3 ++- site/content/index.md | 9 +++++++-- site/index.html | 6 ++++++ 5 files changed, 47 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 06b369e..4527bd7 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ cohesive experience—beautiful by default and unmistakably yours. motion that update without restarting your session. - **Ready for real setups:** gestures, multi-monitor support, fractional scaling, screenshots, background services and session locking. +- **Screen sharing:** a native display picker and PipeWire video streams for + portal-compatible recording and conferencing apps. ## Make it yours @@ -92,6 +94,7 @@ Settings → Shortcuts** to change them or assign gestures to other actions. - [Desktop widgets](docs/desktop-widgets.md) - [Notifications](docs/notifications.md) - [Native locker](docs/locking.md) +- [Screen sharing and recording](docs/screen-sharing.md) ## Development diff --git a/docs/screen-sharing.md b/docs/screen-sharing.md index be77645..48397f9 100644 --- a/docs/screen-sharing.md +++ b/docs/screen-sharing.md @@ -5,6 +5,9 @@ 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. +There is no built-in Record button or video-file recorder in the shell yet. +Start recording from an application that supports the Wayland ScreenCast portal. + ## Start sharing Use a Wayland screen-sharing or recording source in your application. Ferese @@ -55,6 +58,32 @@ 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. +## Development checks + +Build the backend after installing the native dependencies in the +[installation guide](installation.md#requirements): + +```sh +cargo build --release --locked -p xdg-desktop-portal-ferese +cargo test --locked -p xdg-desktop-portal-ferese +``` + +The opt-in integration test opens a temporary nested compositor and uses a +private D-Bus session. It requires built Ferese and locker binaries, Python +GI/GStreamer with `pipewiresrc`, `dbus-daemon`, `xdg-desktop-portal`, and `bwrap`. +It checks capture delivery, cancellation, frontend loss, and lock revocation: + +```sh +FERESE_TEST_PORTAL=1 \ +FERESE_TEST_PORTAL_BINARY=target/release/xdg-desktop-portal-ferese \ +python3 scripts/tests/test_portal_isolated.py +``` + +Add `FERESE_TEST_PORTAL_CONSENT=1` to exercise the native picker and restricted +PipeWire connection. Select the temporary display and click **Share** when +prompted. Tests capture only the nested preview and leave host PAM policies and +D-Bus activation unchanged. + ## Troubleshooting Confirm that `XDG_CURRENT_DESKTOP` contains `Ferese`, PipeWire is running, and diff --git a/site/README.md b/site/README.md index e4ebeb1..563e8df 100644 --- a/site/README.md +++ b/site/README.md @@ -18,7 +18,8 @@ site sources or Markdown guides, then refresh the browser. - `site/index.html` and `site/styles.css`: homepage and shared visual design. - `site/content/index.md`: handbook introduction. -- `docs/{installation,configuration,desktop-widgets,notifications}.md`: source guides. +- `docs/{installation,configuration,desktop-widgets,notifications,locking,screen-sharing}.md`: + source guides. - `scripts/build-site.py`: renders Markdown, resolves links, generates section navigation, previous/next links, and the search index. - `site/app.js`: handbook search and code copying. Reading and navigation work diff --git a/site/content/index.md b/site/content/index.md index 499bce4..12ed516 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -43,6 +43,13 @@ If you prefer a text editor, your configuration lives at: Ferese reloads changes as you make them. An invalid edit keeps the last working configuration. Settings also preserves a backup of your previous save. See [Saving and validation](configuration.md#saving-and-validation). +## Share your screen + +Use Ferese’s native display picker to share a monitor with a portal-compatible +recording or conferencing app. The app handles saving or sending video; Ferese +does not yet have a Record button in the shell. See [Screen sharing and +recording](screen-sharing.md) for setup, stopping a session, and supported sources. + ## Keep a recovery path Keep another desktop session available while testing hardware behavior. Save your work before logging out: `feresectl exit` and **Super + Shift + E** end the current session immediately. @@ -59,5 +66,3 @@ cargo fmt --all --check ``` The [source repository](https://github.com/ferese-wm/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs. - -[Screen sharing](screen-sharing.md) covers display consent, PipeWire streams, and recording support. diff --git a/site/index.html b/site/index.html index 8b3d79b..09ac611 100644 --- a/site/index.html +++ b/site/index.html @@ -112,6 +112,12 @@ preview Ferese inside an existing Wayland session before installing.

+

+ Share a display with recording and conferencing apps through Ferese’s + native screen-sharing portal. Choose what to share and stop at any time. + See screen sharing and recording + for setup and current capabilities. +

Built in Rust on Smithay. Development happens on GitHub.