diff --git a/README.md b/README.md index 71c8d33e..efb98e7a 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ On macOS the terminal needs the Screen Recording permission, as `komorebi` does. with `--log-level trace` first: the recorder never changes komorebi's log level, it only warns. A session made with `--no-video` has everything but the screen. [Recording a bug repro](docs/usage/recording-a-bug-repro.md) has the rest: what is captured on each OS, docking, sleep and lock, and recovering a recording after a crash. -`record --window-track` also samples where every window is at video rate, and `sheet --windows` draws those rects on +`record` also samples where every window is at video rate (`--no-window-track` turns that off), and `sheet --windows` draws those rects on the frames. ## Investigate it diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md index b00cea75..0c77a559 100644 --- a/docs/PLATFORM.md +++ b/docs/PLATFORM.md @@ -112,7 +112,7 @@ that a contact sheet never decodes more pixels than it shows. ### The window track -`record --window-track[=HZ]` samples every top-level window into `windows.jsonl` (see +`record` samples every top-level window (on by default; `--window-track=HZ` picks the rate, `--no-window-track` turns it off) into `windows.jsonl` (see `src/sources/windowtrack.rs`), listed by `platform::window::list`. | | macOS | Windows | @@ -123,6 +123,7 @@ that a contact sheet never decodes more pixels than it shows. | `visible` | `kCGWindowIsOnscreen` (false for windows on other spaces) | `IsWindowVisible`; invisible windows and tool windows are not listed | | `minimized` | always false: the window server does not say | `IsIconic` | | `cloaked` | absent | `DWMWA_CLOAKED` | +| `border` | never set | `komoborder-` tool windows are listed (other tool windows are not), with `border` true, and `border_of` when the id is a window handle (a floating window); a tiled window's border is named for its container, see `windowtrack.rs` | | `title` | `kCGWindowName` | `GetWindowTextW` | | status | written against the `objc2` sources and not built or run | built and run | @@ -157,7 +158,7 @@ KDE. What is written from the sources and has not been seen to work on a real Pl | the video | H.264 only, written by GStreamer (`x264enc` and `mp4mux`) as fragmented MP4 in segments, as on the other hosts. HEVC is refused. A display of an odd size, or one H.264 cannot take, is scaled by the pipeline | | decoding | GStreamer: `decodebin` to BGRA at the size asked for, seeking to the key frame before the time and decoding forward. A frame's time is its stream time, because an MP4's edit list puts the media time of the first frame after zero | | the OS trace | the journal: `oslog/system.ndjson` (`journalctl --user`, of `kwin_wayland`, `plasmashell` and `komorebi`, stream `journal`) and `oslog/eventlog.ndjson` (every warning and worse, stream `journal-warnings`). An entry's time is `__MONOTONIC_TIMESTAMP`, which is the master clock | -| the window track | komorebi for KDE's own state: a Wayland client cannot list other programs' windows, so only windows komorebi manages are listed, each shown when its workspace is showing and it is in front of its stack | +| the window track | komorebi for KDE's own *beliefs*, not KWin's geometry: only windows komorebi manages are listed, with komorebi's rect, each shown when its workspace is showing and it is in front of its stack. **Not done:** listing KWin's real windows. KWin has no D-Bus call that lists windows: `getWindowInfo` needs a UUID, and the only listing the recorder uses is `/WindowsRunner` `Match(query)`, which is a KRunner text search (it may need a minimum query length; not checked, so not relied on) and costs one `getWindowInfo` per window per tick. A complete, cheap source needs a KWin script (`loadScript` over `org.kde.kwin.Scripting`) that pushes `frameGeometryChanged`/`windowAdded` to a D-Bus service of the recorder's, or the `org.komorebi.Bridge` events; that was not built or tried on the Plasma guest. Until then the track on KDE cannot show a window komorebi does not manage, nor a frame that disagrees with komorebi's `rect` (use `--probe-windows` for per-event real frames). komorebi for KDE has no border windows (KWin's rounded-corners effect paints them), so there is nothing to mark `border` there | | komorebi's sockets | `$XDG_RUNTIME_DIR/komorebi/` (the command socket `komorebi.sock` and the subscribers'), and the data directory where there is no runtime directory | | komorebi's log | `~/.local/share/komorebi/komorebi_plaintext.log.`; the span of an event's handler is `handle_event` and of a command's `process_command` | | the program's own windows | left out of the video by a KWin window rule (`excludefromcapture`, forced for the window class `komorebi-recorder`), which `record` writes to `~/.config/kwinrulesrc` and has KWin read; komorebi is told to ignore them by their application id, `komorebic ignore-rule class komorebi-recorder`, run before the window exists. Whether KWin honours the rule for a screencast of an output is a check still to make (K3) | diff --git a/docs/dev/kde-checkpoints.md b/docs/dev/kde-checkpoints.md index 1bcabc07..e34a2e0d 100644 --- a/docs/dev/kde-checkpoints.md +++ b/docs/dev/kde-checkpoints.md @@ -113,5 +113,5 @@ Status: the journal was followed on a machine with no Plasma. 1. `record --duration 30`, and cause some noise: open a program that is not in the session, plug something in. Expect `oslog/system.ndjson` to have `kwin_wayland` and `plasmashell` entries, and `oslog/eventlog.ndjson` the warnings. A user who is not in the `systemd-journal` group may see none of the system's: the problems say so. -2. `record --window-track --duration 30`. Expect `windows.jsonl` with the windows komorebi manages, a window behind a +2. `record --duration 30` (the window track is on by default). Expect `windows.jsonl` with the windows komorebi manages, a window behind a stack not shown, and a window of another workspace not shown. diff --git a/docs/usage/recording-a-bug-repro.md b/docs/usage/recording-a-bug-repro.md index 225da8cb..a13f4715 100644 --- a/docs/usage/recording-a-bug-repro.md +++ b/docs/usage/recording-a-bug-repro.md @@ -163,7 +163,8 @@ Useful options: | `--oslog-all` | One extra unfiltered system-wide stream (very large) | | `--no-oslog`, `--no-komorebi` | Skip the OS trace, or skip touching komorebi entirely | | `--no-video` | Do not capture the screen; record everything else on the same clock (see below) | -| `--window-track[=HZ]` | Also sample every window's rect and state alongside the video (30 Hz by default, 1 to 120; see below) | +| `--window-track[=HZ]` | Sample every window's rect and state alongside the video: on by default at 30 Hz where windows can be listed; this picks another rate, 1 to 120 (see below) | +| `--no-window-track` | Do not sample the windows | | `--no-probe-windows` | Windows: do not record what Windows says about each window event, which is on by default (see below) | | `--fps N`, `--retina`, `--codec hevc\|h264` | Video settings (display-rate capture (`--fps 0`, the default; N caps it), logical points, HEVC by default) | @@ -249,7 +250,7 @@ question is different: _which window was where, in this frame_. `record --window visible or minimized and, on Windows, whether it is cloaked, front to back, into `windows.jsonl`. A row is written only when something changed, plus a full row each second, so a still desktop costs about one row a second and a busy one a few kilobytes a second. The recorder's own windows and tool -windows (tooltips, toasts) are left out. It is off unless asked for. `komorebi-recorder sheet +windows (tooltips, toasts) are left out, except komorebi's border windows on Windows, which are kept and marked `border` so that a border that lagged its window can be seen. It is on by default on every host that can list windows (Windows, macOS, KDE); `--no-window-track` turns it off and `--window-track=HZ` picks another rate (30 Hz is the default; the sampler does not catch up when a sample is late, it counts it and says so in the warnings). `komorebi-recorder sheet --windows` then draws each window's rect, labelled with its program and id, on every frame of the sheet; a session with no track says so and gets a plain sheet. A recording that cannot keep the rate says so in its warnings. @@ -351,7 +352,7 @@ frames-[-].csv every frame's host-clock timestamp komorebi.log exact slice of komorebi's own log events.jsonl, states/ subscriber notifications; full State stored only when it changed state-start.json, state-end.json -windows.jsonl window track (only with --window-track): every window's rect, on change and once a second +windows.jsonl window track (on by default; not with --no-window-track): every window's rect, on change and once a second recorder.jsonl what happened to the recording environment (displays, sleep/wake, lock, restarts) annotations.jsonl bug regions, notes and findings (appended, never rewritten) oslog/komorebi.ndjson unified log, komorebi's process (oslog/komorebi-.ndjson after a restart) diff --git a/komorebi-recorder/src/guide.md b/komorebi-recorder/src/guide.md index 15ef7806..cf3bdf2c 100644 --- a/komorebi-recorder/src/guide.md +++ b/komorebi-recorder/src/guide.md @@ -109,11 +109,13 @@ locations as hints. `blank --region x,y,w,h` (when a region went one colour, such as white, or froze) and `compare ` (two recordings' frames, motion and findings side by side). Regions are in display points, the same as the `bbox_points` of `changes`. They need a host that can decode the video. -- A session recorded with `--window-track` has `windows.jsonl`: every top-level window's rect, +- A session recorded with the window track (on by default; `--no-window-track` turns it off) has `windows.jsonl`: every top-level window's rect, visibility and minimized state (and `cloaked` on Windows) sampled at video rate, front to back, so "which window was where in this frame" has an answer. `sheet --windows` draws the rects on each frame (`windows` in the answer names the ones drawn). Rects are in the display's own units - (pixels on Windows, points on a Mac). Without it only the sparse per-event probes exist. + (pixels on Windows, points on a Mac). On Windows komorebi's border windows are in the track too, marked `border` + (`border_of` names the window for a floating window's border; a tiled one is named for its container in the + `title`, to be joined with `State`; pairing by rect is a heuristic, not recorded). Without it (`--no-window-track`, or a host that cannot list windows) only the sparse per-event probes exist. - Video time `00:00.000` is the first frame of any display. A display that was unplugged, asleep or whose capture failed has a gap, and `incident` records say why.