feat: Add keystroke overlay

README.md

@@ -515,6 +515,22 @@ Set CursorBlink false
   <img width="600" alt="Example of setting the cursor blink." src="https://vhs.charm.sh/vhs-3rMCb80VEkaDdTOJMCrxKy.gif">
 </picture>
 
+#### Set KeyStroke Overlay
+
+Set whether keystrokes in the recording should be rendered in subtitle fashion on the recording. You can toggle keystrokes rendering on or off for sections of the tape.
+
+**NOTE**: Keystroke overlay will use symbols for certain non-printable keystrokes (e.g. Backspace). If these symbols do not render correctly, investigate your `fontconfig` settings for the `monospace` family.
+
+```elixir
+Set KeyStrokes Show
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://vhs.charm.sh/vhs-7GzZg7oEHSbXtghZi97gwf.gif">
+  <source media="(prefers-color-scheme: light)" srcset="https://vhs.charm.sh/vhs-7GzZg7oEHSbXtghZi97gwf.gif">
+  <img width="600" alt="Example of setting the keystroke overlay." src="https://vhs.charm.sh/vhs-7GzZg7oEHSbXtghZi97gwf.gif">
+</picture>
+
 ### Type
 
 Use `Type` to emulate key presses. That is, you can use `Type` to script typing

command.go

@@ -89,7 +89,7 @@ func ExecuteKey(k input.Key) CommandFunc {
 			repeat = 1
 		}
 		for i := 0; i < repeat; i++ {
-			_ = v.Page.Keyboard.Type(k)
+			v.Page.Keyboard.Type(k)
 			time.Sleep(typingSpeed)
 		}
 	}
@@ -140,45 +140,45 @@ func ExecuteCtrl(c parser.Command, v *VHS) {
 // ExecuteAlt is a CommandFunc that presses the argument key with the alt key
 // held down on the running instance of vhs.
 func ExecuteAlt(c parser.Command, v *VHS) {
-	_ = v.Page.Keyboard.Press(input.AltLeft)
+	v.Page.Keyboard.Press(input.AltLeft)
 	if k, ok := token.Keywords[c.Args]; ok {
 		switch k {
 		case token.ENTER:
-			_ = v.Page.Keyboard.Type(input.Enter)
+			v.Page.Keyboard.Type(input.Enter)
 		case token.TAB:
-			_ = v.Page.Keyboard.Type(input.Tab)
+			v.Page.Keyboard.Type(input.Tab)
 		}
 	} else {
 		for _, r := range c.Args {
 			if k, ok := keymap[r]; ok {
-				_ = v.Page.Keyboard.Type(k)
+				v.Page.Keyboard.Type(k)
 			}
 		}
 	}
 
-	_ = v.Page.Keyboard.Release(input.AltLeft)
+	v.Page.Keyboard.Release(input.AltLeft)
 }
 
 // ExecuteShift is a CommandFunc that presses the argument key with the shift
 // key held down on the running instance of vhs.
 func ExecuteShift(c parser.Command, v *VHS) {
-	_ = v.Page.Keyboard.Press(input.ShiftLeft)
+	v.Page.Keyboard.Press(input.ShiftLeft)
 	if k, ok := token.Keywords[c.Args]; ok {
 		switch k {
 		case token.ENTER:
-			_ = v.Page.Keyboard.Type(input.Enter)
+			v.Page.Keyboard.Type(input.Enter)
 		case token.TAB:
-			_ = v.Page.Keyboard.Type(input.Tab)
+			v.Page.Keyboard.Type(input.Tab)
 		}
 	} else {
 		for _, r := range c.Args {
 			if k, ok := keymap[r]; ok {
-				_ = v.Page.Keyboard.Type(k)
+				v.Page.Keyboard.Type(k)
 			}
 		}
 	}
 
-	_ = v.Page.Keyboard.Release(input.ShiftLeft)
+	v.Page.Keyboard.Release(input.ShiftLeft)
 }
 
 // ExecuteHide is a CommandFunc that starts or stops the recording of the vhs.
@@ -219,9 +219,9 @@ func ExecuteType(c parser.Command, v *VHS) {
 	for _, r := range c.Args {
 		k, ok := keymap[r]
 		if ok {
-			_ = v.Page.Keyboard.Type(k)
+			v.Page.Keyboard.Type(k)
 		} else {
-			_ = v.Page.MustElement("textarea").Input(string(r))
+			v.Page.Keyboard.Input(string(r))
 			v.Page.MustWaitIdle()
 		}
 		time.Sleep(typingSpeed)
@@ -263,9 +263,9 @@ func ExecutePaste(_ parser.Command, v *VHS) {
 	for _, r := range clip {
 		k, ok := keymap[r]
 		if ok {
-			_ = v.Page.Keyboard.Type(k)
+			v.Page.Keyboard.Type(k)
 		} else {
-			_ = v.Page.MustElement("textarea").Input(string(r))
+			v.Page.Keyboard.Input(string(r))
 			v.Page.MustWaitIdle()
 		}
 	}
@@ -283,6 +283,7 @@ var Settings = map[string]CommandFunc{
 	"Padding":       ExecuteSetPadding,
 	"Theme":         ExecuteSetTheme,
 	"TypingSpeed":   ExecuteSetTypingSpeed,
+	"KeyStrokes":    ExecuteSetKeyStrokes,
 	"Width":         ExecuteSetWidth,
 	"Shell":         ExecuteSetShell,
 	"LoopOffset":    ExecuteLoopOffset,
@@ -369,6 +370,13 @@ func ExecuteSetTheme(c parser.Command, v *VHS) {
 	_, _ = v.Page.Eval(fmt.Sprintf("() => term.options.theme = %s", string(bts)))
 	v.Options.Video.Style.BackgroundColor = v.Options.Theme.Background
 	v.Options.Video.Style.WindowBarColor = v.Options.Theme.Background
+	// The intuitive behavior is to have keystroke overlay inherit from the
+	// foreground color. One key benefit of this behavior is that you won't have
+	// issues where e.g. a light theme makes a default white-value keystroke
+	// overlay be hard to read. If it does, then the theme is likely
+	// fundamentally 'broken' since the text you type at the shell will
+	// similarly be very hard to read.
+	v.Options.Video.KeyStrokeOverlay.Color = v.Options.Theme.Foreground
 }
 
 // ExecuteSetTypingSpeed applies the default typing speed on the vhs.
@@ -378,6 +386,19 @@ func ExecuteSetTypingSpeed(c parser.Command, v *VHS) {
 		return
 	}
 	v.Options.TypingSpeed = typingSpeed
+	v.Options.Video.KeyStrokeOverlay.TypingSpeed = typingSpeed
+}
+
+// ExecuteSetKeyStrokes enables or disables keystroke overlay recording.
+func ExecuteSetKeyStrokes(c parser.Command, v *VHS) {
+	switch c.Args {
+	case "Hide":
+		v.Page.KeyStrokeEvents.Disable()
+	case "Show":
+		v.Page.KeyStrokeEvents.Enable()
+	default:
+		return
+	}
 }
 
 // ExecuteSetPadding applies the padding on the vhs.

command_test.go

@@ -17,6 +17,11 @@ func TestCommand(t *testing.T) {
 	if len(CommandFuncs) != numberOfCommandFuncs {
 		t.Errorf("Expected %d commands, got %d", numberOfCommandFuncs, len(CommandFuncs))
 	}
+
+	const numberOfSettings = 20
+	if len(Settings) != numberOfSettings {
+		t.Errorf("Expected %d settings, got %d", numberOfSettings, len(Settings))
+	}
 }
 
 func TestExecuteSetTheme(t *testing.T) {

evaluator.go

@@ -15,6 +15,22 @@ import (
 // EvaluatorOption is a function that can be used to modify the VHS instance.
 type EvaluatorOption func(*VHS)
 
+// isIntermediateAllowedSet returns true if the set command is allowed to be
+// evaluated in the middle of the tape.
+// This function assumes that the given option is from a Set command.
+func isIntermediateAllowedSet(opt string) bool {
+	intermediateAllowedSets := []string{
+		"TypingSpeed",
+		"KeyStrokes",
+	}
+	for _, allowed := range intermediateAllowedSets {
+		if opt == allowed {
+			return true
+		}
+	}
+	return false
+}
+
 // Evaluate takes as input a tape string, an output writer, and an output file
 // and evaluates all the commands within the tape string and produces a GIF.
 func Evaluate(ctx context.Context, tape string, out io.Writer, opts ...EvaluatorOption) []error {
@@ -134,7 +150,7 @@ func Evaluate(ctx context.Context, tape string, out io.Writer, opts ...Evaluator
 		// GIF as the frame sequence will change dimensions. This is fixable.
 		//
 		// We should remove if isSetting statement.
-		isSetting := cmd.Type == token.SET && cmd.Options != "TypingSpeed"
+		isSetting := cmd.Type == token.SET && !isIntermediateAllowedSet(cmd.Options)
 		if isSetting || cmd.Type == token.REQUIRE {
 			fmt.Fprintln(out, Highlight(cmd, true))
 			continue

examples/fixtures/all.tape

@@ -19,6 +19,8 @@ Set Padding 50
 Set Framerate 60
 Set PlaybackSpeed 2
 Set TypingSpeed .1
+Set KeyStrokes Hide
+Set KeyStrokes Show
 Set LoopOffset 60.4
 Set LoopOffset 20.99%
 Set CursorBlink false

ffmpeg.go

@@ -172,6 +172,76 @@ func (fb *FilterComplexBuilder) WithMarginFill(marginStream int) *FilterComplexB
 	return fb
 }
 
+// WithKeyStrokes adds key stroke drawtext options to the ffmpeg filter_complex.
+func (fb *FilterComplexBuilder) WithKeyStrokes(opts VideoOptions) *FilterComplexBuilder {
+	var (
+		defaultFontFamily = "monospace"
+		horizontalCenter  = "(w-text_w)/2"
+		verticalCenter    = fmt.Sprintf("h-text_h-%d", opts.Style.Margin+opts.Style.Padding)
+	)
+	events := opts.KeyStrokeOverlay.Events
+
+	// When we are dealing with the last event, things can actually get very
+	// subtly tricky.
+	// If the last keystroke event is _very_ close to the end of the recording
+	// (e.g. the last line of the .tape is Type), then there is a chance that
+	// this keystroke draw event gets effectively dropped. That is because the
+	// gte() clause here may have a timestamp that is exactly equal to or
+	// slightly greater than the actual length of the recording itself. In order
+	// to fix this, we actually want to "pad" the recording a little extra in
+	// this case.  While we could simply unconditionally record a few more
+	// seconds at the end of every vhs recording, this is actually not a
+	// generalizable solution for a dynamic typing speed, where we would
+	// proportionally require _more_ extra frames to make sure to not drop any
+	// keystrokes.
+	// Now, the condition in which we need to do this corrective action is if
+	// the last event is recorded after the duration of the recording with a
+	// tolerance of 100 ms:
+	if overflow := events[len(events)-1].WhenMS - opts.KeyStrokeOverlay.Duration.Milliseconds(); overflow > -100 && overflow < 100 {
+		// If so, extend the recording by a window twice the length of the
+		// typing speed. This should give ample time for the last keystroke
+		// event to be properly rendered.
+		fb.filterComplex.WriteString(fmt.Sprintf(";\n[%s]tpad=stop_mode=clone:stop_duration=%f[endpad]\n", fb.prevStageName, opts.KeyStrokeOverlay.TypingSpeed.Seconds()*2))
+		fb.prevStageName = "endpad"
+	}
+
+	prevStageName := fb.prevStageName
+	for i := range events {
+		event := events[i]
+		fb.filterComplex.WriteString(";")
+		stageName := fmt.Sprintf("keystrokeOverlay%d", i)
+
+		// When setting the enable conditions, we have to handle the very last
+		// event specially. It technically has no 'end' so we set it to render
+		// until the end of the video.
+		enableCondition := fmt.Sprintf("gte(t,%f)", float64(event.WhenMS)/1000)
+		if i < len(events)-1 {
+			enableCondition = fmt.Sprintf("between(t,%f,%f)", float64(events[i].WhenMS)/1000, float64(events[i+1].WhenMS)/1000)
+		}
+		fb.filterComplex.WriteString(
+			fmt.Sprintf(`
+			[%s]drawtext=font=%s:text='%s':fontcolor=%s:fontsize=%d:x='%s':y='%s':enable='%s'[%s]
+			`,
+				prevStageName,
+				defaultFontFamily,
+				events[i].Display,
+				opts.KeyStrokeOverlay.Color,
+				defaultFontSize,
+				horizontalCenter,
+				verticalCenter,
+				enableCondition,
+				stageName,
+			),
+		)
+		prevStageName = stageName
+	}
+
+	// At the end of the loop, the previous stage name is now transfered to the filter complex builder's
+	// state for use in subsequent filters.
+	fb.prevStageName = prevStageName
+	return fb
+}
+
 // WithGIF adds gif options to ffmepg filter_complex.
 func (fb *FilterComplexBuilder) WithGIF() *FilterComplexBuilder {
 	fb.filterComplex.WriteString(";")

keys.go

@@ -129,3 +129,13 @@ var keymap = map[rune]input.Key{
 	'→':    input.ArrowRight,
 	'↓':    input.ArrowDown,
 }
+
+// inverseKeymap is the inverse map of keymap, mapping input.Keys to runes.
+var inverseKeymap = make(map[input.Key]rune)
+
+// init initializes the invKeymap map to ensure it stays in-sync with keymap.
+func init() {
+	for r, k := range keymap {
+		inverseKeymap[k] = r
+	}
+}