asciinema — Record and Share Terminal Sessions

Introduction

asciinema captures terminal output as a timestamped text stream rather than pixel-based video. This produces tiny files that replay at full fidelity, allow copy-paste from the playback, and can be shared via asciinema.org or self-hosted with the asciinema-server.

What asciinema Does

• Records terminal sessions to .cast files (JSON-based asciicast format)
• Plays back recordings in-terminal or via an embeddable web player
• Uploads recordings to asciinema.org for sharing via URL
• Supports idle time compression and speed adjustment on playback
• Integrates with agg (asciinema GIF generator) for conversion to animated GIFs

Architecture Overview

asciinema spawns a pseudo-terminal (pty) and records stdout bytes with microsecond timestamps into the asciicast v2 format (newline-delimited JSON). The web player (asciinema-player, written in TypeScript) interprets these events through a virtual terminal emulator to render frames in the browser without video codecs.

Self-Hosting & Configuration

• Install the CLI from PyPI, Homebrew, or system package manager
• Self-host the server component (asciinema-server, Elixir-based) for private recordings
• Configure ~/.config/asciinema/config for default settings (idle_time_limit, API URL)
• Embed the web player in documentation with a single script tag
• Convert recordings to GIF/SVG using agg or svg-term for offline sharing

Key Features

• Text-based recordings: tiny file size, searchable, copy-paste friendly
• No screen capture artifacts: resolution-independent, always sharp
• Idle time trimming: automatically compress long pauses
• Web player with pause, seek, and speed controls
• Open asciicast format: parseable by third-party tools

Comparison with Similar Tools

• VHS (Charm) — generates GIFs from scripted terminal commands; asciinema records live sessions
• ttyrec/ttygif — older format with less tooling and no web player
• OBS Studio — full screen recording; much larger files, no text selectability
• Terminalizer — Node.js based recorder with GIF export; similar concept, less mature ecosystem
• script (coreutils) — records raw typescript; no timing data or playback player

FAQ

Q: Can viewers copy text from a recording? A: Yes. The web player renders real text, not pixels, so viewers can select and copy.

Q: How do I share without uploading to asciinema.org? A: Self-host asciinema-server, or convert to GIF with agg for embedding anywhere.

Q: Can I edit recordings after capture? A: The .cast format is plain JSON lines. You can trim, splice, or adjust timings with text tools or purpose-built editors like asciinema-edit.

Q: Does it capture colors and cursor position? A: Yes. Full ANSI escape sequence support including 256-color and truecolor.

Sources

• https://github.com/asciinema/asciinema
• https://asciinema.org