cli-screencast

About

An easy to use Node.js API for rendering terminal screenshots and recordings to animated svg or png.

Installation

Install with npm:

npm install cli-screencast

Or with yarn:

yarn add cli-screencast

API

All methods accept an options object as the last argument. Options common to all methods are listed in the options section below.

All methods are asynchronous and return a string or Buffer depending on the output format specified by the output option. If output is 'svg', the method will return an svg image string. If output is 'png', the method will return a png image Buffer.

renderScreen(content, options)

Render a single terminal frame to svg or png.

Arguments:

›   content  •  string

Screen content to render

›   options  •  Object

Options config object to specify configuration options.

renderFrames(frames, options)

Render an animated terminal screen capture from an array of content frames.

Arguments:

›   frames  •  Object[]

Array of content frames in the form of { content: string, duration: number }.

›   options  •  Object

Options config object to specify configuration options.

renderSpawn(command, args, options)

Record and render the terminal output of a spawned sub process. Signature mimics that of child_process.spawn.

Arguments:

›   command  •  string

The command to run.

›   args  •  string[]

List of string arguments.

›   options  •  Object

Options config object to specify configuration options as well as the additional options listed below.

Additional Options:

›   shell  •  boolean | string

Run the command inside of a shell. Default is false. If true, Unix will try to use the current shell (process.env.SHELL), falling back to /bin/sh if that fails, while Windows will try to use process.env.ComSpec, falling back to cmd.exe if that fails. Different shells can be specified using a string. The shell should understand the -c switch, or if the shell is cmd.exe, it should understand the /d /s /c switches.

›   cwd  •  string

Working directory to be set for the child process. Default is process.cwd().

›   env  •  Object

Environment key-value pairs to be set for the child process. Automatically extends from process.env, which can be changed by setting extendEnv to false. Default is undefined.

›   extendEnv  •  boolean

The child process environment extends from process.env. Defaults to true.

›   silent  •  boolean

Silently capture the spawned process' stdout and stderr output. If set to false, the output of the spawned process will be piped to process.stdout. Defaults to true.

›   connectStdin  •  boolean

Connect spawn to process.stdin to capture any input from the user. If the spawned process requires user input to complete, this option must be enabled, or the process will hang. Defaults to false. If enabled, the silent option must be set to false, or omitted.

›   timeout  •  number

The maximum amount of time the process is allowed to run in milliseconds. If greater than 0, the spawned process will be killed if it runs longer than the timeout milliseconds. Default is 0.

›   killSignal  •  string

The signal to be used when the spawned process is killed by timeout. Default is 'SIGTERM'.

renderCapture(fn, options)

Capture and render all terminal output that occurs within a callback function.

Arguments:

›   fn  •  (source) => void

Callback function within which terminal output is captured. Can be synchronous or asynchronous. The callback function will be passed a TerminalRecordingStream instance.

Note: Within the scope of this function, all writes to process.stdout and process.stderr, (and by extension calls to console.log and console.error) will be captured.

›   options  •  Object

Options config object to specify configuration options as well as the additional options listed below.

Additional Options:

›   connectStdin  •  boolean

Connect capture session to process.stdin to capture any input from the user. Defaults to false.

›   silent  •  boolean

Silently capture output to process.stdout and process.stderr. Defaults to true.

Options

›   logLevel  •  string

Controls how much info is logged to the console during the render process. Options are (in order of descending verbosity): 'debug', 'info', 'warn', 'error', and 'silent'. Defaults to 'info'.

Output Related Options

›   output  •  string

The desired output format. Must be either 'svg' or 'png'. The default is 'svg'.

›   scaleFactor  •  number

The device scale factor used when rendering to png. Default is 4.

Note: This option is only applicable when output is 'png'.

›   embedFonts  •  boolean

Embed required fonts when rendering to svg, Defaults to true.

Note: This option is only applicable when output is 'svg'.

Capture Related Options

›   writeMergeThreshold  •  number

Consecutive writes will be merged if they occur within this number of milliseconds of each other. Default is 80.

›   endTimePadding  •  number

Milliseconds to add to the end of a captured terminal recording. Default is 500.

›   cropStartDelay  •  boolean

Remove the time difference between the start of the capture and the first write when capturing a terminal recording. Defaults to true.

›   captureCommand  •  boolean

Include a prompt and command string at the beginning of a captured recording, if the recording was started with a command. Defaults to true.

›   prompt  •  string

The prompt prefix string to use when a command is captured. Default is '> '.

