LGUG2Z
658827fcd5
The ban (`just lint`, and now the hygiene job) came from the macOS and KDE repositories and was never applied to the Windows code, so the unified tree had sixteen uses of the macro: seven in the Windows daemon, six in komorebi-core (written during the unification), one in the KDE backend and two in the recorder. Each becomes eyre::Report::msg, with format! where the message has arguments.
komorebi-recorder
Synchronized screen, log and trace capture for komorebi bug reproduction. komorebi-recorder records a bug while it
happens, on macOS and on Windows: the screen, komorebi's log, every event komorebi sends its subscribers and the
operating system's own trace, all on one clock, into a single session directory. It then answers, from that
directory alone, what komorebi and the OS were doing at any second of the video and where in the video any log line or
event is: for a person, with a window that plays the recording with everything that happened laid out on a timeline,
and for an agent, with commands that print JSON.
Install
Every release has, for macOS and for both architectures of Windows, a zip of the executables and, for Windows, an MSI
installer that puts them in Program Files\komorebi-recorder\bin and optionally on the PATH. The nightly release
is rebuilt every week from master.
| file | |
|---|---|
| macOS (Apple silicon) | komorebi-recorder-<version>-aarch64-apple-darwin.zip |
| Windows x86_64 | komorebi-recorder-<version>-x86_64.msi or komorebi-recorder-<version>-x86_64-pc-windows-msvc.zip |
| Windows ARM64 | komorebi-recorder-<version>-aarch64.msi or komorebi-recorder-<version>-aarch64-pc-windows-msvc.zip |
checksums.txt lists the SHA-256 of every file. The installers and executables are not signed, so Windows
SmartScreen and Defender may warn about them.
From source
The recorder is a crate of the komorebi repository, and ships in the komorebi release, installer included. In a checkout of the repository:
nix develop # the toolchain, ffmpeg and the rest
cargo install --path komorebi-recorder --locked
nix build .#komorebi-recorder makes the macOS or Linux binary, and nix build .#windows-komorebi-recorder
cross-compiles komorebi-recorder.exe (and .#windows-komorebi-recorder-gui the viewer) from either.
nix run github:LGUG2Z/komorebi#komorebi-recorder runs the latest commit without a checkout.
Record a bug
komorebi-recorder displays # which displays can be recorded
komorebi-recorder record --duration 30 --out ./repro
komorebi-recorder record --until-exit --out ./repro -- ./repro.sh # record while a script runs, stop when it exits
Run komorebi-recorder with no command for a small window with Record and Stop buttons instead.
On macOS the terminal needs the Screen Recording permission, as komorebi does. For a useful recording, start komorebi
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 has the rest:
what is captured on each OS, docking, sleep and lock, and recovering a recording after a crash.
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
komorebi-recorder brief ./repro # what the user marked as the bug, and what the recording shows around it
komorebi-recorder brief ./repro --compact # the same in about 40 lines, for a small context window
komorebi-recorder findings ./repro # detector findings (with stable ids) and an agent's conclusions, in one list
komorebi-recorder overview ./repro # the whole recording at a glance
komorebi-recorder trace ./repro event:7 # one event, from the handler that ran to what changed and who changed it
A script that drives the repro can name its steps on the timeline while recording, with
komorebi-recorder mark "step 3: move window right"; they show up as notes. And the same script can end with a
pass or fail: komorebi-recorder assert ./repro --check "findings kind=layout-mismatch count<=0" --check "log \"level=ERROR\" count==0"
exits 0 when every check holds and 6 when one does not (checks over findings, the log, motion, blank regions and
notes; see the guide).
For example, a four second recording of a Mac with komorebi running:
$ komorebi-recorder overview ./repro
session /private/tmp/kr-sample: 4 s of video, 2 events, 2 log lines, 1 incidents
findings, most worth looking at first (1 of 1):
info 00:00.631 incident:recorder recorder: recording started without video; komorebi pid 2732
when things happened (events | errors | incidents):
00:00.500 ############################## 1 0 1
00:04.500 ############################## 1 0 0
komorebi-recorder view ./repro opens the recording in the window, which is where you mark where the bug is. There is
only ever one window, for recording and for reviewing: its first tab is Record and each recording is a tab after it.
Running komorebi-recorder or view again (or Open session… in the Record tab) raises that window instead of
making another, and --new-window makes a window of its own.
Every command takes --json (including record, displays, reindex and selftest), and komorebi-recorder guide
prints a playbook for an agent.
Investigating a recording walks through both ways of working.
How it fits together
Two things vary independently: the host the recorder runs on (macOS or Windows) and the flavor of komorebi it records (komorebi for Mac or komorebi for Windows). A session records both, so one recorded on Windows can be investigated on a Mac. Every record in a session is stamped on one monotonic clock, and the files in it are never rewritten after they are written. Architecture explains the model and which layer enforces each rule; Platform answers the same questions for each host.
Crates
komorebi-recorder: the library, thekomorebi-recordercommand and, with the same code, thekomorebi-recorder-guiexecutable (no console window on Windows).
Checks
The recorder is checked with the rest of the repository. nix build .#checkSets.recorder-lint and
.#checkSets.recorder-test are its clippy and tests on this host, and the windows-* checks type-check its
Windows code from a Mac or Linux machine (windows-clippy; the Windows tests only compile there, and run in the
guest). CI runs the same sets, and the Windows workflow builds the executables and the komorebi installer that
carries them.
Documentation
cargo doc --workspace --no-deps --open for the code. CONTRIBUTING.md says how to work on it.