Files
komorebi/docs/PLATFORM.md
T
LGUG2Z d5eacecef8 feat(clock): the master clock
Every record in a session is stamped on one monotonic clock:
`mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows, behind a
`platform` facade with a third `unsupported` host that builds anywhere. Anchors
pair that clock with the wall clock, a map interpolates between them, and a jump
detector notices sleep and clock steps by comparing how far each moved. Video
timecodes are parsed and printed here too.

`Host` and `ClockKind` say what a session was recorded on.
2026-10-27 22:22:56 -07:00

3.9 KiB

Platform support

This document gathers, in one place, what differs by operating system. Most of the details are written down on the items that implement them; here the same questions are answered once per host, so that someone who has to run the recorder on a machine, or change it for one, does not have to read the code to find out.

The recorder is built for macOS and Windows. A third host, unsupported, builds on anything else so that the commands that only read a session directory work on a Linux agent box; recording there says that it cannot.

Status

host built run
macOS (Apple silicon) yes yes: written and run on macOS 26
Windows x86_64 yes, natively on windows-latest and cross-compiled from a Mac no: type-checked and cross-built only
Windows ARM64 yes, cross-built on an x86_64 runner no
anything else the unsupported host builds nothing records

Nothing that touches a real Windows desktop has been seen running: the Windows host was written from the Windows API documentation and komorebi for Windows' source, and every claim below about Windows says what the code does, not what was observed.

Vocabulary

  • Host: the OS the recorder runs on. It decides how the screen is captured, which clock is read, how the OS says it is going to sleep and what the OS trace is made of.
  • Flavor: which komorebi is being recorded. There is one per OS, and a recorder watches the one on its own host, but a session records its flavor, so a session from either can be read on either host.
  • Master clock: the host's monotonic clock, in nanoseconds, on which every record in a session is stamped.
  • Session: the directory a recording is written to.
  • Segment: one contiguous stretch of one display's video, a file of its own. A display that is unplugged and plugged in again has two.

The same questions, per host

The master clock

macOS Windows unsupported
clock mach_absolute_time, scaled by mach_timebase_info QueryPerformanceCounter, scaled by QueryPerformanceFrequency (10 MHz when Windows will not say) the time since the first reading in the process, plus one second so that no reading is zero
host.clock in the manifest mach qpc std
counts the time the machine sleeps no not known: measured, not assumed no
other clocks read beside it mach_continuous_time, which counts sleep QueryInterruptTime, which counts sleep, and QueryUnbiasedInterruptTimePrecise, which does not none

Video frame times and the OS trace are on the master clock already on both hosts (ScreenCaptureKit and the unified log's machTimestamp on a Mac; Windows.Graphics.Capture on Windows). The field names ending in _mach_ns are spelled that way on every host: see the architecture.

Degraded modes

  • record --no-video records everything but the screen, on the same clock. It asks the system nothing about displays and needs no permission.
  • record --no-komorebi skips touching komorebi altogether, and --no-oslog skips the OS trace.
  • A komorebi that is not running when a recording starts is not an error: it is noted, and the recorder subscribes when it appears.
  • The unsupported host investigates sessions and refuses to record.

Advice by audience

  • Recording on macOS. Grant Screen Recording to the terminal, and start komorebi with --log-level trace.
  • Recording on Windows. There is nothing to grant. Use komorebi-recorder.exe for commands, since the GUI build prints nowhere, and start komorebi with --log-level debug and RUST_LOG=komorebi=debug.
  • Investigating on any host. A session is read the same everywhere. ffmpeg is needed only for frames and selftest.
  • Changing code that has a host-specific part. Provide the function on every host, and run just check-windows from a Mac: it type-checks every cfg(windows) line, tests included.