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): state that a window over the recording hides the popup menu

EtienneLescot02a7fc4041ea
diff --git a/electron/native/README.md b/electron/native/README.md
index 2504cbb4c..5f68fb254 100644
--- a/electron/native/README.md
+++ b/electron/native/README.md
@@ -97,11 +97,12 @@ At startup the helper also emits `capture-adapter`, naming the GPU its D3D devic
Desktop icons: `"hideDesktopIcons": true` on a display capture puts a borderless window, painted with the wallpaper by `PaintDesktop`, on the captured monitor directly above the window that hosts the icons (`SHELLDLL_DefView`'s top-level parent) and below every app window (`src/desktop_icon_cover.cpp`). WGC cannot exclude another process's window, so covering is the only route that changes no setting. The window belongs to the helper, so it goes away with the recording or with a crashed helper; there is nothing to restore. Windows notifications cannot be kept out: toasts are drawn above every app window, and the only switch is Do Not Disturb, a user setting the helper does not touch.
-Menus and popups in window recordings: a window source is captured per HWND, and a context menu or dropdown is a window of its own, so it used to be missing from the video (#894). On Windows 11 24H2 (build 26100) and later the helper sets `GraphicsCaptureSession.IncludeSecondaryWindows` (`IGraphicsCaptureSession6`) on window sources, and DWM draws the popups belonging to the captured window into the same texture: the frame size, DPI handling, occlusion immunity and the fixed frame pool are unchanged. Monitor sources never set it, since they already contain everything on the screen. Three things to know:
+Menus and popups in window recordings: a window source is captured per HWND, and a context menu or dropdown is a window of its own, so it used to be missing from the video (#894). On Windows 11 24H2 (build 26100) and later the helper sets `GraphicsCaptureSession.IncludeSecondaryWindows` (`IGraphicsCaptureSession6`) on window sources, and DWM draws the popups belonging to the captured window into the same texture: the frame size, DPI handling, occlusion immunity and the fixed frame pool are unchanged. Monitor sources never set it, since they already contain everything on the screen. Four things to know:
- **Popups are clipped at the window's edge.** The texture is the window's size, so the part of a menu that overhangs it is not recorded (measured: a 276 px menu opened 138 px inside the right edge shows 138 px, cut at the last column).
- **It needs 24H2.** Older runtimes keep capturing the window alone, as before. The helper reports the outcome as `{"event":"secondary-windows","applied":true|false}` (absent for monitor sources and when the option is disabled); the app logs it and shows nothing. Set `OPENSCREEN_WGC_DISABLE_SECONDARY_WINDOWS=1` to turn the option off and get the window-only capture back.
- **What DWM lets in was measured, because Microsoft's rule is style and z-order, not process.** It draws windows with `WS_POPUP` or `WS_EX_TOOLWINDOW` that overlap the window and have only other such windows between them and it. On build 26200, three unrelated TopMost popups from other processes (`WS_POPUP`, `WS_POPUP` plus `WS_EX_TOOLWINDOW`, and `WS_EX_TOOLWINDOW` alone), all overlapping the window with nothing else above it, stayed out of the recording, as did Explorer's own Win+X menu; the window's own owned menu was in. `npm run test:wgc-window-popup:win` reproduces the measurement (menu present, strangers absent, overhang clipped, kill switch removes the menu) and refuses to pass if a non-qualifying window sits above its target, since a stranger missing for that reason would prove nothing.
+- **The menu shows up only when no ordinary window sits above the recorded window.** If another window (neither a popup nor a tool window) overlaps it, the menu is missing from the first frame to the last, which is expected from how DWM selects secondary windows (#910). Measured on a second machine (Windows 11 build 26200, AMD, 46 runs of the fixture): the menu was captured in all 25 runs with nothing ordinary above the window, and absent in all 21 runs with one above it (Claude Desktop, Notepad); in the 20 valid runs at 2000 ms and 5000 ms no unrelated popup leaked (0 px). That is 0 leaks in 20 runs, which does not exclude a failure rate up to about 15 percent, and the fixture is synthetic WinForms, not a real application's menus.
Encoder diagnostic on final sink-writer failure: when the final sink-writer attempt fails (`MFCreateSinkWriterFromMediaSink` on the fragmented container, `MFCreateSinkWriterFromURL` on the plain one; the message names which), the helper logs the registered H.264 video encoder MFT count (via `MFTEnumEx`), the registered AAC encoder count when audio was requested, and the hex HRESULT. If no H.264 encoder is registered, it additionally emits the four-bullet actionable error (missing Media Feature Pack / GPU driver registration / empty `HKLM:\SOFTWARE\Microsoft\Windows Media Foundation\Transforms` / reboot). If an H.264 encoder IS registered but the sink writer still failed, it logs a hint pointing at invalid output path, missing MP4 mux, or GPU driver incompatibility. There is still no fail-fast pre-flight gate because `MFTEnumEx` and the sink writer can disagree about which H.264 encoders are available in non-interactive / Session 0 contexts.
diff --git a/scripts/test-windows-wgc-helper.mjs b/scripts/test-windows-wgc-helper.mjs
index acb3ca47a..0ff318bc0 100644
--- a/scripts/test-windows-wgc-helper.mjs
+++ b/scripts/test-windows-wgc-helper.mjs
@@ -27,6 +27,12 @@ const WITH_WINDOW =
* the strangers are not (getopenscreen/openscreen#894). The second half is the
* point: DWM picks the windows IncludeSecondaryWindows draws by style and
* z-order, so what it lets in has to be measured, not assumed.
+ *
+ * It shows windows on the desktop. Run it with no ordinary window (neither a
+ * popup nor a tool window) over the test zone, about x 400-1110, y 150-685 at
+ * 100 percent DPI, for as long as it runs: with one above the target the menu is
+ * missing from the first frame to the last (#910). A run that prints
+ * `fixture invalid` found one and measures nothing.
*/
const WITH_WINDOW_POPUP =
process.env.OPENSCREEN_WGC_TEST_WINDOW_POPUP === "true" ||
diff --git a/technical-documentation/testing/manual-e2e-checklist.md b/technical-documentation/testing/manual-e2e-checklist.md
index a9a959d78..a8ee9c9d0 100644
--- a/technical-documentation/testing/manual-e2e-checklist.md
+++ b/technical-documentation/testing/manual-e2e-checklist.md
@@ -726,7 +726,7 @@ Edits are saved as they land. The dot after the project name reads "Unsaved" (ho
- [ ] Disable hardware H.264 if the test machine supports that diagnostic path and confirm the software-encoder notice is clear and non-blocking.
- [ ] Switch the recording HUD between displays and confirm it remains positioned on the intended display.
- [ ] Switch the desktop to an odd-pixel window size and confirm the recorded frame dimensions remain valid.
-- [ ] On Windows 11 24H2 or later, record a single-window source, right-click inside that window and confirm the context menu is in the video; then open one that overhangs the window's edge and confirm it is cut off at the edge. Before 24H2 the menu is absent, which is expected (`secondary-windows` `applied:false` in the log).
+- [ ] On Windows 11 24H2 or later, record a single-window source, right-click inside that window and confirm the context menu is in the video; then open one that overhangs the window's edge and confirm it is cut off at the edge. Run it with nothing ordinary overlapping the recorded window: with another window (neither a popup nor a tool window) above it the menu is missing, which is expected and not a failure (#910). Before 24H2 the menu is absent too, which is expected (`secondary-windows` `applied:false` in the log).
- [ ] Run tray → *Save Diagnostics* and confirm a diagnostic bundle can be written.
- [ ] **post-1.10.0** — Record with no encoder override and confirm the helper's `encoder-selection` log line reports `videoEncoderRuntime: "hardware"`. The plain sink-writer path never asked for hardware transforms before, so every ordinary recording ran the software encoder; on a slow machine that is what blew the stop-shutdown budget.
- [ ] **post-1.10.0** — Confirm forcing the software encoder still reports `"software"`, so the default is a default and not a hard-wire.