Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs(capture-linux): mark the window-cursor gap as read from mutter, not observed

Etienne Lescot9038c7b5fc9c
diff --git a/electron/native/README.md b/electron/native/README.md
index f649d8a2e..8dbdba609 100644
--- a/electron/native/README.md
+++ b/electron/native/README.md
@@ -237,11 +237,12 @@ electron/native/bin/linux-x64/openscreen-pipewire-helper '{"probeOnly":true}'
never keystrokes (see `pipewire-capture/src/input.rs`), and
`OPENSCREEN_DISABLE_CLICK_CAPTURE=1` turns it off entirely. User setup:
[Mouse clicks on Wayland](../../website/docs/installation.md#mouse-clicks-on-wayland).
-- **Window takes keep the client-side shadow as a black border, and have cursor
- data only while the pointer is over the window.** Both come from what mutter
- puts in a window stream: its crop is the window's whole buffer, shadow
- included, and it attaches the cursor only while the window has the pointer.
- Details and measurements:
+- **Window takes keep the client-side shadow as a black border, and are
+ expected to have cursor data only while the pointer is over the window.**
+ Both come from what mutter puts in a window stream: its crop is the window's
+ whole buffer, shadow included (measured), and its source attaches the cursor
+ only while the window has the pointer (read from the mutter 46.2 code, not
+ yet observed live). Details and measurements:
[recording.md, Known gaps](../../technical-documentation/architecture/recording.md#known-gaps).
- **The user picks a source twice.** Electron's `desktopCapturer` raises its own
portal dialog for the video, and this helper raises a second one for the cursor.
diff --git a/technical-documentation/architecture/recording.md b/technical-documentation/architecture/recording.md
index d068276eb..0b958e09e 100644
--- a/technical-documentation/architecture/recording.md
+++ b/technical-documentation/architecture/recording.md
@@ -89,6 +89,6 @@ Cursor samples are persisted as cursor telemetry rather than baked into editable
- On Linux the compositor's source picker appears on every recording. That is deliberate — see "Why Linux sends no source identity" — but it is an interruption, and there is currently no way to reuse a previous choice without also making it impossible to change.
- Holding a portal session across the countdown means the compositor's "screen is being shared" indicator is up before recording begins. That is honest — access really has been granted — but the user can click it to revoke, or close the window they picked. The helper's exit surfaces as a rejected `waitUntilSourceSelected`; the session is not yet subscribed to the portal's `Session::Closed` signal, so a revocation is reported as a failed start rather than a specific message.
- On Linux a window take keeps the window's client-side shadow as an opaque black border. The helper does honour mutter's `SPA_META_VideoCrop`, but for a window that crop is the window's *buffer* (`meta_window_actor_get_buffer_bounds`: the whole surface, at 0,0). A client that draws its own decorations, such as GTK or libadwaita, draws its drop shadow inside that buffer, around the visible geometry it declares through `xdg_surface.set_window_geometry`. mutter knows that geometry but puts nothing in the stream that carries it. It clears the stream buffer to transparent before painting the window, so the shadow arrives with alpha below 255 and the margin beyond it with alpha 0. H.264 has no alpha, so all of it encodes as black. Measured on a GNOME 46 terminal take of 866×628: bands of exact RGB 0,0,0, 26, 23, 26 and 28 px wide on the left, top, right and bottom. Cropping to the window means finding its opaque bounds in the alpha channel. On the default zero-copy path (dmabuf → VAAPI) that needs a GPU readback, which the importer deliberately never does (`dmabuf_import.rs`, #534 and #576). It also needs a rule for translucent windows and for a window resized after the encoder size is committed. Until then, the editor's Crop tool removes the band. A maximized window draws no shadow.
-- On Linux a window take only has cursor data while the pointer is over the window. mutter writes `SPA_META_Cursor` into a window stream only while `meta_window_has_pointer()` holds, meaning the pointer's actor is inside the window's. Otherwise it clears the metadata (`id = 0`). A window take in which the pointer never enters the window therefore has no cursor samples. `stop-native-linux-recording` writes no `.cursor.json` for a take without samples, so the editor shows no Cursor facet for it. This comes from the compositor, not from a gap in the mapping: when the pointer is over the window, mutter reports it relative to the window buffer, and `emit_sample` records it against the same rectangle the file shows.
+- On Linux a window take is expected to have cursor data only while the pointer is over the window. This is read from the mutter 46.2 source and not yet observed in a live capture. In `meta_screen_cast_window_stream_src_set_cursor_metadata`, mutter writes `SPA_META_Cursor` into a window stream only while `meta_window_has_pointer()` holds, meaning the pointer's actor is inside the window's. Otherwise it clears the metadata (`id = 0`). A window take in which the pointer never enters the window should therefore have no cursor samples. `stop-native-linux-recording` writes no `.cursor.json` for a take without samples, so the editor shows no Cursor facet for it. That matches the one window take from the v2.1.0-rc.1 pass, which wrote no sidecar, but its `cursorSamples` count and the pointer's path were not recorded. If this holds, it comes from the compositor, not from a gap in the mapping: when the pointer is over the window, mutter reports it relative to the window buffer, and `emit_sample` records it against the same rectangle the file shows.
- `preferSoftwareEncoder` is read when recording starts. The recorder has no UI for setting it; Windows also accepts `OPENSCREEN_WGC_PREFER_SOFTWARE_ENCODER=true` in the helper request path.
- The `encoder-selection` event's `video` field ("default", "software-preferred", "software-fallback") names which *configuration path* `MFEncoder::initialize` took, not which encoder Media Foundation actually picked; `videoEncoderRuntime` ("hardware", "software", or "unknown") answers that, by walking the sink writer's own transform pipeline after `BeginWriting()` for a node that self-identifies as hardware (`MFT_ENUM_HARDWARE_URL_Attribute`). It exists because of what it found (getopenscreen/openscreen#460): `MF_READWRITE_ENABLE_HARDWARE_TRANSFORMS` defaults to FALSE, and until this was fixed, leaving it unset on the "default" (non-DXGI) path meant the sink writer only ever considered software MFTs there, even on a machine with a working hardware H.264 encoder — "default" recording was, in practice, software-encoded on every machine that had not separately opted into the DXGI path above. `createSinkWriter` now sets that attribute to TRUE whenever `forceSoftwareEncoder` is false, DXGI device manager or not, so a hardware encoder is used on the "default" path when one is registered and working — which is most of the point, since it is weak-CPU machines running the software encoder that blow the stop-timeout budget in the first place. `videoEncoderRuntime` stays in the event to catch the cases that don't fit that story: a machine with no real hardware encoder falling back to software regardless, or a hardware encoder that itself turns out to be the slow or unstable one.