LGUG2Z 11f028b8c9 feat(capture): record at the display's refresh rate, and give each frame its real duration
Windows Graphics Capture holds a capture to 60 frames a second unless it is
given a minimum update interval, so a 120 Hz display was recorded at half its
rate and a one-refresh flash could fall between two frames. ScreenCaptureKit
was asked for at most 30 (the default --fps), so macOS lost frames the same
way.

--fps now means the most frames a second, and 0, the new default, means no
cap: Windows sets the session's minimum update interval to a millisecond (or
a frame at --fps), and macOS sets a zero minimum frame interval. The encoder
is told 60 fps when there is no cap.

On Windows each sample was also stamped to last 1/fps whatever the gap to the
next frame. A frame is now held until the next arrives and given the real
time between them; the last one still gets a frame at the nominal rate. macOS
passes ScreenCaptureKit's own sample timing through, so needs no change.

Checked on a Mac with a 120 Hz display and komorebi for Mac running: with no
cap a display is recorded a frame every 8.3 ms, and --fps 30 holds it to about
30 a second. The video holds as many frames as the frame log has rows, and the
state komorebi was recorded in matches what the frames show. The macOS encoder
never reads fps, so CaptureConfig::fps now says it reaches only the Windows
one.
2026-10-28 16:24:29 -07:00
2026-10-28 16:24:29 -07:00
2026-10-28 16:24:29 -07:00
2026-10-28 16:24:29 -07:00
2026-10-27 22:22:56 -07:00

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:

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

komorebi-recorder displays                       # which displays can be recorded
komorebi-recorder record --duration 30 --out ./repro

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.

Investigate it

komorebi-recorder brief ./repro        # what the user marked as the bug, and what the recording shows around it
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

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 viewer, which is where you mark where the bug is. Every command takes --json, 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, 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 says how to work on it.

License

Komorebi License 2.0.0.

S
Description
No description provided
Readme
47 MiB
0 Stars 1 Watchers 0 Forks
Latest
2026-02-14 21:52:25 +01:00
Languages
Rust 98.2%
Python 0.6%
AutoHotkey 0.5%
Nix 0.5%
Just 0.2%