This repo is reachable at https://github.com/mmirko/handsomehandson.git

Handsome Hands-on

Simple Python3 program to create demos from actual shell scripts

Usage

The purpose of HandsomeHandson (HH) is to transform a Linux shell script into a demo (target) script. I created it to simplify the creation of hands-on for my projects.
The two scripts (the source one and the demo) execute the same commands but the demo will pause the execution waiting for a key press according to some comments placed in the source script. The pause is meant to be used by an hypothetical speaker that is talking about the current script’s line. HH can also create a sequence of frames, a video, a gif or a Beamer slide showing the script execution.

HH accepts the following options:

Usage:
  hh -s <sourcescript> [--marker <textmarker>] [-d] (-t <targetscript> | -f <framesdirectory> | -v <videofile> | -g <giffile> | -b <beamerdirectory>)
  hh -h | --help

Options:
  -h --help                                         Show this screen.
  -s <sourcescript>, --source <sourcescript>        Source script
  --marker <textmarker>                             Marker to intercept commands [default: handsomeh]
  -d                                                Debug
  -t <targetscript>, --target <targetscript>        Target script
  -v <videofile>, --video <videofile>               Video file
  -g <giffile>, --gif <giffile>                     GIF image
  -f <framesdirectory>, --frames <framesdirectory>  Target frames directory
  -b <beamerdirectory>, --beamer <beamerdirectory>  Target beamer directory

Example

This is a simple example. A Script like the following (sourcescript):

#!/bin/bash

reset

#handsomeh_begin {}
echo "Test01"
#handsomeh_end

#handsomeh_begin {"show_output_header": "yes"}
echo "Test02"
#handsomeh_end

is transformed by HH into a usable demo script (targetscript) by giving this command:

hh -s sourcescript -t targetscript

The resulting script is the following. This is usable interactively in an hypothetical live presentation.

#!/bin/bash

reset

# Pre-Command wait
read -n 1 -s -r

# Command header
[ Command > "

# Command display
cat << EndOfBlock
echo "Test01"
EndOfBlock

# Pre-output wait
read -n 1 -s -r

# Output header
[ Output  > "

# Output display
echo "Test01"

# Pre-Command wait
read -n 1 -s -r

# Command header
[ Command > "

# Command display
cat << EndOfBlock
echo "Test02"
EndOfBlock

# Pre-output wait
read -n 1 -s -r

# Output header
[ Output  > "

# Output display
echo "Test02"

# Final wait
read -n 1 -s -r

HH can also create a gif file that shows the script running this way:

hh -s sourcescript -g testscript01.gif

The result is the following

Block commands

HH works grouping lines of the original script into blocks. Blocks can be started with a special comment that HH understands that has the form #[marker]_begin (the default marker is handsomeh ), and ended with #[marker]_end. The defaults comments are then #handsomeh_begin and #handsomeh_end. The begin comment can be followed on the same line by a JSON hash object (eventually empty) that control the behavior of that block.

The following hash keys are valid commands to control the block behavior:

Video and speech synthesis

HH can also produce videos of the demos using a syntax similar to the previous examples.

hh -s sourcescript -v testscript01.mp4

When in video mode, hh can also use the related block commands shown in the previous table. In particular for every block can be specified:

• an audio file to merge with the video when the specific block is reached.
• a text file to be converted in audio by the mimic speech synthesis application.

This is an example of a such a block commands:

#handsomeh_begin {"pre_command_text": "/home/mirko/sometext.txt"}

When using the speech synthesis, the text can also be given inline putting the “content:” prefix in the value of the command. This is an example:

#handsomeh_begin {"pre_command_text": "content:This will be synthesized."}

Installation

Just copy the HH script in a directory within the PATH. The script has same dependencies:

• docopt, a python library to handle command line arguments easily.
• xdotool, to grab X windows.
• imagemagick, to build gif files.
• ffmpeg, to manupulate audio and videos files.
• mimic, for the speech synthesis.

Issues

The code is written quickly and has some issues. These are the first that came to mind:

• There is a poor error handling. If an error arise things are not done and no message is reported.
• block commands cannot be more than a single line.
• Images for gifs and videos are grabbed from an X window. This means that the focus should stay on that window when HH runs.