Note: This option is only applicable when captureCommand is true.

›   keystrokeAnimation  •  boolean

Include a command input keystroke animation at the start of the recording if command prompt line is captured. Defaults to true.

Note: This option is only applicable when captureCommand is true.

›   keystrokeAnimationInterval  •  number

The delay in milliseconds between keystrokes to use when creating a command input animation. Default is 140.

Note: This option is only applicable when keystrokeAnimation is true.

Rendering Related Options

›   columns  •  number  •  Required

The column width of the captured terminal window.

›   rows  •  number  •  Required

The row height of the captured terminal window.

›   tabSize  •  number

Tab column width. Defaults to 8.

›   cursorHidden  •  boolean

Cursor is hidden in the captured terminal recording or frame. Defaults to false.

›   fontSize  •  number

The font size of the rendered terminal output. Default is 16.

›   lineHeight  •  number

The line height of the rendered terminal output. Default is 1.25.

›   columnWidth  •  number

The aspect ratio used to determine the width of each terminal column, which will be calculated as this value times the fontSize. If unspecified, the renderer will attempt to determine the aspect ratio of the embedded font family, but if that fails will fall back to the standard value 0.6.

›   theme  •  Object

Terminal theme specification object. See the themes section below.

›   windowTitle  •  string

Terminal window title. Default is undefined.

›   windowIcon  •  string | boolean

Terminal window icon. Can be set to a keyword string to specify a specific icon (see the window icons section below for a list of keywords). If set to true, the value of windowTitle is used. Default is undefined.

›   iconColumnWidth  •  number

The column span of title icons in the rendered terminal output. Default is 1.6.

›   borderRadius  •  number

Border radius of the rendered terminal window frame. Default is 5.

›   paddingX  •  number

Amount of padding in pixels to be added to the left and right of the rendered window content box. Default is 5.

›   paddingY  •  number

Amount of padding in pixels to be added to the top and bottom of the rendered window content box. Default is 5.

›   decorations  •  boolean

Render the terminal window with stoplight buttons in the top left corner. Defaults to true.

›   insetMajor  •  number

Amount of inset space in pixels added to the top of the window frame when rendering it with decorations. Default is 40.

Note: This option is ignored if decorations is false.

›   insetMinor  •  number

Amount of inset space in pixels added to the left, right, and bottom of the window frame when rendering it with decorations. Default is 20.

Note: This option is ignored if decorations is false.

---

The following diagram shows how various window rendering related options function:

Theme

The terminal theme can be specified by passing a theme configuration object to the theme option. One or more of the properties in the table below can be specified, and any unspecified properties will be inherited from the default theme.

Color values can be a hexadecimal color string or a [number, number ,number] rgb color triplet.

Property	Description	Default
black	SGR foreground code 30 and background code 40	#000000
red	SGR foreground code 31 and background code 41	#ff5c57
green	SGR foreground code 32 and background code 42	#5af78e
yellow	SGR foreground code 33 and background code 43	#f3f99d
blue	SGR foreground code 34 and background code 44	#57c7ff
magenta	SGR foreground code 35 and background code 45	#d76aff
cyan	SGR foreground code 36 and background code 46	#9aedfe
white	SGR foreground code 37 and background code 47	#f1f1f0
brightBlack	SGR foreground code 90 and background code 100	#686868
brightRed	SGR foreground code 91 and background code 101	#ff5c57
brightGreen	SGR foreground code 92 and background code 102	#5af78e
brightYellow	SGR foreground code 93 and background code 103	#f3f99d
brightBlue	SGR foreground code 94 and background code 104	#57c7ff
brightMagenta	SGR foreground code 95 and background code 105	#d76aff
brightCyan	SGR foreground code 96 and background code 106	#9aedfe
brightWhite	SGR foreground code 97 and background code 107	#f1f1f0
background	Terminal window background color	#282a36
iconColor	Terminal window title icon color	#d3d7de
text	Default text color	#b9c0cb
cursorColor	Cursor color	#d7d5c9
cursorType	Cursor style, either 'beam', 'block', or 'underline'	'beam'
cursorBlink	Enable cursor blinking	false
dim	Opacity of dim text (styled with SGR code 2)	0.5
fontFamily	Font family name	"'Monaco', 'Cascadia Code', 'Courier New'"

Window Icons

The windowIcon option can be used to specify an icon to display next to the rendered terminal window title. The following diagram shows the keywords that can be specified to for particular window icons:

License

MIT