Skip to content

feat: add asciicast v2 output format#711

Open
veeceey wants to merge 1 commit intocharmbracelet:mainfrom
veeceey:feat/issue-109-asciicast-output
Open

feat: add asciicast v2 output format#711
veeceey wants to merge 1 commit intocharmbracelet:mainfrom
veeceey:feat/issue-109-asciicast-output

Conversation

@veeceey
Copy link

@veeceey veeceey commented Feb 23, 2026

Adds support for generating .cast (asciicast v2) files as an output format, so you can do:

Output demo.cast

This has been a requested feature since the early days (#109) - being able to export recordings as asciicast means you can use them with asciinema players, convert to SVG with svg-term-cli, or generate GIFs with agg.

How it works

  • Added Asciicast field to VideoOutputs so .cast is a first-class output alongside GIF/MP4/WebM
  • During recording, terminal buffer snapshots are captured each frame (only when .cast output is requested to avoid overhead)
  • At render time, GenerateAsciicast writes the asciicast v2 JSON Lines format: a header line with version/width/height/timestamp, followed by "o" (output) events with deduplicated content

Testing

$ go test ./...
ok      github.com/charmbracelet/vhs    4.806s
ok      github.com/charmbracelet/vhs/lexer      5.044s
ok      github.com/charmbracelet/vhs/parser      5.272s
ok      github.com/charmbracelet/vhs/token      5.482s

Closes #109

Add support for .cast (asciicast v2) output format, allowing users to
generate asciicast recordings alongside GIF/MP4/WebM outputs.

The asciicast output captures terminal buffer snapshots during recording
and writes them as asciicast v2 JSON Lines format with proper header
and output events.

Usage: Output demo.cast

Closes charmbracelet#109
@veeceey veeceey requested a review from a team as a code owner February 23, 2026 03:50
@veeceey veeceey requested review from andreynering and meowgorithm and removed request for a team February 23, 2026 03:50
@veeceey
Copy link
Author

veeceey commented Feb 23, 2026

Test Results

$ go build ./...
# no errors

$ go test ./...
ok      github.com/charmbracelet/vhs    4.806s
ok      github.com/charmbracelet/vhs/lexer      5.044s
ok      github.com/charmbracelet/vhs/parser      5.272s
ok      github.com/charmbracelet/vhs/token      5.482s

All existing tests pass with the new code.

@moritzdietz
Copy link

moritzdietz commented Feb 23, 2026

Great PR and indeed something a log of people were longing for!

No snark, but may I ask why you chose to implement v2 instead of v3 of the asciicast file format?
See https://blog.asciinema.org/post/three-point-o/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Asciicast Output

2 participants