The chooser appears, you select a monitor, and the recorder receives frames. It can feel like one permission switch. Underneath, it is a negotiated session with distinct steps—and it does not choose every input in the recording.
The portal lifecycle in four calls
The XDG ScreenCast interface documents this lifecycle and returns PipeWire stream node IDs after Start. Applications should treat portal requests as asynchronous and handle cancellation or denial. See the primary source.
- CreateSession creates a ScreenCast session.
- SelectSources requests source types, cursor mode, and related options.
- Start presents the user-facing selection and begins the session.
- OpenPipeWireRemote returns a file descriptor for the PipeWire remote.
The prompt controls the visual source grant
The specification defines MONITOR, WINDOW, and VIRTUAL source-type bits. A compositor or portal frontend decides how those choices are presented; requesting a type does not silently grant the desktop. See the primary source.
Cursor mode is part of screen capture
The documented cursor modes are HIDDEN, EMBEDDED, and METADATA. Embedded means the cursor is already in the stream; metadata supplies cursor position and appearance separately when the implementation supports it. The portal exposes available cursor modes so clients need not assume all three. See the primary source.
PipeWire carries the selected streams
After portal authorization, the client connects through the returned PipeWire remote and uses the stream node IDs. PipeWire models multimedia processing as a graph of nodes, ports, and links; the portal grant and PipeWire transport are connected parts of the path, not synonyms. See the primary source.
What the prompt does not control
Screenix selects microphone and system audio independently from the visual portal session. That is why a correct monitor choice can coexist with missing audio, and why audio should be diagnosed as its own path.
- It does not select Screenix's microphone.
- It does not select the playback sink whose monitor is used for system audio.
- It does not decide camera framing.
- It does not determine export codec, resolution, captions, or sharing access.
- It does not promise that a restore token will always bypass future interaction; persistence remains subject to portal behavior.
How to reason about the Screenix chooser
On Wayland, choose the visual source in the portal, then verify the separate audio controls in Screenix. If the picture is wrong, revisit the portal source. If sound is wrong, inspect the selected microphone or output monitor. This narrows the failure instead of treating the prompt as a universal permission dialog.
Sources and verification
Technical claims in this guide were checked against the upstream documentation below. Screenix-specific behavior was also verified against the desktop implementation current on August 31, 2026.
- 1. ScreenCast portal specification
XDG Desktop Portal · The session lifecycle, selectable source types, cursor modes, restore tokens, and PipeWire handoff.
- 2. PipeWire: Objects Design
PipeWire · PipeWire's graph objects, including nodes, ports, links, clients, and devices.
- 3. Share your desktop
GNOME Help · GNOME's user-facing distinction between desktop sharing settings and application behavior.