apparebit / asciifx

a special effects shop for asciinema

asciifx

asciinema is a great tool for recording, viewing, and sharing live terminal performances. But sometimes, a performance really needs to be carefully scripted and its staging carefully controlled. That's when you turn to asciifx.

In particular, asciifx turns plain Python scripts into version 2 asciicasts of what might be a person executing the script line by line in an interactive Python interpreter. It features semi-realistic keystroke dynamics as well as pauses for reading interpreter output. Beyond this first use-case, asciifx has well-defined internal interfaces that make extension straight-forward.

An Example

Consider this Python script to show off the libray that inspired this package, konsole:

# https://github.com/apparebit/konsole
#[keypress-speed=0.6]
#[off]
import konsole
konsole.config(use_color=True)
#[on]
konsole.info("fyi", detail="stuff")
konsole.warning("beware")
konsole.error("fail")
konsole.critical("boom!")
quit()

Some of the comments may look like Rust annotations but still are valid Python. In the context of asciifx, they also are called pragmas and control the performance. keypress-speed speeds up simulated keypresses because they just aren't that interesting to watch. off/on prevent the import and configuration of konsole from appearing in the final asciicast, though the two statements are executed nonetheless.

With that, we are ready to stage a performance:

$ python -m asciifx --width 50 --height 12 -o output.cast input.py

You can watch the resulting asciicast with asciinema — or convert it to SVG with svg-term-cli:

Pragmas

To be recognized by asciifx, a pragma must appear on a line, by itself. asciifx supports the following pragmas:

• #[off] suspends rendering to asciicast events.
• #[on] restores the rendering of asciicast events.
• #[think-time=FLOAT] inserts a pause of FLOAT seconds after the next interaction's interpreter prompt.
• #[speed=FLOAT] adjusts overall duration by multiplying all delays by FLOAT.
• #[keypress-speed=FLOAT] adjusts keypress duration by multiplying keypress delays by FLOAT.

Whereas think-time takes an absolute value in seconds, speed and keypress-speed take relative, multiplicative values. To make these semantics obvious even to casual users, think-time ends with time, whereas speed and keypress-speed end with speed. The speed and keypress-speed pragmas multiply by their arguments instead of the inverse of their arguments because that makes jumping through time trivial: Just set speed or keypress-speed to zero! At the same time, beware that the combined impact of speed and keypress-speed is multiplicative on the duration between keypresses.

An Itch to Scratch

asciifx exists because I had an itch to scratch: creating an animated screenshot to show off konsole. Python's REPL is great for showing off an interface, since it displays the result of each statement right after executing, and asciinema is great for recording such interactions. The problem is that getting such a performance right pretty much requires scripting everything beforehand. But if it's already scripted, it makes little sense to type out the code again at a Python REPL.

So I scoped out writing my own tool: Python's code module has all the REPL support I'd need, nicely abstracted. asciicast v2 is an eminently reasonable file format to target. The one thing that was missing was a suitable model for human keystroke dynamics. After a quick literature search, even that model seemed within reach.

Alas, turning scientific writing into executable code easily becomes an exercise in frustration. There is ambiguous language in the definition of critical metrics when perfectly well-defined terminology and metrics exist. (Yes, IKI is the same as flight time shifted by hold time. No, "keypress event" is not an abstract event related to pressing keys but an actual, deprecated JavaScript event.) There also are probability distributions that are surprisingly hostile to casual human use. (No, μ and σ are not the mean and standard deviation of the log-normal distribution. Yes, they are the customary parameters for that distribution nonetheless. Converting the mean and standard deviation to these parameters is left as an exercise for the reader. 😈)

---

© 2022 Robert Grimm. Apache 2.0 license. GitHub.