Using the screen capture API with wayland

Modern linux system use Wayland instead of X11. This has some challenges when it comes to screen sharing. While X11 doesn’t have any hesitation with screen sharing, wayland is more strict: It requires active user permission to allow the screen to be shared. And you’ll get a little notification, that you are sharing your screen.

This is much like screen capturing, see also Taking screenshots with Java under Wayland.


When sharing the screen in web pages, the API is standardized: Screen Capture API. All major desktop browsers support this. Really?

Try it out:

The issue

So, does it work? Can you share the entire screen? Can share individual windows? Or can you only share your browsers tabs and nothing else?

Screen captures works entirely different on a Wayland enabled system. E.g. GNOME uses pipewire to stream the display content from the compositor Mutter to whoever is connecting to the stream. In the example above, it would be the browser.

The problem is now, that the default configuration for the browser is, to not use Wayland, but use the compatibility layer XWayland. The browsers still use X11 to draw to the screen, but XWayland then displays it through Wayland.

If the browser is using this mode, then it’s likely that the screen sharing is not working. Or only working partially.

Solution for Firefox

In order to figure out, whether firefox already uses Wayland or not, go to . In section "Graphics" search for "Window Protocol". If it displays already "Wayland", then there's nothing to do. Screen sharing should work already. But likely, there is "xwayland" displayed. Then you need to enable Wayland support. Note, that there's a reason, why this is not enabled by default: There might be some issues.

In order to enable Wayland support for Firefox, you need to start Firefox with the environment variable MOZ_ENABLE_WAYLAND=1 set.

Note: Screen capturing seems to be working even without using Wayland mode today. If it doesn’t work for you, enabling Wayland support might help.

Solution for Chrome

In Chrome, you might only be able to select other browser tabs, but not other windows or an entire display. If that’s the case, you need to enable the experimental flag enable-webrtc-pipewire-capturer in “chrome://flags” (chrome://flags/#enable-webrtc-pipewire-capturer). Then Chrome uses the pipewire interface to grab the screen content for capturing. That will display an OS specific dialog to allow/disallow sharing and to select the window or display.

Other issues

Screen capturing needs a lot of libraries to be present. Maybe you are missing one. E.g. under Debian, make sure to have package xdg-desktop-portal-gnome installed - this provides the OS specific dialogs to select windows/screens to share. It’s an implementation of the API xdg-desktop-portal. Each desktop environment needs such an implementation. If it’s missing, you might not even see an error, screen sharing just doesn’t work.


No comments yet.

Leave a comment

Your email address will not be published. Required fields are marked *. All comments are held for moderation to avoid spam and abuse.

Andreas Dangel | subscribe via RSS | adangel | .onion © Copyright 2023. (31 May 2023)