feat[playback]: add per-section playback speed control

[0xjuanma]

• I have read CONTRIBUTING.md.
• I have created a discussion that was approved by a maintainer (for new features).

Summary

#685

Adds new playback speed control feature to VHS, allowing users to vary playback speed at different points in their recordings using the Playback@<speed> command. The value can be either an integer or float with 1 decimal place.

This enables speeding through setup sections while slowing down for important demonstrations, providing more control over the final output than the global Set PlaybackSpeed setting(which defines a single speed for the full GIF). Its effectively a way to set up multiple playback speeds as part of the tape file or commands being run.

To demonstrate this, I used one of my timer packages which makes it very easy to see the playback speed.

Output GIF:

TL;DR:
Stage 1 runs at 3x speed,
Stage 2 runs at 1x speed,
Stage 3 runs at 1x speed(for 10sec) then switches to 3x,
finally Stage 4 runs at 1x speed again.

Here is the demo.tape used to generate the GIF above:

Output helm-demo.gif
Set FontSize 14
Set Width 800
Set Height 500
Set Theme "Darkside"

# Launch Helm(Note: helm is my timer TUI package)
Playback@1
Type "helm"
Enter
Sleep 1s

# Navigate down to show other options
Down
Sleep 500ms
Down
Sleep 500ms

# Pause on current selection
Sleep 500ms

# Select Demo timer
Enter
Sleep 1s

# Start stage(1)
Sleep 1s
Space

# Playback [Stage 1] at 3x speed
Playback@3.0
Sleep 50s

# Pause
Playback@1.0
Space
Sleep 1s

# Skip to next stage(2)
Type "n"
Sleep 1s

# Start [Stage 2] at 1x speed
Space
Playback@1.0
Sleep 30s

# Pause
Space
Sleep 1s

# Start [Stage 3] at 1x speed for 10sec
Type "n"
Space
Sleep 10s


# Update [Stage 3] Playback to 3x speed
Playback@3.0
Sleep 30s

Playback@1.0
# Pause
Space
Sleep 1s

# Skip to next [Stage 4] at 1x speed
Type "n"
Sleep 1s
Space
Sleep 20s

# End
Type "q"
Sleep 1s

Updates

• Added Playback@<speed> command with @ syntax for section-based speed control(follows similar patterns a Type@Xms)
• Implemented per-section playback speed rendering with FFmpeg filter chain
• Added tests coverage for lexer, parser, and command execution
• Documented playback command usage and added syntax highlighting

[cwarden]

Why not use the existing SET PlaybackSpeed inline like SET TypingSpeed?

[0xjuanma]

@cwarden Great question! I wanted to leave the existing implementation as is, specially because "PlaybackSpeed" is a global setting.

This was a compromise on my part to ensure "PlaybackSpeed" remains global and the new "Playback@*" commands become anchors/markers for this section-base speed configuration.

[cwarden]

I didn't check for an existing pull request before adding the same feature, but reusing SET PlaybackSpeek. I don't feel that strongly about it, but making playback speed congruent with typing speed makes sense to me. There's an alternative implementation in 5b1c930 using this approach.

[0xjuanma]

Yeah, as you pointed out I also went with the "Playback@" approach to try to follow what "TypingSpeed" and "Type@*" are currently doing.

I also don't have strong opinions about this, so I'll let the maintainers decide whats the better choice for this 👍🏽