Help us shape the future of Go! Take the 2026 Go Developer Survey

asciicast

package
v1.233.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: Apache-2.0 Imports: 46 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// DefaultWidth is the fallback terminal width for cast recordings.
	DefaultWidth = 120
	// DefaultHeight is the fallback terminal height for cast recordings.
	DefaultHeight = 36
)

Variables

View Source
var (
	// ErrEmptyCastFile indicates that a cast file had no header line.
	ErrEmptyCastFile = errUtils.ErrEmptyCastFile
	// ErrRenderOutputExists indicates that a render target already exists.
	ErrRenderOutputExists = errUtils.ErrRenderOutputExists
	// ErrMissingAgg is retained for backwards compatibility. Animated rendering
	// now installs agg through the Atmos toolchain instead of returning this error.
	ErrMissingAgg = errUtils.ErrMissingAgg
	// ErrMissingFFmpeg is retained for backwards compatibility. MP4 rendering
	// now installs FFmpeg through the Atmos toolchain instead of returning this error.
	ErrMissingFFmpeg = errUtils.ErrMissingFFmpeg
)
View Source
var (
	// ErrUnknownSessionAction indicates an unsupported scripted session action type.
	ErrUnknownSessionAction = errUtils.ErrUnknownSessionAction
	// ErrWaitTimeout indicates that a wait action did not observe the expected output before its deadline.
	ErrWaitTimeout = errUtils.ErrWaitTimeout
	// ErrUnsupportedCastKey indicates that a key action requested an unknown key sequence.
	ErrUnsupportedCastKey = errUtils.ErrUnsupportedCastKey
	// ErrSimulateActionMissingCallback indicates a "simulate" action was built without its Fn callback set.
	ErrSimulateActionMissingCallback = errUtils.ErrSimulateActionMissingCallback
)
View Source
var ErrCastOutputExists = errUtils.ErrCastOutputExists

ErrCastOutputExists indicates that a requested cast output path already exists.

View Source
var ErrMissingExecCommand = errUtils.ErrMissingExecCommand

ErrMissingExecCommand indicates that ExecRecord was called without a command.

Functions

func BuildGrid

func BuildGrid(path string) (*cellbuf.Buffer, error)

BuildGrid replays a cast file's output events into a styled terminal cell grid. The grid preserves the full scrollback (it grows past the recorded terminal height) so renderers can emit complete command output, matching how the legacy aha-based screengrab pipeline converted entire streams.

func CommandSlug

func CommandSlug(args []string) string

CommandSlug converts command arguments into a filesystem-safe cast filename slug.

func Play

func Play(path string, out io.Writer) error

Play replays an asciicast file to the provided writer.

func RandomID

func RandomID(n int) string

RandomID returns a short lowercase hexadecimal identifier.

func ReadEvents

func ReadEvents(path string) (Header, []Event, error)

ReadEvents reads an asciicast file header and event stream.

func Render

func Render(input string, opts *RenderOptions) error

Render generates requested media outputs from an asciicast file.

func RenderASCII

func RenderASCII(input, output string) error

RenderASCII writes the final terminal content of a cast file as plain text with no ANSI escape sequences. The output is a durable, diffable artifact suitable for committing to git and for machine consumption (e.g. Atmos Pro).

func RenderHTML

func RenderHTML(input, output string) error

RenderHTML writes the final terminal content of a cast file as an HTML fragment of inline-styled spans, one line per text line. The fragment is consumed by the website Screengrab component via dangerouslySetInnerHTML inside a <pre>, so no wrapper element and no background colors are emitted (backgrounds broke light/dark themes with the legacy aha pipeline).

func RenderJPEG

func RenderJPEG(input, output string) error

RenderJPEG writes the final terminal content of a cast file as a JPEG image.

func RenderPNG

func RenderPNG(input, output string) error

RenderPNG writes the final terminal content of a cast file as a PNG image.

func ResolvePath

func ResolvePath(opts *Options, started time.Time) (string, error)

ResolvePath returns the cast output path for the supplied options and start time.

func RunSession

func RunSession(ctx context.Context, opts *SessionOptions) error

RunSession executes scripted session actions against an interactive shell.

Types

type Event

type Event struct {
	Time   float64
	Stream string
	Data   string
}

Event is one asciicast v2 event entry.

type ExecOptions

type ExecOptions struct {
	// Command is the argv to run; Command[0] is resolved via PATH.
	Command []string
	// Dir is the working directory for the command (empty = inherit).
	Dir string
	// Env is the full environment for the command (nil = inherit).
	Env []string
	// Path is the output .cast file path.
	Path string
	// Width and Height size the recorded terminal (0 = defaults).
	Width  int
	Height int
	// Title is an optional cast title.
	Title string
}

