asciinema-director

Record and share your terminal sessions, the simple way. Forget screen recording apps and blurry video. Experience a lightweight, text-based approach to terminal recording. https://asciinema.org

Installation

This project uses VSCode dev-container to start a docker environment, which contains all necessary dependencies. You can start this dev-container by using the VSCode extension "ms-vscode-remote.remote-containers" or by manually tapping into the .devcontainer directory and exec (docker must be installed):

docker compose up -d

Mandatory dependencies

• asciinema - https://docs.asciinema.org/getting-started/
• python (minimum version v3.11) - https://www.python.org/downloads/ - Hint: See Optional dependencies
• uv - https://docs.astral.sh/uv/getting-started/installation/

Steps for this project

Prepare your python environment:

# assume you are in the root of this repo
uv venv
uv install

With this repo you can direct your terminal sessions by the scripts provided in the ./scripts folder, e.g.:

• demo_script.sh contains the commands
• demo_rec.sh runs the recording

# run rec session
cd scripts/
./demo_rec.sh

# upload .cast files - instead to publish your cast to the public server, you can also choose your private
# server instance - see https://docs.asciinema.org/getting-started/#self-hosting-the-server
asciinema upload casts/demo.cast

Example configuration for asciinema

Put this config into your ~/.config/asciinema/config file and modify to your needs:

[api]

; API server URL, default: https://asciinema.org
; If you run your own instance of asciinema server then set its address here
; It can also be overriden by setting ASCIINEMA_API_URL environment variable
url = https://asciinema.starconnect.ch

[record]

; Command to record, default: $SHELL
command = PS1="\u@\h:\w\$ " bash -l

[play]

; Playback speed (can be fractional), default: 1
; speed = 2

; Limit replayed terminal inactivity to max n seconds, default: off
idle_time_limit = 1

; Define hotkey for pausing/resuming playback,
; default: space
; pause_key = p

; Define hotkey for stepping through playback, a frame at a time,
; default: . (dot)
; step_key = s

; Define hotkey for jumping to the next marker,
; default: ]
next_marker_key = m

[notifications]
; Desktop notifications are displayed in several situations, e.g. when
; pausing/resuming the capture of terminal with C-\ keyboard shortcut.

; Should desktop notifications be enabled, default: yes
enabled = no

; Custom notification command
; asciinema automatically detects available desktop notification system
; (notify-send on GNU/Linux, osacript on macOS). Custom command can be
; used if needed.
; When invoked, environment variable $TEXT contains notification text, while
; $ICON_PATH contains path to the asciinema logo image.
; command = tmux display-message "$TEXT"