preview

Documentation

Overview

Package preview replays a closed recording's frames in the user's OWN terminal via the kitty graphics protocol — the tool that exists because VHS could not speak kitty graphics, speaking it back. Support is decided by asking the terminal itself, never by sniffing environment variables.

Index

• func Play(ctx context.Context, tty *os.File, framesDir string) error
• func ShowGIF(tty *os.File, g *gif.GIF, cols int) error
• func Supported(tty *os.File, timeout time.Duration) bool

Functions

func Play

func Play(ctx context.Context, tty *os.File, framesDir string) error

Play replays a closed recording (its frames directory) on the tty: every frame at its exact recorded duration, drawn at a stable position, sized to fit the terminal. The image is transmitted under one id and replaced per frame — the retransmit-same-id idiom every kitty-graphics terminal animates without flicker. Ctrl-C works: the terminal stays in cooked mode during playback (signals live), and ctx cancellation strikes the set early.

func ShowGIF

func ShowGIF(tty *os.File, g *gif.GIF, cols int) error

ShowGIF plays an animated GIF at the cursor via the kitty graphics ANIMATION protocol: root frame transmitted with a=T, the rest appended as a=f with their gaps, then set running in a loop. A terminal that speaks graphics but not animation simply shows the root frame — degradation is built into the protocol (unknown APC payloads are ignored). Frames are re-encoded as PNG (the only payload format every implementation takes).

func Supported

func Supported(tty *os.File, timeout time.Duration) bool

Supported reports whether the tty speaks kitty graphics — by handshake, in raw mode, bounded by timeout. Any failure along the way (no raw mode, no reply) is a plain "no": the caller falls back, it never breaks. The timeout runs on unix.Poll over the raw fd — NOT SetReadDeadline: /dev/tty is not kqueue-pollable on darwin, so the runtime refuses deadlines there (ErrNoDeadline) and the probe found Supported silently always-false on macOS.