felis-cast

The .fcast session-cast format for felis, and the tools that record and replay it. Think asciinema's .cast, but the frames are the daemon→client messages of one felis session, in felis's own felis-json form, so a player replays through felis's real grid and renderer rather than re-parsing a terminal byte stream.

felis core stays unchanged: recording is a client attach that tees the frames. play and serve replay by standing in for the daemon, so an unmodified felis client renders the recording. Browser playback lives in felis-web-component, and felis-reel renders a recording to video.

Install

felis runs felis cast … by finding felis-cast beside its own binary or on PATH:

nix profile install git+https://git.natsukium.com/natsukium/felis-fcast

Quick start

# Record yourself: inside felis, this window switches to a new shell,
# and `exit` ends the recording and brings you back. (Outside felis, a
# new window opens instead.)
felis cast record demo.fcast

# Record one program, or a script with no window.
felis cast record demo.fcast -- htop
felis cast record --headless --max-duration 10 build.fcast -- cargo build

# Record a session you already have; Ctrl-C stops the recording, not the
# session.
felis cast record --session 1a2b demo.fcast

# Watch it. Space pauses, q quits, any key leaves the final screen.
felis cast play demo.fcast
felis cast play -s 2 -i 1 demo.fcast   # twice as fast, pauses cut to 1 s

# Serve it to any felis client over a socket.
felis cast serve --socket /tmp/replay.sock demo.fcast
felis --socket /tmp/replay.sock attach 1

A .fcast is NDJSON: a header on line 1, then [t_us, kind, msg] frames, so jq reads it. A Rust program reads one with the parser crate, which brings no felis dependency:

[dependencies]
felis-cast-format = { git = "https://git.natsukium.com/natsukium/felis-fcast", rev = "<commit>" }

let cast = felis_cast_format::parse(&text)?;
for frame in &cast.frames {
    // frame.t_us, frame.kind, and frame.msg (felis-json, opaque here)
}

Documentation

• docs/format.md: the .fcast format.
• docs/pseudo-daemon.md: what serve answers on the daemon wire.
• docs/cli.md: every command and option, and the exit codes.
• CONTRIBUTING.md: building, the crate layout, and the tests.
• Issues: open work.

Each spec page ends with design notes: the rationale, the alternatives rejected, and when to revisit.