Recording

quarto-term can record terminal sessions to asciicast (.cast) files and embed an interactive player for playback.

Recording a session

Add the record option at the document level to capture everything into a .cast file:

extensions:
  term:
    record: "demo.cast"

The file is written relative to the document directory. You can record to multiple formats simultaneously:

extensions:
  term:
    record:
      - "demo.cast"
      - "demo.termshow"

Combine with typing to make the recording look like a human is typing:

extensions:
  term:
    record: "demo.cast"
    typing:
      speed: 400
      error-rate: 0.01

The speed controls characters per minute (default: 300) and error-rate adds occasional typos that get corrected (0.01 = 1% chance per keystroke). Use typing: true for defaults.

Embedding the player

Use the term-player shortcode to embed a recording. The format is auto-detected from the file extension.

Playing asciicast recordings

Asciicast (.cast) files are played using the asciinema player, which renders terminal output live in the browser:

{{< term-player src="demo.cast" >}}

Asciicast options

{{< term-player src="demo.cast" autoplay=true speed=2 loop=true >}}

Option	Type	Default	Description
`src`	string	(required)	Path to the `.cast` file
`autoplay`	boolean	`false`	Start playback automatically
`loop`	boolean/number	`false`	Loop playback; number sets loop count
`speed`	number	`1`	Playback speed multiplier
`controls`	boolean/string	`"auto"`	Show control bar
`poster`	string	first frame	Preview frame specification
`cols`	number	from file	Terminal width in columns
`rows`	number	from file	Terminal height in rows
`preload`	boolean	`false`	Preload the recording on init
`start-at`	number/string	`0`	Start time (seconds or “mm:ss”)
`idle-time-limit`	number	unlimited	Cap idle time to N seconds
`theme`	string	document theme	Colorscheme name (uses quarto-term themes)
`fit`	string	`"width"`	Sizing: “width”, “height”, “both”, “none”
`keystroke-overlay`	boolean	`false`	Show keystroke overlay
`markers`	JSON array	none	Timeline markers
`pause-on-markers`	boolean	`false`	Auto-pause at markers
`font-size`	string	`"small"`	Font size (CSS value or “small”/“medium”/“big”)
`font-family`	string	system mono	CSS font-family
`line-height`	number	`1.33`	Line height
`cursor-mode`	string	`"blinking"`	Cursor: “blinking”, “steady”, “hidden”

Asciicast theming

The player automatically uses the document’s colorscheme (set via style.html.colorscheme-light / colorscheme-dark). To override for a specific player instance, use the theme attribute with any quarto-term theme name:

{{< term-player src="demo.cast" theme="dracula" >}}

All themes from the Styling page are available.

Playing termshow recordings

Termshow (.termshow) files are played using a lightweight SVG-based player. The recording must be pre-built into a directory of SVG keyframes using Great Docs:

{{< term-player src="recording-demo.termshow" >}}

The player expects a termshow/<basename>/ directory containing manifest.json and SVG frame files (generated by great-docs termshow render). It supports chapters, annotations, highlights, and copy-snippet buttons defined in the companion .termshow.yml script.

Termshow options

Option	Type	Default	Description
`src`	string	(required)	Path to the `.termshow` file (basename used for directory lookup)
`autoplay`	boolean	`false`	Start playback automatically
`loop`	boolean	`false`	Loop playback
`speed`	number	`1`	Playback speed multiplier
`controls`	boolean	`true`	Show control bar
`poster`	number	`0`	Time (seconds) for poster frame
`pause-on-chapters`	boolean	`false`	Auto-pause at chapter boundaries
`theme`	string	`"auto"`	Player shell theme: “auto”, “dark”, “light”

Chrome

Both player types support window chrome decoration:

{{< term-player src="demo.cast" chrome=true chrome-title="Terminal" >}}

Recording

Option	Type	Default	Description
`chrome`	boolean/string	`false`	Enable chrome; string sets OS style (“macos”, “windows”)
`chrome-title`	string	none	Window title text
`chrome-os`	string	`"macos"`	OS style: “macos” or “windows”
`chrome-color`	string	none	Custom title bar background color
`chrome-shadow`	boolean	`true`	Show drop shadow

Source

The players on this page all use the same recording, generated by this page’s front matter and the {term} blocks below. The termshow SVG frames are rendered via uvx great-docs termshow render in the project’s pre-render step:

---
extensions:
  term:
    record:
      - "recording-demo.cast"
      - "recording-demo.termshow"
    typing:
      speed: 400
---

```{term}
echo "This is being recorded using quarto-term"
for i in 1 2 3; do
  echo "Step $i"
  sleep 0.3
done
echo "Done."
htop -d 1 #! enter: false, hold: 0.5
```

```{term}
#| fullscreen: true
#| timeout: 4
enter #! literal: false, hold: 5.0
```

```{term}
#| include: false
q #! literal: false
```

echo "This is being recorded using quarto-term"
This is being recorded using quarto-term

for i in 1 2 3; do
  echo "Step $i"
  sleep 0.3
done
Step 1
Step 2
Step 3

echo "Done."
Done.

htop -d 1


    0[                            0.0%] Tasks: 42, 109 thr, 115 kthr; 1 runnin
    1[                            0.0%] Load average: 0.70 0.62 0.27 
    2[                            0.0%] Uptime: 00:04:01
    3[                            0.0%]
  Mem[|||||||||||||||||    1021M/15.6G]
  Swp[                        0K/3.00G]

  [Main] [I/O]
    PID USER       PRI  NI  VIRT   RES   SHR S  CPU%▽MEM%   TIME+  Command      
   4887 runner      20   0  8356  4908  3920 R   9.8  0.0  0:00.19 htop -d 1    
      1 root        20   0 22876 14340  9880 S   0.0  0.1  0:02.17 /sbin/init
    155 root        19  -1 75076 16440 15164 S   0.0  0.1  0:00.18 /usr/lib/syst
    221 root        RT   0  298M 43676  8760 S   0.0  0.3  0:00.01 /sbin/multipa
    226 root        20   0 25956  8032  5220 S   0.0  0.0  0:00.11 /usr/lib/syst
    228 root        20   0  298M 43676  8760 S   0.0  0.3  0:00.00 /sbin/multipa
    229 root        RT   0  298M 43676  8760 S   0.0  0.3  0:00.00 /sbin/multipa
    230 root        RT   0  298M 43676  8760 S   0.0  0.3  0:00.00 /sbin/multipa
    231 root        RT   0  298M 43676  8760 S   0.0  0.3  0:00.00 /sbin/multipa
    232 root        RT   0  298M 43676  8760 S   0.0  0.3  0:00.00 /sbin/multipa
    233 root        RT   0  298M 43676  8760 S   0.0  0.3  0:00.00 /sbin/multipa
    309 root        20   0  3848  2972  2052 S   0.0  0.0  0:00.04 /usr/lib/linu
    411 systemd-re  20   0 21476 13380 11164 S   0.0  0.1  0:00.10 /usr/lib/syst
F1Help  F2Setup F3SearchF4FilterF5Tree  F6SortByF7Nice -F8Nice +F9Kill  F10Quit