ExecOptions configures a one-shot, non-interactive command recording. Unlike RunSession, no PTY is allocated: callers force color output through environment variables (e.g. ATMOS_FORCE_COLOR/CLICOLOR_FORCE) instead.

type ExecResult

type ExecResult struct {
	// ExitCode is the command's exit status (0 on success).
	ExitCode int
}

ExecResult reports the outcome of a recorded command.

func ExecRecord

func ExecRecord(ctx context.Context, opts *ExecOptions) (*ExecResult, error)

ExecRecord runs a command and records its stdout and stderr as asciicast output events. It returns the command's exit code in ExecResult; a non-zero exit is not an error (callers decide how to treat command failures).

type Header struct {
	Version   int               `json:"version"`
	Width     int               `json:"width,omitempty"`
	Height    int               `json:"height,omitempty"`
	Term      *Term             `json:"term,omitempty"`
	Timestamp int64             `json:"timestamp,omitempty"`
	Title     string            `json:"title,omitempty"`
	Command   string            `json:"command,omitempty"`
	Env       map[string]string `json:"env,omitempty"`
}

Header is the asciicast header written as the first line of a recording. Atmos writes v3 headers, but keeps the v2 width/height fields for legacy reads.

type Options

type Options struct {
	Path       string
	BasePath   string
	Name       string
	Title      string
	Command    []string
	Width      int
	Height     int
	RecordIn   bool
	Explicit   bool
	Overwrite  bool
	Env        map[string]string
	Now        func() time.Time
	Executable string
	OutputRate time.Duration
}

Options configures an asciicast recorder.

type Recorder

type Recorder struct {
	// contains filtered or unexported fields
}

Recorder writes asciicast v3 header and event records to a file.

Events stream into a temporary file next to the final path; Close commits the recording by moving the temp file into place, and Discard drops it without ever touching the final path. A failed recording therefore never replaces a previously committed cast.

func Start

func Start(opts *Options) (*Recorder, error)

Start creates a new recorder and writes its asciicast header.

func (*Recorder) Close

func (r *Recorder) Close() error

Close commits the recording: it flushes and closes the temp cast file and moves it into place at the final path. After a Discard it is a no-op.

func (*Recorder) Discard

func (r *Recorder) Discard() error

Discard closes the recording and removes the temp cast file without ever touching the final path. It is safe on an already-closed recorder.

func (*Recorder) Event

func (r *Recorder) Event(stream, content string) error

Event writes a single asciicast event to the recording.

func (*Recorder) Path

func (r *Recorder) Path() string

Path returns the cast file path used by the recorder.

func (*Recorder) Record

func (r *Recorder) Record(stream, content string)

Record writes stream content as an asciicast event, applying input-recording rules.

func (*Recorder) Resize

func (r *Recorder) Resize(width, height int) error

Resize records a terminal resize event.

func (*Recorder) Width

func (r *Recorder) Width() int

Width returns the recorded terminal width in columns.

func (*Recorder) WithPlaybackDuration

func (r *Recorder) WithPlaybackDuration(duration time.Duration, run func() error) (err error)

WithPlaybackDuration scales all recorded events produced by run into duration. Live output is unchanged. Groups cannot overlap or nest; only the active group's events are buffered, and subsequent recording resumes at its new end time.

type RenderOptions

type RenderOptions struct {
	GIF   string
	MP4   string
	HTML  string
	ASCII string
	PNG   string
	JPEG  string
}

RenderOptions selects the render outputs to generate from a cast file.

type SessionAction

type SessionAction struct {
	Type     string
	Text     string
	Regex    string
	Key      string
	Duration string
	Timeout  string
	Rate     string
	Interval string
	Repeat   int
	Actions  []SessionAction
	// Fn runs a caller-supplied action (Type == "simulate") in place, letting
	// a session mix in the same styled, non-interactive narration steps
	// mode: steps uses (see pkg/runner/step's simulate rendering) instead of
	// typing raw, unstyled keystrokes for comment/narration lines. asciicast
	// deliberately has no styling logic of its own; the caller renders and
	// writes the styled bytes itself, and this callback is how a session
	// action list carries that back out to it in order.
	Fn func() error
}

SessionAction describes one scripted action to perform in an interactive cast session.

type SessionOptions

type SessionOptions struct {
	Shell       string
	Dir         string
	Env         map[string]string
	Width       int
	Height      int
	WriteRate   time.Duration
	KeyInterval time.Duration
	Actions     []SessionAction
	Recorder    *Recorder
}

SessionOptions configures a scripted shell session used to generate cast output.

type Term

type Term struct {
	Cols int    `json:"cols"`
	Rows int    `json:"rows"`
	Type string `json:"type,omitempty"`
}

Term describes the recorded terminal in asciicast v3 headers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL