asciicast

package
v1.223.0 Latest Latest
Warning

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

Go to latest
Published: Jul 15, 2026 License: Apache-2.0 Imports: 42 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 indicates that the agg renderer executable was not found.
	ErrMissingAgg = errUtils.ErrMissingAgg
	// ErrMissingFFmpeg indicates that the ffmpeg executable was not found.
	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
)
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.

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
}

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
}

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