Asciinema v3 on Ubuntu — Installation, Configuration & Power Setup

Obsidian‑ready notes.

✅ TL;DR

• Install asciinema v3 (Rust rewrite) via official GitHub binary
• Remove old apt/Python v2 first
• Use x86_64-unknown-linux-gnu on Ubuntu
• Recording is now file-first, uploads are explicit
• Optional: auto‑record every terminal session like a menace

🧠 What is Asciinema (v3)

Asciinema records terminal sessions into .cast files that can be replayed, shared, streamed live, or converted to plain text.

v3 highlights:

• Full Rust rewrite (faster, cleaner)
• New asciicast v3 format (relative timestamps)
• Live streaming (LAN or remote)
• Explicit uploads (no magic auto‑upload)
• Built‑in server, better docs, TOML config

🧹 Step 0 — Remove old asciinema (IMPORTANT)

If you ever installed asciinema via apt, it’s the old Python v2. Kill it.

sudo apt remove asciinema -y
which asciinema || true

If which asciinema still returns a path → you didn’t clean properly. Fix before proceeding.

📥 Step 1 — Download correct binary (Ubuntu)

Ubuntu uses glibc and almost always runs on x86_64.

Correct file:

• asciinema-x86_64-unknown-linux-gnu

cd ~/Downloads
wget https://github.com/asciinema/asciinema/releases/download/v3.0.0/asciinema-x86_64-unknown-linux-gnu

Sanity check architecture:

uname -m

• x86_64 → correct
• aarch64 → you need the ARM build instead

🔐 Step 2 — Make binary executable

chmod +x asciinema-x86_64-unknown-linux-gnu

📦 Step 3 — Install into PATH (proper way)

sudo mv asciinema-x86_64-unknown-linux-gnu /usr/local/bin/asciinema

Verify:

asciinema --version

Expected output:

asciinema 3.0.0

If this fails, stop. Don’t continue broken installs.

🎥 Step 4 — Basic recording test

asciinema rec test.cast

Inside session:

echo "asciinema v3 works"
exit

Replay:

asciinema play test.cast

If playback works → installation is solid.

⚠️ Critical v3 Behavior Changes

❌ No automatic uploads anymore

• asciinema rec always requires a filename
• Nothing is uploaded automatically

✅ Explicit upload command

asciinema upload test.cast

This is intentional. Predictability > magic.

🔁 Auto‑record EVERY terminal session (Power User Setup)

This will record all terminal sessions automatically.

Add to very bottom of ~/.bashrc or ~/.zshrc

if [ -z "$ASCIINEMA_SESSION" ]; then
  exec asciinema rec ~/sessions/$(date '+%Y/%m/%d/%H-%M-%S')-$.cast
fi

Result

• Every terminal session recorded
• Organized by year/month/day
• Directories auto‑created by asciinema
• Zero effort, full history

📁 Output File Formats

Default (recommended)

• asciicast v3 (.cast)
• Keeps timing, metadata, colors

Plain text output

asciinema rec output.txt

OR

asciinema convert demo.cast demo.txt

⚠️ Text output is one‑way (no timing, no replay).

🔄 Convert recordings

v2 → v3

asciinema convert old-v2.cast new-v3.cast

v3 → v2 (legacy tooling)

asciinema convert -f asciicast-v2 new-v3.cast old-v2.cast

📡 Live Streaming

Local (LAN only, nothing sent online)

asciinema stream --local

Remote (shareable URL)

asciinema stream --remote

You can use both at once.

🎬 Record + Stream at same time

asciinema session -l -r -o demo.cast

This is the replacement for juggling rec + stream.

⚙️ Config file (v3)

Location

~/.config/asciinema/config.toml

Format change

• Old: INI‑style config
• New: TOML config.toml

Section renames

• api → server
• record → session
• play → playback

🧪 Recommended habits (non‑negotiable)

• Always verify install with --version
• Never mix apt + manual binaries
• Keep .cast as source of truth
• Convert to .txt only when exporting
• Track configs in Obsidian (you’re doing that now)

📌 Status

• OS: Ubuntu (glibc)
• Install method: GitHub static binary
• Version: asciinema v3.0.0
• Setup: clean, reproducible, future‑proof

🔥 Next upgrades (optional)

• Self‑host asciinema server
• Index .cast files in Obsidian
• Auto‑upload on session exit
• Git‑track terminal history (yes, it’s possible)