mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-17 06:11:21 +01:00
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:
1 parent
1006ec2570
commit
05d87908c5
16 files changed
+6462
-13
No files matched your search
Generated
+102
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
]
|
||||
]
|
||||
|
||||
@@ -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.
|
||||
@@ -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"
|
||||
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
@@ -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
@@ -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(())
|
||||
}
|
||||
@@ -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(())
|
||||
}
|
||||
@@ -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;
|
||||
@@ -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
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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())
|
||||
}
|
||||
Reference in new issue
Block a user