feat(doctor): check what a recording leans on

`doctor` says what the machine can do for a recording: which komorebi runs and
how it logs, whether the screen can be captured and played back, the displays
and their scale, and the host clock. Probes measure one thing: the clock across
a sleep, a short capture, a decode, whether komorebi would tile a window of
ours.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent 3e30d81bc5
commit e3a1f01fd7
6 files changed
+1647 -3

No files matched your search

+1
View File
@@ -32,6 +32,7 @@ Three things are worth knowing before reading a session:
changed would stop older sessions being readable by newer builds and the reverse.
- The master clock is not the wall clock. On macOS it pauses while the machine sleeps, so video time skips a sleep
instead of showing a hole. Whether the performance counter counts a suspend on Windows is measured, not assumed.
(`doctor --probe clock` measures it.)
- A timestamp is a plain `u64` of nanoseconds. Nothing in the type system says which clock it is on: that is held by
convention, and by the tests that place records at known times.
+15 -1
View File
@@ -44,7 +44,8 @@ directory; a session recorded on one OS can be investigated on the other. What d
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.
`komorebi-recorder doctor` says what the machine can do, and `komorebi-recorder record --no-video` records without the
screen.
The recorder window keeps itself out of the video (Windows 10 version 2004 or later).
## Before you record
@@ -100,6 +101,19 @@ display (or no Screen Recording permission), or when what is on the screen must
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.
### Checking your setup
```
komorebi-recorder doctor # what this machine can do for a recording
komorebi-recorder doctor --json # the same, for a bug report
```
`doctor` says which komorebi is running (binary, version and commit, log level, whether it answers a state query and
where its log is), whether the screen can be captured and played back, whether `ffmpeg` is there, the displays and
their scale, and the host clock. Anything wrong is listed at the end in plain words. `doctor --probe clock|capture|decode`
measures one thing instead; `--probe clock` shows what the clock does while the machine sleeps (put it to sleep while it
runs).
## Docking, sleep and lock
The set of displays, and whether ScreenCaptureKit streams stay alive, changes underneath a laptop all the time. The
+125
View File
@@ -0,0 +1,125 @@
//! `doctor`: what this machine can do for a recording, and probes that measure what a recording
//! leans on.
//!
//! With no `--probe`, `doctor` describes the machine ([`crate::doctor::report`]) and prints it as
//! text, or with `--json` as the `doctor/1` envelope whose warnings are the report's. With
//! `--probe`, it runs one measurement and prints what it found, as text or as the `probe/1`
//! envelope:
//!
//! | `--probe` | Measures | Takes | Runs |
//! |---|---|---|---|
//! | `clock` | whether the master clock keeps counting while the machine sleeps | `--seconds` | [`crate::doctor::probe_clock`] |
//! | `capture` | what the capture pipeline produces from the screen alone | `--seconds`, `--out` | [`crate::doctor::probe_capture`] |
//! | `decode` | first-frame time, speed and exactness of seeking of a recorded video | `--file` (required) | [`crate::doctor::probe_decode`] |
//! | `window` | what komorebi for Windows says about whether it manages a window | `--hwnd` (required) | [`crate::doctor::probe_window`] |
//!
//! A probe that needs an argument and is not given it fails with a usage error. The clock and
//! capture probes print to standard error what they are about to do before they start.
//!
//! The probes need the outside world (sleep, a screen, a video file, komorebi), so they have no
//! example.
use super::print_json;
use crate::analysis::envelope::Envelope;
use crate::doctor;
use crate::doctor::ProbeReport;
use clap::Args;
use clap::ValueEnum;
use color_eyre::eyre;
use color_eyre::eyre::WrapErr;
use std::path::PathBuf;
use std::time::Duration;
/// A measurement `doctor --probe` can take.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum Probe {
/// Whether the master clock keeps counting while the machine sleeps (put it to sleep and wake
/// it while this runs)
Clock,
/// Record the screen alone for a while and report what the capture pipeline produced
Capture,
/// Decode a recorded video: first-frame time, speed and whether seeking is exact
Decode,
/// Ask komorebi (for Windows) whether it would manage a window, and why
Window,
}
/// The arguments of `doctor`.
#[derive(Args, Debug)]
pub struct DoctorArgs {
/// Measure one thing instead of describing the machine
#[arg(long, value_enum)]
pub probe: Option<Probe>,
/// How long the clock and capture probes run
#[arg(long, default_value_t = 60.0, value_name = "SECONDS")]
pub seconds: f64,
/// The video file for the decode probe
#[arg(long, value_name = "FILE")]
pub file: Option<PathBuf>,
/// The window handle for the window probe
#[arg(long, value_name = "HWND")]
pub hwnd: Option<u32>,
/// Where the capture probe puts its recording [default: next to the others]
#[arg(long, value_name = "DIR")]
pub out: Option<PathBuf>,
/// Machine-readable JSON output
#[arg(long)]
pub json: bool,
}
pub(super) fn doctor(args: &DoctorArgs) -> eyre::Result<()> {
let Some(kind) = args.probe else {
let report = doctor::report();
let warnings = report.warnings.clone();
if args.json {
return print_json(&Envelope::ok(doctor::SCHEMA_DOCTOR, report).warnings(warnings));
}
print!("{}", doctor::text(&report));
return Ok(());
};
let probe = match kind {
Probe::Clock => {
eprintln!(
"reading the clocks for {:.0} s: put the machine to sleep and wake it while this \
runs to learn what the master clock does then",
args.seconds
);
ProbeReport::Clock(doctor::probe_clock(
args.seconds,
Duration::from_millis(250),
))
}
Probe::Capture => {
eprintln!(
"recording the screen for {:.0} s: leave it still for part of that",
args.seconds
);
ProbeReport::Capture(doctor::probe_capture(args.seconds, args.out.clone())?)
}
Probe::Decode => {
let file = args
.file
.as_ref()
.ok_or_else(|| crate::analysis::envelope::usage("--probe decode needs --file"))?;
ProbeReport::Decode(
doctor::probe_decode(file)
.wrap_err_with(|| format!("could not decode {}", file.display()))?,
)
}
Probe::Window => {
let hwnd = args
.hwnd
.ok_or_else(|| crate::analysis::envelope::usage("--probe window needs --hwnd"))?;
ProbeReport::Window(doctor::probe_window(hwnd)?)
}
};
if args.json {
return print_json(&Envelope::ok(doctor::SCHEMA_PROBE, probe));
}
print!("{}", doctor::probe_text(&probe));
Ok(())
}
+16 -2
View File
@@ -5,6 +5,7 @@
//! 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 doctor;
mod record;
use crate::session::Session;
@@ -12,8 +13,10 @@ use clap::Args;
use clap::Parser;
use clap::Subcommand;
use color_eyre::eyre;
use serde::Serialize;
use std::path::PathBuf;
pub use doctor::DoctorArgs;
pub use record::RecordArgs;
/// The command line of `komorebi-recorder`.
@@ -44,6 +47,8 @@ pub enum Command {
Record(RecordArgs),
/// List the displays that can be recorded
Displays,
/// What this machine can do for a recording, and probes that measure what one leans on
Doctor(DoctorArgs),
/// Rebuild a session's timeline from its raw files, recovering it first if the recorder died
Reindex(ReindexArgs),
/// Check the video-to-clock alignment against a rendered on-screen clock
@@ -74,12 +79,20 @@ pub struct SelftestArgs {
pub out: Option<PathBuf>,
}
/// Print `value` as pretty JSON.
pub(crate) fn print_json(value: &impl Serialize) -> eyre::Result<()> {
println!("{}", serde_json::to_string_pretty(value)?);
Ok(())
}
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
match self {
Self::Doctor(args) => args.json,
_ => false,
}
}
}
@@ -116,6 +129,7 @@ pub fn run(command: Command) -> eyre::Result<()> {
Command::Gui(args) => crate::app::run(args),
Command::Record(args) => record::record(&args),
Command::Displays => record::displays(),
Command::Doctor(args) => doctor::doctor(&args),
Command::Reindex(args) => reindex(&args),
Command::Selftest(args) => crate::selftest::run(&args),
Command::SelftestClock => crate::selftest::run_clock(),
File diff suppressed because it is too large. Load diff
+2
View File
@@ -57,6 +57,7 @@
//! | [`cli`] | the command line |
//! | [`app`] | the recorder window |
//! | [`av`] and [`selftest`] | decoding the recorded video and checking it against the clocks |
//! | [`doctor`] | what a recording leans on, and probes that measure it |
//!
//! # What is not supported
//!
@@ -76,6 +77,7 @@ pub mod av;
pub mod capture;
pub mod cli;
pub mod clock;
pub mod doctor;
pub mod frames;
pub mod incidents;
pub mod komorebi_link;