asciinema records terminal sessions. Nothing diffs them. So "it passed on my machine and failed in CI, where did they diverge?" is a question nobody can answer except by scrolling two logs side by side.
They are instructions for producing what the user saw. Two runs that displayed identical output can share almost no bytes — a progress bar redrawn with \r versus one redrawn with a cursor-position sequence, colour that CI disabled because it is not a TTY. diff reports all of it.
So the bytes have to be interpreted, which means a real terminal emulator. The parser follows the DEC state machine Paul Williams derived from the VT500 series, whose virtue is being total: every byte in every state has a defined transition, so a recording of a crashed program recovers instead of wedging.
Bare escapes, unterminated OSC, absurd parameters, invalid UTF-8 — there is a test asserting it recovers from all of them.
A character in the last column does not move the cursor until the next arrives. Getting it wrong adds a blank line to every wrapped line.
A build log is mostly scrollback. Only full-screen scrolls capture, so a TUI redrawing itself does not fill the log with frames.
A Myers edit script over commands first, so one extra step does not report everything after it as different.
Where the shell emits integration markers, segmentation is exact — including the exit code of each command.
Without markers it matches prompts, and the report says the segmentation was guessed rather than presenting it as fact.
The fixtures in the repo make the point — two builds drawing progress bars with completely different escape sequences:
It does not record — asciinema does that well and reimplementing PTY capture would be work with no payoff. No sixel or ReGIS. And timing is not compared: two runs where one took twice as long are identical unless the output says so, because wall-clock is the least reproducible thing about a build.
The README goes deeper, and the tests are the honest documentation. Happy to walk through the trade-offs.