mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-20 07:31:39 +01:00
docs(windowtrack): the window track is on by default, borders, and what KDE lacks
This commit is contained in:
1 parent
f945442c52
commit
69ee42079e
5 files changed
+13
-9
No files matched your search
@@ -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
|
||||
|
||||
+3
-2
@@ -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-<id>` 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.<UTC date>`; 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) |
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
<session> --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-<displayID>[-<n>].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-<pid>.ndjson after a restart)
|
||||
|
||||
@@ -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 <a> <b>` (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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user