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.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent ab0b943ba0
commit d5eacecef8
17 files changed
+2676 -1

No files matched your search

Generated
+449
View File
@@ -2,6 +2,21 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "addr2line"
version = "0.25.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
dependencies = [
"gimli",
]
[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
[[package]]
name = "anstream"
version = "1.0.0"
@@ -52,12 +67,33 @@ dependencies = [
"windows-sys 0.60.2",
]
[[package]]
name = "backtrace"
version = "0.3.76"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
dependencies = [
"addr2line",
"cfg-if",
"libc",
"miniz_oxide",
"object",
"rustc-demangle",
"windows-link",
]
[[package]]
name = "bitflags"
version = "2.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
[[package]]
name = "cfg-if"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "clap"
version = "4.6.1"
@@ -99,12 +135,45 @@ version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
[[package]]
name = "color-eyre"
version = "0.6.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e5920befb47832a6d61ee3a3a846565cfa39b331331e68a3b1d1116630f2f26d"
dependencies = [
"backtrace",
"color-spantrace",
"eyre",
"indenter",
"once_cell",
"owo-colors",
"tracing-error",
]
[[package]]
name = "color-spantrace"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b8b88ea9df13354b55bc7234ebcce36e6ef896aca2e42a15de9e10edce01b427"
dependencies = [
"once_cell",
"owo-colors",
"tracing-core",
"tracing-error",
]
[[package]]
name = "colorchoice"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
[[package]]
name = "dyn-clone"
version = "1.0.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
[[package]]
name = "errno"
version = "0.3.14"
@@ -115,25 +184,65 @@ dependencies = [
"windows-sys 0.52.0",
]
[[package]]
name = "eyre"
version = "0.6.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7cd915d99f24784cdc19fd37ef22b97e3ff0ae756c7e492e9fbfe897d61e2aec"
dependencies = [
"indenter",
"once_cell",
]
[[package]]
name = "gimli"
version = "0.32.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
[[package]]
name = "heck"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
[[package]]
name = "indenter"
version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "964de6e86d545b246d84badc0fef527924ace5134f30641c203ef52ba83f58d5"
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
[[package]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "komorebi-recorder"
version = "0.1.0"
dependencies = [
"clap",
"color-eyre",
"libc",
"schemars",
"serde",
"serde_json_lenient",
"windows",
]
[[package]]
name = "lazy_static"
version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
[[package]]
name = "libc"
version = "0.2.186"
@@ -146,12 +255,54 @@ version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "memchr"
version = "2.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
[[package]]
name = "miniz_oxide"
version = "0.8.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
dependencies = [
"adler2",
]
[[package]]
name = "object"
version = "0.37.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
dependencies = [
"memchr",
]
[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "once_cell_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "owo-colors"
version = "4.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d211803b9b6b570f68772237e415a029d5a50c65d382910b879fb19d3271f94d"
[[package]]
name = "pin-project-lite"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "proc-macro2"
version = "1.0.106"
@@ -170,6 +321,32 @@ dependencies = [
"proc-macro2",
]
[[package]]
name = "ref-cast"
version = "1.0.25"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d"
dependencies = [
"ref-cast-impl",
]
[[package]]
name = "ref-cast-impl"
version = "1.0.25"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "rustc-demangle"
version = "0.1.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"
[[package]]
name = "rustix"
version = "1.1.4"
@@ -183,6 +360,112 @@ dependencies = [
"windows-sys 0.52.0",
]
[[package]]
name = "ryu"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
[[package]]
name = "schemars"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a2b42f36aa1cd011945615b92222f6bf73c599a102a300334cd7f8dbeec726cc"
dependencies = [
"dyn-clone",
"ref-cast",
"schemars_derive",
"serde",
"serde_json",
]
[[package]]
name = "schemars_derive"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7d115b50f4aaeea07e79c1912f645c7513d81715d0420f8bc77a18c6260b307f"
dependencies = [
"proc-macro2",
"quote",
"serde_derive_internals",
"syn",
]
[[package]]
name = "serde"
version = "1.0.228"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde_core"
version = "1.0.228"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.228"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "serde_derive_internals"
version = "0.29.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "serde_json"
version = "1.0.149"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
dependencies = [
"itoa",
"memchr",
"serde",
"serde_core",
"zmij",
]
[[package]]
name = "serde_json_lenient"
version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0e033097bf0d2b59a62b42c18ebbb797503839b26afdda2c4e1415cb6c813540"
dependencies = [
"itoa",
"memchr",
"ryu",
"serde",
]
[[package]]
name = "sharded-slab"
version = "0.1.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
dependencies = [
"lazy_static",
]
[[package]]
name = "strsim"
version = "0.11.1"
@@ -210,6 +493,56 @@ dependencies = [
"windows-sys 0.59.0",
]
[[package]]
name = "thread_local"
version = "1.1.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
dependencies = [
"cfg-if",
]
[[package]]
name = "tracing"
version = "0.1.44"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
dependencies = [
"pin-project-lite",
"tracing-core",
]
[[package]]
name = "tracing-core"
version = "0.1.36"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
dependencies = [
"once_cell",
"valuable",
]
[[package]]
name = "tracing-error"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8b1581020d7a273442f5b45074a6a57d5757ad0a47dac0e9f0bd57b81936f3db"
dependencies = [
"tracing",
"tracing-subscriber",
]
[[package]]
name = "tracing-subscriber"
version = "0.3.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
dependencies = [
"sharded-slab",
"thread_local",
"tracing-core",
]
[[package]]
name = "unicode-ident"
version = "1.0.24"
@@ -222,12 +555,113 @@ version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "valuable"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
[[package]]
name = "windows"
version = "0.62.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
dependencies = [
"windows-collections",
"windows-core",
"windows-future",
"windows-numerics",
]
[[package]]
name = "windows-collections"
version = "0.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
dependencies = [
"windows-core",
]
[[package]]
name = "windows-core"
version = "0.62.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
dependencies = [
"windows-implement",
"windows-interface",
"windows-link",
"windows-result",
"windows-strings",
]
[[package]]
name = "windows-future"
version = "0.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
dependencies = [
"windows-core",
"windows-link",
"windows-threading",
]
[[package]]
name = "windows-implement"
version = "0.60.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "windows-interface"
version = "0.59.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-numerics"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
dependencies = [
"windows-core",
"windows-link",
]
[[package]]
name = "windows-result"
version = "0.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
dependencies = [
"windows-link",
]
[[package]]
name = "windows-strings"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
dependencies = [
"windows-link",
]
[[package]]
name = "windows-sys"
version = "0.52.0"
@@ -288,6 +722,15 @@ dependencies = [
"windows_x86_64_msvc 0.53.1",
]
[[package]]
name = "windows-threading"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
dependencies = [
"windows-link",
]
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.52.6"
@@ -383,3 +826,9 @@ name = "windows_x86_64_msvc"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
[[package]]
name = "zmij"
version = "1.0.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+2
View File
@@ -41,6 +41,8 @@ Two things vary independently: the _host_ the recorder runs on (macOS or Windows
records (komorebi for Mac or komorebi for Windows). A session records both, so one recorded on Windows can be
investigated on a Mac. Every record in a session is stamped on one monotonic clock, and the files in it are never
rewritten after they are written.
[Architecture](docs/ARCHITECTURE.md) explains the model and which layer enforces each rule;
[Platform](docs/PLATFORM.md) answers the same questions for each host.
## Crates
+110 -1
View File
@@ -1,36 +1,80 @@
{
"licenses": [
[
"0BSD",
[
"adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"Apache-2.0",
[
"addr2line 0.25.1 registry+https://github.com/rust-lang/crates.io-index",
"adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index",
"anstream 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
"anstyle 1.0.14 registry+https://github.com/rust-lang/crates.io-index",
"anstyle-parse 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
"anstyle-query 1.1.5 registry+https://github.com/rust-lang/crates.io-index",
"anstyle-wincon 3.0.11 registry+https://github.com/rust-lang/crates.io-index",
"backtrace 0.3.76 registry+https://github.com/rust-lang/crates.io-index",
"bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index",
"cfg-if 1.0.4 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",
"clap_derive 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
"clap_lex 1.1.0 registry+https://github.com/rust-lang/crates.io-index",
"color-eyre 0.6.5 registry+https://github.com/rust-lang/crates.io-index",
"color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index",
"colorchoice 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",
"gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index",
"heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index",
"indenter 0.3.4 registry+https://github.com/rust-lang/crates.io-index",
"is_terminal_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
"itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index",
"lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index",
"libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index",
"miniz_oxide 0.8.9 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",
"once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
"pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index",
"proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index",
"quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index",
"ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
"ref-cast-impl 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
"rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index",
"rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index",
"ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index",
"serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
"serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
"serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
"serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index",
"serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index",
"serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index",
"syn 2.0.117 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",
"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",
"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",
"windows-future 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-implement 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-interface 0.59.3 registry+https://github.com/rust-lang/crates.io-index",
"windows-link 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
"windows-numerics 0.3.1 registry+https://github.com/rust-lang/crates.io-index",
"windows-result 0.4.1 registry+https://github.com/rust-lang/crates.io-index",
"windows-strings 0.5.1 registry+https://github.com/rust-lang/crates.io-index",
"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-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",
"windows_x86_64_msvc 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
"windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index"
]
@@ -41,6 +85,12 @@
"rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"BSL-1.0",
[
"ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"LicenseRef-Komorebi-2.0",
[
@@ -50,37 +100,84 @@
[
"MIT",
[
"addr2line 0.25.1 registry+https://github.com/rust-lang/crates.io-index",
"adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index",
"anstream 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
"anstyle 1.0.14 registry+https://github.com/rust-lang/crates.io-index",
"anstyle-parse 1.0.0 registry+https://github.com/rust-lang/crates.io-index",
"anstyle-query 1.1.5 registry+https://github.com/rust-lang/crates.io-index",
"anstyle-wincon 3.0.11 registry+https://github.com/rust-lang/crates.io-index",
"backtrace 0.3.76 registry+https://github.com/rust-lang/crates.io-index",
"bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index",
"cfg-if 1.0.4 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",
"clap_derive 4.6.1 registry+https://github.com/rust-lang/crates.io-index",
"clap_lex 1.1.0 registry+https://github.com/rust-lang/crates.io-index",
"color-eyre 0.6.5 registry+https://github.com/rust-lang/crates.io-index",
"color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index",
"colorchoice 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",
"gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index",
"heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index",
"indenter 0.3.4 registry+https://github.com/rust-lang/crates.io-index",
"is_terminal_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
"itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index",
"lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index",
"libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index",
"memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index",
"miniz_oxide 0.8.9 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",
"once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index",
"owo-colors 4.3.0 registry+https://github.com/rust-lang/crates.io-index",
"pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index",
"proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index",
"quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index",
"ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
"ref-cast-impl 1.0.25 registry+https://github.com/rust-lang/crates.io-index",
"rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index",
"rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index",
"schemars 1.2.1 registry+https://github.com/rust-lang/crates.io-index",
"schemars_derive 1.2.1 registry+https://github.com/rust-lang/crates.io-index",
"serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
"serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
"serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index",
"serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index",
"serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index",
"serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index",
"sharded-slab 0.1.7 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",
"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",
"tracing 0.1.44 registry+https://github.com/rust-lang/crates.io-index",
"tracing-core 0.1.36 registry+https://github.com/rust-lang/crates.io-index",
"tracing-error 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
"tracing-subscriber 0.3.23 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",
"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",
"windows-future 0.3.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-implement 0.60.2 registry+https://github.com/rust-lang/crates.io-index",
"windows-interface 0.59.3 registry+https://github.com/rust-lang/crates.io-index",
"windows-link 0.2.1 registry+https://github.com/rust-lang/crates.io-index",
"windows-numerics 0.3.1 registry+https://github.com/rust-lang/crates.io-index",
"windows-result 0.4.1 registry+https://github.com/rust-lang/crates.io-index",
"windows-strings 0.5.1 registry+https://github.com/rust-lang/crates.io-index",
"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-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",
"windows_x86_64_msvc 0.52.6 registry+https://github.com/rust-lang/crates.io-index",
"windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index"
"windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index",
"zmij 1.0.21 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
@@ -88,6 +185,18 @@
[
"unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"Unlicense",
[
"memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index"
]
],
[
"Zlib",
[
"miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index"
]
]
]
}
+51
View File
@@ -0,0 +1,51 @@
# Architecture
`komorebi-recorder` connects three things that do not know about each other: komorebi, which says what it is doing in
a log and in events on a socket; the operating system, which says what it is doing in its own trace and shows it on a
screen; and the person or agent who has to work out why they disagreed. It records all of them on one clock into a
session directory, and reads that directory back.
Two things about it vary independently, and everything below is arranged so that neither leaks into the other.
| axis | what varies | where the variation lives | what a session records |
|---|---|---|---|
| host | the OS the recorder runs on: macOS or Windows (a third `unsupported` host builds anywhere) | [`platform`](../komorebi-recorder/src/platform/mod.rs), selected by `cfg` | `host` in the manifest |
## The master clock
Everything in a session is stamped on one clock: the host's monotonic clock, in nanoseconds. That is
`mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows. Video frames and the OS trace are already on it.
komorebi's log lines carry UTC wall-clock time, so they are mapped onto it: the recorder samples a paired reading of
both clocks (an `Anchor`) at the start, every few seconds and at every sleep, and a `ClockMap` interpolates between
them. A `JumpDetector` notices sleep and clock steps by comparing how far each clock moved between two observations,
and the anchors on either side of the jump are what make the mapping right on both sides of it.
Three things are worth knowing before reading a session:
- The field names ending in `_mach_ns` keep their historical spelling. They hold master-clock nanoseconds on whichever
host recorded the session; the manifest's `host.clock` says which clock that was (`mach`, `qpc` or `std`). A name that
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.
- 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.
## The platform facade
The rest of the crate never names a system API. [`platform`](../komorebi-recorder/src/platform/mod.rs) is a facade of
small modules (`clock`, `shell` and, as the recorder grows, `capture`, `power`, `session`, `trace`, `process`, `apps`
and `window`), and `cfg` selects the directory behind it: `platform/macos/`, `platform/win/` or `platform/unsupported.rs`.
Each host provides the same names with the same signatures. A missing or mismatched function is a compile error on the
host being built, and on no other, so the Windows host is built from a Mac by `just check-windows` and by CI, and
`unsupported` (which exists so that the commands that only read a session directory work on a Linux agent box) is built
only on a third OS.
Where one host has no analogue of something, the facade function exists on both and one answers "nothing": `trace::start`
on the `unsupported` host returns no taps and a line saying so, and `power::start` returns no watcher.
## Rules and the layer that enforces them
| Rule | Enforced by |
|---|---|
| Every host provides the same functions with the same signatures | the compiler, for the host being built; `just check-windows` and CI build the Windows host from a Mac; nothing builds `unsupported` |
| A timestamp in a session is on the master clock | convention, and the tests that place records at known times: the type is a plain `u64` |
+66
View File
@@ -0,0 +1,66 @@
# 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](ARCHITECTURE.md#the-master-clock).
## 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.
+47
View File
@@ -7,3 +7,50 @@ repository.workspace = true
[dependencies]
clap = { workspace = true }
color-eyre = { workspace = true }
schemars = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
[target.'cfg(target_os = "macos")'.dependencies]
libc = "0.2"
[target.'cfg(windows)'.dependencies]
windows = { version = "0.62", features = [
"Foundation",
"Graphics",
"Graphics_Capture",
"Graphics_DirectX",
"Graphics_DirectX_Direct3D11",
"Wdk_System_SystemServices",
"Win32_Foundation",
"Win32_Graphics_Direct3D",
"Win32_Graphics_Direct3D11",
"Win32_Graphics_Dwm",
"Win32_Graphics_Dxgi",
"Win32_Graphics_Dxgi_Common",
"Win32_Graphics_Gdi",
"Win32_Media",
"Win32_Media_MediaFoundation",
"Win32_System_Com",
"Win32_System_Com_StructuredStorage",
"Win32_System_EventLog",
"Win32_System_LibraryLoader",
"Win32_System_Performance",
"Win32_System_Power",
"Win32_System_RemoteDesktop",
"Win32_System_StationsAndDesktops",
"Win32_System_SystemInformation",
"Win32_System_SystemServices",
"Win32_System_Threading",
"Win32_System_Variant",
"Win32_System_WinRT",
"Win32_System_WinRT_Direct3D11",
"Win32_System_WinRT_Graphics_Capture",
"Win32_System_WindowsProgramming",
"Win32_UI_Accessibility",
"Win32_UI_HiDpi",
"Win32_UI_Shell",
"Win32_UI_Shell_Common",
"Win32_UI_WindowsAndMessaging",
] }
+949
View File
@@ -0,0 +1,949 @@
//! The master clock: the one monotonic clock every record in a session is stamped on, and the
//! conversions between it, the wall clock and video time.
//!
//! Every source in a recording is expressed in nanoseconds on one host monotonic clock: capture
//! frame timestamps, the OS trace, komorebi's subscriber events, incidents. komorebi's own log
//! lines are the exception. They carry a UTC wall clock time, and are mapped
//! onto the master clock with the [`Anchor`]s sampled while recording.
//!
//! # Which clock is the master clock
//!
//! [`mono_now_ns`] reads it, through [`crate::platform::clock`], and [`Host::clock`] names it: the
//! field holds the [`ClockKind`] the session was recorded with, which the manifest stores as
//! `host.clock`. It does not name the wall clock, or any [`ReferenceClock`].
//!
//! | [`ClockKind`] | `host.clock` | read with |
//! |---|---|---|
//! | [`Mach`](crate::platform::ClockKind::Mach) | `mach` | `mach_absolute_time`, on macOS |
//! | [`Qpc`](crate::platform::ClockKind::Qpc) | `qpc` | `QueryPerformanceCounter`, on Windows |
//! | [`Std`](crate::platform::ClockKind::Std) | `std` | [`std::time::Instant`] since the first reading in the process, plus one second so that it is never zero, on a host with no capture |
//!
//! `mach_absolute_time` pauses while the machine sleeps. Whether the Windows counter does is not
//! assumed: `doctor --probe clock` measures it, and where the OS can announce a sleep the
//! recorder listens for it (`platform::power`) rather than inferring it from the clocks alone.
//!
//! The `*_mach_ns` field names throughout a session are historical: they mean "master monotonic
//! nanoseconds", whichever clock that was, and keeping them means a session written by any build
//! is readable by any other. `host.clock` is what says which clock the numbers are on.
//!
//! # The four scales
//!
//! | Scale | Unit | Where it appears | Converted with |
//! |---|---|---|---|
//! | host ticks | ticks of the OS counter | raw counter reads, the unified log's `machTimestamp` | [`Timebase`] |
//! | master clock | nanoseconds, `u64` | every `*_mach_ns` field | (the scale the others convert to and from) |
//! | wall time | microseconds since the Unix epoch, `i64`, UTC | komorebi's log lines, every `wall_us` field | [`ClockMap`] |
//! | video time | seconds, `f64`, since the first captured frame | timecodes (see [`crate::timecode`]), `video_s` fields | subtracting the master clock time of video `t = 0` |
//!
//! Video `t = 0` is the master clock time of the earliest first frame across displays, recorded in
//! the manifest as `video_t0_mach_ns`; with no frame at all it is the recording's start. A time
//! before the first frame is negative. The session manifest's `video_seconds` and
//! `mach_at_video_seconds` do that subtraction in each direction.
//!
//! # How the pieces relate
//!
//! * [`Timebase`] says what one host tick is worth. It is read from the OS once ([`timebase`]),
//! and stored in the manifest, so that a session recorded on one machine is read on another with
//! the tick size of the machine that recorded it.
//! * [`Anchor`] pairs one wall clock reading with the master clock time at which it was made.
//! The recording loop samples one about every 5 seconds, and one on either side of every sleep.
//! * [`ClockMap`] is built from a session's anchors, and maps between wall time and the master
//! clock by interpolating between them.
//! * [`JumpDetector`] compares the wall clock with the master clock over each loop iteration, and
//! reports a [`Jump`] when they disagree. The two anchors of a [`Jump`] are the pair of anchors
//! [`ClockMap`] needs to treat a sleep as a step, rather than as drift.
//! * [`ReferenceClock`] is another host clock, read next to the master clock so that a probe can
//! say what the master clock does across a sleep.
//!
//! # Example: ticks, master clock, wall time and video time
//!
//! ```rust
//! use komorebi_recorder::clock::{Anchor, ClockMap, Timebase};
//!
//! // a counter that ticks at 24 MHz, which is 125/3 nanoseconds a tick
//! let timebase = Timebase::from_frequency(24_000_000);
//! assert_eq!(timebase, Timebase { numer: 125, denom: 3 });
//!
//! // host ticks -> master clock nanoseconds
//! let mach_ns = timebase.ticks_to_ns(2_400_000_000);
//! assert_eq!(mach_ns, 100_000_000_000);
//!
//! // two anchors taken 5 seconds apart, as the recorder does
//! let map = ClockMap::new(vec![
//! Anchor { wall_us: 1_800_000_000_000_000, mach_ns: 100_000_000_000 },
//! Anchor { wall_us: 1_800_000_005_000_000, mach_ns: 105_000_000_000 },
//! ]);
//!
//! // master clock -> wall time, and back
//! let wall_us = map.mach_to_wall(102_500_000_000).expect("the map has anchors");
//! assert_eq!(wall_us, 1_800_000_002_500_000);
//! assert_eq!(map.wall_to_mach(wall_us), Some(102_500_000_000));
//!
//! // master clock -> video time, for a first frame that was captured at 101 s on the master clock
//! let video_t0_mach_ns = 101_000_000_000_i128;
//! let video_s = (102_500_000_000_i128 - video_t0_mach_ns) as f64 / 1e9;
//! assert_eq!(video_s, 1.5);
//!
//! // and back, from video time to the master clock
//! assert_eq!(video_t0_mach_ns + (video_s * 1e9).round() as i128, 102_500_000_000);
//!
//! // a time before the first frame is negative in video time
//! assert_eq!((100_500_000_000_i128 - video_t0_mach_ns) as f64 / 1e9, -0.5);
//! ```
//!
//! [`Host::clock`]: crate::platform::Host::clock
//! [`ClockKind`]: crate::platform::ClockKind
use crate::platform;
use serde::Deserialize;
use serde::Serialize;
use std::time::SystemTime;
use std::time::UNIX_EPOCH;
/// The size of one tick of the host clock: `numer / denom` nanoseconds.
///
/// It is read from the OS once ([`timebase`]) and stored in a session's manifest as `timebase`, so
/// that a session recorded on one machine is converted with the tick size of the machine that
/// recorded it, and not with the reader's. The unified log's `machTimestamp` is in ticks of this
/// size, and the manifest's timebase is what converts it.
///
/// A timebase this crate produces has a non-zero `numer` and `denom`. The fields are public and
/// are read back from `session.json`, so a hand-edited manifest can hold zeros, which make
/// [`ticks_to_ns`](Timebase::ticks_to_ns) and [`ns_to_ticks`](Timebase::ns_to_ticks) panic.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::Timebase;
///
/// // Apple silicon's counter: 24 MHz, so 125/3 nanoseconds a tick
/// let timebase = Timebase { numer: 125, denom: 3 };
/// assert_eq!(timebase.ticks_to_ns(24_000_000), 1_000_000_000);
/// assert_eq!(timebase.ns_to_ticks(1_000_000_000), 24_000_000);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Timebase {
/// The numerator of the nanoseconds a tick is worth.
pub numer: u32,
/// The denominator of the nanoseconds a tick is worth.
pub denom: u32,
}
impl Timebase {
/// Returns the timebase of a counter that ticks `hertz` times a second, as
/// `QueryPerformanceCounter` does.
///
/// One tick is `1e9 / hertz` nanoseconds. The fraction is reduced, so a 10 MHz counter is
/// `100/1`, not `1000000000/10000000`. A counter faster than about 4.29 GHz has a reduced
/// denominator that does not fit in a `u32`: both parts are then halved until they do, which
/// keeps the ratio approximately. A `hertz` of zero is treated as one.
///
/// The result always has a non-zero `numer` and `denom`.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::Timebase;
///
/// // the usual `QueryPerformanceFrequency`: 10 MHz, which is 100 ns a tick
/// assert_eq!(Timebase::from_frequency(10_000_000), Timebase { numer: 100, denom: 1 });
///
/// // Apple silicon's counter
/// assert_eq!(Timebase::from_frequency(24_000_000), Timebase { numer: 125, denom: 3 });
///
/// // a nanosecond counter, and a nonsense zero, are both fine
/// assert_eq!(Timebase::from_frequency(1_000_000_000), Timebase { numer: 1, denom: 1 });
/// assert_eq!(Timebase::from_frequency(0).ticks_to_ns(5), 5_000_000_000);
/// ```
#[must_use]
pub fn from_frequency(hertz: u64) -> Self {
fn gcd(a: u64, b: u64) -> u64 {
if b == 0 { a } else { gcd(b, a % b) }
}
let hertz = hertz.max(1);
let divisor = gcd(1_000_000_000, hertz);
let (mut numer, mut denom) = (1_000_000_000 / divisor, hertz / divisor);
while numer > u64::from(u32::MAX) || denom > u64::from(u32::MAX) {
numer = (numer / 2).max(1);
denom = (denom / 2).max(1);
}
Self {
numer: numer as u32,
denom: denom as u32,
}
}
/// Returns `ticks` host clock ticks as nanoseconds: `ticks * numer / denom`.
///
/// The product is computed in 128 bits, so it cannot overflow, and the quotient is truncated
/// toward zero. A result that does not fit in a `u64` is truncated to its low 64 bits.
///
/// # Panics
///
/// Panics if `denom` is zero.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::Timebase;
///
/// let timebase = Timebase { numer: 125, denom: 3 };
/// assert_eq!(timebase.ticks_to_ns(24_000_000), 1_000_000_000);
///
/// // one tick is 41.67 ns, truncated
/// assert_eq!(timebase.ticks_to_ns(1), 41);
/// ```
#[must_use]
pub fn ticks_to_ns(self, ticks: u64) -> u64 {
(u128::from(ticks) * u128::from(self.numer) / u128::from(self.denom)) as u64
}
/// Returns `ns` nanoseconds as host clock ticks: `ns * denom / numer`.
///
/// The product is computed in 128 bits, so it cannot overflow, and the quotient is truncated
/// toward zero. A result that does not fit in a `u64` is truncated to its low 64 bits.
///
/// # Panics
///
/// Panics if `numer` is zero.
///
/// # Example: a round trip can lose a tick
///
/// Both directions truncate, so a tick count that goes to nanoseconds and back comes back
/// equal only when the nanoseconds were exact:
///
/// ```rust
/// use komorebi_recorder::clock::Timebase;
///
/// let timebase = Timebase { numer: 125, denom: 3 };
/// assert_eq!(timebase.ns_to_ticks(timebase.ticks_to_ns(24_000_000)), 24_000_000);
/// assert_eq!(timebase.ns_to_ticks(timebase.ticks_to_ns(1)), 0);
/// ```
#[must_use]
pub fn ns_to_ticks(self, ns: u64) -> u64 {
(u128::from(ns) * u128::from(self.denom) / u128::from(self.numer)) as u64
}
}
/// Returns what one tick of the host clock is worth in nanoseconds.
///
/// It is the host's own: from `mach_timebase_info` on macOS (125/3 on Apple silicon, and 1/1 if the
/// OS reports an unusable one), from [`Timebase::from_frequency`] of `QueryPerformanceFrequency` on
/// Windows (10 MHz if that cannot be read), and 1/1 on a host with no capture, whose clock already
/// counts nanoseconds. A session records the timebase it was written with in its manifest; use that
/// one, not this, to convert a recorded session's ticks.
#[must_use]
pub fn timebase() -> Timebase {
platform::clock::timebase()
}
/// Another clock the host has, read alongside the master clock to find out what the master clock
/// does while the machine sleeps.
///
/// A reference clock is never used to stamp a record. `doctor` reads each one together with the
/// master clock and the wall clock, and reports how far each moved across a sleep.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)]
pub struct ReferenceClock {
/// The name of the OS clock, as the OS spells it (`mach_continuous_time`).
pub name: String,
/// Whether it keeps counting while the machine is suspended.
pub counts_sleep: bool,
/// Its reading, in nanoseconds from an origin that the clock chooses: only differences between
/// two readings of the same clock mean anything.
pub ns: u64,
}
/// Returns a reading of each of the host's other clocks (see [`ReferenceClock`]).
///
/// On macOS that is `mach_continuous_time`, which counts the time the machine sleeps. On Windows
/// it is `QueryInterruptTime`, which counts it, and `QueryUnbiasedInterruptTimePrecise`, which
/// does not. A host with no capture has none.
#[must_use]
pub fn reference_clocks() -> Vec<ReferenceClock> {
platform::clock::reference_clocks()
}
/// Returns the master clock in nanoseconds: the host monotonic clock every record in a session is
/// on.
///
/// On macOS this is `mach_absolute_time`, which pauses while the machine sleeps; on Windows it is
/// `QueryPerformanceCounter`. The `*_mach_ns` fields in a session keep their historical names and
/// hold this value; the manifest's `host.clock` says which clock it was.
///
/// The origin is chosen by the OS, so a reading means something only next to another reading of the
/// same clock. The clock is monotonic: it does not go backwards, and `doctor` reports whether it
/// did while it was read.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::mono_now_ns;
///
/// let first = mono_now_ns();
/// let second = mono_now_ns();
/// assert!(second >= first);
/// ```
#[must_use]
pub fn mono_now_ns() -> u64 {
platform::clock::now_ns()
}
/// Returns the wall clock in microseconds since the Unix epoch (UTC).
///
/// Unlike [`mono_now_ns`], the wall clock can be stepped, forwards or backwards, by the user or by
/// time synchronization, and keeps counting while the machine sleeps. A time before 1970, which
/// means the clock is badly wrong, is returned as a negative number rather than as an error.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::wall_now_us;
///
/// // after 2020-01-01 and before 2100-01-01
/// let now = wall_now_us();
/// assert!(now > 1_577_836_800_000_000);
/// assert!(now < 4_102_444_800_000_000);
/// ```
#[must_use]
pub fn wall_now_us() -> i64 {
match SystemTime::now().duration_since(UNIX_EPOCH) {
Ok(since) => since.as_micros() as i64,
// before 1970: the clock is badly wrong, but a negative time is still a time
Err(before) => -(before.duration().as_micros() as i64),
}
}
/// A paired reading of the wall clock and the master clock: the master clock time at which the
/// wall clock read `wall_us`.
///
/// An anchor is the only link between komorebi's log, which is stamped with the wall clock, and
/// everything else, which is on the master clock. A session keeps a series of them in its manifest
/// (`anchors`), and [`ClockMap`] interpolates between them.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::{wall_now_us, Anchor};
///
/// let anchor = Anchor::sample();
/// // the wall clock was read a moment ago
/// assert!((wall_now_us() - anchor.wall_us).abs() < 1_000_000);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Anchor {
/// The wall clock, in microseconds since the Unix epoch (UTC).
pub wall_us: i64,
/// The master clock, in nanoseconds, at the same moment.
pub mach_ns: u64,
}
impl Anchor {
/// Takes a tight paired reading: several back-to-back samples, keeping the one whose wall read
/// was bracketed by the narrowest pair of mach reads, which bounds the pairing error to the
/// duration of a couple of syscalls.
///
/// Seven samples are taken. The `mach_ns` of the one kept is the midpoint of the two master
/// clock reads around its wall clock read.
#[must_use]
pub fn sample() -> Self {
let mut best: Option<(u64, Anchor)> = None;
for _ in 0..7 {
let before = mono_now_ns();
let wall_us = wall_now_us();
let after = mono_now_ns();
let width = after.saturating_sub(before);
let anchor = Anchor {
wall_us,
mach_ns: before + width / 2,
};
if best.is_none_or(|(best_width, _)| width < best_width) {
best = Some((width, anchor));
}
}
best.map(|(_, anchor)| anchor).unwrap_or_else(|| Anchor {
wall_us: wall_now_us(),
mach_ns: mono_now_ns(),
})
}
/// The wall clock minus the mach clock, in microseconds.
fn offset_us(self) -> i128 {
i128::from(self.wall_us) - i128::from(self.mach_ns / 1_000)
}
}
/// How far the wall clock must outrun the mach clock between two close observations for it to
/// count as a jump. Observations are made every ~50 ms, so ordinary drift is microseconds.
const JUMP_THRESHOLD_NS: i128 = 1_000_000_000;
/// A discontinuity between the wall clock and the master clock, as [`JumpDetector::observe`]
/// reports it.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Jump {
/// How far the wall clock moved beyond the master clock, in seconds. Positive: the machine
/// slept (mach time pauses while asleep, wall time does not) or the clock stepped forward.
/// Negative: the wall clock was stepped back.
pub seconds: f64,
/// The last good pairing before the jump: the previous observation.
pub before: Anchor,
/// The first pairing after the jump: the observation that found it.
pub after: Anchor,
}
/// Notices sleep/wake and clock steps by watching both clocks.
///
/// Feed it a fresh [`Anchor`] every loop iteration. When the two clocks disagree about how much
/// time passed since the previous observation, the machine was suspended (or the clock was
/// stepped), and the two anchors on either side of the discontinuity are exactly what
/// [`ClockMap`] needs to map wall time to mach time correctly on both sides of it.
///
/// The detector is a state machine with one piece of state, the previous observation. It reports a
/// [`Jump`] when the wall clock and the master clock moved by amounts that differ by 1 second or
/// more since then. Observations are expected about every 50 ms, so ordinary drift is
/// microseconds, and a process that was merely descheduled for a long time is not a jump, because
/// both clocks moved together. A suspension shorter than 1 second is not reported.
///
/// On a host whose master clock keeps counting through a sleep, the two clocks do not disagree and
/// a sleep is not noticed this way: see the module docs, and `PowerTracker` for the OS's own
/// announcement of a sleep.
///
/// # Example: noticing a sleep, and mapping time across it
///
/// ```rust
/// use komorebi_recorder::clock::{Anchor, ClockMap, JumpDetector};
///
/// // wall time 2000 s and master clock time 1000 s are the same moment
/// let start = Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 };
/// let mut detector = JumpDetector::new(start);
///
/// // 50 ms later on both clocks: nothing to report
/// let before = Anchor { wall_us: 2_000_050_000, mach_ns: 1_000_050_000_000 };
/// assert_eq!(detector.observe(before), None);
///
/// // the lid is closed for an hour: the wall clock moves on, the master clock barely does
/// let after = Anchor {
/// wall_us: 2_000_100_000 + 3_600_000_000,
/// mach_ns: 1_000_100_000_000,
/// };
/// let jump = detector.observe(after).expect("the clocks disagree by an hour");
/// assert!((jump.seconds - 3_600.0).abs() < 0.01);
/// assert_eq!((jump.before, jump.after), (before, after));
///
/// // with both anchors in the map, wall time maps correctly on either side of the sleep
/// let map = ClockMap::new(vec![jump.before, jump.after]);
/// assert_eq!(map.wall_to_mach(2_000_050_000), Some(1_000_050_000_000));
/// let two_seconds_after_waking = after.wall_us + 2_000_000;
/// assert_eq!(map.wall_to_mach(two_seconds_after_waking), Some(1_002_100_000_000));
///
/// // the detector carries on from the new position
/// let later = Anchor { wall_us: after.wall_us + 50_000, mach_ns: after.mach_ns + 50_000_000 };
/// assert_eq!(detector.observe(later), None);
/// ```
#[derive(Debug, Clone, Copy)]
pub struct JumpDetector {
last: Anchor,
}
impl JumpDetector {
/// Returns a detector whose previous observation is `first`.
#[must_use]
pub fn new(first: Anchor) -> Self {
Self { last: first }
}
/// Compares `now` with the previous observation, and makes `now` the previous observation.
///
/// Returns a [`Jump`] if the wall clock and the master clock moved by amounts that differ by
/// at least 1 second, in either direction, and `None` otherwise. The observation is recorded
/// either way, so one discontinuity is reported once.
pub fn observe(&mut self, now: Anchor) -> Option<Jump> {
let wall_ns = (i128::from(now.wall_us) - i128::from(self.last.wall_us)) * 1_000;
let mach_ns = i128::from(now.mach_ns) - i128::from(self.last.mach_ns);
let difference = wall_ns - mach_ns;
let before = std::mem::replace(&mut self.last, now);
(difference.abs() >= JUMP_THRESHOLD_NS).then_some(Jump {
seconds: difference as f64 / 1e9,
before,
after: now,
})
}
}
/// Segments whose wall and mach durations disagree by more than this are treated as a clock step
/// (an NTP jump, or the machine sleeping while the mach clock was paused) rather than as drift.
const STEP_THRESHOLD_NS: i128 = 20_000_000;
/// A two-way map between wall clock time and the master clock, built by piecewise-linear
/// interpolation between the anchors sampled during a recording.
///
/// A map is built from a session's anchors (the manifest's `anchors`) and answers in both
/// directions: [`wall_to_mach`] turns a wall clock time, such as one of komorebi's log lines, into
/// the master clock, and [`mach_to_wall`] does the reverse, to show a master clock time as UTC.
///
/// Each pair of neighboring anchors, ordered by master clock time, is a segment. The wall clock
/// and the master clock tick at slightly different rates, so inside a segment a time is
/// interpolated linearly. If the two clocks moved by amounts that differ by more than 20 ms over a
/// segment, the segment holds a step rather than drift: the machine slept while the master clock
/// was paused, or the wall clock was stepped. Where in the segment the step happened is not
/// known, so a time inside it is taken from the nearer of the segment's two anchors, using that
/// anchor's offset between the clocks. Outside the first and last anchors, a time is taken
/// from the nearer end in the same way. With a single anchor, the map is a constant offset.
///
/// Both directions return `None` if, and only if, the map has no anchors.
///
/// A sleep inside a segment is placed at the nearer anchor, which is why the recorder adds an
/// anchor on either side of every sleep it finds (see [`JumpDetector`]).
///
/// The anchors of a map are guaranteed to be sorted by master clock time, with no two at the same
/// time, because [`ClockMap::new`] is the only way to make one that has any: the field is private.
///
/// ```rust,compile_fail,E0451
/// use komorebi_recorder::clock::{Anchor, ClockMap};
///
/// // an unsorted list of anchors, which `ClockMap::new` would put in order
/// let anchors = vec![
/// Anchor { wall_us: 2_005_000_000, mach_ns: 1_005_000_000_000 },
/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 },
/// ];
/// let _map = ClockMap { anchors };
/// ```
///
/// # Example: a clock step
///
/// ```rust
/// use komorebi_recorder::clock::{Anchor, ClockMap};
///
/// let at = |wall_s: i64, mach_s: u64| Anchor {
/// wall_us: wall_s * 1_000_000,
/// mach_ns: mach_s * 1_000_000_000,
/// };
///
/// // the wall clock jumps forward 30 s between the second and third anchors, while the master
/// // clock moves 5 s: the machine slept, or the clock was stepped
/// let map = ClockMap::new(vec![at(2000, 1000), at(2005, 1005), at(2040, 1010)]);
///
/// // before the step, the clocks are 1000 s apart
/// assert_eq!(map.wall_to_mach(2_001_000_000), Some(1_001_000_000_000));
/// // after it, 1030 s apart
/// assert_eq!(map.wall_to_mach(2_039_000_000), Some(1_009_000_000_000));
/// // and the other direction agrees on both sides
/// assert_eq!(map.mach_to_wall(1_001_000_000_000), Some(2_001_000_000));
/// assert_eq!(map.mach_to_wall(1_009_000_000_000), Some(2_039_000_000));
///
/// // an empty map has no answer
/// assert_eq!(ClockMap::default().wall_to_mach(1), None);
/// ```
///
/// [`wall_to_mach`]: ClockMap::wall_to_mach
/// [`mach_to_wall`]: ClockMap::mach_to_wall
#[derive(Debug, Clone, Default)]
pub struct ClockMap {
anchors: Vec<Anchor>,
}
impl ClockMap {
/// Returns a map over `anchors`, which may be given in any order.
///
/// The anchors are sorted by master clock time, and of several with the same master clock time
/// only the first given is kept.
#[must_use]
pub fn new(mut anchors: Vec<Anchor>) -> Self {
anchors.sort_by_key(|anchor| anchor.mach_ns);
anchors.dedup_by_key(|anchor| anchor.mach_ns);
Self { anchors }
}
/// Returns the anchors the map was built from, ascending by master clock time, with no two
/// sharing a master clock time.
#[must_use]
pub fn anchors(&self) -> &[Anchor] {
&self.anchors
}
/// Returns true if and only if the map has no anchors, in which case every lookup returns
/// `None`.
#[must_use]
pub fn is_empty(&self) -> bool {
self.anchors.is_empty()
}
/// Whether the segment between two anchors contains a clock step rather than plain drift.
fn is_step(a: Anchor, b: Anchor) -> bool {
let wall_ns = (i128::from(b.wall_us) - i128::from(a.wall_us)) * 1_000;
let mach_ns = i128::from(b.mach_ns) - i128::from(a.mach_ns);
(wall_ns - mach_ns).abs() > STEP_THRESHOLD_NS
}
/// Returns the master clock time, in nanoseconds, of the wall clock time `wall_us`
/// (microseconds since the Unix epoch), or `None` if the map has no anchors.
///
/// The result is never negative: a time that maps before the origin of the master clock is
/// returned as zero. If the wall clock was stepped back, two segments can contain the same wall
/// clock time; the segment earlier in master clock time is used.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::{Anchor, ClockMap};
///
/// // wall = master + 1000 s, with the wall clock running slightly fast between the anchors
/// let map = ClockMap::new(vec![
/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 },
/// Anchor { wall_us: 2_005_000_500, mach_ns: 1_005_000_000_000 },
/// ]);
///
/// // halfway between them, interpolated
/// assert_eq!(map.wall_to_mach(2_002_500_250), Some(1_002_500_000_000));
///
/// // outside them, extended from the nearer end at a constant offset
/// assert_eq!(map.wall_to_mach(1_999_000_000), Some(999_000_000_000));
/// assert_eq!(map.wall_to_mach(2_010_000_500), Some(1_010_000_000_000));
/// ```
#[must_use]
pub fn wall_to_mach(&self, wall_us: i64) -> Option<u64> {
let (first, last) = (*self.anchors.first()?, *self.anchors.last()?);
let extrapolate = |anchor: Anchor| {
let mach = i128::from(wall_us) - anchor.offset_us();
(mach * 1_000).max(0) as u64
};
if self.anchors.len() == 1 {
return Some(extrapolate(first));
}
for pair in self.anchors.windows(2) {
let (a, b) = (pair[0], pair[1]);
let (lo, hi) = (a.wall_us.min(b.wall_us), a.wall_us.max(b.wall_us));
if wall_us < lo || wall_us > hi {
continue;
}
if Self::is_step(a, b) {
// we cannot know when inside the segment the step happened, so trust whichever
// end is closer in wall time
let nearest = if (wall_us - a.wall_us).abs() <= (wall_us - b.wall_us).abs() {
a
} else {
b
};
return Some(extrapolate(nearest));
}
let wall_span = i128::from(b.wall_us) - i128::from(a.wall_us);
if wall_span == 0 {
return Some(a.mach_ns);
}
let mach_span = i128::from(b.mach_ns) - i128::from(a.mach_ns);
let into = i128::from(wall_us) - i128::from(a.wall_us);
return Some((i128::from(a.mach_ns) + into * mach_span / wall_span).max(0) as u64);
}
// outside every segment: extend from whichever end is nearest in wall time
let nearest = if (wall_us - first.wall_us).abs() <= (wall_us - last.wall_us).abs() {
first
} else {
last
};
Some(extrapolate(nearest))
}
/// Returns the wall clock time, in microseconds since the Unix epoch, of the master clock time
/// `mach_ns`, or `None` if the map has no anchors.
///
/// The master clock has a resolution finer than a microsecond, and the result is truncated to
/// whole microseconds. Within a segment that holds no step, a wall clock time taken through
/// [`wall_to_mach`](ClockMap::wall_to_mach) and back comes back within 1 microsecond (the test
/// `roundtrips_within_a_microsecond`); that is not guaranteed across a step.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::clock::{Anchor, ClockMap};
///
/// let map = ClockMap::new(vec![
/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 },
/// Anchor { wall_us: 2_005_000_000, mach_ns: 1_005_000_000_000 },
/// ]);
///
/// let wall_us = map.mach_to_wall(1_002_345_678_000).expect("the map has anchors");
/// assert_eq!(wall_us, 2_002_345_678);
///
/// let back = map.wall_to_mach(wall_us).expect("the map has anchors");
/// assert_eq!(back, 1_002_345_678_000);
/// ```
#[must_use]
pub fn mach_to_wall(&self, mach_ns: u64) -> Option<i64> {
let (first, last) = (*self.anchors.first()?, *self.anchors.last()?);
let extrapolate = |anchor: Anchor| {
let wall = i128::from(mach_ns / 1_000) + anchor.offset_us();
wall as i64
};
if mach_ns <= first.mach_ns {
return Some(extrapolate(first));
}
if mach_ns >= last.mach_ns {
return Some(extrapolate(last));
}
for pair in self.anchors.windows(2) {
let (a, b) = (pair[0], pair[1]);
if mach_ns < a.mach_ns || mach_ns > b.mach_ns {
continue;
}
if Self::is_step(a, b) {
let nearest = if mach_ns - a.mach_ns <= b.mach_ns - mach_ns {
a
} else {
b
};
return Some(extrapolate(nearest));
}
let mach_span = i128::from(b.mach_ns) - i128::from(a.mach_ns);
let wall_span = i128::from(b.wall_us) - i128::from(a.wall_us);
let into = i128::from(mach_ns) - i128::from(a.mach_ns);
return Some((i128::from(a.wall_us) + into * wall_span / mach_span) as i64);
}
Some(extrapolate(last))
}
}
#[cfg(test)]
mod tests {
use super::*;
fn anchor(wall_s: i64, mach_s: u64) -> Anchor {
Anchor {
wall_us: wall_s * 1_000_000,
mach_ns: mach_s * 1_000_000_000,
}
}
#[test]
fn a_counters_frequency_is_a_timebase() {
// the usual QueryPerformanceFrequency: 10 MHz, 100 ns a tick
let ten_mhz = Timebase::from_frequency(10_000_000);
assert_eq!(
ten_mhz,
Timebase {
numer: 100,
denom: 1
}
);
assert_eq!(ten_mhz.ticks_to_ns(10_000_000), 1_000_000_000);
assert_eq!(ten_mhz.ns_to_ticks(1_000_000_000), 10_000_000);
// one that does not divide evenly
let odd = Timebase::from_frequency(3_579_545);
let one_second = odd.ns_to_ticks(1_000_000_000);
assert!(
(3_579_544..=3_579_546).contains(&one_second),
"{one_second}"
);
// a nanosecond counter, and a nonsense zero, are both fine
assert_eq!(
Timebase::from_frequency(1_000_000_000),
Timebase { numer: 1, denom: 1 }
);
assert_eq!(Timebase::from_frequency(0).ticks_to_ns(5), 5_000_000_000);
// faster than u32 can hold: still close
let fast = Timebase::from_frequency(10_000_000_000);
assert!(fast.ticks_to_ns(10_000_000_000).abs_diff(1_000_000_000) < 10_000_000);
}
#[test]
fn timebase_roundtrip() {
let tb = Timebase {
numer: 125,
denom: 3,
};
let ns = tb.ticks_to_ns(24_000_000);
assert_eq!(ns, 1_000_000_000);
assert_eq!(tb.ns_to_ticks(ns), 24_000_000);
}
#[test]
fn mach_is_monotonic_and_wall_is_sane() {
let a = mono_now_ns();
let b = mono_now_ns();
assert!(b >= a);
// after 2020 and before 2100
assert!(wall_now_us() > 1_577_836_800_000_000);
assert!(wall_now_us() < 4_102_444_800_000_000);
}
#[test]
fn anchor_sample_is_close_to_now() {
let anchor = Anchor::sample();
let now = wall_now_us();
assert!((now - anchor.wall_us).abs() < 50_000);
}
#[test]
fn interpolates_between_anchors() {
// wall = mach + 1000s, with the wall clock running 100ppm fast over the segment
let a = anchor(2000, 1000);
let b = Anchor {
wall_us: 2005 * 1_000_000 + 500,
mach_ns: 1005 * 1_000_000_000,
};
let map = ClockMap::new(vec![a, b]);
let mach = map.wall_to_mach(2_002_500_000 + 250).expect("mach");
assert_eq!(mach, 1_002_500_000_000);
let wall = map.mach_to_wall(1_002_500_000_000).expect("wall");
assert_eq!(wall, 2_002_500_000 + 250);
}
#[test]
fn roundtrips_within_a_microsecond() {
let map = ClockMap::new(vec![
anchor(2000, 1000),
anchor(2005, 1005),
anchor(2010, 1010),
]);
for wall in [2_000_123_456, 2_004_999_999, 2_007_777_777, 2_009_000_001] {
let mach = map.wall_to_mach(wall).expect("mach");
let back = map.mach_to_wall(mach).expect("wall");
assert!((back - wall).abs() <= 1, "{wall} -> {mach} -> {back}");
}
}
#[test]
fn extrapolates_outside_the_anchor_range() {
let map = ClockMap::new(vec![anchor(2000, 1000), anchor(2005, 1005)]);
assert_eq!(
map.wall_to_mach(1_999_000_000),
Some(999_000_000_000),
"before the first anchor"
);
assert_eq!(
map.wall_to_mach(2_010_000_000),
Some(1_010_000_000_000),
"after the last anchor"
);
}
#[test]
fn handles_a_clock_step() {
// the wall clock jumps forward 30s between the second and third anchors (an NTP step, or
// the machine slept while mach time was paused)
let map = ClockMap::new(vec![
anchor(2000, 1000),
anchor(2005, 1005),
anchor(2040, 1010),
]);
// before the step the offset is 1000s
assert_eq!(map.wall_to_mach(2_001_000_000), Some(1_001_000_000_000));
// after the step the offset is 1030s
assert_eq!(map.wall_to_mach(2_039_000_000), Some(1_009_000_000_000));
// and mach -> wall agrees on both sides
assert_eq!(map.mach_to_wall(1_001_000_000_000), Some(2_001_000_000));
assert_eq!(map.mach_to_wall(1_009_000_000_000), Some(2_039_000_000));
}
#[test]
fn single_anchor_is_a_constant_offset() {
let map = ClockMap::new(vec![anchor(2000, 1000)]);
assert_eq!(map.wall_to_mach(2_003_000_000), Some(1_003_000_000_000));
assert_eq!(map.mach_to_wall(1_003_000_000_000), Some(2_003_000_000));
}
#[test]
fn the_jump_detector_ignores_ordinary_time_passing() {
let mut detector = JumpDetector::new(anchor(2000, 1000));
// 50 ms later on both clocks, with a little drift
let tick = |wall_us: i64, mach_ns: u64| Anchor { wall_us, mach_ns };
assert_eq!(
detector.observe(tick(2_000_050_010, 1_000_050_000_000)),
None
);
// a long but consistent interval (the process was merely descheduled)
assert_eq!(
detector.observe(tick(2_030_050_010, 1_030_050_000_000)),
None
);
}
#[test]
fn the_jump_detector_notices_sleep_and_brackets_it() {
let mut detector = JumpDetector::new(anchor(2000, 1000));
let before = Anchor {
wall_us: 2_000_050_000,
mach_ns: 1_000_050_000_000,
};
assert_eq!(detector.observe(before), None);
// the lid is closed for 3600 s: wall time moves on, mach time barely does
let after = Anchor {
wall_us: 2_000_100_000 + 3_600_000_000,
mach_ns: 1_000_100_000_000,
};
let jump = detector.observe(after).expect("a jump");
assert!((jump.seconds - 3_600.0).abs() < 0.01, "{}", jump.seconds);
assert_eq!(
jump.before, before,
"the last good pairing before the sleep"
);
assert_eq!(jump.after, after);
// and with those two anchors the map is right on both sides of the sleep
let map = ClockMap::new(vec![jump.before, jump.after]);
assert_eq!(map.wall_to_mach(2_000_050_000), Some(1_000_050_000_000));
assert_eq!(
map.wall_to_mach(2_000_100_000 + 3_600_000_000),
Some(1_000_100_000_000)
);
assert_eq!(
map.wall_to_mach(2_000_100_000 + 3_600_000_000 + 2_000_000),
Some(1_000_100_000_000 + 2_000_000_000),
"two seconds after waking"
);
// the detector carries on from the new position
assert_eq!(
detector.observe(Anchor {
wall_us: after.wall_us + 50_000,
mach_ns: after.mach_ns + 50_000_000
}),
None
);
}
#[test]
fn the_jump_detector_notices_the_clock_stepping_back() {
let mut detector = JumpDetector::new(anchor(2000, 1000));
let jump = detector
.observe(Anchor {
wall_us: 2_000_050_000 - 30_000_000,
mach_ns: 1_000_050_000_000,
})
.expect("a jump");
assert!(
jump.seconds < -29.0 && jump.seconds > -31.0,
"{}",
jump.seconds
);
}
#[test]
fn empty_map_has_no_answer() {
let map = ClockMap::default();
assert_eq!(map.wall_to_mach(1), None);
assert_eq!(map.mach_to_wall(1), None);
}
}
+49
View File
@@ -8,3 +8,52 @@
//! This crate is the library behind the `komorebi-recorder` command. A reader who wants to run it should start with the
//! [README](https://github.com/LGUG2Z/komorebi-recorder#readme); this documentation is for someone who is changing it,
//! or reading a session directory from a program of their own.
//!
//! # The model
//!
//! Two things vary independently. The _host_ is the OS the recorder runs on, and everything that differs by it is behind
//! [`platform`]. The _flavor_ is the komorebi being recorded, komorebi for Mac or komorebi for Windows, and everything
//! that differs by it is behind a trait in the analysis. A session records both, so a session recorded on one host can
//! be read on the other.
//!
//! Every record in a session is stamped on one monotonic clock, the _master clock_ ([`clock`]). Video frames and the OS
//! trace are already on it; komorebi's log lines carry wall-clock time and are mapped onto it with paired readings of
//! both clocks. For example, a log line stamped five seconds after the first of two anchors that are ten seconds apart
//! is five seconds after it on the master clock too:
//!
//! ```rust
//! use komorebi_recorder::clock::Anchor;
//! use komorebi_recorder::clock::ClockMap;
//!
//! let map = ClockMap::new(vec![
//! Anchor { wall_us: 1_000_000, mach_ns: 5_000_000_000 },
//! Anchor { wall_us: 11_000_000, mach_ns: 15_000_000_000 },
//! ]);
//!
//! assert_eq!(map.wall_to_mach(6_000_000), Some(10_000_000_000));
//! ```
//!
//! # Where to start
//!
//! The modules, from the ones everything else uses to the ones that use everything:
//!
//! | module | what it is |
//! |---|---|
//! | [`timecode`] | parsing and printing video timecodes |
//! | [`clock`] | the master clock, anchors and the map between the wall clock and the master clock |
//! | [`platform`] | everything that differs by host, behind one facade |
//!
//! # What is not supported
//!
//! The recorder does not change komorebi's log level or lifecycle, it does not need `sudo` and changes no SIP setting on
//! a Mac, and it does not trace system calls. A session records what komorebi, the OS trace and the screen said, and
//! nothing from before the recording began.
//!
//! # Platform support
//!
//! The Windows host is type-checked and cross-built from a Mac and built on Windows in CI, and has never been run. See
//! [`platform`] for what each host provides.
pub mod clock;
pub mod platform;
pub mod timecode;
@@ -0,0 +1,112 @@
//! The master clock on macOS: `mach_absolute_time`, the clock `ScreenCaptureKit` and the unified
//! log already use.
//!
//! Every time in a session is nanoseconds on this clock (see [`crate::clock`]). It counts ticks of
//! a size the OS reports ([`timebase`]) and pauses while the machine sleeps, so a sleep shows up as
//! the wall clock moving on while this one does not. [`reference_clocks`] reads the clock that does
//! keep counting through a sleep.
//!
//! The same items exist on Windows, where the clock is `QueryPerformanceCounter`.
use crate::clock::Timebase;
use crate::platform::ClockKind;
use std::sync::OnceLock;
/// Which clock the master clock is: [`ClockKind::Mach`], recorded as `host.clock` in the manifest.
pub const KIND: ClockKind = ClockKind::Mach;
#[repr(C)]
struct MachTimebaseInfo {
numer: u32,
denom: u32,
}
// `libc` marks its mach bindings deprecated in favour of the `mach2` crate; these two symbols
// are all we need from libSystem, so declare them directly instead of adding a dependency
unsafe extern "C" {
fn mach_absolute_time() -> u64;
fn mach_continuous_time() -> u64;
fn mach_timebase_info(info: *mut MachTimebaseInfo) -> i32;
}
/// Returns what one tick of [`now_ticks`] is worth, as `numer / denom` nanoseconds.
///
/// It is read from `mach_timebase_info` once and kept. If the OS reports no usable timebase (which
/// a Mac that can run this always does), it is `1 / 1`.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::platform::clock::{now_ns, now_ticks, timebase};
///
/// // the master clock is the tick count scaled by the timebase, and never goes backwards
/// let ns = timebase().ticks_to_ns(now_ticks());
/// assert!(now_ns() >= ns);
/// ```
#[must_use]
pub fn timebase() -> Timebase {
static TIMEBASE: OnceLock<Timebase> = OnceLock::new();
*TIMEBASE.get_or_init(|| {
let mut info = MachTimebaseInfo { numer: 0, denom: 0 };
// SAFETY: `info` is a valid out pointer for the duration of the call
let status = unsafe { mach_timebase_info(&raw mut info) };
if status != 0 || info.denom == 0 {
// every Mac that can run this has a valid timebase; 1/1 is the safe identity
return Timebase { numer: 1, denom: 1 };
}
Timebase {
numer: info.numer,
denom: info.denom,
}
})
}
/// Returns the raw tick count of `mach_absolute_time`, which pauses while the machine sleeps.
#[must_use]
pub fn now_ticks() -> u64 {
// SAFETY: no preconditions
unsafe { mach_absolute_time() }
}
/// Returns nanoseconds on the host monotonic clock: the master clock every record in a session is
/// on. It is [`now_ticks`] scaled by [`timebase`], so it pauses while the machine sleeps.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::platform::clock::now_ns;
///
/// let first = now_ns();
/// let second = now_ns();
/// assert!(second >= first);
/// ```
#[must_use]
pub fn now_ns() -> u64 {
timebase().ticks_to_ns(now_ticks())
}
/// Returns the host's other clocks, to be read beside the master clock: one,
/// `mach_continuous_time`, which counts the time the machine spends asleep, unlike the master
/// clock.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::platform::clock::reference_clocks;
///
/// let clocks = reference_clocks();
/// assert_eq!(clocks.len(), 1);
/// assert_eq!(clocks[0].name, "mach_continuous_time");
/// assert!(clocks[0].counts_sleep);
/// ```
#[must_use]
pub fn reference_clocks() -> Vec<crate::clock::ReferenceClock> {
// SAFETY: no preconditions
let ticks = unsafe { mach_continuous_time() };
vec![crate::clock::ReferenceClock {
name: "mach_continuous_time".to_string(),
counts_sleep: true,
ns: timebase().ticks_to_ns(ticks),
}]
}
@@ -0,0 +1,22 @@
//! The macOS host: what the [`platform`](crate::platform) facade is made of on a Mac.
//!
//! | module | built on |
//! |---|---|
//! | `apps` | the window server's window list (`CGWindowListCopyWindowInfo`) |
//! | `capture` | `ScreenCaptureKit` and `AVFoundation` (in `crate::capture::sck`) |
//! | `clock` | `mach_absolute_time` |
//! | `power` | nothing: a Mac's sleep is found from the clocks, so there is no watcher |
//! | `process` | process groups and `SIGTERM` |
//! | `session` | the CoreGraphics session dictionary |
//! | `shell` | `open`, `osascript` and `sw_vers` |
//! | `trace` | nothing: the OS trace is `log stream` children (`crate::sources::oslog`), not taps |
//!
//! Nothing here is public API except through the facade: this module is private, and the facade
//! re-exports its submodules under the same names on every host.
pub mod clock;
pub mod shell;
/// Does nothing: a Mac needs nothing done once at the start of `main`. (Windows makes the process
/// DPI aware.)
pub fn init() {}
@@ -0,0 +1,72 @@
//! Showing a folder, asking for one, and naming the OS.
//!
//! The recorder window offers to show a finished session in the file manager, the viewer asks for
//! a session folder, and the manifest records the OS version. On macOS these are `open`,
//! `osascript` and `sw_vers`; the same items exist on Windows.
use std::path::Path;
use std::path::PathBuf;
use std::process::Command;
/// What the OS calls its file manager, for button labels: `Finder`.
pub const FILE_MANAGER: &str = "Finder";
/// Returns the OS version as `sw_vers -productVersion` prints it, e.g. `26.0`, or `None` if that
/// cannot be run or prints nothing. On Windows it is `major.minor.build`.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::platform::shell::{FILE_MANAGER, os_version};
///
/// assert_eq!(FILE_MANAGER, "Finder");
/// if let Some(version) = os_version() {
/// assert!(version.chars().all(|c| c.is_ascii_digit() || c == '.'), "{version}");
/// }
/// ```
#[must_use]
pub fn os_version() -> Option<String> {
let output = Command::new("/usr/bin/sw_vers")
.arg("-productVersion")
.output()
.ok()?;
let version = String::from_utf8(output.stdout).ok()?.trim().to_string();
(!version.is_empty()).then_some(version)
}
/// Shows `path` in the file manager.
///
/// This runs `open path` and does not wait for it, and a failure to start it is not reported. A
/// folder opens in Finder. A file opens in its default application, not selected in Finder (`open
/// -R` would select it); the recorder only passes folders. On Windows a file is selected in its
/// folder.
///
/// This starts another program, so it has no doctest.
pub fn reveal(path: &Path) {
let _ = Command::new("open").arg(path).spawn();
}
/// Asks the user for a folder with the system's own dialog, and blocks until they answer.
///
/// Returns the folder they chose, or `None` if they canceled, the dialog could not be shown, or
/// the path came back empty. `prompt` is the dialog's prompt text. It is not escaped: it is placed
/// inside an `AppleScript` string, so it should not contain `"` or `\`.
///
/// This shows a dialog, so it has no doctest.
#[must_use]
pub fn pick_folder(prompt: &str) -> Option<PathBuf> {
let output = Command::new("osascript")
.args([
"-e",
&format!("POSIX path of (choose folder with prompt \"{prompt}\")"),
])
.output()
.ok()?;
output
.status
.success()
.then(|| String::from_utf8_lossy(&output.stdout).trim().to_string())
.filter(|path| !path.is_empty())
.map(PathBuf::from)
}
+181
View File
@@ -0,0 +1,181 @@
//! Everything that differs by the OS the recorder runs on.
//!
//! The rest of the crate never names a system API. It asks this module for the handful of things
//! that are not portable, and each host provides them:
//!
//! | module | what it answers |
//! |---|---|
//! | [`clock`] | the master monotonic clock and its tick size |
//! | [`shell`] | the OS version, and (for the recorder window) showing a folder and asking for one |
//!
//! A third host, `unsupported`, builds on anything else so that the investigation commands (which
//! only read a session directory) still work on a Linux agent box; recording there says so.
//!
//! # The host axis
//!
//! This is the *host* axis: what the recorder is running on.
//! Which komorebi produced a session is a separate axis, the *flavor*: a session recorded on
//! Windows can be investigated on a Mac, and the [`Host`] a session was recorded on is part of its
//! manifest.
//!
//! # Adding a function
//!
//! A function that the rest of the crate calls as `platform::<module>::<name>` has to exist, with
//! the same signature, in `macos/<module>.rs`, `win/<module>.rs` and `unsupported.rs`. The
//! compiler enforces that for the host being built, and for no other: the Windows host is built
//! from a Mac by `just check-windows` and by CI, and `unsupported` is built only on a third OS,
//! where nothing in CI builds it.
#[cfg(target_os = "macos")]
mod macos;
#[cfg(target_os = "macos")]
use macos as imp;
#[cfg(not(any(target_os = "macos", windows)))]
mod unsupported;
#[cfg(not(any(target_os = "macos", windows)))]
use unsupported as imp;
// not `windows`: that would be ambiguous with the `windows` crate in every `use` of this module
#[cfg(windows)]
mod win;
#[cfg(windows)]
use win as imp;
pub use imp::clock;
pub use imp::shell;
/// Things the OS wants done once, first thing in `main`: on Windows, becoming DPI aware so that
/// sizes and positions are in physical pixels. Nothing on other hosts.
pub fn init() {
imp::init();
}
use schemars::JsonSchema;
use serde::Deserialize;
use serde::Serialize;
/// Which master clock a session's `*_mach_ns` values are on.
///
/// The field names keep their historical `mach_` spelling so that sessions stay readable by every
/// build of the tool; what they hold is "nanoseconds on the host's monotonic clock", and this says
/// which clock that was.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ClockKind {
/// `mach_absolute_time`: pauses while the machine sleeps.
Mach,
/// `QueryPerformanceCounter`.
Qpc,
/// A host with no capture, which still needs some monotonic clock to run on.
Std,
}
/// What a session was recorded on.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::platform::ClockKind;
/// use komorebi_recorder::platform::Host;
///
/// // a session from before hosts were recorded can only have been recorded on a Mac
/// let host = Host::legacy_macos(Some("26.0".to_string()));
/// assert!(host.is_macos() && !host.is_windows());
/// assert_eq!(host.clock, ClockKind::Mach);
/// assert_eq!(host.describe(), "macOS 26.0");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Host {
/// `macos`, `windows`, ...
pub os: String,
/// The CPU architecture, as Rust names it (`aarch64`, `x86_64`).
pub arch: String,
/// The OS version, if the host could say (`26.0` on macOS, `10.0.26100` on Windows).
pub os_version: Option<String>,
/// Which clock the session's `*_mach_ns` values are on.
pub clock: ClockKind,
}
impl Host {
/// The machine this process is running on.
#[must_use]
pub fn current() -> Self {
Self {
os: std::env::consts::OS.to_string(),
arch: std::env::consts::ARCH.to_string(),
os_version: shell::os_version(),
clock: clock::KIND,
}
}
/// What a session from before hosts were recorded was recorded on: it can only have been a Mac.
#[must_use]
pub fn legacy_macos(os_version: Option<String>) -> Self {
Self {
os: "macos".to_string(),
arch: "aarch64".to_string(),
os_version,
clock: ClockKind::Mach,
}
}
#[must_use]
/// Returns `true` if and only if this is macOS.
pub fn is_macos(&self) -> bool {
self.os == "macos"
}
#[must_use]
/// Returns `true` if and only if this is Windows.
pub fn is_windows(&self) -> bool {
self.os == "windows"
}
/// `macOS 26.0`, `windows 10.0.26100`: for prose.
#[must_use]
pub fn describe(&self) -> String {
let os = match self.os.as_str() {
"macos" => "macOS",
"windows" => "Windows",
other => other,
};
match &self.os_version {
Some(version) => format!("{os} {version}"),
None => os.to_string(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_host_reads_back_what_it_wrote() {
let host = Host::current();
let text = serde_json::to_string(&host).expect("serialize");
let back: Host = serde_json::from_str(&text).expect("parse");
assert_eq!(back, host);
}
#[test]
fn the_clock_kind_is_spelled_in_lowercase() {
assert_eq!(
serde_json::to_string(&ClockKind::Qpc).expect("serialize"),
r#""qpc""#
);
assert_eq!(
serde_json::to_string(&ClockKind::Mach).expect("serialize"),
r#""mach""#
);
}
#[test]
fn a_session_from_before_hosts_were_recorded_was_a_mac() {
let host = Host::legacy_macos(Some("26.0".into()));
assert!(host.is_macos());
assert_eq!(host.describe(), "macOS 26.0");
assert_eq!(host.clock, ClockKind::Mach);
}
}
@@ -0,0 +1,62 @@
//! Any other OS: enough to build and to investigate a session directory that was recorded
//! elsewhere (the commands that only read files), but not to record one.
/// Nothing to do first.
pub fn init() {}
/// The master clock, which here is Rust's monotonic [`Instant`].
pub mod clock {
use crate::clock::Timebase;
use crate::platform::ClockKind;
use std::sync::OnceLock;
use std::time::Instant;
/// The clock a session recorded here is on: Rust's [`Instant`].
pub const KIND: ClockKind = ClockKind::Std;
/// Returns the identity timebase: [`now_ns`] is already in nanoseconds.
#[must_use]
pub fn timebase() -> Timebase {
Timebase { numer: 1, denom: 1 }
}
/// Returns no other clocks.
#[must_use]
pub fn reference_clocks() -> Vec<crate::clock::ReferenceClock> {
Vec::new()
}
/// Nanoseconds since the first reading in this process, offset so that none is ever zero
/// (zero means "not yet" in the capture counters).
#[must_use]
pub fn now_ns() -> u64 {
static START: OnceLock<Instant> = OnceLock::new();
START.get_or_init(Instant::now).elapsed().as_nanos() as u64 + 1_000_000_000
}
}
/// Showing a folder, asking for one, and naming the OS, with what this host can offer.
pub mod shell {
use std::path::Path;
use std::path::PathBuf;
/// What this host calls its file manager, for button labels.
pub const FILE_MANAGER: &str = "file manager";
/// Returns `None`: this host cannot say which version it is.
#[must_use]
pub fn os_version() -> Option<String> {
None
}
/// Asks `xdg-open` to show `path`.
pub fn reveal(path: &Path) {
let _ = std::process::Command::new("xdg-open").arg(path).spawn();
}
/// Returns `None`: this host has no dialog to ask with.
#[must_use]
pub fn pick_folder(_prompt: &str) -> Option<PathBuf> {
None
}
}
@@ -0,0 +1,83 @@
//! The master clock on Windows: `QueryPerformanceCounter`, the clock Windows.Graphics.Capture frame
//! times are on.
//!
//! Every time in a session is nanoseconds on this clock (see [`crate::clock`]). It counts ticks of
//! a size the OS reports ([`timebase`]). Whether it keeps counting while the machine sleeps is not
//! assumed: `doctor --probe clock` measures it, using the two clocks of [`reference_clocks`], and
//! the power watcher (`crate::platform::power`) says when a sleep happens either way.
//!
//! The same items exist on macOS, where the clock is `mach_absolute_time`.
use crate::clock::Timebase;
use crate::platform::ClockKind;
use std::sync::OnceLock;
use windows::Win32::System::Performance::QueryPerformanceCounter;
use windows::Win32::System::Performance::QueryPerformanceFrequency;
use windows::Win32::System::WindowsProgramming::QueryInterruptTime;
use windows::Win32::System::WindowsProgramming::QueryUnbiasedInterruptTimePrecise;
/// Which clock the master clock is: [`ClockKind::Qpc`], recorded as `host.clock` in the manifest.
pub const KIND: ClockKind = ClockKind::Qpc;
/// Returns what one tick of [`now_ticks`] is worth, as `numer / denom` nanoseconds.
///
/// It is made from `QueryPerformanceFrequency` once and kept. If that cannot be read, which it
/// cannot do on any Windows that runs this, the frequency is taken to be 10 MHz, which is what it
/// is nearly everywhere.
#[must_use]
pub fn timebase() -> Timebase {
static TIMEBASE: OnceLock<Timebase> = OnceLock::new();
*TIMEBASE.get_or_init(|| {
let mut frequency = 0_i64;
// SAFETY: `frequency` is a valid out pointer for the duration of the call
let known = unsafe { QueryPerformanceFrequency(&raw mut frequency) }.is_ok();
// it cannot fail on any Windows that runs this; 10 MHz is what it says nearly everywhere
Timebase::from_frequency(if known && frequency > 0 {
frequency as u64
} else {
10_000_000
})
})
}
/// Returns the raw `QueryPerformanceCounter` tick count. A negative reading, which does not
/// happen, is `0`.
#[must_use]
pub fn now_ticks() -> u64 {
let mut ticks = 0_i64;
// SAFETY: `ticks` is a valid out pointer for the duration of the call
let _ = unsafe { QueryPerformanceCounter(&raw mut ticks) };
ticks.max(0) as u64
}
/// Returns nanoseconds on the host monotonic clock: the master clock every record in a session is
/// on. It is [`now_ticks`] scaled by [`timebase`].
#[must_use]
pub fn now_ns() -> u64 {
timebase().ticks_to_ns(now_ticks())
}
/// Returns the host's other clocks, to be read beside the master clock: the two interrupt-time
/// clocks.
///
/// `QueryInterruptTime` counts the time the machine is suspended and
/// `QueryUnbiasedInterruptTimePrecise` does not. Both are read in 100 ns units and returned in
/// nanoseconds. Which of them the performance counter behaves like is what decides how a sleep
/// can be noticed.
#[must_use]
pub fn reference_clocks() -> Vec<crate::clock::ReferenceClock> {
// SAFETY: no preconditions
let (biased, unbiased) = unsafe { (QueryInterruptTime(), QueryUnbiasedInterruptTimePrecise()) };
vec![
crate::clock::ReferenceClock {
name: "QueryInterruptTime".to_string(),
counts_sleep: true,
ns: biased.saturating_mul(100),
},
crate::clock::ReferenceClock {
name: "QueryUnbiasedInterruptTimePrecise".to_string(),
counts_sleep: false,
ns: unbiased.saturating_mul(100),
},
]
}
+33
View File
@@ -0,0 +1,33 @@
//! The Windows host: what the [`platform`](crate::platform) facade is made of on Windows.
//!
//! | module | built on |
//! |---|---|
//! | `apps` | `EnumWindows` and `GetWindowThreadProcessId` |
//! | `capture` | monitor enumeration and per-monitor DPI; the capture itself is Windows.Graphics.Capture (in `crate::capture::wgc`) |
//! | `clock` | `QueryPerformanceCounter` |
//! | `media` | Windows Runtime and Media Foundation start-up, shared by the capture and the decoder |
//! | `power` | a hidden window that is sent suspend, resume, lid, display and session messages |
//! | `process` | process creation flags and `TerminateProcess` |
//! | `session` | whether the input desktop can be opened |
//! | `shell` | Explorer, the folder dialog and `RtlGetVersion` |
//! | `trace` | a `WinEvent` hook and Event Log subscriptions (see `crate::sources::wintrace`) |
//! | `window` | this program's own windows and the reads about any window |
//!
//! Nothing here is public API except through the facade: this module is private, and the facade
//! re-exports its submodules (all but `window`, which the shared `platform::window` calls) under the
//! same names as on the other hosts.
//!
//! This code is compiled only for Windows. From another host it is type-checked and linted with
//! `just check-windows`, and the checklist for running it on a real machine is
//! `docs/dev/windows-checkpoints.md`.
pub mod clock;
pub mod shell;
/// Does what Windows needs once, first thing in `main`: makes the process per-monitor DPI aware
/// ([`capture::become_per_monitor_dpi_aware`]), so that every size and position it reads is in
/// physical pixels, as komorebi's are. A Mac needs nothing here.
pub fn init() {
// Without this Windows lies to us about sizes: a display scaled to 150 % reads as smaller than
// it is, and komorebi's rects (which are physical pixels) would not match ours.
}
+111
View File
@@ -0,0 +1,111 @@
//! Showing a folder, asking for one, and naming the OS.
//!
//! The recorder window offers to show a finished session in the file manager, the viewer asks for
//! a session folder, and the manifest records the OS version. On Windows these are Explorer, the
//! common file dialog and `RtlGetVersion`; the same items exist on macOS.
use std::path::Path;
use std::path::PathBuf;
use std::process::Command;
use windows::Wdk::System::SystemServices::RtlGetVersion;
use windows::Win32::System::Com::CLSCTX_INPROC_SERVER;
use windows::Win32::System::Com::COINIT_APARTMENTTHREADED;
use windows::Win32::System::Com::CoCreateInstance;
use windows::Win32::System::Com::CoInitializeEx;
use windows::Win32::System::Com::CoTaskMemFree;
use windows::Win32::System::Com::CoUninitialize;
use windows::Win32::System::SystemInformation::OSVERSIONINFOW;
use windows::Win32::UI::Shell::FOS_FORCEFILESYSTEM;
use windows::Win32::UI::Shell::FOS_PICKFOLDERS;
use windows::Win32::UI::Shell::FileOpenDialog;
use windows::Win32::UI::Shell::IFileOpenDialog;
use windows::Win32::UI::Shell::SIGDN_FILESYSPATH;
use windows::core::PCWSTR;
/// What the OS calls its file manager, for button labels: `Explorer`.
pub const FILE_MANAGER: &str = "Explorer";
/// Returns the Windows version as `major.minor.build`, e.g. `10.0.26100`, or `None` if it cannot be
/// read. On macOS it is the product version, e.g. `26.0`.
///
/// This is `RtlGetVersion`, because the documented `GetVersionEx` lies to a program without a
/// manifest saying which Windows it was made for.
#[must_use]
pub fn os_version() -> Option<String> {
let mut info = OSVERSIONINFOW {
dwOSVersionInfoSize: size_of::<OSVERSIONINFOW>() as u32,
..Default::default()
};
// SAFETY: `info` is a valid, correctly sized out structure
let status = unsafe { RtlGetVersion(&raw mut info) };
status.is_ok().then(|| {
format!(
"{}.{}.{}",
info.dwMajorVersion, info.dwMinorVersion, info.dwBuildNumber
)
})
}
/// Shows `path` in the file manager: a folder is opened, a file is selected in its folder.
///
/// This starts `explorer` and does not wait for it; Explorer exits with status 1 even when it
/// worked, so only starting it is checked, and a failure to start it is not reported. On macOS a
/// file is opened in its default application instead of being selected.
pub fn reveal(path: &Path) {
let mut command = Command::new("explorer");
if path.is_file() {
let mut select = std::ffi::OsString::from("/select,");
select.push(path);
command.arg(select);
} else {
command.arg(path);
}
// explorer exits with 1 even when it worked; only starting it matters
let _ = command.spawn();
}
/// Asks the user for a folder with the system's own dialog, and blocks until they answer.
///
/// Returns the folder they chose, or `None` if they canceled, the dialog could not be shown, or
/// the path came back empty. `prompt` is the dialog's title. The dialog is made on the calling
/// thread, which is given a COM apartment for the duration unless it already has one.
#[must_use]
pub fn pick_folder(prompt: &str) -> Option<PathBuf> {
// SAFETY: COM is initialised for this thread for the duration of the dialog and released after
// (unless some other code had initialised it differently, in which case it is theirs to release)
unsafe {
let initialised = CoInitializeEx(None, COINIT_APARTMENTTHREADED).is_ok();
let chosen = pick(prompt);
if initialised {
CoUninitialize();
}
chosen
}
}
/// # Safety
/// COM must be initialized on the calling thread.
unsafe fn pick(prompt: &str) -> Option<PathBuf> {
// SAFETY: the caller initialised COM; every pointer below is owned by a COM wrapper or freed
unsafe {
let dialog: IFileOpenDialog =
CoCreateInstance(&FileOpenDialog, None, CLSCTX_INPROC_SERVER).ok()?;
let options = dialog.GetOptions().ok()?;
dialog
.SetOptions(options | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM)
.ok()?;
let title: Vec<u16> = prompt.encode_utf16().chain(Some(0)).collect();
dialog.SetTitle(PCWSTR(title.as_ptr())).ok()?;
// cancelling is an error as far as COM is concerned
dialog.Show(None).ok()?;
let item = dialog.GetResult().ok()?;
let name = item.GetDisplayName(SIGDN_FILESYSPATH).ok()?;
let path = name.to_string().ok();
CoTaskMemFree(Some(name.0.cast_const().cast()));
path.filter(|path| !path.is_empty()).map(PathBuf::from)
}
}
+277
View File
@@ -0,0 +1,277 @@
//! Parsing and formatting of video timecodes: the way a position in a recording is typed on a
//! command line and shown back.
//!
//! A timecode is a number of seconds of video time, an `f64`, counted from the first captured
//! frame of a session (video `00:00.000`). A time before the first frame is negative.
//!
//! | Function | Does |
//! |---|---|
//! | [`parse`] | reads a timecode into seconds |
//! | [`parse_span`] | reads a duration (`500ms`, `2m`) into seconds |
//! | [`format()`] | writes seconds as a timecode |
//!
//! Accepted by [`parse`]: `12.5` (seconds), `12`, `00:12.500`, `1:02`, `1:02:03` and `1:02:03.25`.
//! A leading `-` is accepted so that offsets before the start of the video can be expressed.
//! [`format()`] writes `MM:SS.mmm`, or `H:MM:SS.mmm` from one hour on, and [`parse`] reads back
//! what it writes.
//!
//! This module has no idea what a recording is: it converts between text and a number of seconds,
//! and places nothing on a clock. Turning video seconds into a time on the master clock is the
//! session manifest's `mach_at_video_seconds`, and the reverse its `video_seconds`.
//!
//! # Example
//!
//! ```rust
//! use komorebi_recorder::timecode;
//!
//! assert_eq!(timecode::parse("00:12.500")?, 12.5);
//! assert_eq!(timecode::parse("1:02:03")?, 3723.0);
//! assert_eq!(timecode::parse("-1.5")?, -1.5);
//!
//! assert_eq!(timecode::format(12.5), "00:12.500");
//! assert_eq!(timecode::format(3723.25), "1:02:03.250");
//!
//! // a span is a length of time, not a position
//! assert_eq!(timecode::parse_span("500ms")?, 0.5);
//! assert_eq!(timecode::parse_span("2m")?, 120.0);
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
use color_eyre::eyre;
/// Parses a timecode into seconds.
///
/// The forms are `[[H:]M:]S[.fraction]`, optionally preceded by `-`, with surrounding whitespace
/// ignored: `12.5`, `12`, `00:12.500`, `1:02`, `1:02:03` and `1:02:03.25`. The hours and minutes
/// are whole numbers, and the seconds are any non-negative number Rust reads as an `f64`. The
/// parts are not range checked, so `1:75` is `135` seconds and `90:00` is `5400`. A `-` negates
/// the whole timecode, and is only accepted once, at the start.
///
/// # Errors
///
/// Returns an error if the input
///
/// * is empty (after trimming, and after a leading `-`): `empty timecode`;
/// * has more than three `:`-separated parts: `expected [[H:]M:]S[.fraction]`;
/// * has an hours or minutes part that is not an unsigned whole number (`1.5:30`, `1:-2:30`);
/// * has a seconds part, the last one, that is not a number, or is negative, `NaN` or infinite
/// (`abc`, `--1`, `1:-2`, `nan`, `inf`).
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::timecode::parse;
///
/// assert_eq!(parse("12.5")?, 12.5);
/// assert_eq!(parse("1:02")?, 62.0);
/// assert_eq!(parse("1:02:03.25")?, 3723.25);
/// assert_eq!(parse("-0:01.500")?, -1.5);
///
/// // the parts are not range checked
/// assert_eq!(parse("1:75")?, 135.0);
///
/// let error = parse("1:2:3:4").unwrap_err();
/// assert_eq!(error.to_string(), "invalid timecode '1:2:3:4': expected [[H:]M:]S[.fraction]");
/// assert_eq!(parse("").unwrap_err().to_string(), "empty timecode");
/// assert!(parse("nan").is_err());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn parse(input: &str) -> eyre::Result<f64> {
let trimmed = input.trim();
let (negative, body) = match trimmed.strip_prefix('-') {
Some(rest) => (true, rest),
None => (false, trimmed),
};
if body.is_empty() {
eyre::bail!("empty timecode");
}
let parts: Vec<&str> = body.split(':').collect();
if parts.len() > 3 {
eyre::bail!("invalid timecode '{input}': expected [[H:]M:]S[.fraction]");
}
let mut seconds = 0.0_f64;
for (index, part) in parts.iter().enumerate() {
let is_last = index == parts.len() - 1;
let invalid = || eyre::Report::msg(format!("invalid timecode '{input}'"));
let value: f64 = if is_last {
part.parse().map_err(|_| invalid())?
} else {
f64::from(part.parse::<u32>().map_err(|_| invalid())?)
};
if !value.is_finite() || value < 0.0 {
eyre::bail!("invalid timecode '{input}'");
}
seconds = seconds * 60.0 + value;
}
Ok(if negative { -seconds } else { seconds })
}
/// Parses a duration such as `1s`, `500ms`, `1.5` (seconds) or `2m` into seconds.
///
/// A number followed by `ms` (milliseconds), `s` (seconds) or `m` (minutes), with nothing after it
/// meaning seconds. Whitespace around the input, and between the number and its unit, is ignored.
/// Hours are not a unit: use minutes, or a timecode with [`parse`].
///
/// # Errors
///
/// Returns an error if the number is not a number Rust reads as an `f64` (`soon`, or an empty
/// string), or if it is negative, `NaN` or infinite: a span cannot be negative.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::timecode::parse_span;
///
/// assert_eq!(parse_span("1s")?, 1.0);
/// assert_eq!(parse_span("500ms")?, 0.5);
/// assert_eq!(parse_span("1.5")?, 1.5);
/// assert_eq!(parse_span("2m")?, 120.0);
///
/// assert!(parse_span("-1s").is_err());
/// assert!(parse_span("soon").is_err());
/// assert_eq!(
/// parse_span("soon").unwrap_err().to_string(),
/// "invalid duration 'soon': expected e.g. 1s, 500ms or 1.5"
/// );
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn parse_span(input: &str) -> eyre::Result<f64> {
let trimmed = input.trim();
let (number, scale) = if let Some(rest) = trimmed.strip_suffix("ms") {
(rest, 0.001)
} else if let Some(rest) = trimmed.strip_suffix('s') {
(rest, 1.0)
} else if let Some(rest) = trimmed.strip_suffix('m') {
(rest, 60.0)
} else {
(trimmed, 1.0)
};
let value: f64 = number.trim().parse().map_err(|_| {
eyre::Report::msg(format!(
"invalid duration '{input}': expected e.g. 1s, 500ms or 1.5"
))
})?;
if !value.is_finite() || value < 0.0 {
eyre::bail!("invalid duration '{input}': must be a non-negative number");
}
Ok(value * scale)
}
/// Returns `seconds` as a timecode: `MM:SS.mmm`, or `H:MM:SS.mmm` from one hour on.
///
/// The value is rounded to the nearest millisecond. Minutes and seconds are two digits and
/// milliseconds three; hours have as many digits as they need. A negative value is written with a
/// leading `-`, which a value that rounds to zero keeps (`-00:00.000`). The result is not
/// specified for a `NaN` or infinite `seconds`.
///
/// [`parse`] reads back what this writes: a value that is a whole number of milliseconds comes
/// back equal, to within floating point error (the test `format_parse_roundtrip`).
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::timecode::{format, parse};
///
/// assert_eq!(format(0.0), "00:00.000");
/// assert_eq!(format(12.5), "00:12.500");
/// assert_eq!(format(62.0), "01:02.000");
/// assert_eq!(format(3723.25), "1:02:03.250");
/// assert_eq!(format(-1.5), "-00:01.500");
///
/// // rounded to the millisecond
/// assert_eq!(format(1.2346), "00:01.235");
///
/// assert!((parse(&format(7322.125))? - 7322.125).abs() < 1e-9);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn format(seconds: f64) -> String {
let sign = if seconds < 0.0 { "-" } else { "" };
let total_ms = (seconds.abs() * 1_000.0).round() as u64;
let ms = total_ms % 1_000;
let total_s = total_ms / 1_000;
let s = total_s % 60;
let m = (total_s / 60) % 60;
let h = total_s / 3_600;
if h > 0 {
format!("{sign}{h}:{m:02}:{s:02}.{ms:03}")
} else {
format!("{sign}{m:02}:{s:02}.{ms:03}")
}
}
#[cfg(test)]
mod tests {
use super::*;
fn close(a: f64, b: f64) -> bool {
(a - b).abs() < 1e-9
}
#[test]
fn parses_plain_seconds() {
assert!(close(parse("12.5").unwrap(), 12.5));
assert!(close(parse("12").unwrap(), 12.0));
assert!(close(parse("0.04").unwrap(), 0.04));
}
#[test]
fn parses_clock_forms() {
assert!(close(parse("00:12.500").unwrap(), 12.5));
assert!(close(parse("1:02").unwrap(), 62.0));
assert!(close(parse("1:02:03").unwrap(), 3723.0));
assert!(close(parse("1:02:03.25").unwrap(), 3723.25));
}
#[test]
fn parses_negative_offsets() {
assert!(close(parse("-1.5").unwrap(), -1.5));
assert!(close(parse("-0:01.500").unwrap(), -1.5));
}
#[test]
fn rejects_garbage() {
for bad in [
"", "abc", "1:2:3:4", "1.5:30", "::", "1:-2", "--1", "nan", "inf",
] {
assert!(parse(bad).is_err(), "{bad:?} should not parse");
}
}
#[test]
fn parses_spans() {
assert!(close(parse_span("1s").unwrap(), 1.0));
assert!(close(parse_span("500ms").unwrap(), 0.5));
assert!(close(parse_span("1.5").unwrap(), 1.5));
assert!(close(parse_span("2m").unwrap(), 120.0));
assert!(parse_span("-1s").is_err());
assert!(parse_span("soon").is_err());
assert!(parse_span("").is_err());
}
#[test]
fn formats() {
assert_eq!(format(12.5), "00:12.500");
assert_eq!(format(0.0), "00:00.000");
assert_eq!(format(62.0), "01:02.000");
assert_eq!(format(3723.25), "1:02:03.250");
assert_eq!(format(-1.5), "-00:01.500");
}
#[test]
fn format_parse_roundtrip() {
for value in [0.0, 0.001, 12.5, 59.999, 3600.0, 7322.125] {
assert!(close(parse(&format(value)).unwrap(), value));
}
}
}