cassete-deck

Record terminal commands into a GIF file.

⚠️ This is still just a MVP/technical demo/etc. Most features are not implemented/tested. Use cautiously.

This project was inspired by VHS.

VHS requires ffmpeg and chromium to record terminal emulator GIFs. Both terminals and GIFs were invented many years ago, and are really simple and stupid. While using modern technologies to work with them is alright, it's not efficient to use millions SLOCs of chromium and ffmpeg for such a simple tasks.

The aim of this project is to recreate core of VHS with minimal dependencies. cassete-deck built with 2 pieces of software:

lecram/gifenc to write GIF files;
uobikiemukot/yaft used as a simple terminal emulator implementation:
- This project is essentially a fork of yaft with GIF backend and .tape player.

Such utility may be usefull to enrich documentation with animated GIFs which illustrate usage of CLI programs.

Prior art

Of course, there's a lot of similar projects, like:

VHS:
- depends on chromium and ffmpeg.
uobikiemukot/recterm:
- implementation by the author of yaft;
- was not designed to execute commands from file.
asciinema:
- records terminal to upload and replay it in browser;
- was not designed to execute commands from file.
lecram/config:
- renders script recordings as GIFs.
script and scriptreplay:
- GNU utility to record and replay terminal sessions.

If you know any other interesting utilities for recording terminal emulators, feel free to update this list via pull request or issue.

Build

Clone this repo with submodules, build using cmake 3.0+ and C/CPP compiler with C++17 support:

Usage

CLI usage:

Preview mode --- depends on X11, opens graphic window to show shell in real time.
```
./build/cassette_deck ./demo/hello.gif
```
Headless mode --- does not depend on X11 at all, does everything in background, suitable for CI and such.
```
./build/cassette_deck --headless ./demo/hello.gif
```

Tape reference

See examples in ./examples. Commands are modelled after VHS's ones and should be almost compatible.

There's one command that is not implemented in VHS:

TYPE start_long_running_process
ENTER
AWAIT

AWAIT commands pauses tape playback until last command is complete. This is implemented by sending SIGUSR1 from controlled shell via PROMPT_COMMAND environment variable.

List of implemented commands

OUTPUT {path} --- specifies output GIF file. ./output.gif if not specified.
WIDTH {width} --- shell width, in pixels. 640 by default.
HEIGHT {height} --- shell height, in pixels. 384 by default.
REQUIRE {command} --- checks if specified command is in PATH. If not, throws an error.
KEY {key} --- presses specified key.
ENTER, BACKSPACE, SPACE, TAB --- aliases for specified keys.
SLEEP {ms} --- sleeps for specified duration, in milliseconds.
TYPE {text} --- enters sequence of keys specified by keys, sleeping 50ms between them.
AWAIT --- sleeps until last executed shell command finishes.
THEME --- applies a theme to TTY. See themes directory for list

TODO

more commands from VHS, compatibility with VHS tapes;
themes;
CI actions;
padding, decorations.