Terminal Recordings

Live example

Recording a session

Use the just command to start a recording:

just record-cast my-demo

This runs asciinema rec and saves the output to public/recordings/my-demo.cast. Run your commands in the terminal session, then press Ctrl+D or type exit to stop recording.

Tip

Idle time is automatically capped at 2.5 seconds during recording. This keeps recordings tight without needing to rush through commands.

Embedding in a page

Import the wrapper component and use it as a JSX tag:

import AsciinemaPlayerWrapper from "../../../../../components/AsciinemaPlayerWrapper.astro";

<AsciinemaPlayerWrapper src="/recordings/my-demo.cast" />

The player loads no JavaScript until the user scrolls it into view, matching the lazy hydration pattern used by the chart and counter components.

Playback options

All attributes beyond src are optional:

Attribute	Type	Description
src	String	Path to the .cast file (required)
cols	Number	Terminal width in columns
rows	Number	Terminal height in rows
autoPlay	Boolean	Start playing automatically
loop	Boolean	Loop playback
speed	Number	Playback speed multiplier (e.g. 2 for double speed)
idleTimeLimit	Number	Cap idle time during playback (seconds)
theme	String	Color theme (e.g. "dracula", "solarized-dark")
fit	String	Fit mode: "width", "height", "both", "none"
controls	String	Show player controls
poster	String	Text to show before playback starts
startAt	Number	Start playback at this time (seconds)
preload	Boolean	Preload the recording
terminalFontSize	String	Terminal font size (e.g. "15px")

Examples

Auto-playing at double speed:

<AsciinemaPlayerWrapper src="/recordings/my-demo.cast" autoPlay={true} speed={2} />

Looping with a theme:

<AsciinemaPlayerWrapper src="/recordings/my-demo.cast" loop={true} theme="dracula" />

Fixed dimensions:

<AsciinemaPlayerWrapper src="/recordings/my-demo.cast" cols={80} rows={24} fit="none" />

How it works

The implementation follows the same pattern as the other interactive components (counter, charts):

1. AsciinemaPlayer.tsx — A Solid.js component that dynamically imports asciinema-player on mount and calls AsciinemaPlayer.create() on a ref div. Cleans up the player instance on unmount.
2. AsciinemaPlayerWrapper.astro — An Astro wrapper that renders the Solid.js component with client:visible for progressive hydration.
3. MDX import — Content authors import the Astro wrapper and use it as a component tag.

Cast files are plain text (JSON lines), so they’re small and version-control friendly.