mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-19 23:28:34 +01:00
The recorder is now the pinned first tab (Record, not closable, with a REC marker while recording) of the viewer window; sessions follow as tabs. There is one process and one window: komorebi-recorder, gui and view all claim the same socket, and a second launch forwards (gui shows the Record tab, view opens tabs) and exits. The request protocol gains an optional "tab" field; old requests still parse. gui takes the record options (they only seed the window that is started) and --new-window. The window starts compact (420x380, always on top, Record tab only) when launched plainly and full size for view; opening any session expands it, and Compact / Expand is remembered in the prefs. RecorderApp::poll runs on every frame whichever tab is showing, so recordings continue and finalize while another tab is looked at. Cmd/Ctrl+0 shows the Record tab; Cmd/Ctrl+W on it does nothing; closing the last session tab returns to Record. KOMOREBI_RECORDER_PREFS_DIR and KOMOREBI_RECORDER_NO_IGNORE_RULE let tests and end-to-end runs avoid the real prefs and the real komorebi. The macOS/unix cfg branches (hidden title bar spacing) mirror the existing tested patterns and could not be compiled on the Windows machine this was written on.
120 lines
6.2 KiB
Markdown
120 lines
6.2 KiB
Markdown
# 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 repository is a Nix flake. In a checkout:
|
|
|
|
```sh
|
|
nix develop # the toolchain and the pinned komorebi sources
|
|
cargo install --path komorebi-recorder --locked
|
|
```
|
|
|
|
`nix build` makes the macOS binary in `./result/bin`, and `nix build .#komorebi-recorder-windows` cross-compiles
|
|
`komorebi-recorder.exe` and, with it, `komorebi-recorder-gui.exe` from a Mac. `nix run github:LGUG2Z/komorebi-recorder`
|
|
runs the latest commit without a checkout.
|
|
|
|
## Record a bug
|
|
|
|
```sh
|
|
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](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
|
|
the frames.
|
|
|
|
## Investigate it
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
$ 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](docs/usage/investigating-a-recording.md) 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](docs/ARCHITECTURE.md) explains the model and which layer enforces each rule;
|
|
[Platform](docs/PLATFORM.md) answers the same questions for each host.
|
|
|
|
## Crates
|
|
|
|
- [`komorebi-recorder`](komorebi-recorder): the library, the `komorebi-recorder` command and, with the same code, the
|
|
`komorebi-recorder-gui` executable (no console window on Windows).
|
|
|
|
## Checks
|
|
|
|
`just check` runs formatting, clippy and the tests for macOS, clippy for Windows (the Windows code is type-checked
|
|
from a Mac, not run), rustdoc with its warnings as errors for both hosts, and `cargo deny`. It needs `nix develop`.
|
|
CI runs the same checks, builds both platforms and, for Windows, the installer.
|
|
|
|
## Documentation
|
|
|
|
`cargo doc --workspace --no-deps --open` for the code. [CONTRIBUTING.md](CONTRIBUTING.md) says how to work on it.
|
|
|
|
## License
|
|
|
|
[Komorebi License 2.0.0](LICENSE.md).
|