Files
komorebi/komorebi-recorder/src/session.rs
T
LGUG2Z eab0b6af35 fix(windowtrack): mark komorebi for Mac's border windows in the window track
komorebi for Mac draws each border as an untitled, ordinary-level NSWindow owned by
the komorebi process. The Mac listing kept them but never set `border`, so a
recording gave an agent no way to tell a border from a window. They are now marked,
which lets `lag` compare a border with its window. `border_of` stays unset: a Mac
border does not name its window.
2026-10-29 16:31:31 -07:00

942 lines
39 KiB
Rust

//! The on-disk session directory and its manifest (`session.json`).
//!
//! Raw data is never duplicated or rewritten: `timeline.jsonl` only *references* byte ranges in
//! the raw files, so streams stay separate and can be reconciled or re-indexed later.
use crate::analysis::flavor::Flavor;
use crate::capture::DisplayResult;
use crate::clock::Anchor;
use crate::clock::Timebase;
use crate::platform::Host;
use crate::sources::komorebi_events::EventSummary;
use crate::sources::komorebi_log::DetectedLevel;
use crate::sources::komorebi_log::LogSegment;
use crate::sources::komorebi_version::KomorebiVersion;
use crate::sources::managed_apps::AppRecord;
use crate::sources::oslog::StreamInfo;
use crate::sources::windowtrack::WindowTrackInfo;
use chrono::DateTime;
use chrono::Utc;
use color_eyre::eyre;
use color_eyre::eyre::WrapErr;
use serde::Deserialize;
use serde::Serialize;
#[cfg(test)]
use serde_json::Value;
use std::path::Path;
use std::path::PathBuf;
/// The version of the manifest format this build writes and the newest it reads. [`Session::manifest`] refuses a
/// manifest with a greater one.
pub const SCHEMA_VERSION: u32 = 1;
/// The recorder is (or died while) recording; the manifest is a checkpoint.
pub const STATUS_RECORDING: &str = "recording";
/// Stopped normally and fully indexed.
pub const STATUS_COMPLETE: &str = "complete";
/// The recorder died; `reindex` rebuilt the session from what was on disk.
pub const STATUS_RECOVERED: &str = "recovered";
fn complete_status() -> String {
STATUS_COMPLETE.to_string()
}
/// The name of the manifest in a session's directory.
pub const MANIFEST_FILE: &str = "session.json";
/// The name of the time-sorted index of every record in a session. It points into the raw files, which it never
/// replaces, so it can be rebuilt from them.
pub const TIMELINE_FILE: &str = "timeline.jsonl";
/// A point in time on both clocks.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Moment {
/// Nanoseconds on the master clock.
///
pub mach_ns: u64,
/// Microseconds since the Unix epoch on the wall clock, read together with `mach_ns`.
pub wall_us: i64,
}
impl Moment {
#[must_use]
/// Returns the current time on both clocks, read together as one [`Anchor`].
pub fn now() -> Self {
let anchor = Anchor::sample();
Self {
mach_ns: anchor.mach_ns,
wall_us: anchor.wall_us,
}
}
}
/// What the recorder knew about komorebi: which one it was, whether and as which process it ran, and how it was
/// logging.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct KomorebiInfo {
/// Which komorebi this was: they differ in what their events and log say. Sessions from
/// before this was recorded were all of komorebi for Mac.
#[serde(default)]
pub flavor: Flavor,
/// Whether a komorebi process was found, when the recording started or later in it.
pub running: bool,
/// The komorebi process seen most recently, if any.
pub pid: Option<i32>,
/// Every komorebi process seen during the recording, in order (it can be restarted).
#[serde(default)]
pub pids: Vec<i32>,
/// The log level komorebi was running at, and how that was found out, for the process in `pid`.
pub log_level: Option<DetectedLevel>,
/// Which komorebi each of `pids` was, as its binary reported: what a log line means depends on
/// the source it was built from.
#[serde(default)]
pub versions: Vec<KomorebiVersion>,
/// The name this recorder registered as with komorebi; komorebi's DEBUG log names it when it
/// pushes each notification, which ties an event to its handler exactly.
#[serde(default)]
pub subscriber: Option<String>,
/// Levels that actually appear in the recorded slice of komorebi's log.
pub observed_levels: Vec<String>,
/// komorebi's data directory, where its sockets are.
pub data_dir: String,
/// The directory komorebi's plaintext log was read from, where that is not `data_dir` (komorebi
/// for Windows logs into the temp directory).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub log_dir: Option<String>,
}
/// A display's capture plus where its file sits relative to the session's video time.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DisplayEntry {
#[serde(flatten)]
/// What capturing this segment produced.
pub result: DisplayResult,
/// Seconds between the session's video t=0 and this file's first frame (>= 0). A timestamp
/// `t` in session video time is at `t - offset_s` in this segment's file.
pub offset_s: f64,
/// Session video time at which this segment ended, once it has.
#[serde(default)]
pub end_s: Option<f64>,
}
/// The outcome of the self-test that checks the video against the clocks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Calibration {
/// How the readings were taken.
pub method: String,
/// The readings the result is computed from.
pub samples: Vec<CalibrationSample>,
/// The largest absolute error among the samples, in milliseconds.
pub max_abs_error_ms: f64,
/// The largest error that still passes, in milliseconds.
pub tolerance_ms: f64,
/// Whether there were samples and `max_abs_error_ms` is within `tolerance_ms`.
pub passed: bool,
}
/// One reading of the on-screen clock: where in the video it was taken, and what the clock showed against what the
/// session predicted.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CalibrationSample {
/// Where in the video the reading was taken, in seconds.
pub video_s: f64,
/// The master-clock time the session predicts for that moment, at millisecond resolution.
pub predicted_mach_ns: u64,
/// The master-clock time the on-screen clock showed in that frame, at millisecond resolution.
pub observed_mach_ns: u64,
/// Observed minus predicted, in milliseconds, wrapped to the period of the on-screen clock.
pub error_ms: f64,
}
/// The manifest of a session (`session.json`): everything the other files in the directory need to be read, and the
/// summary of what the recording was.
///
/// A manifest is written when a recording starts and rewritten at checkpoints while it runs, so one with `status`
/// [`STATUS_RECORDING`] is either a recording in progress or one whose recorder died. [`Manifest::host`] says what it was
/// recorded on, and `komorebi.flavor` which komorebi it recorded.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::Anchor;
/// use komorebi_recorder::session::Manifest;
/// use komorebi_recorder::session::Moment;
///
/// let anchor = Anchor::sample();
/// let start = Moment { mach_ns: anchor.mach_ns, wall_us: anchor.wall_us };
/// let manifest = Manifest::new(start, vec![anchor]);
///
/// // the first frame was captured a second after the recording started
/// let mut manifest = manifest;
/// manifest.video_t0_mach_ns = Some(start.mach_ns + 1_000_000_000);
/// assert_eq!(manifest.video_seconds(start.mach_ns + 3_500_000_000), 2.5);
/// assert_eq!(manifest.mach_at_video_seconds(2.5), start.mach_ns + 3_500_000_000);
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Manifest {
/// The version of this format ([`SCHEMA_VERSION`]) the manifest was written with.
pub schema_version: u32,
/// `recording`, `complete` or `recovered`.
#[serde(default = "complete_status")]
pub status: String,
/// The version of `komorebi-recorder` that wrote the session.
pub recorder_version: String,
/// What the session was recorded on. Absent in sessions from before Windows support, which
/// were all recorded on a Mac: use [`Manifest::host`], which knows that.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub host: Option<Host>,
/// The macOS version of a Mac host. Superseded by `host.os_version`; still written on a Mac so
/// that older builds of the tool read the session, and read from sessions that only have it.
#[serde(default)]
pub macos_version: Option<String>,
/// The komorebi that was recorded.
pub komorebi: KomorebiInfo,
/// What one tick of the host clock is worth (`numer / denom` nanoseconds).
pub timebase: Timebase,
/// Paired readings of the wall and master clocks taken while recording, which map komorebi's log lines onto the
/// master clock (see [`crate::clock::ClockMap`]).
pub anchors: Vec<Anchor>,
/// When the recording started.
pub start: Moment,
/// When the recording stopped, if it did: `None` while it runs and in a session whose recorder died before
/// `reindex` recovered it.
pub stop: Option<Moment>,
/// Session video t=0 on the mach clock: the earliest first frame across displays.
pub video_t0_mach_ns: Option<u64>,
/// When video capture was stopped on the mach clock.
pub video_end_mach_ns: Option<u64>,
/// Every segment of every display's video, with its place in video time.
pub displays: Vec<DisplayEntry>,
/// The byte ranges of komorebi's log that were recorded, which together make `komorebi.log`.
pub log_segments: Vec<LogSegment>,
/// The OS trace streams that were recorded, one per file under `oslog/`.
pub oslog: Vec<StreamInfo>,
/// The applications that own windows komorebi manages, which each get an OS trace stream of their own on a Mac.
pub apps: Vec<AppRecord>,
/// What was recorded of komorebi's subscriber events.
pub events: EventSummary,
/// The sampled window track (`windows.jsonl`), unless `--no-window-track` (it is on by default where windows can be listed).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub window_track: Option<WindowTrackInfo>,
/// `host-clock` when frame timestamps were verified to be on the mach clock.
pub sync_quality: String,
/// The result of `selftest`, if it was run on this session.
pub calibration: Option<Calibration>,
/// Things the recorder wants the reader to know about the recording, in words.
pub warnings: Vec<String>,
}
impl Manifest {
#[must_use]
/// Returns the manifest of a recording that has just started, on this host: its host and komorebi flavor are the
/// ones this process runs on, its status is [`STATUS_RECORDING`] and it has nothing recorded yet.
pub fn new(start: Moment, anchors: Vec<Anchor>) -> Self {
let host = Host::current();
Self {
schema_version: SCHEMA_VERSION,
status: STATUS_RECORDING.to_string(),
recorder_version: env!("CARGO_PKG_VERSION").to_string(),
macos_version: host.is_macos().then(|| host.os_version.clone()).flatten(),
host: Some(host),
komorebi: KomorebiInfo {
flavor: Flavor::of_host(),
..KomorebiInfo::default()
},
timebase: crate::clock::timebase(),
anchors,
start,
stop: None,
video_t0_mach_ns: None,
video_end_mach_ns: None,
displays: Vec::new(),
log_segments: Vec::new(),
oslog: Vec::new(),
apps: Vec::new(),
events: EventSummary::default(),
window_track: None,
sync_quality: "host-clock".to_string(),
calibration: None,
warnings: Vec::new(),
}
}
/// What this session was recorded on.
#[must_use]
pub fn host(&self) -> Host {
self.host
.clone()
.unwrap_or_else(|| Host::legacy_macos(self.macos_version.clone()))
}
/// Install the display segments: every segment's offset from the session's video t=0 (the
/// earliest first frame of all of them) and the session-level video start and end.
pub fn apply_segments(&mut self, results: Vec<DisplayResult>) {
self.video_t0_mach_ns = results.iter().filter_map(|r| r.video_t0_mach_ns).min();
let all_ended =
!results.is_empty() && results.iter().all(|r| r.video_end_mach_ns.is_some());
self.video_end_mach_ns = if all_ended {
results.iter().filter_map(|r| r.video_end_mach_ns).max()
} else {
None
};
let t0 = self.video_t0_mach_ns;
self.displays = results
.into_iter()
.map(|result| {
let offset_s = match (result.video_t0_mach_ns, t0) {
(Some(this), Some(first)) => this.saturating_sub(first) as f64 / 1e9,
_ => 0.0,
};
let end_s = result.video_end_mach_ns.map(|end| self.video_seconds(end));
DisplayEntry {
result,
offset_s,
end_s,
}
})
.collect();
}
/// The segment of `display` that has video at session video time `video_s`, if any. When a
/// display was unplugged or the machine slept there is a gap with no file to look in.
#[must_use]
pub fn segment_at(&self, display: u32, video_s: f64) -> Option<&DisplayEntry> {
// segment boundaries are sampled, not exact, so allow a frame either side
const SLACK_S: f64 = 0.05;
let (_, session_end) = self.video_span();
self.displays
.iter()
.filter(|entry| entry.result.display.id == display && entry.result.frames > 0)
.filter(|entry| {
video_s >= entry.offset_s - SLACK_S
&& video_s <= entry.end_s.unwrap_or(session_end) + SLACK_S
})
.max_by(|a, b| a.offset_s.total_cmp(&b.offset_s))
}
/// The distinct display ids that were recorded at any point.
#[must_use]
pub fn display_ids(&self) -> Vec<u32> {
let mut ids: Vec<u32> = self
.displays
.iter()
.map(|entry| entry.result.display.id)
.collect();
ids.sort_unstable();
ids.dedup();
ids
}
/// The master clock value that is `t = 0` in video time. Falls back to the recording start if
/// no frame was ever captured, so timelines remain usable for the non-video sources.
#[must_use]
pub fn video_t0(&self) -> u64 {
self.video_t0_mach_ns.unwrap_or(self.start.mach_ns)
}
#[must_use]
/// Returns the video time, in seconds, of a master-clock time. It is negative before the first frame.
pub fn video_seconds(&self, mach_ns: u64) -> f64 {
(i128::from(mach_ns) - i128::from(self.video_t0())) as f64 / 1e9
}
#[must_use]
/// Returns the master-clock time of `video_s` seconds into the video, which is zero for a time before the clock
/// started.
pub fn mach_at_video_seconds(&self, video_s: f64) -> u64 {
let ns = i128::from(self.video_t0()) + (video_s * 1e9).round() as i128;
ns.max(0) as u64
}
/// The span of video time covered by the recording, `(0, duration)`. The end is the moment
/// video capture stopped (frames are variable-rate, so the last frame can be earlier).
#[must_use]
pub fn video_span(&self) -> (f64, f64) {
let end = self
.video_end_mach_ns
.or(self.stop.map(|stop| stop.mach_ns))
.map_or(0.0, |end| self.video_seconds(end));
(0.0, end.max(0.0))
}
}
/// A session directory on disk.
#[derive(Debug, Clone)]
pub struct Session {
/// The directory the session is in.
pub dir: PathBuf,
}
/// The default parent of session directories: komorebi's data dir, under `recordings/`.
#[must_use]
pub fn default_recordings_dir() -> PathBuf {
crate::komorebi_link::data_dir().join("recordings")
}
impl Session {
/// Creates a fresh session directory: `base` if given, otherwise
/// `<komorebi data dir>/recordings/<YYYYmmddTHHMMSSZ>/`.
///
/// # Errors
///
/// Returns an error if the directory already contains a session, or cannot be created.
pub fn create(base: Option<PathBuf>, now: DateTime<Utc>) -> eyre::Result<Self> {
let dir = base.unwrap_or_else(|| {
default_recordings_dir().join(now.format("%Y%m%dT%H%M%SZ").to_string())
});
if dir.join(MANIFEST_FILE).exists() {
eyre::bail!(
"{} already contains a session; choose a different --out",
dir.display()
);
}
for sub in ["oslog/apps", "states"] {
std::fs::create_dir_all(dir.join(sub))
.wrap_err_with(|| format!("could not create {}", dir.join(sub).display()))?;
}
Ok(Self { dir })
}
/// Opens the session in `dir`.
///
/// # Errors
///
/// Returns an error if `dir` has no manifest: it is not a session.
pub fn open(dir: impl Into<PathBuf>) -> eyre::Result<Self> {
let dir = dir.into();
if !dir.join(MANIFEST_FILE).is_file() {
eyre::bail!(
"{} is not a recording session (no {MANIFEST_FILE})",
dir.display()
);
}
Ok(Self { dir })
}
#[must_use]
/// Returns `relative` inside the session's directory.
pub fn path(&self, relative: impl AsRef<Path>) -> PathBuf {
self.dir.join(relative)
}
/// Reads the session's manifest.
///
/// # Errors
///
/// Returns an error if the manifest cannot be read, is not a valid manifest, or was written by a newer
/// `komorebi-recorder` than this one ([`SCHEMA_VERSION`] is greater than what this build reads).
pub fn manifest(&self) -> eyre::Result<Manifest> {
let path = self.path(MANIFEST_FILE);
let text = std::fs::read_to_string(&path)
.wrap_err_with(|| format!("could not read {}", path.display()))?;
let manifest: Manifest = serde_json::from_str(&text)
.wrap_err_with(|| format!("{} is not a valid session manifest", path.display()))?;
if manifest.schema_version > SCHEMA_VERSION {
eyre::bail!(
"{} was written by a newer komorebi-recorder (schema {}, this build reads up to {})",
path.display(),
manifest.schema_version,
SCHEMA_VERSION
);
}
Ok(manifest)
}
/// Writes the manifest. It is written to a temporary file and renamed over the old one, so a reader or a crash never
/// sees a half-written manifest.
///
/// # Errors
///
/// Returns an error if the manifest cannot be serialized or the files cannot be written.
pub fn write_manifest(&self, manifest: &Manifest) -> eyre::Result<()> {
let path = self.path(MANIFEST_FILE);
let temporary = self.path(format!("{MANIFEST_FILE}.tmp"));
std::fs::write(&temporary, serde_json::to_string_pretty(manifest)?)?;
// rename so a reader (or a crash) never sees a half-written manifest
std::fs::rename(&temporary, &path)?;
Ok(())
}
/// Writes the generated `README.md` for this session (see [`readme`]).
///
/// # Errors
///
/// Returns an error if the file cannot be written.
pub fn write_readme(&self, manifest: &Manifest) -> eyre::Result<()> {
std::fs::write(self.path("README.md"), readme(&self.dir, manifest))?;
Ok(())
}
}
/// The generated `README.md`: what every file is and the exact commands to query this session.
#[must_use]
pub fn readme(dir: &Path, manifest: &Manifest) -> String {
let session = shell_quote(&dir.display().to_string());
let host = manifest.host();
let (_, duration) = manifest.video_span();
let mut out = String::new();
out.push_str("# komorebi-recorder session\n\n");
out.push_str(&format!(
"Recorded with komorebi-recorder {} on {}.\nVideo duration: about {:.1}s. Video time `00:00.000` is the first captured frame.\n\n",
manifest.recorder_version,
manifest.host().describe(),
duration
));
out.push_str("## Investigating a bug\n\n");
out.push_str(&format!(
"Start with what the user marked and described, then what the recording shows around it:\n\n\
```sh\n\
komorebi-recorder brief {session}\n\
komorebi-recorder guide # how to investigate, step by step\n\
komorebi-recorder view {session} # the same, in a window you can play and scrub\n\
```\n\n\
Every command takes `--json`. `annotate` adds a bug region (a start, an end and what is wrong)\n\
to `annotations.jsonl`; `state`, `diff`, `events`, `trace`, `window`, `code`, `search`,\n\
`changes` and `sheet` dig in.\n\n"
));
out.push_str("## How to read it\n\n");
out.push_str(
"Every second of video maps to the exact records from every other source. Use the\n\
`komorebi-recorder` CLI from this binary (this directory is self-contained):\n\n",
);
out.push_str(&format!(
"```sh\n\
# what happened around 12.5s into the video? (komorebi log + events + OS trace, +-1s)\n\
komorebi-recorder at {session} 12.5 --window 1s\n\
# narrow to one app's OS trace, or one source\n\
komorebi-recorder at {session} 00:12.500 --app Ghostty\n\
komorebi-recorder at {session} 12.5 --source events\n\
# a span\n\
komorebi-recorder range {session} 10 15\n\
# a per-second digest of the whole recording\n\
komorebi-recorder summary {session}\n\
# reverse: a log line / event / UTC time -> video timecode\n\
komorebi-recorder locate {session} --log-line 120\n\
komorebi-recorder locate {session} --event-seq 7\n\
komorebi-recorder locate {session} --utc 2026-10-26T19:43:35.062613Z\n\
# extract PNG frames to look at (needs ffmpeg)\n\
komorebi-recorder frames {session} 12.5 14.0\n\
# rebuild timeline.jsonl from the raw files\n\
komorebi-recorder reindex {session}\n\
```\n\n\
Add `--json` to any query for machine-readable output.\n\n"
));
out.push_str("## Files\n\n");
out.push_str("| File | What it is |\n|---|---|\n");
out.push_str("| `session.json` | Manifest: versions, displays, clock anchors, log segments, OS-trace streams and apps, warnings |\n");
out.push_str("| `video-<displayID>[-<n>].mp4` | Screen recording of one display. Variable frame rate: frames only exist when the screen changed. A display that was unplugged, whose stream stopped, or that changed resolution has several numbered segments, each a complete file; `session.json` lists every segment with its time span |\n");
out.push_str("| `frames-<displayID>[-<n>].csv` | Every frame's host-clock timestamp (`pts_mach_ns`) and when it was received |\n");
out.push_str("| `annotations.jsonl` | Bug regions (a start, an end and what is wrong), notes and findings, appended by the viewer and `annotate`. Never rewritten |\n");
out.push_str("| `recorder.jsonl` | What happened to the recording environment: displays connected/disconnected, sleep/wake, screen lock, restarts of log streams or komorebi. Shown as the `recorder` source |\n");
out.push_str("| `komorebi.log` | The exact byte slice of komorebi's own log for this recording (UTC timestamps) |\n");
out.push_str("| `events.jsonl` | Every komorebi subscriber notification: `{seq, recv_wall_us, recv_mach_ns, event, state_id}` |\n");
out.push_str("| `states/<id>.json` | Full komorebi `State`, stored only when it changed (referenced by `state_id`) |\n");
out.push_str(
"| `state-start.json`, `state-end.json` | `State` when recording started / stopped |\n",
);
if manifest.window_track.is_some() {
out.push_str("| `windows.jsonl` | The window track: every top-level window's rect and state, front to back, written when something changed and in full once a second: `{mach_ns, key?, windows: [{id, owner, title?, rect: [l,t,r,b], visible, minimized, cloaked?, border?, border_of?}]}`; `border` marks komorebi's own border windows (Windows and macOS; `border_of` is Windows only). `sheet --windows` draws it on frames |
");
}
out.push_str(os_trace_rows(&host));
out.push_str("| `timeline.jsonl` | Merged index of every record, sorted by time, pointing into the raw files |\n\n");
out.push_str("## Gaps are expected\n\n");
out.push_str(
"Docking, undocking, sleep, wake and screen lock change what can be recorded. The recorder keeps\n\
going through all of them: a display that disappears has its video finalized on the spot and a new\n\
segment starts when it returns, and a `log stream` or komorebi that goes away is picked up again.\n\
Whatever happened is in `recorder.jsonl` (`komorebi-recorder at <session> <time> --source recorder`).\n",
);
out.push_str(if host.is_windows() {
"Whether the host clock counts the time a machine sleeps is measured, not assumed: `recorder.jsonl`\n\
says for each sleep how long it was by the wall clock and how far the host clock moved.\n\n"
} else {
"While the machine sleeps the host clock pauses, so video time skips the sleep rather than showing\n\
a gap.\n\n"
});
if manifest.status != STATUS_COMPLETE {
out.push_str("## This session was recovered\n\n");
out.push_str(
"The recorder did not finish normally. Everything that had been written was kept (video is\n\
fragmented so it plays up to the last fragment) and `reindex` rebuilt this session from it.\n\
The end of the recording is approximate and a second or two of video may be missing.\n\n",
);
}
out.push_str("## Clocks\n\n");
out.push_str(if host.is_windows() {
"The master clock is the host performance counter (`QueryPerformanceCounter`, ns). Video frame\n\
timestamps are on it directly, and the OS trace's records carry it as `hostNs`."
} else {
"The master clock is the host monotonic clock (`mach_absolute_time`, ns). Video frame\n\
timestamps and the unified log's `machTimestamp` are on it directly."
});
out.push_str(
" komorebi's log lines\n\
(UTC wall clock) are mapped onto it with the `anchors` in `session.json`. Subscriber events\n\
are stamped on receipt, and komorebi sends them after handling the event, so a stamp is when\n\
the handler *finished*; the start of the handler is in `komorebi.log` (`komorebi-recorder trace`\n\
ties the two together).\n\n",
);
if !manifest.warnings.is_empty() {
out.push_str("## Warnings recorded\n\n");
for warning in &manifest.warnings {
out.push_str(&format!("- {warning}\n"));
}
out.push('\n');
}
out.push_str("## Privacy\n\n");
out.push_str(if host.is_windows() {
"The video contains whatever was on screen, and komorebi's events, state and log contain window\n\
titles and program names. Review this directory before sharing it.\n"
} else {
"The video contains whatever was on screen, and application logs can contain window titles\n\
and URLs. Review this directory before sharing it. `<private>` values in the OS log are\n\
redacted by macOS (no sudo or SIP changes are made by this tool).\n"
});
out
}
/// The OS trace files a session of this host has, as rows of the README's table of files.
fn os_trace_rows(host: &Host) -> &'static str {
if host.is_windows() {
"| `oslog/system.ndjson` | What the OS told komorebi: Windows' WinEvents for every top-level window (shown, hidden, cloaked, focused, moved, renamed, destroyed), repeated moves folded together |\n\
| `oslog/eventlog.ndjson` | The System Event Log: warnings, errors, and the providers that talk about displays, power and the GPU |\n"
} else {
"| `oslog/komorebi.ndjson` | macOS unified log for the komorebi process (system frameworks as the daemon sees them) |\n\
| `oslog/system.ndjson` | macOS unified log: accessibility / HIServices / workspace subsystems |\n\
| `oslog/apps/<exe>-<pid>.ndjson` | macOS unified log for one managed application process |\n"
}
}
/// `value` as one argument to a shell: left alone if it needs no quoting, else in the quotes this
/// machine's shells understand (single quotes in a unix shell and `PowerShell`, which cmd.exe does not
/// read, so double quotes where the host is Windows).
fn shell_quote(value: &str) -> String {
quote_for(cfg!(windows), value)
}
fn quote_for(windows: bool, value: &str) -> String {
let plain = |c: char| {
c.is_ascii_alphanumeric()
|| matches!(c, '/' | '.' | '-' | '_' | ':' | '+')
|| (windows && c == '\\')
};
if value.chars().all(plain) {
value.to_string()
} else if windows {
format!("\"{}\"", value.replace('"', "\\\""))
} else {
format!("'{}'", value.replace('\'', "'\\''"))
}
}
#[cfg(test)]
mod tests {
use super::*;
use chrono::TimeZone;
fn manifest() -> Manifest {
let start = Moment {
mach_ns: 1_000_000_000_000,
wall_us: 1_800_000_000_000_000,
};
Manifest::new(
start,
vec![Anchor {
wall_us: start.wall_us,
mach_ns: start.mach_ns,
}],
)
}
#[test]
fn paths_are_quoted_the_way_the_hosts_shell_reads_them() {
assert_eq!(quote_for(false, "/tmp/a b"), "'/tmp/a b'");
assert_eq!(quote_for(false, "it's"), r"'it'\''s'");
assert_eq!(quote_for(false, "/tmp/plain"), "/tmp/plain");
// cmd.exe does not read single quotes; both it and PowerShell read double ones
assert_eq!(
quote_for(true, r"C:\Users\me\komorebi"),
r"C:\Users\me\komorebi"
);
assert_eq!(
quote_for(true, r"C:\Users\Jane Doe\x"),
r#""C:\Users\Jane Doe\x""#
);
}
#[test]
fn the_readme_describes_the_os_trace_the_hosts_session_has() {
let mut manifest = manifest();
manifest.host = Some(Host {
os: "windows".to_string(),
arch: "x86_64".to_string(),
os_version: Some("10.0.26100".to_string()),
clock: crate::platform::ClockKind::Qpc,
});
let text = readme(Path::new("/tmp/s"), &manifest);
assert!(text.contains("oslog/eventlog.ndjson"));
assert!(text.contains("QueryPerformanceCounter"));
assert!(!text.contains("unified log"), "{text}");
// a Mac's, whichever host runs this test
let mut mac_manifest = self::tests::manifest();
mac_manifest.host = Some(Host {
os: "macos".to_string(),
arch: "aarch64".to_string(),
os_version: Some("26.0".to_string()),
clock: crate::platform::ClockKind::Mach,
});
let mac = readme(Path::new("/tmp/s"), &mac_manifest);
assert!(mac.contains("macOS unified log"));
}
#[test]
fn a_manifest_from_before_hosts_were_recorded_was_recorded_on_a_mac() {
let mut value = serde_json::to_value(manifest()).expect("serialize");
let object = value.as_object_mut().expect("object");
object.remove("host");
object.insert("macos_version".into(), "26.0".into());
let old: Manifest = serde_json::from_value(value).expect("an old manifest parses");
let host = old.host();
assert!(host.is_macos());
assert_eq!(host.os_version.as_deref(), Some("26.0"));
assert_eq!(host.clock, crate::platform::ClockKind::Mach);
}
#[test]
fn a_new_manifest_records_the_host_it_was_made_on() {
let host = manifest().host();
assert_eq!(host.os, std::env::consts::OS);
assert_eq!(host.clock, crate::platform::clock::KIND);
}
#[test]
fn video_time_is_relative_to_the_first_frame() {
let mut manifest = manifest();
manifest.video_t0_mach_ns = Some(1_002_000_000_000);
assert!((manifest.video_seconds(1_004_500_000_000) - 2.5).abs() < 1e-9);
assert!((manifest.video_seconds(1_001_000_000_000) + 1.0).abs() < 1e-9);
assert_eq!(manifest.mach_at_video_seconds(2.5), 1_004_500_000_000);
}
#[test]
fn video_time_falls_back_to_the_recording_start() {
let manifest = manifest();
assert_eq!(manifest.video_t0(), 1_000_000_000_000);
}
#[test]
fn manifests_roundtrip_through_json() {
let manifest = manifest();
let text = serde_json::to_string_pretty(&manifest).expect("serialize");
let back: Manifest = serde_json::from_str(&text).expect("parse");
assert_eq!(back, manifest);
}
#[test]
fn creates_opens_and_refuses_to_overwrite_a_session() {
let base =
std::env::temp_dir().join(format!("komorebi-recorder-session-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&base);
let now = Utc
.with_ymd_and_hms(2026, 10, 26, 19, 43, 35)
.single()
.expect("time");
let session = Session::create(Some(base.clone()), now).expect("create");
assert!(session.path("oslog/apps").is_dir());
assert!(session.path("states").is_dir());
assert!(Session::open(&base).is_err(), "no manifest yet");
session.write_manifest(&manifest()).expect("write");
assert!(!session.path("session.json.tmp").exists());
assert_eq!(
Session::open(&base)
.expect("open")
.manifest()
.expect("manifest"),
manifest()
);
assert!(
Session::create(Some(base), now).is_err(),
"must not clobber a session"
);
}
#[test]
fn rejects_manifests_from_the_future() {
let base =
std::env::temp_dir().join(format!("komorebi-recorder-future-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&base);
let session = Session::create(Some(base), Utc::now()).expect("create");
let mut future = manifest();
future.schema_version = SCHEMA_VERSION + 1;
session.write_manifest(&future).expect("write");
let error = session.manifest().expect_err("too new").to_string();
assert!(error.contains("newer komorebi-recorder"), "{error}");
}
#[test]
fn the_readme_embeds_the_session_path_and_every_query() {
let text = readme(Path::new("/tmp/a b/session"), &manifest());
assert!(
text.contains(&shell_quote("/tmp/a b/session")),
"paths with spaces are quoted"
);
for command in [
"at ", "range ", "summary ", "locate ", "frames ", "reindex ", "brief ", "guide",
] {
assert!(
text.contains(&format!("komorebi-recorder {command}")),
"{command}"
);
}
}
fn segment(display: u32, number: u32, t0: u64, end: Option<u64>) -> DisplayResult {
DisplayResult {
display: crate::capture::DisplayDescriptor {
id: display,
frame: [0.0, 0.0, 100.0, 100.0],
width_points: 100,
height_points: 100,
asleep: false,
scale: 1.0,
},
segment: number,
scale: 1.0,
width_px: 100,
height_px: 100,
codec: crate::capture::Codec::Hevc,
file: crate::capture::video_file_name(display, number),
frames_file: crate::capture::frames_file_name(display, number),
video_t0_mach_ns: Some(t0),
video_end_mach_ns: end,
end_reason: end.map(|_| crate::capture::EndReason::Stopped),
frames: 10,
dropped: 0,
idle_callbacks: 0,
latency: crate::capture::LatencyStats::default(),
error: None,
}
}
const S: u64 = 1_000_000_000;
/// Display 1 is recorded for 0-10s, unplugged, and back for 30-40s; display 2 for 2-40s.
fn docked_and_undocked() -> Manifest {
let mut manifest = manifest();
manifest.apply_segments(vec![
segment(1, 1, 100 * S, Some(110 * S)),
segment(2, 1, 102 * S, Some(140 * S)),
segment(1, 2, 130 * S, Some(140 * S)),
]);
manifest.video_end_mach_ns = Some(140 * S);
manifest
}
#[test]
fn segments_are_placed_relative_to_the_first_frame_of_any_of_them() {
let manifest = docked_and_undocked();
assert_eq!(manifest.video_t0_mach_ns, Some(100 * S));
let by_file = |file: &str| {
manifest
.displays
.iter()
.find(|entry| entry.result.file == file)
.expect("segment")
};
assert!((by_file("video-1.mp4").offset_s - 0.0).abs() < 1e-9);
assert!((by_file("video-2.mp4").offset_s - 2.0).abs() < 1e-9);
assert!((by_file("video-1-2.mp4").offset_s - 30.0).abs() < 1e-9);
assert_eq!(by_file("video-1.mp4").end_s, Some(10.0));
assert_eq!(by_file("video-1-2.mp4").end_s, Some(40.0));
assert_eq!(manifest.display_ids(), vec![1, 2]);
assert_eq!(manifest.video_span(), (0.0, 40.0));
}
#[test]
fn the_right_segment_is_found_and_a_gap_has_none() {
let manifest = docked_and_undocked();
let at = |display: u32, t: f64| {
manifest
.segment_at(display, t)
.map(|entry| entry.result.file.as_str())
};
assert_eq!(at(1, 5.0), Some("video-1.mp4"));
assert_eq!(at(1, 35.0), Some("video-1-2.mp4"));
assert_eq!(
at(1, 20.0),
None,
"display 1 was unplugged between 10s and 30s"
);
assert_eq!(at(2, 20.0), Some("video-2.mp4"), "display 2 never stopped");
assert_eq!(at(2, 1.0), None, "display 2 had not started yet");
assert_eq!(at(9, 5.0), None, "no such display");
// a frame of slack at each boundary absorbs sampling error
assert_eq!(at(1, 10.03), Some("video-1.mp4"));
assert_eq!(at(1, 10.2), None);
}
#[test]
fn a_segment_still_being_recorded_extends_to_the_end_of_the_session() {
let mut manifest = manifest();
manifest.apply_segments(vec![segment(1, 1, 100 * S, None)]);
manifest.stop = Some(Moment {
mach_ns: 160 * S,
wall_us: 0,
});
manifest.video_end_mach_ns = Some(160 * S);
assert!(manifest.segment_at(1, 50.0).is_some());
assert!(manifest.segment_at(1, 59.9).is_some());
}
#[test]
fn manifests_from_before_segments_and_status_existed_still_load() {
// exactly the shape a pre-segment recorder wrote: no `status`, no segment fields
let mut value = serde_json::to_value(manifest()).expect("value");
let object = value.as_object_mut().expect("object");
object.remove("status");
object.remove("video_end_mach_ns");
object
.get_mut("komorebi")
.and_then(Value::as_object_mut)
.expect("komorebi")
.remove("pids");
let old: Manifest = serde_json::from_value(value).expect("an old manifest parses");
assert_eq!(
old.status, STATUS_COMPLETE,
"an old manifest was a finished recording"
);
assert!(old.komorebi.pids.is_empty());
}
}