feat: add asciicast session recording and playback (#469)

[SemperFu]

Hey! I've wanted built-in terminal recording for a while and wasn't happy with the existing options, so I built this for my own use. It's been working well, and since #469 has been open for years I figured I'd contribute it upstream. I'm sure it's not exactly how people want it but, just wanted to get the ball rolling. Happy to iterate on feedback

Summary of the Pull Request

Adds built-in terminal session recording and playback using the asciicast format. Records in asciicast v3 (interval-based timing) and plays back both v2 and v3 files, compatible with the asciinema ecosystem (asciinema play, agg, asciinema.org).

Watch an interactive demo of a WT recorded .cast file via asciinema-player.

Demo.mp4

Screen recording of the full workflow: starting a recording, saving, and playing back a cast file. (2x speed)

References and Relevant Issues

• Closes Feature request: Recording #469
• asciicast v3 spec
• asciicast v2 spec
• Feature spec: doc/specs/469 - Session Recording.md

Detailed Description of the Pull Request / Additional comments

Recording

Right-click a tab > "Record session" (or Ctrl+Shift+R) to open a Save As dialog with a timestamped default filename. A red dot appears in the tab header while recording. The current prompt line is captured with VT attributes as the first event so recordings don't start blank. All subsequent terminal output is written as timestamped VT data. Toggle the shortcut or menu item again to stop.

Recording works with any shell or connection type (PowerShell, cmd, WSL, SSH) since it captures raw VT output from the TerminalOutput event.

Playback

Open cast file from the command palette or Ctrl+Shift+O. The selected .cast file replays in a new tab with original timing. After playback, the tab shows "Playback complete. Press any key to close." Auto-detects v2 vs v3 from the header.

UI integration

Feature	Details
Ctrl+Shift+R	Toggle recording (Save dialog on start)
Ctrl+Shift+O	Open cast file for playback
Tab context menu	"Record session" / "Stop recording"
Command palette	Both actions listed
Tab header	Red dot indicator during recording

Architecture

AsciicastRecorder (plain C++ class):

• Subscribes to ITerminalConnection::TerminalOutput to capture raw VT data
• Writes asciicast v3 JSON (header + interval-timed events + exit event)
• Thread-safe via std::mutex; managed by ControlCore

AsciicastConnection (new ITerminalConnection implementation):

• Parses .cast files, auto-detects v2 vs v3 from header
• Replays output events as a fire_and_forget coroutine with timed delays
• Skips # comment lines (v3 feature)

New files

• src/cascadia/TerminalConnection/AsciicastRecorder.h/.cpp
• src/cascadia/TerminalConnection/AsciicastConnection.idl/.h/.cpp
• doc/specs/469 - Session Recording.md

Validation Steps Performed

• Deployed CascadiaPackage, recorded sessions with PowerShell
• Confirmed recording works across shells (PowerShell, cmd, WSL)
• Verified prompt line appears with colors at start of recording
• Verified playback timing matches original session
• Verified tab header indicator and context menu toggle correctly
• Verified playback completion message appears cleanly after last event
• Verified v3 .cast files play correctly in asciinema-player 3.15.1 (web)
• Verified v2 backward compatibility (plays v2 files from asciinema.org)
• Generated GIF from recorded .cast file using agg with Campbell theme

PR Checklist

• Closes Feature request: Recording #469
• Tests added/passed (TAEF tests planned for follow-up)
• Documentation updated
  • Feature spec: doc/specs/469 - Session Recording.md
• Schema updated (if necessary)

[SemperFu]

@microsoft-github-policy-service agree

[SemperFu]

Switched the recorder to a dedicated writer thread so the rendering thread doesn't stall during recording.
Added resize ("r") and marker ("m") events per the v3 spec, as well as terminal type, theme, and title.
The player reads idle_time_limit now and does error diffusion timing to avoid drift on long recordings.
Also grouped the record/open actions into a "Recording" submenu in the tab context menu.
Auto-resize only works when the playback tab is the only tab in the window. Going to try and have playback open a new window which may work better anyways.

[SemperFu]

Playback now opens in a dedicated window instead of a tab in the current window. This fixes the auto-resize issue. There is a setting "autoResizeForPlayback" to use new window or tab. Made OpenCastFile a serializable action with a path parameter, which enables future command-line support and file association.

Added a video-player-style transport bar that appears at the bottom of the terminal during cast file playback. Supports play/pause, restart, seek via timeline slider, and speed control (0.5x/1x/2x/4x). The bar auto-hides and reappears on mouse hover and can restart after playback finishes.

DemoNew.mp4

Tried focus mode for the playback window to hide tabs and titlebar, but you can't move the window. also tried hiding just the tab row, but tabs-in-titlebar mode doesn't render a separate title, so the titlebar was blank. These need more thought, possibly a custom playback window mode?

Blank titlebar

Good stopping point for now