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.
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:
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.
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.