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

Generated
+102
View File
@@ -140,6 +140,12 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "cfg_aliases"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
[[package]]
name = "chrono"
version = "0.4.44"
@@ -257,6 +263,17 @@ version = "0.8.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
[[package]]
name = "ctrlc"
version = "3.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e0b1fab2ae45819af2d0731d60f2afe17227ebb1a1538a236da84c93e9a60162"
dependencies = [
"dispatch2",
"nix",
"windows-sys 0.61.2",
]
[[package]]
name = "dirs"
version = "6.0.0"
@@ -290,6 +307,12 @@ dependencies = [
"objc2",
]
[[package]]
name = "dunce"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
[[package]]
name = "dyn-clone"
version = "1.0.20"
@@ -515,8 +538,10 @@ dependencies = [
"clap",
"color-eyre",
"crossbeam-channel",
"ctrlc",
"dirs",
"dispatch2",
"dunce",
"libc",
"objc2",
"objc2-av-foundation",
@@ -530,6 +555,7 @@ dependencies = [
"schemars",
"serde",
"serde_json_lenient",
"sysinfo",
"uds_windows",
"windows",
]
@@ -607,6 +633,27 @@ dependencies = [
"simd-adler32",
]
[[package]]
name = "nix"
version = "0.31.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5d6d0705320c1e6ba1d912b5e37cf18071b6c2e9b7fa8215a1e8a7651966f5d3"
dependencies = [
"bitflags",
"cfg-if",
"cfg_aliases",
"libc",
]
[[package]]
name = "ntapi"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c3b335231dfd352ffb0f8017f3b6027a4917f7df785ea2143d8af2adc66980ae"
dependencies = [
"winapi",
]
[[package]]
name = "num-traits"
version = "0.2.19"
@@ -730,6 +777,16 @@ dependencies = [
"objc2",
]
[[package]]
name = "objc2-io-kit"
version = "0.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15"
dependencies = [
"libc",
"objc2-core-foundation",
]
[[package]]
name = "objc2-io-surface"
version = "0.3.2"
@@ -1090,6 +1147,20 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "sysinfo"
version = "0.38.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92ab6a2f8bfe508deb3c6406578252e491d299cbbf3bc0529ecc3313aee4a52f"
dependencies = [
"libc",
"memchr",
"ntapi",
"objc2-core-foundation",
"objc2-io-kit",
"windows",
]
[[package]]
name = "tempfile"
version = "3.27.0"
@@ -1321,6 +1392,28 @@ dependencies = [
"semver",
]
[[package]]
name = "winapi"
version = "0.3.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
dependencies = [
"winapi-i686-pc-windows-gnu",
"winapi-x86_64-pc-windows-gnu",
]
[[package]]
name = "winapi-i686-pc-windows-gnu"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
[[package]]
name = "winapi-x86_64-pc-windows-gnu"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
[[package]]
name = "windows"
version = "0.62.2"
@@ -1449,6 +1542,15 @@ dependencies = [
"windows-targets 0.53.5",
]
[[package]]
name = "windows-sys"
version = "0.61.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
dependencies = [
"windows-link",
]
[[package]]
name = "windows-targets"
version = "0.52.6"
+12
View File
@@ -35,6 +35,18 @@ cargo install --path komorebi-recorder --locked
`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
```
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.
## How it fits together
Two things vary independently: the _host_ the recorder runs on (macOS or Windows) and the _flavor_ of komorebi it
+27
View File
@@ -32,9 +32,11 @@
"crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index",
"crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index",
"crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index",
"ctrlc 3.5.2 registry+https://github.com/rust-lang/crates.io-index",
"dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index",
"dirs-sys 0.5.0 registry+https://github.com/rust-lang/crates.io-index",
"dispatch2 0.3.1 registry+https://github.com/rust-lang/crates.io-index",
"dunce 1.0.5 registry+https://github.com/rust-lang/crates.io-index",
"dyn-clone 1.0.20 registry+https://github.com/rust-lang/crates.io-index",
"errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index",
"eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index",
@@ -52,12 +54,14 @@
"libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index",
"lock_api 0.4.14 registry+https://github.com/rust-lang/crates.io-index",
"miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index",
"ntapi 0.4.3 registry+https://github.com/rust-lang/crates.io-index",
"num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index",
"objc2-av-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-core-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-core-media 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-core-video 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-io-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-screen-capture-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"object 0.37.3 registry+https://github.com/rust-lang/crates.io-index",
"once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index",
@@ -87,6 +91,7 @@
"thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index",
"unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index",
"utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index",
"winapi 0.3.9 registry+https://github.com/rust-lang/crates.io-index",
"windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
@@ -100,6 +105,7 @@
"windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index",
"windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index",
"windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-sys 0.61.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
"windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index",
"windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
@@ -119,6 +125,12 @@
"ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"CC0-1.0",
[
"dunce 1.0.5 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"LicenseRef-Komorebi-2.0",
[
@@ -140,6 +152,7 @@
"bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index",
"block2 0.6.2 registry+https://github.com/rust-lang/crates.io-index",
"cfg-if 1.0.4 registry+https://github.com/rust-lang/crates.io-index",
"cfg_aliases 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
"chrono 0.4.44 registry+https://github.com/rust-lang/crates.io-index",
"clap 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
"clap_builder 4.6.0 registry+https://github.com/rust-lang/crates.io-index",
@@ -152,6 +165,7 @@
"crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index",
"crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index",
"crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index",
"ctrlc 3.5.2 registry+https://github.com/rust-lang/crates.io-index",
"dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index",
"dirs-sys 0.5.0 registry+https://github.com/rust-lang/crates.io-index",
"dispatch2 0.3.1 registry+https://github.com/rust-lang/crates.io-index",
@@ -174,6 +188,8 @@
"memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index",
"memoffset 0.9.1 registry+https://github.com/rust-lang/crates.io-index",
"miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index",
"nix 0.31.2 registry+https://github.com/rust-lang/crates.io-index",
"ntapi 0.4.3 registry+https://github.com/rust-lang/crates.io-index",
"num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index",
"objc2 0.6.4 registry+https://github.com/rust-lang/crates.io-index",
"objc2-av-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
@@ -183,6 +199,7 @@
"objc2-core-video 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-encode 4.1.0 registry+https://github.com/rust-lang/crates.io-index",
"objc2-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-io-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-screen-capture-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"object 0.37.3 registry+https://github.com/rust-lang/crates.io-index",
"once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index",
@@ -212,6 +229,7 @@
"smallvec 1.15.1 registry+https://github.com/rust-lang/crates.io-index",
"strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index",
"syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index",
"sysinfo 0.38.4 registry+https://github.com/rust-lang/crates.io-index",
"tempfile 3.27.0 registry+https://github.com/rust-lang/crates.io-index",
"terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index",
"thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index",
@@ -222,6 +240,7 @@
"uds_windows 1.2.1 registry+https://github.com/rust-lang/crates.io-index",
"unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index",
"utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index",
"winapi 0.3.9 registry+https://github.com/rust-lang/crates.io-index",
"windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index",
@@ -235,6 +254,7 @@
"windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index",
"windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index",
"windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-sys 0.61.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
"windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index",
"windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
@@ -243,6 +263,12 @@
"zmij 1.0.21 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"MIT-0",
[
"dunce 1.0.5 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"MPL-2.0",
[
@@ -271,6 +297,7 @@
"objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-core-media 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-core-video 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-io-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"objc2-screen-capture-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index"
]
]
+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.
+3
View File
@@ -10,12 +10,15 @@ chrono = { workspace = true }
clap = { workspace = true }
color-eyre = { workspace = true }
crossbeam-channel = { workspace = true }
ctrlc = { version = "3", features = ["termination"] }
dirs = { workspace = true }
dunce = { workspace = true }
parking_lot = { workspace = true }
png = "0.18"
schemars = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
sysinfo = { workspace = true }
[target.'cfg(target_os = "macos")'.dependencies]
block2 = "0.6"
+239
View File
@@ -0,0 +1,239 @@
//! Keeping file access inside the session directory.
//!
//! Session files name other session files (a timeline entry's `file`, an annotation's log
//! reference), and sessions are handed between people and agents. Nothing read from a session may
//! therefore be allowed to point outside it: absolute paths, `..`, and symlinks that lead out are
//! all refused.
//!
//! [`SessionPath`] is the checked session directory, and [`SessionPath::resolve`] is the one way the
//! analysis turns a name from inside a session into a path. [`is_plain_relative`] is the lexical
//! check it starts with. Failures are errors that carry an exit kind, `Usage` for a name that
//! points out and `NotFound` for a directory that is not a session, so a command that hits one
//! fails with the matching exit code (see the `envelope` module).
//!
//! # What is guaranteed, and by what
//!
//! | Rule | Enforced by | Proof | Escape hatch |
//! |---|---|---|---|
//! | A path from [`SessionPath::resolve`] is a plain relative path under the session root | runtime error: `Usage` | `escapes_are_refused` | none |
//! | An existing path whose real location is outside the session is refused, symlinks included | runtime error: `Usage` | `a_symlink_that_leads_out_is_refused` (Unix only) | none |
//! | A path that does not exist yet is checked lexically only | not guaranteed: the symlink check needs the path to exist | none | none |
//! | A [`SessionPath`] is a directory with a manifest | runtime error: `NotFound`, in [`SessionPath::new`] | `a_directory_without_a_manifest_is_not_a_session` | none |
//! | A file whose name is read from the contents of a session is opened through [`SessionPath::resolve`] | convention only: files with a fixed name, such as `events.jsonl`, are opened without it | none | none |
use super::envelope;
use crate::session::MANIFEST_FILE;
use color_eyre::eyre;
use std::path::Component;
use std::path::Path;
use std::path::PathBuf;
/// Returns whether `relative` is a non-empty relative path made only of ordinary names: no `..`,
/// no `.`, no root or drive prefix.
///
/// This looks at the text only. It does not look at the file system, so it cannot see a symlink;
/// [`SessionPath::resolve`] does that.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::guard::is_plain_relative;
///
/// assert!(is_plain_relative("events.jsonl"));
/// assert!(is_plain_relative("oslog/apps/x.jsonl"));
///
/// assert!(!is_plain_relative(""));
/// assert!(!is_plain_relative("."));
/// assert!(!is_plain_relative("../x"));
/// assert!(!is_plain_relative("a/../../x"));
/// assert!(!is_plain_relative("/etc/passwd"));
/// ```
#[must_use]
pub fn is_plain_relative(relative: &str) -> bool {
!relative.is_empty()
&& Path::new(relative)
.components()
.all(|component| matches!(component, Component::Normal(_)))
}
/// A session directory known to be one, with its real (symlink-free) location.
///
/// It is constructed only by [`SessionPath::new`], which checks that the directory has a manifest,
/// so a value of this type is guaranteed to name a directory that held one when it was made. Whether
/// the directory still does is not checked again. Files are reached through
/// [`SessionPath::resolve`], which refuses any name that points outside it.
#[derive(Debug, Clone)]
pub struct SessionPath {
root: PathBuf,
}
impl SessionPath {
/// Returns the checked session directory `dir`, with symlinks resolved.
///
/// The directory is made canonical with `dunce`, which, unlike [`Path::canonicalize`], does
/// not give a `\\?\` path on Windows, so paths shown to a reader or an agent can be copied.
///
/// # Errors
///
/// Both cases are a `NotFound` error:
///
/// - `dir` cannot be opened (it does not exist or cannot be made canonical):
/// `cannot open <dir>: <error>`;
/// - `dir` has no manifest file (`session.json`), so it is not a recording session:
/// `<dir> is not a recording session (no session.json)`.
///
/// # Example
///
/// Reading a session needs a session directory on disk, so this example is only compiled.
/// It is covered by `a_directory_without_a_manifest_is_not_a_session` and
/// `plain_relative_paths_resolve_inside_the_session` in this module's tests.
///
/// ```rust,no_run
/// use komorebi_recorder::analysis::guard::SessionPath;
/// use std::path::Path;
///
/// let session = SessionPath::new(Path::new("/path/to/session"))?;
/// println!("{}", session.root().display());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn new(dir: &Path) -> eyre::Result<Self> {
// not `Path::canonicalize`: on Windows that returns a `\\?\` path, which would then show up
// in every path this tool prints for an agent to copy
let root = dunce::canonicalize(dir).map_err(|error| {
envelope::not_found(format!("cannot open {}: {error}", dir.display()))
})?;
if !root.join(MANIFEST_FILE).is_file() {
return Err(envelope::not_found(format!(
"{} is not a recording session (no {MANIFEST_FILE})",
dir.display()
)));
}
Ok(Self { root })
}
/// Returns the session directory: absolute, with symlinks resolved.
#[must_use]
pub fn root(&self) -> &Path {
&self.root
}
/// Returns the path of `relative` inside the session. It must be a plain relative path (see
/// [`is_plain_relative`]) and, if it exists, must really be inside the session once symlinks
/// are followed.
///
/// The returned path is `root().join(relative)`: it is not canonicalized, and the file it names
/// is not opened or required to exist.
///
/// # Errors
///
/// Both cases are a `Usage` error:
///
/// - `relative` is not a plain relative path (it is empty, absolute, or has a `..`, a `.` or
/// a drive prefix): `'<relative>' is not a path inside the session`;
/// - `relative` exists and, with every symlink followed, is outside the session:
/// `'<relative>' leads outside the session`.
///
/// A path that does not exist passes the second check, because there is nothing to follow. If
/// one of its parent directories is a symlink that leads out, the path is still returned.
///
/// # Example
///
/// Covered by `escapes_are_refused` and `a_symlink_that_leads_out_is_refused` in this module's
/// tests; the example needs a session directory on disk, so it is only compiled.
///
/// ```rust,no_run
/// use komorebi_recorder::analysis::guard::SessionPath;
/// use std::path::Path;
///
/// let session = SessionPath::new(Path::new("/path/to/session"))?;
/// let events = session.resolve("events.jsonl")?;
/// assert!(events.starts_with(session.root()));
/// assert!(session.resolve("../elsewhere").is_err());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn resolve(&self, relative: &str) -> eyre::Result<PathBuf> {
let path = Path::new(relative);
if !is_plain_relative(relative) {
return Err(envelope::usage(format!(
"'{relative}' is not a path inside the session"
)));
}
let joined = self.root.join(path);
if let Ok(real) = dunce::canonicalize(&joined)
&& !real.starts_with(&self.root)
{
return Err(envelope::usage(format!(
"'{relative}' leads outside the session"
)));
}
Ok(joined)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn temp(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!(
"komorebi-recorder-guard-{name}-{}",
std::process::id()
));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("dir");
dir
}
#[test]
fn a_directory_without_a_manifest_is_not_a_session() {
let dir = temp("empty");
let error = SessionPath::new(&dir).expect_err("not a session");
assert_eq!(envelope::exit_kind(&error), envelope::ExitKind::NotFound);
let missing = SessionPath::new(&dir.join("nope")).expect_err("missing");
assert_eq!(envelope::exit_kind(&missing), envelope::ExitKind::NotFound);
}
#[test]
fn plain_relative_paths_resolve_inside_the_session() {
let dir = temp("plain");
std::fs::write(dir.join(MANIFEST_FILE), "{}").expect("manifest");
let session = SessionPath::new(&dir).expect("session");
let path = session.resolve("oslog/apps/x.jsonl").expect("resolve");
assert!(path.starts_with(session.root()));
assert!(path.ends_with("oslog/apps/x.jsonl"));
}
#[test]
fn escapes_are_refused() {
let dir = temp("escape");
std::fs::write(dir.join(MANIFEST_FILE), "{}").expect("manifest");
let session = SessionPath::new(&dir).expect("session");
for bad in ["../x", "a/../../x", "/etc/passwd", "", "."] {
assert!(session.resolve(bad).is_err(), "{bad:?} should be refused");
}
}
#[cfg(unix)]
#[test]
fn a_symlink_that_leads_out_is_refused() {
let outside = temp("outside");
std::fs::write(outside.join("secret.txt"), "x").expect("secret");
let dir = temp("symlink");
std::fs::write(dir.join(MANIFEST_FILE), "{}").expect("manifest");
std::os::unix::fs::symlink(&outside, dir.join("link")).expect("symlink");
let session = SessionPath::new(&dir).expect("session");
assert!(session.resolve("link/secret.txt").is_err());
assert!(session.resolve("link").is_err());
// a symlink that stays inside is fine
std::fs::create_dir_all(dir.join("real")).expect("real");
std::os::unix::fs::symlink(dir.join("real"), dir.join("alias")).expect("alias");
assert!(session.resolve("alias").is_ok());
}
}
+4 -1
View File
@@ -3,10 +3,13 @@
//! Everything here reads a session directory and produces plain serializable values, so the same
//! answers serve the command line and anything else that wants them.
//! This module holds the parts every command shares: the JSON envelope and exit codes
//! ([`envelope`]) and how an event or a log line is named ([`ids`]).
//! ([`envelope`]), how a point in time is named ([`timespec`], [`ids`]) and the guard that keeps
//! file access inside the session ([`guard`]).
pub mod classify;
pub mod envelope;
pub mod events;
pub mod flavor;
pub mod guard;
pub mod ids;
pub mod timespec;
+602
View File
@@ -0,0 +1,602 @@
//! Naming a moment: every command that takes a time takes any of these.
//!
//! | form | meaning |
//! |---|---|
//! | `12.5`, `1:02.5`, `-1.5` | video time, see [`crate::timecode`] |
//! | `wall:2026-10-26T20:00:00Z` | a UTC time (RFC 3339) |
//! | `mach:123456789` | the recorder's master clock, in nanoseconds |
//! | `event:12`, `log:345`, `incident:2` | when that record happened |
//! | `bug:a-3f9c1e02`, `bug:a-3f9c1e02.start`, `bug:a-3f9c1e02.end` | an annotation's start or end |
//!
//! Any of them can be followed by `+3s` or `-500ms` to move it. The units are `ms`, `s` and `m`
//! (minutes), and an offset without one (`12.5+3`) is not an offset. An event or annotation can be
//! followed by `.start` or `.end` first (`bug:a-3f9c1e02.end+2s`); the default is the start. The
//! suffix is accepted after any item reference, but only an event and an annotation have two edges:
//! on a log line or an incident it changes nothing.
//!
//! Resolving a name never guesses: an unknown event, a log line without a timestamp or an
//! annotation that does not exist is an error with the "not found" exit code. The one exception is
//! an annotation whose end was never set, which ends when the recording did.
//!
//! # How a name is read
//!
//! A name is read in two steps, and both are in this module. [`TimeSpec`]'s [`FromStr`] splits off
//! the offset and reads the rest as an [`Anchor`], with no session needed: this checks the syntax
//! only. [`TimeSpec::resolve`] then turns the anchor into a moment on the master clock with the
//! session's [`Manifest`] (for video time and wall time) and a [`Lookup`] (for the things a name
//! can point at), and adds the offset. The result is a [`Resolved`], on both the master clock and
//! the video timeline.
//!
//! The master clock is the host's master monotonic clock, in nanoseconds; fields named
//! `*_mach_ns` are readings of it (`mach_` is a historical spelling, and the manifest's
//! `host.clock` says `mach`, `qpc` or `std`).
//!
//! # Example
//!
//! ```rust
//! use komorebi_recorder::analysis::ids::ItemRef;
//! use komorebi_recorder::analysis::timespec::{Anchor, Edge, TimeSpec};
//!
//! // a video time, moved three seconds later
//! let spec: TimeSpec = "1:02.5+3s".parse()?;
//! assert_eq!(spec.anchor, Anchor::Video(62.5));
//! assert_eq!(spec.offset_s, 3.0);
//!
//! // when komorebi finished handling event 12, half a second before
//! let spec: TimeSpec = "event:12.end-500ms".parse()?;
//! assert_eq!(
//! spec.anchor,
//! Anchor::Item { item: ItemRef::Event(12), edge: Edge::End }
//! );
//! assert_eq!(spec.offset_s, -0.5);
//!
//! // a UTC time. The `+01:00` zone is not an offset: it does not end in a unit.
//! let spec: TimeSpec = "wall:2026-10-26T20:00:00+01:00".parse()?;
//! assert_eq!(spec.offset_s, 0.0);
//!
//! // nonsense is an error that describes what was expected
//! let error = "soon".parse::<TimeSpec>().unwrap_err();
//! assert_eq!(error.to_string(), "invalid timecode 'soon'");
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
use super::envelope;
use super::ids::ItemRef;
use super::ids::is_annotation_id;
use crate::clock::ClockMap;
use crate::session::Manifest;
use crate::timecode;
use chrono::DateTime;
use chrono::Utc;
use color_eyre::eyre;
use std::str::FromStr;
/// Which end of a span a name means: an event or an annotation has a start and an end.
///
/// The default is [`Edge::Start`], which is what a name with no `.start` or `.end` means.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Edge {
/// The start: for an event, when komorebi began handling it, where the log has it; for an
/// annotation, its start.
#[default]
Start,
/// The end: for an event, when the notification was received; for an annotation, its end, or
/// the end of the recording if it has none.
End,
}
/// The point in the session a [`TimeSpec`] starts from, before its offset is added.
#[derive(Debug, Clone, PartialEq)]
pub enum Anchor {
/// A time on the video timeline, in seconds: `12.5`. It is negative before the video's `t = 0`.
Video(f64),
/// A UTC time (`wall:...`), mapped to the master clock through the session's clock anchors.
Wall(DateTime<Utc>),
/// A reading of the master clock in nanoseconds (`mach:...`).
Mach(u64),
/// When a recorded item happened: an event, a log line, an incident or an annotation. `edge`
/// picks the start or the end of an event or an annotation.
Item {
/// The thing pointed at.
item: ItemRef,
/// Which end of it.
edge: Edge,
},
}
/// A parsed time argument: an [`Anchor`] and an offset to move it by.
///
/// Parse one from text with [`str::parse`], which needs no session, and turn it into a moment with
/// [`TimeSpec::resolve`]. The module documentation has the forms a time can take.
///
/// # Errors
///
/// Parsing fails with a usage error (the exit kind `Usage` of the `envelope` module), whose
/// message describes what was expected, when:
///
/// - the text is empty or only whitespace: `an empty time`;
/// - a `wall:` time is not RFC 3339: `'<text>': expected an RFC 3339 time like
/// wall:2026-10-26T19:43:35.062613Z`;
/// - a `mach:` time is not a whole number of nanoseconds: `'<text>': mach: takes nanoseconds, e.g.
/// mach:123456`;
/// - the text starts like an item reference (`event:`, `log:`, `incident:`, `ann:`, `bug:`,
/// `note:`, `finding:`) or is an annotation id, and does not parse as one: see [`ItemRef`];
/// - anything else is not a video timecode: `invalid timecode '<text>'`, where the text is what
/// remains after an offset was split off (see [`timecode::parse`]).
///
/// Nothing about the session is checked here: `event:99999` parses.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::timespec::{Anchor, TimeSpec};
///
/// let spec: TimeSpec = "mach:5-9s".parse()?;
/// assert_eq!(spec.anchor, Anchor::Mach(5));
/// assert_eq!(spec.offset_s, -9.0);
///
/// // an offset needs a unit, so this is not an offset and not a timecode
/// assert!("12.5+3".parse::<TimeSpec>().is_err());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[derive(Debug, Clone, PartialEq)]
pub struct TimeSpec {
/// Where the name points, before the offset.
pub anchor: Anchor,
/// Added to the anchor, in seconds; negative to move earlier. 0 when the name has no offset.
pub offset_s: f64,
}
/// A moment on both clocks: what a [`TimeSpec`] resolves to.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Resolved {
/// The moment on the host's master monotonic clock, in nanoseconds (`mach_` is a historical
/// spelling). It is never negative: a moment before the clock's zero is 0.
pub mach_ns: u64,
/// The same moment on the video timeline, in seconds since the video's `t = 0`. Negative before
/// the video started.
pub video_s: f64,
}
/// The lookups a [`TimeSpec`] needs from a session: when an event, a log line, an incident or an
/// annotation happened.
///
/// [`TimeSpec::resolve`] calls it for an [`Anchor::Item`]. It is implemented over the real files by
/// the analysis facade (`Analysis`) and by fakes in tests, so a name can be resolved without a
/// session on disk. Every method returns nanoseconds on the master clock, and has no default: an
/// implementor writes all four.
///
/// An item that does not exist, or has no time, should be a not-found error (the `NotFound` exit
/// kind of the `envelope` module), which [`TimeSpec::resolve`] passes on, so that a name never
/// resolves to a guess. Nothing enforces that for an implementor.
///
/// # Example
///
/// A lookup with one event and one annotation, and a manifest whose video starts at 1 second
/// on the master clock:
///
/// ```rust
/// use color_eyre::eyre;
/// use komorebi_recorder::analysis::timespec::{Edge, Lookup, TimeSpec};
/// use komorebi_recorder::clock::Anchor;
/// use komorebi_recorder::session::{Manifest, Moment};
///
/// struct Known;
///
/// impl Lookup for Known {
/// fn event_mach_ns(&self, seq: u64, edge: Edge) -> eyre::Result<u64> {
/// match (seq, edge) {
/// (1, Edge::Start) => Ok(4_000_000_000),
/// (1, Edge::End) => Ok(4_500_000_000),
/// _ => eyre::bail!("no event #{seq}"),
/// }
/// }
/// fn log_mach_ns(&self, line: u64) -> eyre::Result<u64> {
/// eyre::bail!("no log line {line}")
/// }
/// fn incident_mach_ns(&self, number: u64) -> eyre::Result<u64> {
/// eyre::bail!("no incident {number}")
/// }
/// fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option<u64>)> {
/// match id {
/// "a-00000001" => Ok((2_000_000_000, None)), // never closed
/// _ => eyre::bail!("no annotation {id}"),
/// }
/// }
/// }
///
/// let start = Moment { mach_ns: 1_000_000_000, wall_us: 1_000_000 };
/// let mut manifest = Manifest::new(
/// start,
/// vec![Anchor { mach_ns: 1_000_000_000, wall_us: 1_000_000 }],
/// );
/// manifest.video_t0_mach_ns = Some(1_000_000_000);
/// manifest.stop = Some(Moment { mach_ns: 10_000_000_000, wall_us: 10_000_000 });
///
/// let resolve = |text: &str| text.parse::<TimeSpec>()?.resolve(&manifest, &Known);
///
/// // the end of event 1 is 4.5 s on the master clock, which is 3.5 s into the video
/// let resolved = resolve("event:1.end")?;
/// assert_eq!(resolved.mach_ns, 4_500_000_000);
/// assert_eq!(resolved.video_s, 3.5);
///
/// // an annotation that was never closed ends when the recording did
/// assert_eq!(resolve("bug:a-00000001.end")?.mach_ns, 10_000_000_000);
///
/// // an item the lookup does not know is an error, not a guess
/// assert!(resolve("event:2").is_err());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub trait Lookup {
/// Returns when event `seq` happened. [`Edge::Start`] is when komorebi began handling it where
/// known, [`Edge::End`] when the notification was received.
///
/// # Errors
///
/// Returns an error if the session has no such event.
fn event_mach_ns(&self, seq: u64, edge: Edge) -> eyre::Result<u64>;
/// Returns when line `line` of komorebi's recorded log was written. Lines are numbered from 1.
///
/// # Errors
///
/// Returns an error if the log has no such line, or the line has no time.
fn log_mach_ns(&self, line: u64) -> eyre::Result<u64>;
/// Returns when incident `number` of the recorder's incident log happened. Incidents are
/// numbered from 1.
///
/// # Errors
///
/// Returns an error if the session recorded no incidents, or has no such one.
fn incident_mach_ns(&self, number: u64) -> eyre::Result<u64>;
/// Returns an annotation's `(start, end)`; the end is `None` when it has none.
///
/// # Errors
///
/// Returns an error if the session has no annotation with this id.
fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option<u64>)>;
}
impl FromStr for TimeSpec {
type Err = eyre::Report;
fn from_str(input: &str) -> Result<Self, Self::Err> {
let trimmed = input.trim();
if trimmed.is_empty() {
return Err(envelope::usage("an empty time"));
}
let (head, offset_s) = split_offset(trimmed);
Ok(Self {
anchor: parse_anchor(head, input)?,
offset_s,
})
}
}
/// Split a trailing `+3s` / `-500ms` off. The tail must end in a unit, so a `+02:00` time zone or
/// a `-` inside an id is never taken for an offset.
fn split_offset(text: &str) -> (&str, f64) {
for (index, character) in text.char_indices().rev() {
if index == 0 || (character != '+' && character != '-') {
continue;
}
let tail = &text[index + 1..];
if !(tail.ends_with('s') || tail.ends_with('m')) {
continue;
}
if let Ok(span) = timecode::parse_span(tail) {
let signed = if character == '-' { -span } else { span };
return (&text[..index], signed);
}
}
(text, 0.0)
}
fn parse_anchor(head: &str, original: &str) -> eyre::Result<Anchor> {
if let Some(rest) = head.strip_prefix("wall:") {
let time = DateTime::parse_from_rfc3339(rest).map_err(|_| {
envelope::usage(format!(
"'{original}': expected an RFC 3339 time like wall:2026-10-26T19:43:35.062613Z"
))
})?;
return Ok(Anchor::Wall(time.with_timezone(&Utc)));
}
if let Some(rest) = head.strip_prefix("mach:") {
let ns = rest.parse().map_err(|_| {
envelope::usage(format!(
"'{original}': mach: takes nanoseconds, e.g. mach:123456"
))
})?;
return Ok(Anchor::Mach(ns));
}
let (body, edge) = match head
.strip_suffix(".start")
.map(|body| (body, Edge::Start))
.or_else(|| head.strip_suffix(".end").map(|body| (body, Edge::End)))
{
Some((body, edge)) => (body, edge),
None => (head, Edge::Start),
};
if ItemRef::has_prefix(body) || is_annotation_id(body) {
return Ok(Anchor::Item {
item: body.parse()?,
edge,
});
}
timecode::parse(head)
.map(Anchor::Video)
.map_err(|error| envelope::usage(format!("{error}")))
}
impl TimeSpec {
/// Returns the moment this name points at in `manifest`'s session, on the master clock and on
/// the video timeline.
///
/// The anchor is turned into a reading of the master clock (video time through the manifest's
/// video `t = 0`, wall time through its clock anchors, an item through `lookup`), the offset is
/// added, and a result below 0 becomes 0.
///
/// # Errors
///
/// - The `Unusable` exit kind, `the session has no clock anchors`, if the anchor is a `wall:`
/// time and the manifest has no clock anchors to map it with.
/// - Whatever `lookup` returns for an [`Anchor::Item`]: an event, log line, incident or
/// annotation that does not exist is a not-found error (see [`Lookup`]).
///
/// # Example
///
/// A moment before the clock started clamps to 0 instead of failing. See [`Lookup`] for an
/// example with items.
///
/// ```rust
/// use color_eyre::eyre;
/// use komorebi_recorder::analysis::timespec::{Edge, Lookup, TimeSpec};
/// use komorebi_recorder::session::{Manifest, Moment};
///
/// struct Nothing;
///
/// impl Lookup for Nothing {
/// fn event_mach_ns(&self, seq: u64, _: Edge) -> eyre::Result<u64> {
/// eyre::bail!("no event #{seq}")
/// }
/// fn log_mach_ns(&self, line: u64) -> eyre::Result<u64> {
/// eyre::bail!("no log line {line}")
/// }
/// fn incident_mach_ns(&self, number: u64) -> eyre::Result<u64> {
/// eyre::bail!("no incident {number}")
/// }
/// fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option<u64>)> {
/// eyre::bail!("no annotation {id}")
/// }
/// }
///
/// let manifest = Manifest::new(Moment { mach_ns: 0, wall_us: 0 }, Vec::new());
///
/// let resolved = "mach:5-9s".parse::<TimeSpec>()?.resolve(&manifest, &Nothing)?;
/// assert_eq!(resolved.mach_ns, 0);
///
/// // a wall time needs clock anchors to be mapped with, and this manifest has none
/// let error = "wall:2026-10-26T20:00:00Z"
/// .parse::<TimeSpec>()?
/// .resolve(&manifest, &Nothing)
/// .unwrap_err();
/// assert_eq!(error.to_string(), "the session has no clock anchors");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn resolve(&self, manifest: &Manifest, lookup: &dyn Lookup) -> eyre::Result<Resolved> {
let base_ns = match &self.anchor {
Anchor::Video(seconds) => manifest.mach_at_video_seconds(*seconds),
Anchor::Mach(ns) => *ns,
Anchor::Wall(time) => ClockMap::new(manifest.anchors.clone())
.wall_to_mach(time.timestamp_micros())
.ok_or_else(|| envelope::unusable("the session has no clock anchors"))?,
Anchor::Item { item, edge } => match item {
ItemRef::Event(seq) => lookup.event_mach_ns(*seq, *edge)?,
ItemRef::Log(line) => lookup.log_mach_ns(*line)?,
ItemRef::Incident(number) => lookup.incident_mach_ns(*number)?,
ItemRef::Annotation(id) => {
let (start, end) = lookup.annotation_span(id)?;
match edge {
Edge::Start => start,
// an annotation that was never closed lasts until the recording ended
Edge::End => end.unwrap_or_else(|| session_end_ns(manifest)),
}
}
},
};
let shifted = i128::from(base_ns) + (self.offset_s * 1e9).round() as i128;
let mach_ns = u64::try_from(shifted.max(0)).unwrap_or(u64::MAX);
Ok(Resolved {
mach_ns,
video_s: manifest.video_seconds(mach_ns),
})
}
}
/// Returns when the recording ended on the master clock, in nanoseconds.
///
/// That is the manifest's `stop`, else when video capture ended, else when the recording started.
/// A recording that has not stopped and has no video therefore ends where it began.
#[must_use]
pub fn session_end_ns(manifest: &Manifest) -> u64 {
manifest
.stop
.map(|stop| stop.mach_ns)
.or(manifest.video_end_mach_ns)
.unwrap_or(manifest.start.mach_ns)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::clock::Anchor as ClockAnchor;
use crate::session::Moment;
struct Fake;
impl Lookup for Fake {
fn event_mach_ns(&self, seq: u64, edge: Edge) -> eyre::Result<u64> {
match (seq, edge) {
(1, Edge::Start) => Ok(4_000_000_000),
(1, Edge::End) => Ok(4_500_000_000),
_ => Err(envelope::not_found(format!("no event {seq}"))),
}
}
fn log_mach_ns(&self, line: u64) -> eyre::Result<u64> {
Ok(1_000_000_000 * line)
}
fn incident_mach_ns(&self, number: u64) -> eyre::Result<u64> {
Err(envelope::not_found(format!("no incident {number}")))
}
fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option<u64>)> {
match id {
"a-00000001" => Ok((2_000_000_000, Some(3_000_000_000))),
"a-00000002" => Ok((2_000_000_000, None)),
_ => Err(envelope::not_found(format!("no annotation {id}"))),
}
}
}
/// Video t=0 is mach 1s; wall `1_000_000us` is mach 1s; the session ended at mach 10s.
fn manifest() -> Manifest {
let mut manifest = Manifest::new(
Moment {
mach_ns: 1_000_000_000,
wall_us: 1_000_000,
},
vec![ClockAnchor {
mach_ns: 1_000_000_000,
wall_us: 1_000_000,
}],
);
manifest.video_t0_mach_ns = Some(1_000_000_000);
manifest.stop = Some(Moment {
mach_ns: 10_000_000_000,
wall_us: 10_000_000,
});
manifest
}
fn resolve(text: &str) -> eyre::Result<Resolved> {
text.parse::<TimeSpec>()?.resolve(&manifest(), &Fake)
}
fn close(a: f64, b: f64) -> bool {
(a - b).abs() < 1e-6
}
#[test]
fn video_times_resolve_against_the_manifest() {
let resolved = resolve("2.5").expect("resolve");
assert_eq!(resolved.mach_ns, 3_500_000_000);
assert!(close(resolved.video_s, 2.5));
assert!(close(resolve("0:02.5").expect("clock").video_s, 2.5));
}
#[test]
fn offsets_move_any_anchor() {
assert!(close(resolve("2.5+1s").expect("plus").video_s, 3.5));
assert!(close(resolve("2.5-500ms").expect("minus").video_s, 2.0));
assert!(close(
resolve("event:1.end-1s").expect("event").video_s,
2.5
));
// video t=0 is mach 1s here, so half a second before it is still on the clock
assert!(close(
resolve("-0.5").expect("negative video").video_s,
-0.5
));
}
#[test]
fn mach_and_wall_times_resolve() {
assert!(close(
resolve("mach:3000000000").expect("mach").video_s,
2.0
));
// wall 5s after the epoch is 4s after the anchor at wall 1s: mach 5s, video 4s
let wall = resolve("wall:1970-01-01T00:00:05Z").expect("wall");
assert!(close(wall.video_s, 4.0));
// a numeric zone is not an offset
let zoned = resolve("wall:1970-01-01T01:00:05+01:00").expect("zoned");
assert!(close(zoned.video_s, 4.0));
let moved = resolve("wall:1970-01-01T00:00:05Z+2s").expect("moved");
assert!(close(moved.video_s, 6.0));
}
#[test]
fn items_resolve_through_the_lookup() {
assert!(close(resolve("event:1").expect("start").video_s, 3.0));
assert!(close(resolve("event:1.end").expect("end").video_s, 3.5));
assert!(close(resolve("log:7").expect("log").video_s, 6.0));
assert!(close(resolve("bug:a-00000001").expect("bug").video_s, 1.0));
assert!(close(
resolve("bug:a-00000001.end").expect("bug end").video_s,
2.0
));
assert!(close(
resolve("a-00000001.end+1s").expect("bare id").video_s,
3.0
));
}
#[test]
fn an_unclosed_annotation_ends_with_the_session() {
let end = resolve("bug:a-00000002.end").expect("open-ended");
assert_eq!(end.mach_ns, 10_000_000_000);
}
#[test]
fn missing_things_are_not_found_not_guesses() {
for text in ["event:99", "incident:1", "bug:a-0000ffff"] {
let error = resolve(text).expect_err(text);
assert_eq!(
envelope::exit_kind(&error),
envelope::ExitKind::NotFound,
"{text}"
);
}
}
#[test]
fn nonsense_is_a_usage_error() {
for text in [
"",
"soon",
"wall:yesterday",
"mach:x",
"event:one",
"1:2:3:4",
] {
let error = text
.parse::<TimeSpec>()
.map(|_| ())
.expect_err(&format!("{text:?} should not parse"));
assert_eq!(
envelope::exit_kind(&error),
envelope::ExitKind::Usage,
"{text:?}"
);
}
}
#[test]
fn times_before_the_clock_started_clamp_to_zero() {
let resolved = resolve("mach:5-9s").expect("clamped");
assert_eq!(resolved.mach_ns, 0);
}
}
File diff suppressed because it is too large. Load diff
+139
View File
@@ -0,0 +1,139 @@
//! The command line: the table of commands ([`Command`]) and the commands that need no module of
//! their own.
//!
//! Each family of commands is implemented next to its arguments in a module of this one, and every
//! command is run through [`execute`], which turns its outcome into the process's exit status.
//! `--json` on a command also decides how a failure is reported (see [`Command::wants_json`]).
mod record;
use crate::session::Session;
use clap::Args;
use clap::Parser;
use clap::Subcommand;
use color_eyre::eyre;
use std::path::PathBuf;
pub use record::RecordArgs;
/// The command line of `komorebi-recorder`.
#[derive(Parser)]
#[command(
author,
version,
about = "Record the screen, komorebi's logs and events, and the OS trace in lockstep",
long_about = "Record the screen together with komorebi's log, komorebi's subscriber events and \
the OS trace (the unified log on macOS, WinEvents and the Event Log on Windows), \
all on one clock, into a session directory. \
Then ask what was happening at any second of the video, or where in the video any \
log line or event is.\n\n\
Run with no subcommand to open the recorder window."
)]
pub struct Opts {
/// The command to run.
#[command(subcommand)]
pub command: Option<Command>,
}
/// What `komorebi-recorder` was asked to do.
#[derive(Subcommand)]
pub enum Command {
/// Record without a window; Ctrl-C (or --duration) stops and finalizes the session
Record(RecordArgs),
/// List the displays that can be recorded
Displays,
/// Rebuild a session's timeline from its raw files, recovering it first if the recorder died
Reindex(ReindexArgs),
}
/// The arguments of `reindex`.
#[derive(Args, Debug)]
pub struct ReindexArgs {
/// Session directory
pub session: PathBuf,
}
impl Command {
/// Whether this command was asked for JSON, which also decides how a failure is reported.
#[must_use]
pub fn wants_json(&self) -> bool {
let _ = self;
false
}
}
/// Runs `command` and turns its outcome into the process exit status.
///
/// The status is 0, or the code that says what kind of failure it was (see
/// [`crate::analysis::envelope::ExitKind`]). With `--json` a failure is also printed as an envelope
/// so that a caller parsing stdout still gets an answer.
pub fn execute(command: Command) -> std::process::ExitCode {
let json = command.wants_json();
match run(command) {
Ok(()) => std::process::ExitCode::SUCCESS,
Err(error) => {
let kind = crate::analysis::envelope::exit_kind(&error);
if json {
let envelope = crate::analysis::envelope::Envelope::failed(&error);
if let Ok(text) = serde_json::to_string_pretty(&envelope) {
println!("{text}");
}
}
eprintln!("Error: {error:?}");
std::process::ExitCode::from(kind.code())
}
}
}
/// Runs `command`.
///
/// # Errors
///
/// Returns whatever error the command fails with; [`execute`] turns it into an exit status.
pub fn run(command: Command) -> eyre::Result<()> {
match command {
Command::Record(args) => record::record(&args),
Command::Displays => record::displays(),
Command::Reindex(args) => reindex(&args),
}
}
/// What both binaries (`komorebi-recorder` and, on Windows, the no-console
/// `komorebi-recorder-gui`) do: read the command line and run it.
/// No command prints the usage.
///
/// # Errors
///
/// Returns an error if the error report handler cannot be installed. A failing command is not an
/// error here: it is the exit status that is returned.
pub fn main() -> eyre::Result<std::process::ExitCode> {
use clap::Parser;
color_eyre::install()?;
crate::platform::init();
let opts = Opts::parse();
let Some(command) = opts.command else {
use clap::CommandFactory;
Opts::command().print_help()?;
return Ok(std::process::ExitCode::from(2));
};
Ok(execute(command))
}
fn reindex(args: &ReindexArgs) -> eyre::Result<()> {
let session = Session::open(&args.session)?;
let reindexed = crate::recovery::reindex_session(&session)?;
for note in &reindexed.recovered {
println!("recovered: {note}");
}
println!("indexed {} records", reindexed.stats.entries);
for (source, count) in &reindexed.stats.by_source {
println!(" {source}: {count}");
}
Ok(())
}
+266
View File
@@ -0,0 +1,266 @@
//! `record`, `gui` and `displays`: the arguments of a recording and the headless recorder.
//!
//! [`RecordArgs`] is the one set of options for both ways of recording: `record` runs without a
//! window and `gui` opens the recorder window with the same options as its starting settings.
//! [`RecordArgs::to_options`] turns them into the [`RecordOptions`] that [`recorder::record`] takes.
//!
//! `record` installs a Ctrl-C handler that asks the recorder to stop (`--duration` stops it too),
//! runs the recorder on a thread of its own, and meanwhile prints to standard error: the
//! session directory and any start-up warnings once, then a line of counters (time, frames, bytes
//! of komorebi's log, events, OS trace events) that is rewritten every half second. When the
//! recorder has finished it prints the session directory, the length of the video, what was
//! recorded, any warnings and how to query the session. The recorder itself, and what it keeps
//! recording through (monitors coming and going, sleep, lock), is in [`crate::recorder`]. `displays`
//! lists the displays that can be recorded, one a line: the id (what `--display` takes), the size in
//! points and the position.
//!
//! The commands need the outside world (a screen, and komorebi unless `--no-komorebi`), so they have
//! no example; [`RecordArgs::to_options`] does.
use crate::capture::CaptureConfig;
use crate::capture::Codec;
use crate::platform::capture;
use crate::recorder;
use crate::recorder::AppsMode;
use crate::recorder::Live;
use crate::recorder::OsLogOptions;
use crate::recorder::RecordOptions;
use crate::session::Session;
use crate::sources::oslog::OsLogLevel;
use crate::timecode;
use clap::Args;
use color_eyre::eyre;
use color_eyre::eyre::WrapErr;
use std::path::PathBuf;
use std::time::Duration;
/// The options of a recording, shared by `record` and `gui`.
///
/// The default is a recording with no flags given: every display, 30 frames per second at logical
/// resolution, komorebi and the OS trace included, no time limit.
#[derive(Args, Clone, Debug)]
pub struct RecordArgs {
/// Session directory to create [default: in komorebi's data directory, under recordings/,
/// named by the UTC time]
#[arg(long)]
pub out: Option<PathBuf>,
/// Stop automatically after this many seconds
#[arg(long, value_name = "SECONDS")]
pub duration: Option<f64>,
/// Display id to record (repeatable; see `displays`) [default: every display]
#[arg(long = "display", value_name = "ID")]
pub displays: Vec<u32>,
/// Maximum video frame rate (frames are only produced when the screen changes)
#[arg(long, default_value_t = 30)]
pub fps: u32,
/// Record at native pixel resolution instead of logical points
#[arg(long)]
pub retina: bool,
/// Video codec
#[arg(long, value_enum, default_value_t = Codec::default())]
pub codec: Codec,
/// Do not capture komorebi's log or events (video and OS trace only)
#[arg(long)]
pub no_komorebi: bool,
/// Do not capture the screen: record everything else (komorebi's events and log, the OS
/// trace and incidents) on the same clock
#[arg(long, conflicts_with = "displays")]
pub no_video: bool,
/// Do not capture the OS trace at all (the unified log on macOS)
#[arg(long)]
pub no_oslog: bool,
/// Which applications get their own OS trace file
#[arg(long, value_enum, default_value_t = AppsMode::Managed)]
pub oslog_apps: AppsMode,
/// Also capture one unfiltered system-wide stream (very large)
#[arg(long)]
pub oslog_all: bool,
/// Unified log level to capture
#[arg(long, value_enum, default_value_t = OsLogLevel::Debug)]
pub oslog_level: OsLogLevel,
/// Replace the predicate of the `system` OS trace stream
#[arg(long, value_name = "PREDICATE")]
pub predicate: Option<String>,
/// Add a system daemon to the `system` stream, e.g. `WindowServer` (repeatable; high volume)
#[arg(long = "system-process", value_name = "NAME")]
pub system_processes: Vec<String>,
/// Also trace an application by name (repeatable)
#[arg(long = "trace-process", value_name = "NAME")]
pub trace_processes: Vec<String>,
/// Also trace a process by pid (repeatable)
#[arg(long = "trace-pid", value_name = "PID")]
pub trace_pids: Vec<i32>,
/// Never trace this application (repeatable), e.g. a chatty one
#[arg(long = "oslog-exclude", value_name = "NAME")]
pub oslog_exclude: Vec<String>,
}
impl Default for RecordArgs {
fn default() -> Self {
Self {
out: None,
duration: None,
displays: Vec::new(),
fps: 30,
retina: false,
codec: Codec::default(),
no_komorebi: false,
no_video: false,
no_oslog: false,
oslog_apps: AppsMode::Managed,
oslog_all: false,
oslog_level: OsLogLevel::Debug,
predicate: None,
system_processes: Vec::new(),
trace_processes: Vec::new(),
trace_pids: Vec::new(),
oslog_exclude: Vec::new(),
}
}
}
impl RecordArgs {
/// Returns these options as the [`RecordOptions`] that [`recorder::record`] takes.
///
/// `--no-oslog` becomes `oslog.enabled = false`, `--duration` becomes a
/// [`Duration`](std::time::Duration), and the options that name a display, application or
/// process are copied as they are. Nothing is checked here: a display id that does not exist is
/// found out when recording starts.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::cli::RecordArgs;
/// use std::time::Duration;
///
/// let options = RecordArgs {
/// duration: Some(2.5),
/// displays: vec![1],
/// no_oslog: true,
/// ..RecordArgs::default()
/// }
/// .to_options();
///
/// assert_eq!(options.duration, Some(Duration::from_millis(2500)));
/// assert_eq!(options.displays, [1]);
/// assert!(!options.oslog.enabled);
/// assert_eq!(options.capture.fps, 30);
/// ```
#[must_use]
pub fn to_options(&self) -> RecordOptions {
RecordOptions {
out: self.out.clone(),
displays: self.displays.clone(),
capture: CaptureConfig {
fps: self.fps,
retina: self.retina,
codec: self.codec,
},
oslog: OsLogOptions {
enabled: !self.no_oslog,
apps: self.oslog_apps,
all: self.oslog_all,
level: self.oslog_level,
predicate: self.predicate.clone(),
system_processes: self.system_processes.clone(),
trace_processes: self.trace_processes.clone(),
trace_pids: self.trace_pids.clone(),
exclude: self.oslog_exclude.clone(),
},
duration: self.duration.map(Duration::from_secs_f64),
no_komorebi: self.no_komorebi,
no_video: self.no_video,
}
}
}
pub(super) fn displays() -> eyre::Result<()> {
for display in capture::active_displays()? {
println!(
"{} {}x{} points at ({}, {})",
display.id,
display.width_points,
display.height_points,
display.frame[0],
display.frame[1]
);
}
Ok(())
}
pub(super) fn record(args: &RecordArgs) -> eyre::Result<()> {
let live = Live::new();
let handler_live = live.clone();
ctrlc::set_handler(move || handler_live.request_stop())
.wrap_err("could not install the Ctrl-C handler")?;
let options = args.to_options();
let worker_live = live.clone();
let worker = std::thread::Builder::new()
.name("recorder".to_string())
.spawn(move || recorder::record(&options, &worker_live))?;
let mut announced = false;
while !worker.is_finished() {
std::thread::sleep(Duration::from_millis(500));
let snapshot = live.snapshot();
if snapshot.phase == recorder::Phase::Recording {
if !announced {
announced = true;
if let Some(dir) = &snapshot.session_dir {
eprintln!("recording to {} (Ctrl-C to stop)", dir.display());
}
for warning in &snapshot.warnings {
eprintln!("warning: {warning}");
}
}
eprint!(
"\r {} frames {} komorebi log {} B events {} OS trace {} events ",
timecode::format(snapshot.elapsed_s),
snapshot.frames,
snapshot.log_bytes,
snapshot.events,
snapshot.oslog_events,
);
}
}
eprintln!();
let dir = worker
.join()
.map_err(|_| eyre::Report::msg("the recording thread panicked"))??;
let session = Session::open(&dir)?;
let manifest = session.manifest()?;
let (_, duration) = manifest.video_span();
println!("session: {}", dir.display());
if manifest.displays.is_empty() {
println!("length: {duration:.1}s (no video)");
} else {
println!("video: {duration:.1}s");
}
println!(
"recorded: {} komorebi log bytes, {} events, {} OS trace events across {} streams",
manifest.log_segments.iter().map(|s| s.len()).sum::<u64>(),
manifest.events.events,
manifest
.oslog
.iter()
.map(|stream| stream.events)
.sum::<u64>(),
manifest.oslog.len(),
);
for warning in &manifest.warnings {
println!("warning: {warning}");
}
println!(
"\nquery it: komorebi-recorder at {} <timecode>\n komorebi-recorder summary {}",
dir.display(),
dir.display()
);
Ok(())
}
+12
View File
@@ -51,6 +51,10 @@
//! | [`capture`] | capturing the screen into segments of video |
//! | [`power`] and [`system_state`] | sleep, wake, lock and display changes |
//! | [`timeline`] and [`frames`] | the time-sorted index of a session and the frame times of its video |
//! | [`recorder`] | starting every source, keeping them running and stopping them |
//! | [`annotations`] | the bug regions, notes and findings written into a session |
//! | [`recovery`] | rebuilding a session whose recorder died |
//! | [`cli`] | the command line |
//!
//! # What is not supported
//!
@@ -64,7 +68,9 @@
//! [`platform`] for what each host provides.
pub mod analysis;
pub mod annotations;
pub mod capture;
pub mod cli;
pub mod clock;
pub mod frames;
pub mod incidents;
@@ -72,8 +78,14 @@ pub mod komorebi_link;
pub mod lock;
pub mod platform;
pub mod power;
pub mod recorder;
pub mod recovery;
pub mod session;
pub mod sources;
pub mod system_state;
// Test scaffolding, public only because the integration tests in `tests/` are separate crates and
// have to reach it. It is not part of the interface, so it is kept out of the documentation.
#[doc(hidden)]
pub mod testkit;
pub mod timecode;
pub mod timeline;
+5 -12
View File
@@ -1,15 +1,8 @@
//! The `komorebi-recorder` command.
//! The `komorebi-recorder` command: it reads the command line and runs it (see [`komorebi_recorder::cli`]).
use clap::Parser;
use color_eyre::eyre;
use std::process::ExitCode;
#[derive(Parser)]
#[command(
author,
version,
about = "Synchronized screen, log and trace capture for komorebi bug reproduction"
)]
struct Opts;
fn main() {
Opts::parse();
fn main() -> eyre::Result<ExitCode> {
komorebi_recorder::cli::main()
}
File diff suppressed because it is too large. Load diff
+680
View File
@@ -0,0 +1,680 @@
//! Rebuilding a session whose recorder died before it could finish.
//!
//! While recording, everything is written so that a crash, a `kill -9`, a power loss or a
//! panic loses as little as possible: video is fragmented mp4 (playable up to the last fragment),
//! the frame log and every raw source are flushed continuously, and the manifest is checkpointed
//! every few seconds with `status: "recording"`. Recovery turns that checkpoint into a normal,
//! queryable session: it closes the segments that were still open using the frame log, sets a
//! stop time from the latest evidence on disk, and marks the session `recovered`.
//!
//! This is what the `reindex` command does ([`reindex_session`]): recover, rebuild the timeline,
//! rewrite the session's `README.md`. A session that was finished properly is only re-indexed.
//! Recovery is the same on every host: the frame log and the manifest are the same on both, and
//! only the question "how long is this video file" is the host's (see [`recover`]).
//!
//! # What recovery trusts
//!
//! | Question | Answered from | Because |
//! |---|---|---|
//! | how much video survived | the video file's duration, if the host can read it | fragments are cut on a timer and the frame log is flushed on another, so either can be ahead |
//! | how many frames, and when | the frame log, up to the end the file gives | the frame log is authoritative for the time of each frame |
//! | when the recording ended | the latest of the last anchor, the end of the video, and the last event | nothing later is known to have happened |
//!
//! Without a readable video file, recovery falls back to the frame log and says that the file may
//! be unplayable. The end of a recovered session is approximate, and a little of its end may be
//! missing: the manifest gets a warning saying so.
//!
//! # The frame log
//!
//! `frames-<display>[-<n>].csv` is written by the capture, one per video segment. It is UTF-8
//! text, comma separated, with a header and one row for each frame:
//!
//! ```text
//! index,pts_mach_ns,received_mach_ns
//! 0,1000200000000,1000210000000
//! 1,1007000000000,1007010000000
//! -,1007600000000,1007600000000
//! ```
//!
//! | Column | Is |
//! |---|---|
//! | `index` | the frame's number in the segment, counting from 0, over real frames only; `-` for a keep-alive row |
//! | `pts_mach_ns` | the frame's time on the master clock, in nanoseconds: when it was shown |
//! | `received_mach_ns` | when the recorder received it, on the same clock; for a keep-alive row, when it was written |
//!
//! A keep-alive row (`index` is `-`) is the recorder re-submitting the last frame on an idle display
//! so that fragments keep being cut. It is not a new frame, but it shows the segment lasted until
//! its time. A recorder that died while writing can leave the last row cut short. [`read_frame_log`]
//! reads up to the tear.
//!
//! # Example
//!
//! ```rust
//! use komorebi_recorder::recovery::read_frame_log;
//!
//! let dir = std::env::temp_dir().join(format!("komorebi-recorder-doc-recovery-{}", std::process::id()));
//! std::fs::create_dir_all(&dir)?;
//! let path = dir.join("frames-2.csv");
//!
//! // what `kill -9` leaves behind: two frames, a keep-alive, and a last row cut short
//! std::fs::write(
//! &path,
//! "index,pts_mach_ns,received_mach_ns\n0,1000,1010\n1,2000,2010\n-,2600,2600\n2,3000",
//! )?;
//!
//! let log = read_frame_log(&path);
//! assert_eq!(log.frames, 2, "the keep-alive and the torn row are not frames");
//! assert_eq!(log.first_pts_mach_ns, Some(1000));
//! assert_eq!(log.last_pts_mach_ns, Some(2600), "the segment lasted until the keep-alive");
//! # std::fs::remove_dir_all(&dir)?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
use crate::capture::EndReason;
use crate::clock::ClockMap;
use crate::session::Moment;
use crate::session::STATUS_RECORDING;
use crate::session::STATUS_RECOVERED;
use crate::session::Session;
use crate::sources::komorebi_events::EventRow;
use crate::timeline;
use crate::timeline::BuildStats;
use color_eyre::eyre;
use std::path::Path;
/// What the frame log of a segment says about it.
///
/// Rows whose index is `-` are keep-alive re-submissions of the last frame on an idle display: they
/// count towards how long the segment lasted but are not new frames.
///
/// The default is a log with no frames, which is also what reading a log that is missing gives.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct FrameLog {
/// How many real frames the log has: rows that are not keep-alives.
pub frames: u64,
/// The time of the first real frame, in nanoseconds on the master clock. `None` if the log has
/// no frames.
pub first_pts_mach_ns: Option<u64>,
/// The time of the last row, a keep-alive or a frame, in nanoseconds on the master clock. It
/// is when the segment was last known to be alive. `None` if the log has no rows.
pub last_pts_mach_ns: Option<u64>,
}
/// Reads a `frames-*.csv`, ignoring the header and any torn or malformed row (the last row of a
/// log that was being written when the recorder died).
///
/// A row counts only if it has exactly three fields, and the second and third are whole numbers.
/// A missing or unreadable file is a log with no frames, not an error: the caller decides what
/// that means (recovery says that no frames had been recorded). See the [module docs](self) for
/// the format.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::recovery::{read_frame_log, FrameLog};
///
/// // a log that does not exist has no frames
/// let missing = std::env::temp_dir().join("komorebi-recorder-doc-no-such-frames.csv");
/// assert_eq!(read_frame_log(&missing), FrameLog::default());
/// ```
#[must_use]
pub fn read_frame_log(path: &Path) -> FrameLog {
read_frame_log_until(path, u64::MAX)
}
/// Like [`read_frame_log`], but ignoring rows later than `until_pts_mach_ns`: the part of the
/// log that never made it into the video.
///
/// Reading stops at the first row whose `pts_mach_ns` is greater than `until_pts_mach_ns`, so it
/// relies on the rows being in time order, as a capture writes them.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::recovery::read_frame_log_until;
///
/// let dir = std::env::temp_dir().join(format!("komorebi-recorder-doc-until-{}", std::process::id()));
/// std::fs::create_dir_all(&dir)?;
/// let path = dir.join("frames-1.csv");
/// std::fs::write(
/// &path,
/// "index,pts_mach_ns,received_mach_ns\n0,1000,1010\n1,2000,2010\n2,3000,3010\n",
/// )?;
///
/// // the video only holds what was shown up to 2500: the third frame did not make it
/// let log = read_frame_log_until(&path, 2_500);
/// assert_eq!(log.frames, 2);
/// assert_eq!(log.last_pts_mach_ns, Some(2000));
/// # std::fs::remove_dir_all(&dir)?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn read_frame_log_until(path: &Path, until_pts_mach_ns: u64) -> FrameLog {
let Ok(text) = std::fs::read_to_string(path) else {
return FrameLog::default();
};
let mut log = FrameLog::default();
for line in text.lines().skip(1) {
let mut fields = line.split(',');
let (Some(index), Some(pts), Some(received), None) =
(fields.next(), fields.next(), fields.next(), fields.next())
else {
continue;
};
let (Ok(pts), Ok(_)) = (pts.parse::<u64>(), received.parse::<u64>()) else {
continue;
};
if pts > until_pts_mach_ns {
break;
}
if index != "-" {
// a keep-alive can never be the first row, so the first row is a real frame
log.frames += 1;
log.first_pts_mach_ns.get_or_insert(pts);
}
log.last_pts_mach_ns = Some(pts);
}
log
}
/// One frame at the capture frame rate cap, used to give the last recovered frame a duration.
const FRAME_NS: u64 = 33_333_333;
/// What [`reindex_session`] did.
#[derive(Debug)]
pub struct Reindexed {
/// Notes describing a recovery, empty if the session had been finished properly.
pub recovered: Vec<String>,
/// What went into the rebuilt timeline index: how many entries, and how many from each source.
pub stats: BuildStats,
}
/// Closes out `session` if its recorder died, then rebuilds its timeline and README from the raw
/// files.
///
/// This is everything `komorebi-recorder reindex` does, shared so that other commands can bring a
/// session up to date the same way. It is [`recover`], then [`timeline::build`], then rewriting the
/// session's `README.md` from the manifest. It is safe to run again, on a recovered session or a
/// finished one: only the first pass recovers anything, and rebuilding the timeline from the same
/// raw files gives the same index.
///
/// Like [`recover`], this does not check that the session's recorder is gone.
///
/// # Errors
///
/// Returns an error if
///
/// * the manifest cannot be read, parsed, or is from a newer version of the recorder than this one
/// (see [`recover`]);
/// * the recovered manifest cannot be written (see [`recover`]);
/// * the timeline cannot be rebuilt (see [`timeline::build`]);
/// * the `README.md` cannot be written.
///
/// A failure after the recovery step leaves the session recovered, without a rebuilt timeline: run
/// it again to rebuild.
///
/// # Example
///
/// ```rust,no_run
/// use komorebi_recorder::recovery::reindex_session;
/// use komorebi_recorder::session::Session;
///
/// let session = Session::open("/path/to/recordings/20261026T120000Z")?;
/// let reindexed = reindex_session(&session)?;
/// for note in &reindexed.recovered {
/// println!("recovered: {note}");
/// }
/// println!("indexed {} records", reindexed.stats.entries);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// This needs a session directory, so it is not run. The steps it chains are covered by the tests
/// `an_interrupted_session_is_closed_out_from_its_frame_logs` (recovery) and
/// `reindex_is_idempotent_and_recovers_a_deleted_timeline` (the rebuild, in `timeline`).
pub fn reindex_session(session: &Session) -> eyre::Result<Reindexed> {
let recovered = recover(session)?;
let stats = timeline::build(session)?;
session.write_readme(&session.manifest()?)?;
Ok(Reindexed { recovered, stats })
}
/// Recovers `session` if it was left unfinished, asking the host how long each video file really
/// is.
///
/// Returns notes describing what was done, empty if the session was already complete. A session
/// needs recovery if and only if its manifest says `recording`: the recorder checkpoints it that
/// way every few seconds, and writes `complete` when it finishes. For such a session, each video
/// segment that has no end reason is closed: its frame count, its end, and an end reason of
/// [`EndReason::Interrupted`] are written into the manifest, from the frame log and the file's
/// duration; segments that already ended are left alone. The recording's stop time is set to the
/// latest evidence on disk, the status becomes `recovered`, and a warning says the end is
/// approximate.
///
/// The duration of a video file is [`crate::platform::capture::media_duration_s`]: what the host's
/// media framework reads from the file, which is `AVFoundation` on macOS and Media Foundation on
/// Windows. It is the truth about how much video survived, because the file and the frame log are
/// flushed on separate timers. A host that cannot read it (the `unsupported` host, or a file the
/// framework cannot open) makes recovery fall back to the frame log.
///
/// This does not check that the recorder is really gone. A caller that may be handed a session
/// still being recorded asks [`crate::lock::recorder`] first.
///
/// # Errors
///
/// Returns an error if the manifest cannot be read, cannot be parsed, or was written by a newer
/// version of the recorder (schema version), or if the recovered manifest cannot be written.
/// Nothing is changed on disk before the final write.
///
/// # Example
///
/// ```rust,no_run
/// use komorebi_recorder::recovery::recover;
/// use komorebi_recorder::session::Session;
///
/// let session = Session::open("/path/to/recordings/20261026T120000Z")?;
/// for note in recover(&session)? {
/// println!("{note}");
/// }
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// This reads real video files, so it is not run. [`recover_with`] takes the duration lookup as an
/// argument, and is what the tests use: see its example.
pub fn recover(session: &Session) -> eyre::Result<Vec<String>> {
recover_with(session, &crate::platform::capture::media_duration_s)
}
/// [`recover`] with the file-duration lookup supplied, so it can be tested without video files.
///
/// `duration_of` is given the path of a segment's video file, and returns its duration in seconds,
/// or `None` if it cannot say. A duration of zero or less is taken as `None`.
///
/// # Errors
///
/// The same as [`recover`].
///
/// # Example
///
/// ```rust
/// use chrono::Utc;
/// use komorebi_recorder::clock::Anchor;
/// use komorebi_recorder::recovery::recover_with;
/// use komorebi_recorder::session::{Manifest, Moment, Session, STATUS_RECOVERED, STATUS_RECORDING};
/// use std::path::Path;
///
/// let dir = std::env::temp_dir().join(format!("komorebi-recorder-doc-recover-{}", std::process::id()));
/// let _ = std::fs::remove_dir_all(&dir);
/// let session = Session::create(Some(dir.clone()), Utc::now())?;
///
/// // the checkpoint of a recorder that died: still `recording`, with no displays recorded yet
/// let start = Moment { mach_ns: 1_000_000_000_000, wall_us: 1_800_000_000_000_000 };
/// let manifest = Manifest::new(
/// start,
/// vec![Anchor { wall_us: start.wall_us, mach_ns: start.mach_ns }],
/// );
/// assert_eq!(manifest.status, STATUS_RECORDING);
/// session.write_manifest(&manifest)?;
///
/// let notes = recover_with(&session, &|_: &Path| None)?;
/// assert_eq!(notes, ["session marked as recovered"]);
///
/// let recovered = session.manifest()?;
/// assert_eq!(recovered.status, STATUS_RECOVERED);
/// assert!(recovered.warnings[0].contains("stopped unexpectedly"));
///
/// // a second pass has nothing to do
/// assert!(recover_with(&session, &|_: &Path| None)?.is_empty());
/// # std::fs::remove_dir_all(&dir)?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// Segments with frame logs, torn rows and video durations are covered by the tests
/// `an_interrupted_session_is_closed_out_from_its_frame_logs` and
/// `an_unreadable_video_file_falls_back_to_the_frame_log_and_says_so`.
pub fn recover_with(
session: &Session,
duration_of: &dyn Fn(&Path) -> Option<f64>,
) -> eyre::Result<Vec<String>> {
let mut manifest = session.manifest()?;
if manifest.status != STATUS_RECORDING {
return Ok(Vec::new());
}
let mut notes = Vec::new();
let mut results: Vec<_> = manifest
.displays
.iter()
.map(|entry| entry.result.clone())
.collect();
for result in &mut results {
if result.end_reason.is_some() {
continue;
}
let frames_path = session.path(&result.frames_file);
let whole_log = read_frame_log(&frames_path);
let t0 = result.video_t0_mach_ns.or(whole_log.first_pts_mach_ns);
// The video file is the truth about how much was kept: fragments are cut on a timer, and
// the frame log is flushed on another, so either can be ahead of the other. Without a
// readable file, fall back to the log.
let file_duration = duration_of(&session.path(&result.file)).filter(|d| *d > 0.0);
let end = match (t0, file_duration) {
(Some(t0), Some(duration)) => Some(t0 + (duration * 1e9) as u64),
_ => whole_log.last_pts_mach_ns.map(|last| last + FRAME_NS),
};
let log = end.map_or(whole_log, |end| read_frame_log_until(&frames_path, end));
result.frames = log.frames;
result.video_t0_mach_ns = t0;
result.video_end_mach_ns = end;
result.end_reason = Some(EndReason::Interrupted);
notes.push(match (log.frames, file_duration) {
(0, _) => format!("{}: no frames had been recorded", result.file),
(frames, Some(duration)) => format!(
"{}: recovered {frames} frames, {duration:.1}s of video from the file",
result.file
),
(frames, None) => format!(
"{}: {frames} frames are in the frame log but the video file could not be read, so it may be unplayable",
result.file
),
});
}
manifest.apply_segments(results);
// the recording ended no earlier than the latest thing we can see on disk
let clock = ClockMap::new(manifest.anchors.clone());
let mut latest = manifest
.anchors
.iter()
.map(|a| a.mach_ns)
.max()
.unwrap_or(manifest.start.mach_ns);
latest = latest.max(manifest.video_end_mach_ns.unwrap_or(0));
if let Ok(text) = std::fs::read_to_string(session.path("events.jsonl")) {
let last_event = text
.lines()
.filter_map(|line| serde_json::from_str::<EventRow>(line).ok())
.map(|row| row.recv_mach_ns)
.max();
latest = latest.max(last_event.unwrap_or(0));
}
let wall_us = clock.mach_to_wall(latest).unwrap_or(manifest.start.wall_us);
manifest.stop = Some(Moment {
mach_ns: latest,
wall_us,
});
manifest.status = STATUS_RECOVERED.to_string();
manifest.warnings.push(
"the recorder stopped unexpectedly (crash, kill or power loss); this session was recovered \
from what was on disk, so its end is approximate and a little of the end may be missing"
.to_string(),
);
notes.push("session marked as recovered".to_string());
session.write_manifest(&manifest)?;
Ok(notes)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::capture::Codec;
use crate::capture::DisplayDescriptor;
use crate::capture::DisplayResult;
use crate::capture::LatencyStats;
use crate::clock::Anchor;
use crate::session::Manifest;
use chrono::Utc;
fn temp(name: &str) -> std::path::PathBuf {
std::env::temp_dir().join(format!(
"komorebi-recorder-recovery-{name}-{}",
std::process::id()
))
}
fn live_segment(display: u32, segment: u32, t0: u64) -> DisplayResult {
DisplayResult {
display: DisplayDescriptor {
id: display,
frame: [0.0, 0.0, 100.0, 100.0],
width_points: 100,
height_points: 100,
asleep: false,
scale: 1.0,
},
segment,
scale: 1.0,
width_px: 100,
height_px: 100,
codec: Codec::Hevc,
file: crate::capture::video_file_name(display, segment),
frames_file: crate::capture::frames_file_name(display, segment),
video_t0_mach_ns: Some(t0),
video_end_mach_ns: None,
end_reason: None,
frames: 3,
dropped: 0,
idle_callbacks: 0,
latency: LatencyStats::default(),
error: None,
}
}
#[test]
fn a_frame_log_with_a_torn_last_row_is_read_up_to_the_tear() {
let dir = temp("csv");
std::fs::create_dir_all(&dir).expect("dir");
let path = dir.join("frames-2.csv");
// what `kill -9` left behind in a real recording: the last row cut mid-field
std::fs::write(
&path,
"index,pts_mach_ns,received_mach_ns\n0,1000,1010\n1,2000,2010\n2,3000",
)
.expect("write");
let log = read_frame_log(&path);
assert_eq!(log.frames, 2, "the torn row is not counted");
assert_eq!(log.first_pts_mach_ns, Some(1000));
assert_eq!(log.last_pts_mach_ns, Some(2000));
assert_eq!(
read_frame_log(&dir.join("missing.csv")),
FrameLog::default()
);
}
#[test]
fn keep_alive_rows_extend_the_segment_but_are_not_frames() {
let dir = temp("keepalive");
std::fs::create_dir_all(&dir).expect("dir");
let path = dir.join("frames-1.csv");
std::fs::write(
&path,
"index,pts_mach_ns,received_mach_ns\n0,1000,1010\n1,2000,2010\n-,2600,2600\n-,3100,3100\n",
)
.expect("write");
let log = read_frame_log(&path);
assert_eq!(log.frames, 2, "only the real frames");
assert_eq!(log.first_pts_mach_ns, Some(1000));
assert_eq!(
log.last_pts_mach_ns,
Some(3100),
"the segment lasted until the last keep-alive"
);
}
#[test]
fn an_interrupted_session_is_closed_out_from_its_frame_logs() {
let dir = temp("session");
let _ = std::fs::remove_dir_all(&dir);
let session = Session::create(Some(dir.clone()), Utc::now()).expect("create");
// a checkpoint taken 10s in: one finished segment, one still open when the recorder died
let start = Moment {
mach_ns: 1_000_000_000_000,
wall_us: 1_800_000_000_000_000,
};
let mut manifest = Manifest::new(
start,
vec![
Anchor {
wall_us: start.wall_us,
mach_ns: start.mach_ns,
},
Anchor {
wall_us: start.wall_us + 5_000_000,
mach_ns: start.mach_ns + 5_000_000_000,
},
],
);
let mut finished = live_segment(1, 1, 1_000_100_000_000);
finished.video_end_mach_ns = Some(1_003_000_000_000);
finished.end_reason = Some(EndReason::DisplayDisconnected);
manifest.apply_segments(vec![finished, live_segment(2, 1, 1_000_200_000_000)]);
assert_eq!(manifest.status, STATUS_RECORDING);
session.write_manifest(&manifest).expect("write");
// the open segment's frame log, as left on disk (torn last row)
std::fs::write(
session.path("frames-2.csv"),
"index,pts_mach_ns,received_mach_ns\n0,1000200000000,1\n1,1007000000000,2\n2,1008000000000,3\n3,1009000",
)
.expect("csv");
// an event shortly after the last frame
std::fs::write(
session.path("events.jsonl"),
"{\"seq\":1,\"recv_wall_us\":1,\"recv_mach_ns\":1009500000000}\n",
)
.expect("events");
// the video file on disk holds 7.5s of the 8s the frame log covers
let notes = recover_with(&session, &|path: &Path| {
path.ends_with("video-2.mp4").then_some(7.5)
})
.expect("recover");
assert!(
notes
.iter()
.any(|note| note.contains("video-2.mp4: recovered 2 frames, 7.5s")),
"{notes:?}"
);
let recovered = session.manifest().expect("manifest");
assert_eq!(recovered.status, STATUS_RECOVERED);
assert!(
recovered
.warnings
.iter()
.any(|w| w.contains("stopped unexpectedly"))
);
let open = recovered
.displays
.iter()
.find(|entry| entry.result.display.id == 2)
.expect("segment");
assert_eq!(open.result.end_reason, Some(EndReason::Interrupted));
// the 3rd frame (at +8s) is past the 7.5s of video that survived, so it is not counted
assert_eq!(open.result.frames, 2);
assert_eq!(
open.result.video_end_mach_ns,
Some(1_000_200_000_000 + 7_500_000_000)
);
assert!(open.end_s.is_some());
let closed = recovered
.displays
.iter()
.find(|entry| entry.result.display.id == 1)
.expect("segment");
assert_eq!(
closed.result.end_reason,
Some(EndReason::DisplayDisconnected),
"left alone"
);
// the stop time is the latest evidence: the event, not the stale 5s anchor
assert_eq!(recovered.stop.expect("stop").mach_ns, 1_009_500_000_000);
assert!(recovered.video_end_mach_ns.is_some());
// and a second pass does nothing
assert!(
recover_with(&session, &|_: &Path| None)
.expect("again")
.is_empty()
);
}
#[test]
fn an_unreadable_video_file_falls_back_to_the_frame_log_and_says_so() {
let dir = temp("unreadable");
let _ = std::fs::remove_dir_all(&dir);
let session = Session::create(Some(dir), Utc::now()).expect("create");
let start = Moment {
mach_ns: 1_000_000_000_000,
wall_us: 1_800_000_000_000_000,
};
let mut manifest = Manifest::new(
start,
vec![Anchor {
wall_us: start.wall_us,
mach_ns: start.mach_ns,
}],
);
manifest.apply_segments(vec![live_segment(2, 1, 1_000_100_000_000)]);
session.write_manifest(&manifest).expect("write");
std::fs::write(
session.path("frames-2.csv"),
"index,pts_mach_ns,received_mach_ns\n0,1000100000000,1\n1,1002100000000,2\n",
)
.expect("csv");
let notes = recover_with(&session, &|_: &Path| None).expect("recover");
assert!(
notes.iter().any(|note| note.contains("could not be read")),
"{notes:?}"
);
let recovered = session.manifest().expect("manifest");
assert_eq!(recovered.displays[0].result.frames, 2);
assert_eq!(
recovered.displays[0].result.video_end_mach_ns,
Some(1_002_100_000_000 + FRAME_NS)
);
}
#[test]
fn a_complete_session_is_left_alone() {
let dir = temp("complete");
let _ = std::fs::remove_dir_all(&dir);
let session = Session::create(Some(dir), Utc::now()).expect("create");
let start = Moment {
mach_ns: 1,
wall_us: 1,
};
let mut manifest = Manifest::new(start, vec![]);
manifest.status = crate::session::STATUS_COMPLETE.to_string();
session.write_manifest(&manifest).expect("write");
assert!(
recover_with(&session, &|_: &Path| None)
.expect("recover")
.is_empty()
);
assert_eq!(session.manifest().expect("manifest"), manifest);
}
}
+652
View File
@@ -0,0 +1,652 @@
//! Building synthetic sessions for tests, without a screen, komorebi or a recorder.
//!
//! A real recording needs screen-capture permission and a running komorebi, so everything that
//! reads a session is tested against sessions assembled here: a manifest with a clock, komorebi
//! subscriber events with their states, a plaintext log, and recorder incidents, all placed at
//! chosen moments of video time. Not part of the public interface.
use crate::clock::Anchor;
use crate::incidents::INCIDENTS_FILE;
use crate::incidents::Incident;
use crate::session::Manifest;
use crate::session::Moment;
use crate::session::Session;
use crate::sources::komorebi_events::EventRow;
use crate::sources::komorebi_events::state_file_name;
use crate::timeline;
use chrono::Utc;
use serde_json::Value;
use std::path::PathBuf;
/// Video t=0 on the mach clock.
pub const T0_MACH_NS: u64 = 5_000_000_000;
/// What the wall clock reads at mach 0, in microseconds: 2026-10-26T12:00:00Z.
pub const WALL_AT_MACH_ZERO_US: i64 = 1_793_016_000_000_000;
/// The mach time of `video_s` seconds into the video.
#[must_use]
pub fn mach_ns(video_s: f64) -> u64 {
(T0_MACH_NS as i64 + (video_s * 1e9).round() as i64).max(0) as u64
}
/// The wall time, in microseconds, of `video_s` seconds into the video.
#[must_use]
pub fn wall_us(video_s: f64) -> i64 {
WALL_AT_MACH_ZERO_US + (mach_ns(video_s) / 1_000) as i64
}
struct PendingVideo {
display: u32,
start_s: f64,
frames: u32,
fps: u32,
/// Which picture each frame shows.
shown: Box<dyn Fn(u32) -> u32>,
}
struct PendingOsRecord {
video_s: f64,
/// `komorebi`, `system`, or an application's name.
source: String,
pid: i64,
process: String,
message: String,
}
struct PendingEvent {
video_s: f64,
event: Value,
state: Option<Value>,
}
/// A session under construction. Times are seconds of video time.
pub struct SessionBuilder {
dir: PathBuf,
length_s: f64,
events: Vec<PendingEvent>,
log: Vec<(f64, String, String)>,
incidents: Vec<Incident>,
os_records: Vec<PendingOsRecord>,
flavor: crate::analysis::flavor::Flavor,
komorebi_commit: Option<String>,
videos: Vec<PendingVideo>,
}
impl SessionBuilder {
/// A session in a fresh temporary directory, 10 s of video starting 1 s after the recorder
/// started and ending 1 s before it stopped.
#[must_use]
pub fn new(name: &str) -> Self {
let dir = std::env::temp_dir().join(format!(
"komorebi-recorder-testkit-{name}-{}",
std::process::id()
));
let _ = std::fs::remove_dir_all(&dir);
Self {
dir,
length_s: 10.0,
events: Vec::new(),
log: Vec::new(),
incidents: Vec::new(),
os_records: Vec::new(),
flavor: crate::analysis::flavor::Flavor::Macos,
komorebi_commit: None,
videos: Vec::new(),
}
}
/// A display's video file starting `start_s` into the recording: `frames` frames at `fps`,
/// each numbered (see [`write_numbered_video`]). Needs `ffmpeg`; without it no file is written
/// and the session has no video, so tests that need one check [`ffmpeg_available`] first.
#[must_use]
pub fn video(self, display: u32, start_s: f64, frames: u32, fps: u32) -> Self {
self.video_showing(display, start_s, frames, fps, |frame| frame)
}
/// Like [`SessionBuilder::video`] but frame `n` shows the picture numbered `shown(n)`.
#[must_use]
pub fn video_showing(
mut self,
display: u32,
start_s: f64,
frames: u32,
fps: u32,
shown: impl Fn(u32) -> u32 + 'static,
) -> Self {
self.videos.push(PendingVideo {
display,
start_s,
frames,
fps,
shown: Box::new(shown),
});
self
}
/// Say which komorebi was recorded (komorebi for Mac unless told otherwise).
#[must_use]
pub fn flavor(mut self, flavor: crate::analysis::flavor::Flavor) -> Self {
self.flavor = flavor;
self
}
/// Say the recorded komorebi was built from this commit.
#[must_use]
pub fn komorebi_commit(mut self, commit: &str) -> Self {
self.komorebi_commit = Some(commit.to_string());
self
}
/// Say the recording lasted this many seconds of video time.
#[must_use]
pub fn length(mut self, seconds: f64) -> Self {
self.length_s = seconds;
self
}
/// A komorebi subscriber event received at `video_s`, with the state after it if it changed.
#[must_use]
pub fn event(mut self, video_s: f64, event: Value, state: Option<Value>) -> Self {
self.events.push(PendingEvent {
video_s,
event,
state,
});
self
}
/// One line of komorebi's plaintext log at `video_s`, e.g. `log(2.0, "INFO", "komorebi::x: hello")`.
#[must_use]
pub fn log(mut self, video_s: f64, level: &str, message: &str) -> Self {
self.log
.push((video_s, level.to_string(), message.to_string()));
self
}
/// Add an incident of `kind` (see [`crate::incidents::kind`]) that happened at `video_s`.
#[must_use]
pub fn incident(mut self, video_s: f64, kind: &str, detail: &str) -> Self {
self.incidents.push(Incident {
mach_ns: mach_ns(video_s),
wall_us: wall_us(video_s),
kind: kind.to_string(),
detail: detail.to_string(),
display: None,
});
self
}
/// A record of the OS trace at `video_s`: from `komorebi`'s own process, from the `system`, or
/// from the application with this name.
#[must_use]
pub fn os_record(
mut self,
video_s: f64,
source: &str,
pid: i64,
process: &str,
message: &str,
) -> Self {
self.os_records.push(PendingOsRecord {
video_s,
source: source.to_string(),
pid,
process: process.to_string(),
message: message.to_string(),
});
self
}
/// Write the session and index its timeline.
#[must_use]
pub fn build(mut self) -> (Session, Manifest) {
let session = Session::create(Some(self.dir.clone()), Utc::now()).expect("create");
let start = Moment {
mach_ns: mach_ns(-1.0),
wall_us: wall_us(-1.0),
};
let stop = Moment {
mach_ns: mach_ns(self.length_s + 1.0),
wall_us: wall_us(self.length_s + 1.0),
};
let mut manifest = Manifest::new(
start,
vec![
Anchor {
mach_ns: start.mach_ns,
wall_us: start.wall_us,
},
Anchor {
mach_ns: stop.mach_ns,
wall_us: stop.wall_us,
},
],
);
manifest.stop = Some(stop);
manifest.komorebi.flavor = self.flavor;
manifest.status = crate::session::STATUS_COMPLETE.to_string();
manifest.video_t0_mach_ns = Some(T0_MACH_NS);
manifest.video_end_mach_ns = Some(mach_ns(self.length_s));
manifest.events.events = self.events.len() as u64;
if let Some(commit) = &self.komorebi_commit {
manifest.komorebi.versions = vec![crate::sources::komorebi_version::KomorebiVersion {
pid: Some(1),
version: "0.1.0".to_string(),
branch: Some("master".to_string()),
commit: Some(commit.clone()),
}];
}
self.events.sort_by(|a, b| a.video_s.total_cmp(&b.video_s));
let mut state_id = 0_u64;
let mut previous: Option<Value> = None;
let mut rows = String::new();
for (index, pending) in self.events.iter().enumerate() {
if let Some(state) = &pending.state
&& previous.as_ref() != Some(state)
{
state_id += 1;
std::fs::write(
session.path(state_file_name(state_id)),
serde_json::to_string(state).expect("state"),
)
.expect("state file");
previous = Some(state.clone());
}
let row = EventRow {
seq: index as u64 + 1,
recv_wall_us: wall_us(pending.video_s),
recv_mach_ns: mach_ns(pending.video_s),
event: Some(pending.event.clone()),
state_id: (state_id > 0).then_some(state_id),
parse_error: None,
raw: None,
};
rows.push_str(&serde_json::to_string(&row).expect("row"));
rows.push('\n');
}
std::fs::write(session.path("events.jsonl"), rows).expect("events");
self.log.sort_by(|a, b| a.0.total_cmp(&b.0));
// tracing_subscriber right-aligns the level in five columns
let log: String = self
.log
.iter()
.map(|(video_s, level, message)| {
format!(
"{} {level:>5} {message}\n",
timeline::format_wall_us(wall_us(*video_s)).expect("time"),
)
})
.collect();
std::fs::write(session.path("komorebi.log"), log).expect("log");
self.incidents.sort_by_key(|incident| incident.mach_ns);
let incidents: String = self
.incidents
.iter()
.map(|incident| serde_json::to_string(incident).expect("incident") + "\n")
.collect();
std::fs::write(session.path(INCIDENTS_FILE), incidents).expect("incidents");
// the OS trace, one file per source the way the recorder writes them
self.os_records
.sort_by(|a, b| a.video_s.total_cmp(&b.video_s));
let mut files: std::collections::BTreeMap<String, String> =
std::collections::BTreeMap::new();
for record in &self.os_records {
let relative = match record.source.as_str() {
"komorebi" => "oslog/komorebi.ndjson".to_string(),
"system" => "oslog/system.ndjson".to_string(),
"eventlog" => "oslog/eventlog.ndjson".to_string(),
app => format!("oslog/apps/{app}-{}.ndjson", record.pid),
};
let ticks = crate::clock::timebase().ns_to_ticks(mach_ns(record.video_s));
let line = serde_json::json!({
"machTimestamp": ticks,
"timestamp": "2026-10-26 12:00:00.000000-0700",
"processID": record.pid,
"processImagePath": format!("/Applications/{}", record.process),
"subsystem": "com.apple.accessibility.axserver",
"category": "AX",
"messageType": "Debug",
"eventMessage": record.message,
});
let file = files.entry(relative).or_default();
file.push_str(&line.to_string());
file.push('\n');
}
for (relative, text) in &files {
std::fs::write(session.path(relative), text).expect("os trace file");
}
for video in &self.videos {
let name = crate::capture::video_file_name(video.display, 1);
let wrote = write_video(&session.path(&name), video.frames, video.fps, &*video.shown);
if !wrote {
continue;
}
let length = f64::from(video.frames) / f64::from(video.fps);
manifest.displays.push(crate::session::DisplayEntry {
result: crate::capture::DisplayResult {
display: crate::capture::DisplayDescriptor {
id: video.display,
frame: [0.0, 0.0, 1000.0, 800.0],
width_points: 1000,
height_points: 800,
asleep: false,
scale: 1.0,
},
segment: 1,
scale: 1.0,
width_px: NUMBERED_WIDTH as usize,
height_px: NUMBERED_HEIGHT as usize,
codec: crate::capture::Codec::Hevc,
file: name,
frames_file: crate::capture::frames_file_name(video.display, 1),
video_t0_mach_ns: Some(mach_ns(video.start_s)),
video_end_mach_ns: Some(mach_ns(video.start_s + length)),
end_reason: Some(crate::capture::EndReason::Stopped),
frames: u64::from(video.frames),
dropped: 0,
idle_callbacks: 0,
latency: crate::capture::LatencyStats::default(),
error: None,
},
offset_s: video.start_s,
end_s: Some(video.start_s + length),
});
}
session.write_manifest(&manifest).expect("manifest");
timeline::build(&session).expect("timeline");
(session, manifest)
}
}
/// komorebi-style log text from `(video_s, level, text after the level)` lines: the timestamp and
/// the right-aligned level are added the way `tracing_subscriber` does.
#[must_use]
pub fn log_text(lines: &[(f64, &str, &str)]) -> String {
lines
.iter()
.map(|(video_s, level, text)| {
format!(
"{} {level:>5} {text}\n",
timeline::format_wall_us(wall_us(*video_s)).expect("time")
)
})
.collect()
}
/// A komorebi for Windows window as it appears in a `State` or an event.
///
/// `rect` is `[left, top, width, height]`. The shape follows komorebi for Windows' source: every
/// field beside the handle is read live when it is serialized.
#[must_use]
pub fn windows_window(hwnd: i64, exe: &str, rect: Option<[i64; 4]>) -> Value {
let [left, top, width, height] = rect.unwrap_or([0, 0, 0, 0]);
serde_json::json!({
"hwnd": hwnd,
"title": format!("window {hwnd}"),
"exe": exe,
"class": "Window",
// komorebi's `right` and `bottom` are a width and a height
"rect": {"left": left, "top": top, "right": width, "bottom": height},
})
}
/// A komorebi for Windows `State` with one monitor and one tiling workspace whose containers each
/// hold the windows given, so tests can say where windows are without the rest of komorebi's state.
#[must_use]
pub fn windows_state(monitor_id: i64, containers: Vec<Vec<Value>>) -> Value {
let containers: Vec<Value> = containers
.into_iter()
.enumerate()
.map(|(index, windows)| {
serde_json::json!({
"id": format!("c{index}"),
"locked": false,
"windows": {"elements": windows, "focused": 0},
})
})
.collect();
serde_json::json!({
"monitors": {"elements": [{
"id": monitor_id,
"name": "DISPLAY1",
"device": "DISPLAY1",
"device_id": "SIM1234-5&abcdef&0&UID1",
"size": {"left": 0, "top": 0, "right": 1920, "bottom": 1080},
"work_area_size": {"left": 0, "top": 0, "right": 1920, "bottom": 1040},
"workspaces": {"elements": [{
"name": "main",
"containers": {"elements": containers, "focused": 0},
"monocle_container": null,
"maximized_window": null,
"floating_windows": {"elements": [], "focused": 0},
"layout": {"Default": "BSP"},
"latest_layout": [],
"tile": true,
"layer": "Tiling",
}], "focused": 0},
}], "focused": 0},
"is_paused": false,
"virtual_desktop_id": null,
})
}
/// A komorebi window as it appears in a `State`: `rect` is `[left, top, width, height]`.
#[must_use]
pub fn window(id: u64, exe: &str, rect: Option<[i64; 4]>) -> Value {
let mut value = serde_json::json!({
"id": id,
"details": {"title": format!("window {id}"), "exe": exe},
});
if let Some([left, top, width, height]) = rect {
// komorebi's `right` and `bottom` are a width and a height
value["rect"] =
serde_json::json!({"left": left, "top": top, "right": width, "bottom": height});
}
value
}
/// A container of komorebi's `State`, named `id`, that holds these windows.
#[must_use]
pub fn container(id: &str, windows: Vec<Value>) -> Value {
serde_json::json!({"id": id, "windows": {"elements": windows, "focused": 0}})
}
/// A tiling workspace; `layout` is the rects of komorebi's last layout pass, one per container.
#[must_use]
pub fn workspace(name: &str, containers: Vec<Value>, focused: usize, layout: &[[i64; 4]]) -> Value {
let rects: Vec<Value> = layout
.iter()
.map(|[left, top, width, height]| {
serde_json::json!({"left": left, "top": top, "right": width, "bottom": height})
})
.collect();
serde_json::json!({
"name": name,
"layer": "Tiling",
"tile": true,
"layout": {"Default": "Columns"},
"latest_layout": rects,
"containers": {"elements": containers, "focused": focused},
"floating_windows": {"elements": [], "focused": 0},
})
}
/// A monitor of display `id` at `[left, top, width, height]`, hiding windows bottom-left.
#[must_use]
pub fn monitor(id: u64, size: [i64; 4], workspaces: Vec<Value>, focused_workspace: usize) -> Value {
let [left, top, width, height] = size;
let rect = serde_json::json!({"left": left, "top": top, "right": width, "bottom": height});
serde_json::json!({
"id": id,
"device": format!("display {id}"),
"size": rect,
"work_area_size": rect,
"window_hiding_position": "BottomLeft",
"workspaces": {"elements": workspaces, "focused": focused_workspace},
})
}
/// A `State` of these monitors with the given one focused.
#[must_use]
pub fn state(monitors: Vec<Value>, focused_monitor: usize) -> Value {
serde_json::json!({
"monitors": {"elements": monitors, "focused": focused_monitor},
"is_paused": false,
})
}
/// A minimal `State`: one 1000x800 monitor, one workspace, one container per `(window id, exe)`,
/// each window in the place the layout says (columns of equal width).
#[must_use]
pub fn state_with_windows(windows: &[(u64, &str)]) -> Value {
let count = windows.len().max(1) as i64;
let width = 1000 / count;
let layout: Vec<[i64; 4]> = (0..count)
.map(|index| [index * width, 0, width, 800])
.collect();
let containers = windows
.iter()
.enumerate()
.map(|(index, (id, exe))| {
container(
&format!("c{id}"),
vec![window(*id, exe, Some(layout[index]))],
)
})
.collect();
state(
vec![monitor(
1,
[0, 0, 1000, 800],
vec![workspace("one", containers, 0, &layout)],
0,
)],
0,
)
}
/// How wide a numbered test video is, in pixels: sixteen blocks of eight, one per bit of the
/// frame number.
pub const NUMBERED_WIDTH: u32 = 128;
/// How tall a numbered test video is, in pixels.
pub const NUMBERED_HEIGHT: u32 = 64;
/// Writes a test video whose every frame says which frame it is.
///
/// The frame number is drawn in binary as sixteen black or white blocks, which survives lossy
/// compression. Returns `false` if there is no `ffmpeg` to make it with; tests that need a video say
/// so and stop.
#[must_use]
pub fn write_numbered_video(path: &std::path::Path, frames: u32, fps: u32) -> bool {
write_video(path, frames, fps, |frame| frame)
}
/// Like [`write_numbered_video`], but frame `n` shows the picture of frame `shown(n)`, so a video
/// can hold still (`shown` stays put) and change (`shown` advances).
#[must_use]
pub fn write_video(
path: &std::path::Path,
frames: u32,
fps: u32,
shown: impl Fn(u32) -> u32,
) -> bool {
use std::io::Write;
use std::process::Command;
use std::process::Stdio;
// the encoders to try, best first: any of them gives a video the decoder must read
for encoder in [
["-c:v", "hevc_videotoolbox", "-tag:v", "hvc1"],
["-c:v", "libx264", "-tag:v", "avc1"],
] {
let spawned = Command::new("ffmpeg")
.args([
"-y",
"-loglevel",
"error",
"-f",
"rawvideo",
"-pix_fmt",
"gray",
])
.args([
"-s",
&format!("{NUMBERED_WIDTH}x{NUMBERED_HEIGHT}"),
"-r",
&fps.to_string(),
"-i",
"-",
])
.args(["-g", "30", "-pix_fmt", "yuv420p"])
.args(encoder)
.arg(path)
.stdin(Stdio::piped())
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn();
let Ok(mut child) = spawned else {
return false;
};
if let Some(mut stdin) = child.stdin.take() {
for frame in 0..frames {
let mut row = vec![0_u8; NUMBERED_WIDTH as usize];
for bit in 0..16 {
let value = if shown(frame) >> (15 - bit) & 1 == 1 {
255
} else {
0
};
row[bit * 8..bit * 8 + 8].fill(value);
}
for _ in 0..NUMBERED_HEIGHT {
if stdin.write_all(&row).is_err() {
break;
}
}
}
}
if child.wait().is_ok_and(|status| status.success()) && path.is_file() {
return true;
}
}
false
}
/// Which frame a decoded frame of a numbered video is, read back from its blocks. The frame may
/// be any size at least sixteen pixels wide: each block is sampled at its middle.
#[must_use]
pub fn numbered_frame_index(bgra: &[u8], width: u32, height: u32) -> u32 {
let row = (height / 2) as usize * width as usize * 4;
let mut index = 0_u32;
for bit in 0..16_usize {
let x = (bit * width as usize / 16) + width as usize / 32;
// blue channel of a grey pixel
let value = bgra[row + x * 4];
index = index << 1 | u32::from(value >= 128);
}
index
}
/// Whether `ffmpeg` is there to make test videos with.
#[must_use]
pub fn ffmpeg_available() -> bool {
std::process::Command::new("ffmpeg")
.arg("-version")
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::null())
.status()
.is_ok_and(|status| status.success())
}