asciicast File Format Specification
Reference specification for .cast recording files used across the asciinema ecosystem.
Version Comparison
| Feature | asciicast v1 | asciicast v2 | asciicast v3 |
|---|---|---|---|
| Data Format | Monolithic JSON Object | Newline-Delimited JSON (NDJSON) | Newline-Delimited JSON (NDJSON) |
| Streaming Support | No (buffer in memory) | Yes (append line-by-line) | Yes (append line-by-line) |
| Crash Resilience | None (corrupt on interrupt) | Full (valid up to last written line) | Full (valid up to last written line) |
| Timestamps | Inter-frame delays | Absolute elapsed seconds ($t - t_0$) | Relative delta seconds ($\Delta t$ from previous event) |
| Exit Code | No | No | Yes ("x" event) |
| Comment Lines | No | No | Yes (# comment line) |
asciicast v2 Specification
An asciicast v2 file consists of:
- Line 1: A single JSON object representing the recording header.
- Lines 2+: A stream of 3-element JSON arrays representing events:
[time, type, data].
Header Object (Line 1)
{
"version": 2,
"width": 80,
"height": 24,
"timestamp": 1697400000,
"duration": 42.15,
"idle_time_limit": 2.0,
"command": "/bin/zsh",
"title": "Tutorial Demo",
"env": {
"TERM": "xterm-256color",
"SHELL": "/bin/zsh"
},
"theme": {
"fg": "#d0d0d0",
"bg": "#151515",
"palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5"
}
}Fields:
version(integer, required): Must be2.width(integer, required): Terminal columns.height(integer, required): Terminal rows.timestamp(integer, optional): Unix epoch timestamp when recording started.duration(float, optional): Total recording length in seconds.idle_time_limit(float, optional): Maximum idle duration in seconds to preserve during playback.command(string, optional): Command executed inside the session.title(string, optional): Descriptive recording title.env(object, optional): Environment variables captured at startup (typicallyTERMandSHELL).theme(object, optional): Color scheme overrides withfg,bg, and 8- or 16-color colon-delimitedpalette.
Event Line Schema: [time, type, data]
time(float): Absolute elapsed seconds from recording start ($t_0$).type(string):"o": Output (stdout). Terminal escape sequences and UTF-8 characters printed to screen."i": Input (stdin). Keystrokes received from keyboard (disabled by default)."m": Marker. Bookmark/chapter delimiter;datacontains optional label."r": Resize. Window dimension change ("{cols}x{rows}").
data(string): UTF-8 payload.
Example Stream:
{"version": 2, "width": 80, "height": 24, "timestamp": 1697400000}
[0.102450, "o", "\u001b[1;32muser@host\u001b[0m:\u001b[1;34m~\u001b[0m$ "]
[0.650120, "o", "echo 'Hello World'\r\n"]
[0.650800, "o", "Hello World\r\n"]
[1.200000, "m", "Chapter 2: Resizing"]
[1.500000, "r", "100x30"]asciicast v3 Specification (CLI 3.x / Rust)
Introduced with asciinema CLI 3.0:
1. Relative Delta Timestamps
Instead of absolute timestamps from $t_0$, time is the seconds elapsed since the immediately preceding event. Lines can be cut, spliced, or reordered without recalculating timestamps for the rest of the file.
2. Nested Terminal Metadata
Terminal configuration is grouped under "term":
{
"version": 3,
"term": {
"cols": 80,
"rows": 24,
"type": "xterm-256color"
},
"timestamp": 1697400000
}3. Exit Code Event ("x")
Records child process termination status:
[0.051200, "x", 0]Note on final frame holding: In v3 recordings, preceding the "x" event with a 2–3s delay (e.g. [3.0, "x", 0]) holds the completed terminal screen so viewers can read final output before video players or animated GIFs loop. When converting to asciicast v2 (which has no "x" event), replace the "x" event with a trailing no-op stdout event ([total_time, "o", ""]) to preserve the hold duration.
4. Inline Comments
Lines starting with # are treated as comments and ignored by parsers:
# Step 1: Initialize repository
[0.100000, "o", "git init\r\n"]5. Web Player Compatibility (asciinema-player < 3.10 vs >= 3.10)
asciinemaCLI 3.x records inasciicast v3("version": 3) by default.asciinema-playerversions< 3.10.0(including3.8.xand3.9.x) only parseasciicast v1andv2and fail with the explosion emoji (💥) if fed a{"version": 3}header.- Convert v3 recordings to v2 (
trim-cast.py --to-v2,asciinema convert -f asciicast-v2, or an in-memory JS normalizer passed via{ data: v2Text }) whenever targetingasciinema-player< 3.10.0.
6. Chapter Marker ("m") Timestamp & Cursor-Line Semantics
- When
asciinema-playerauto-pauses on a marker (pauseOnMarkers: true) or seeks to a marker (player.seek(T_m)), it evaluates all"o"events whose timestamp satisfiest <= T_m. - Exact
T_mRounding Parity inv3 -> v2Compilers: When compiling warpedasciicast v2timestamps with.toFixed(6)(Number(warpedAbs.toFixed(6))), snapendTime,warpedAbs, and each chapter'splayTimeto the exact roundedmarkerTime = Number(warpedAbs.toFixed(6))written to the v2 stream. Storing an unrounded IEEE-754 float forplayTimecausesplayer.seek(playTime)(via[/]or chapter pills) to land slightly beforemarkerTimewhenever.toFixed(6)rounds up, skipping the final"o"event(s) of the stop-point frame. - Multi-Chunk
dt = 0.0Synchronized Output Frames: Any"o"event placed after an"m"marker withdt = 0.0shares the exact sameasciicast v2timestampT_m, whereas playback withpauseOnMarkers: truestops at the"m"event in stream order before trailingdt = 0.0chunks. When matching a TUI frame that spans multipledt = 0.0PTY chunks (\x1b[?2026h…\x1b[?2026l),mark-cast.pyadvances past consecutivedt = 0.0"o"events so the"m"marker sits after the complete frame flush. - Command-Entry Cursor Placement: With bracketed paste (
\x1b[?2004h), pressingEnterafter pasting a command emits an[UNREV]redraw frame—inbash(GNU Readline),\x08+...<cmd>followed by\r\n\x1b[?2004l\r...; inzsh,\x1b[A\x1b[...C\x1b[27m...ending with\x1b[1B\r\x1b[K. To pause with the command in normal video and the cursor resting at the end of the command on the same line,mark-cast.pyautomatically splits trailing\r\n\x1b[?2004l\r...(bash) or\x1b[1B\r\x1b[K(zsh) into a separate"o"event after the"m"marker withdt = 0.02s.
7. Terminal Emulator Sequences in Modern Recordings (xterm-ghostty / ECMA-48)
When simulating terminal screen state with pyte (via uv run --with pyte), modern terminals such as xterm-ghostty emit ECMA-48 and hyperlink sequences that stock pyte either ignores or mishandles across event boundaries:
REP(\x1b[Nb): Repeats the last drawn graphic characterNtimes (e.g.,[#\x1b[5b]renders as[######]).CBT(\x1b[NZ): Cursor Backward TabulationNtab stops. WithoutCBTsupport, partial-line TUI diff updates land in the wrong column.DECST8C(\x1b[?5W): Resets tab stops to every 8 columns; ignored by stockpyteand handled alongsideCBT.- Multi-Chunk
OSC 8Hyperlinks: Full-screen TUI redraws often split\x1b]8;id=...;file:///...\x07across consecutive"o"events. StrippingOSCsequences with a stateful cross-chunk filter before feedingpyte.Streamprevents URL tails (8;id=...) from leaking onto the simulated display.