# asciinema — Record and Share Terminal Sessions

> asciinema records terminal sessions as lightweight text-based files that can be replayed in a browser, embedded in docs, or converted to GIFs and videos—without screen capture overhead.

## Install

Save as a script file and run:

# asciinema — Record and Share Terminal Sessions

## Quick Use
```bash
# Install
pip install asciinema
# Or via package manager
brew install asciinema        # macOS
sudo apt install asciinema    # Debian/Ubuntu
# Record a session
asciinema rec demo.cast
# Play it back
asciinema play demo.cast
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-b967fb02
Author: Script Depot