Effective terminal presentations with asciinema and doitlive

I’ve been trying to push my personal boundaries of “doing open source right”. On the most recent pet project, that means putting those little README shields that people seem so fond of; leveraging GitHub actions for automated testing, linting, and deploying; and recording a screencast to give an interactive tour of functionality.

asciinema is a popular utility for distributing screencasts but the interactive recording style resulted in a final product with quite a few flaws. I wrote a script, built a few helpers, and recorded segments in multiple takes until arriving at something passable. And “passable” just about summarizes the end result, there’s still the occasional typo, the cuts are jarring, and the typing has awkward pauses even with --idle-time-limit=0.3. Worst of all, it’s ~5 minutes long, which I’d reckon is enough to frustrate even the most motivated viewer.

In hopes of doing better, I found a HackerTyper-like tool called doitlive meant for live presentations in the terminal. Using it with asciinema is straight forward (based on this gist by Thomas Applencourt):

asciinema rec --command 'doitlive play --commentecho --quiet --shell bash <script.sh>' <recording.cast>

This runs the asciinema recorder on the outside and typing controls the pace at which doitlive reads the commands from the provided <script.sh>.

Overall the experience is quite pleasant: you write the script and simply whack the keyboard as fast as you please to control the pacing. It also trivializes making future recordings as the behaviour of the underlying demo changes. It’s not quite a non-linear video editor, but it’ll do.

doitlive has features to inject environment variables and display commentary, however the nature of maintaining independent shell state and interpreting commands mean that recording helpers that export variables and change directories cannot be used. There’s also no affordance to execute hidden commands, though that’s understandable given the motivation of a presentation tool.

Here’s the final result, equivalent to the previous one at just 93 seconds. It could be better, and I’m sure there’s someone that prefers the older version, but I’m shipping it and moving on.

Changelog

2022-01-16: Published.