feat(recorder): orchestrate a recording

`komorebi-recorder record` starts every source in the order that makes the
non-video sources a superset of the video, stops them in reverse, and
checkpoints the manifest as it goes, so that a recorder that is killed leaves a
session `reindex` can recover. `--no-video` records everything but the screen,
and Ctrl-C or `--duration` stops and finalizes a recording. The format of
`annotations.jsonl`, the append-only file that bug regions, notes and findings
are written to, is defined here too. The command table arrives with it, with
`displays` and `reindex`, and with the text-and-JSON conventions the later
commands share.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent 1006ec2570
commit 05d87908c5
16 files changed
+6462 -13

No files matched your search

+179
View File
@@ -0,0 +1,179 @@
# Recording a Bug Repro
`komorebi-recorder` records a bug while it happens: the screen, komorebi's log, every komorebi event and the macOS OS
trace, all on one clock, into a single _session directory_. Afterwards you can ask "what was komorebi doing, and what
was the OS doing, at 00:12.5 in the video?" and the other way around.
```
komorebi-recorder record --duration 30 # record without a window
```
It is built for the situations where komorebi bugs actually show up: laptops that get docked and undocked, woken with the
lid opened, locked and unlocked. Recording carries on through all of that without losing what was already captured; see
[Docking, sleep and lock](#docking-sleep-and-lock).
## What is captured
| What | Where it comes from |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| Screen | ScreenCaptureKit, one `mp4` per display per contiguous span (a _segment_), with every frame's timestamp |
| komorebi's log | The exact byte range of `komorebi_plaintext.log.<date>` written during the recording |
| komorebi's events | A subscriber socket: every `WindowManagerEvent` / socket message plus the full `State` |
| OS trace: komorebi | `log stream` for komorebi's own process: system frameworks (AX, LaunchServices, ...) as it calls them |
| OS trace: system | Accessibility, SkyLight, HIServices and workspace subsystems |
| OS trace: each app | `log stream` for **every process that owns a window in komorebi's state**, one file per app |
| Recording environment | Displays connecting, disconnecting and sleeping; machine sleep/wake; screen lock; restarts of komorebi or of a log stream |
The OS trace is what lets you see both seams: komorebi calling into the system, and the system talking to the apps
komorebi is tiling.
## On Windows
The same tool records komorebi for Windows, on the same clock, into the same kind of session
directory; a session recorded on one OS can be investigated on the other. What differs:
| | macOS | Windows |
| --- | --- | --- |
| Screen | ScreenCaptureKit, HEVC | Windows.Graphics.Capture, H.264 (Windows 10 1803+) |
| OS trace | the unified log: komorebi's process, the system, each managed app | WinEvents for every top-level window, folded when repeated, and the System Event Log's warnings and errors and its display, power and GPU providers |
| komorebi's log | its data directory | `%TEMP%\komorebi_plaintext.log.<date>` |
| Permission | Screen Recording, granted to the terminal or app | none |
| Executables | `komorebi-recorder` | `komorebi-recorder.exe` (console: use this to run commands) and `komorebi-recorder-gui.exe` (no console window) |
| Sleep | found from the host clock pausing | heard from Windows as it happens (suspend, resume, lid, displays off, lock) |
Start komorebi with `komorebi.exe --log-level debug` before recording a bug. (`RUST_LOG=debug` also
prints every dependency's log; `RUST_LOG=komorebi=debug` does not.)
`komorebi-recorder record --no-video` records without the screen.
## Before you record
- **Screen Recording permission.** macOS attaches the grant to the terminal (or app) that launches the binary, exactly as
it does for `komorebi` itself. The window shows a "Grant permission" button if it is missing.
- **komorebi's log level.** The recorder never changes komorebi's log level or lifecycle; it only warns. For a useful
repro, start komorebi with `komorebi --log-level trace` (or `RUST_LOG=komorebi=trace`) first. At the default `info`
level most of what the window manager _decided_ is not in the log.
## Recording
Press **Record**, reproduce the problem, press **Stop**. The window shows live counters, recent events (a display being
unplugged, a wake) and any warnings. The session is written to
`~/Library/Application Support/komorebi/recordings/<UTC timestamp>/` unless you pass `--out`.
Headless recording is the same thing without the window; Ctrl-C, `SIGTERM` or `--duration` stops and finalizes it:
```
komorebi-recorder record --out ./repro --duration 60
komorebi-recorder displays # list display ids
komorebi-recorder record --display 2 # record just one display
```
Useful options:
| Option | Effect |
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
| `--oslog-apps managed\|all-gui\|none` | Which apps get their own OS trace file (default: those komorebi manages) |
| `--trace-process NAME` / `--trace-pid PID` | Also trace an app komorebi does not manage |
| `--oslog-exclude NAME` | Never trace this (chatty) app |
| `--oslog-level debug\|info\|default` | Unified log level (default `debug`) |
| `--system-process NAME` | Add a system daemon to the `system` stream, e.g. `WindowServer` (see volume note below) |
| `--predicate P` | Replace the `system` stream's predicate |
| `--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) |
| `--fps N`, `--retina`, `--codec hevc\|h264` | Video settings (30 fps cap, logical points, HEVC by default) |
### Without video
`komorebi-recorder record --no-video` records everything but the screen: komorebi's events and log, the OS trace and
what happened to the recording environment, all on the same clock. Use it on a machine with no
display (or no Screen Recording permission), or when what is on the screen must not be recorded. It asks the system
nothing about displays. A session made this way has no video, so video time `00:00.000` is the moment the recording
started, and there is nothing for `frames` to show.
## Docking, sleep and lock
The set of displays, and whether ScreenCaptureKit streams stay alive, changes underneath a laptop all the time. The
recorder is built so that **nothing already captured is put at risk by any of it**.
- **A display disappears** (unplugged, undocked, lid closed, or it goes to sleep): that display's video file is finalized
on the spot, so it is complete and playable whatever happens next. The other displays carry on untouched.
- **A display appears or returns:** after a one-second settle, it starts a new _segment_ in a new file
(`video-<id>-2.mp4`, `-3`, ...). Each segment is a whole file; `session.json` lists every one with its time span.
- **The machine sleeps and wakes:** the wall clock and the host clock are compared many times a second, so a sleep is
noticed the moment the machine wakes and the clock anchors on either side of it are recorded exactly. Every display is
then given a fresh stream rather than trusting the old one, because streams can stall across a sleep without reporting
anything. The host clock pauses while asleep, so video time skips the sleep instead of showing a hole.
- **A stream stalls or dies:** a healthy ScreenCaptureKit stream calls back about thirty times a second even when the
screen is not changing, so silence for a few seconds means a dead stream. That segment ends at its last sign of life and
a new one starts.
- **The screen locks, or another user's session comes to the front:** noted, and the displays are watched as above.
- **A `log stream` process dies** (for instance when logd restarts): it is restarted into the same file, appending.
- **komorebi exits or is restarted:** noted, and when it is running again the recorder re-subscribes and traces the new
process. komorebi not running when recording starts is not an error either.
All of this is recorded in `recorder.jsonl`.
### If the recorder dies
Everything is written as it arrives and the manifest is checkpointed every few seconds, so a crash, a `kill -9` or a
power loss does not lose the session. Video is written as fragmented mp4, which plays up to the last fragment (about a
second) even though it was never finalized, and a static screen is kept moving so that it, too, is flushed. To recover:
```
komorebi-recorder reindex <session>
```
This closes the segments that were still open (using the video files themselves to decide how much survived), rebuilds
the timeline, and marks the session `recovered`. The queries tell you to do this if you point them at an unfinished
session.
## The session directory
```
session.json manifest: versions, displays and every video segment, clock anchors, log segments, streams, apps, warnings
video-<displayID>[-<n>].mp4 screen recording of one segment (variable frame rate: frames exist only where the screen changed)
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
recorder.jsonl what happened to the recording environment (displays, sleep/wake, lock, restarts)
oslog/komorebi.ndjson unified log, komorebi's process (oslog/komorebi-<pid>.ndjson after a restart)
oslog/system.ndjson unified log, accessibility / SkyLight / workspace subsystems
oslog/apps/<exe>-<pid>.ndjson unified log, one managed application
timeline.jsonl merged, sorted index pointing into the raw files
README.md generated guide to this session
```
Raw files are never rewritten; `timeline.jsonl` only references them, so `komorebi-recorder reindex <session>` can rebuild
it at any time (including after hand-editing a log).
## How accurate is the alignment?
Everything is placed on the host monotonic clock (`mach_absolute_time`). Video frame timestamps and the unified log's
`machTimestamp` are on that clock directly. komorebi's log lines carry UTC wall-clock time and are mapped onto it with
anchors sampled every 5 seconds during the recording and at every sleep, so clock steps and sleep are handled.
- video to OS trace: within about one frame
- video to komorebi's log: within about one frame plus the wall-clock anchor error (tens of microseconds)
- subscriber events are stamped when the recorder receives them. komorebi sends the notification _after_ it has handled
the event, so the stamp is when the handler **finished**; the `processing event` line in `komorebi.log` is when it
began.
## Things to know
- **What can still be missing.** Events from a `log stream` during the moment it was dead and being restarted; komorebi
events while komorebi was not running; the last second or so of video if the recorder is killed rather than stopped; a
display's video while it was asleep or unplugged (there is simply nothing to record). Each of these leaves a line in
`recorder.jsonl` saying so, rather than a silent hole.
- **Windows komorebi manages are found through the window server.** komorebi's `State` has no process ids, so the
recorder resolves window ids to owning processes itself. A process that appears mid-recording gets its own stream as
soon as it shows up in a state or event; events it emitted in the few hundred milliseconds before that are missed
(`session.json` records `first_seen_mach_ns` for each app so you know where each file starts).
- **Volume.** Per-process debug streams are modest, but system-wide daemons are not: `launchservices` alone was ~500
events/s (~29 MB/min) and `runningboard` ~290 events/s on a normal desktop, which is why they are opt-in. komorebi's
own process emits a few hundred events per second while it is busy. The recorder warns when a stream is abnormal, since
`log stream` can drop events under extreme load.
- **`<private>` values stay redacted.** The tool needs no `sudo` and changes no SIP settings, and it does not do
syscall-level tracing.
- **Privacy.** The video contains whatever was on screen and application logs can contain window titles and URLs. Review
a session before sharing it.