Using the screen capture API with wayland
Wednesday, May 31, 2023 •
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:
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 order to enable Wayland support for Firefox, you need to start Firefox with the environment variable
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.
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.
CommentsNo 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.