diff --git a/documentation/content/en/books/handbook/wayland/_index.adoc b/documentation/content/en/books/handbook/wayland/_index.adoc index d6b5168e9f0..e4656e0b761 100644 --- a/documentation/content/en/books/handbook/wayland/_index.adoc +++ b/documentation/content/en/books/handbook/wayland/_index.adoc @@ -723,3 +723,129 @@ bar { command[mouse-left] = /usr/local/bin/thunderbird; } .... + +[[wayland-screensharing]] +== Screen Sharing on Wayland + +Screen sharing on Wayland requires additional configuration compared to Xorg due to the differences in how Wayland handles display protocols. To enable screen sharing, you will need to set up tools like `xdg-desktop-portal`, a backend implementation compatible with your compositor, and `pipewire`. These tools work together to provide screen sharing functionality in Wayland environments. The key to making screen sharing work is ensuring that **DBus is properly activated** and that the necessary environment variables, particularly `WAYLAND_DISPLAY`, are correctly set. + +=== Required Packages + +First, install the necessary packages: + +[source,shell] +---- +# pkg install xdg-desktop-portal pipewire +---- + +Next, install the appropriate backend implementation for your compositor. For example: + +- **Sway** or other wlroots-based compositors: + [source,shell] + ---- + # pkg install xdg-desktop-portal-wlr + ---- + +- **KDE Plasma**: + [source,shell] + ---- + # pkg install plasma5-xdg-desktop-portal-kde + ---- + +- **GNOME**: + [source,shell] + ---- + # pkg install xdg-desktop-portal-gnome + ---- + +- **Hyprland**: + [source,shell] + ---- + # pkg install xdg-desktop-portal-hyprland + ---- + +- **GTK-based environments**: + [source,shell] + ---- + # pkg install xdg-desktop-portal-gtk + ---- + +These packages provide the necessary infrastructure for screen sharing and screencasting in Wayland. + +=== Essential Step: Activating DBus and Setting Environment Variables + +The most critical step in enabling screen sharing is ensuring that **DBus is properly activated** and that the `WAYLAND_DISPLAY` environment variable is set. This variable is essential for Wayland applications to communicate with the compositor. To activate DBus and set the `WAYLAND_DISPLAY` variable, add the following line to your compositor's startup configuration: + +[source,shell] +---- +exec dbus-update-activation-environment WAYLAND_DISPLAY +---- + +If you need to set additional environment variables for other purposes, you can use the `--all` flag to update all relevant environment variables: + +[source,shell] +---- +exec dbus-update-activation-environment --all +---- + +This ensures that all necessary environment variables are correctly set for screen sharing and other functionalities. + +=== Configuration for Sway (wlroots-based Compositors) + +For Sway or other wlroots-based compositors, you will need to configure the environment to start the required services and set up the appropriate portals. Below are the steps to configure screen sharing for Sway. + +1. **Autostart Configuration for Sway** + + Create or modify the autostart configuration file for Sway to ensure that `pipewire` and the necessary environment variables are set up correctly. Add the following lines to your Sway configuration file, typically located at `~/.config/sway/config`: + + [source,shell] + ---- + exec pipewire + exec dbus-update-activation-environment WAYLAND_DISPLAY + ---- + + This ensures that `pipewire` is running and that the `WAYLAND_DISPLAY` environment variable is properly set for screen sharing. + +2. **Portal Configuration for Sway** + + Create a configuration file for `xdg-desktop-portal` to specify the preferred portal implementations. Create the file `~/.config/xdg-desktop-portal/sway-portals.conf` with the following content: + + [source,shell] + ---- + [preferred] + default=gtk + org.freedesktop.impl.portal.Screencast=wlr + org.freedesktop.impl.portal.Screenshot=wlr + ---- + + This configuration tells `xdg-desktop-portal` to use the `wlr` backend for screen sharing and screenshot functionality. + +3. **Screen Sharing Configuration for `xdg-desktop-portal-wlr`** + + Finally, configure `xdg-desktop-portal-wlr` to use a simple chooser for selecting the screen or window to share. Create the file `~/.config/xdg-desktop-portal-wlr/config` with the following content: + + [source,shell] + ---- + [screencast] + chooser_type = simple + chooser_cmd = slurp -f %o -ro + ---- + + This configuration uses `slurp` to allow the user to select a region of the screen to share. The `-f %o -ro` options specify the output format and region selection. + +=== Testing Screen Sharing + +Once the configuration is complete, restart your compositor session to apply the changes. You should now be able to use screen sharing applications that support the `xdg-desktop-portal` interface, such as web browsers or video conferencing tools. + +To test screen sharing, you can use the [getUserMedia (gUM) Test Page](https://webrtc.github.io/samples/src/content/getusermedia/gum/). This page allows you to test screen sharing functionality in your browser. When prompted, you should be able to select the screen or window you wish to share. + +[NOTE] +==== +If you encounter issues with screen sharing, ensure that all required services (`pipewire`, `xdg-desktop-portal`, and the appropriate backend) are running and that **DBus is properly activated** with the `WAYLAND_DISPLAY` environment variable set. Without these, screen sharing will not function correctly. +==== + +=== Other Compositors + +For other compositors, such as KDE Plasma, GNOME, or Hyprland, the setup process is similar. Install the corresponding `xdg-desktop-portal` backend for your compositor, ensure that `pipewire` is running, and **activate DBus** using the `dbus-update-activation-environment` command with `WAYLAND_DISPLAY`. If needed, you can use the `--all` flag to set additional environment variables. Most compositors will automatically configure the necessary portal settings. + +By following these steps, you should be able to enable and use screen sharing functionality in your Wayland compositor on FreeBSD.