Skip to main content

captureFrames

captureFrames(frames, options)​

Asynchronous function that creates an animated terminal screen capture from an array of content frames.

Returns a promise that resolves either a string if the output format option is 'svg', 'json', or 'yaml', or a Buffer if the output format is 'png'.

Arguments​

frames​Object[]

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

options​Object

A config object to specify the following common options, as well as the additional options listed in the next section.

Required
columns, rows
Terminal Related
tabSize, cursorHidden, windowTitle, windowIcon
Output Related
output, outputPath, scaleFactor, embedFonts, fonts
Capture Related
writeMergeThreshold, endTimePadding
Command Related
includeCommand, prompt, keystrokeAnimation, keystrokeAnimationInterval
Rendering Related
theme, fontFamily, fontSize, lineHeight, columnWidth, iconColumnWidth, borderRadius, boxShadow, offsetX, offsetY, paddingX, paddingY, decorations, insetMajor, insetMinor
Debugging
logLevel

Additional Options​

command​string

Command prompt string to include in the beginning of the capture. It will only be rendered if the includeCommand option is enabled.

Usage​

Basic Example​

This basic example demonstrates how to create a capture of a spinner animation from an array of content frames.

import { captureFrames } from 'cli-screencast';
import chalk from 'chalk';

// Define spinner frames for loading animation
const spinner = ['⡇', '⠏', '⠋', '⠙', '⠹', '⢸', '⣰', '⣠', '⣄', '⣆'];

// Create array of content frames with colored content and duration
const frames = spinner.map((frame) => ({
    content: `\r${chalk.yellow(frame)} Loading`,
    duration: 90, // milliseconds
}));

// Capture frames into an SVG string
captureFrames(frames, {
    columns: 50,
    rows: 10,
    cursorHidden: true,
    endTimePadding: 0,
}).then((svg) => {
    // Use or save the generated SVG string here
});
result
⡇ Loading⠏ Loading⠋ Loading⠙ Loading⠹ Loading⢸ Loading⣰ Loading⣠ Loading⣄ Loading⣆ Loading

Emulating a command​

This example demonstrates how to use the command option to capture a command prompt. It captures several frames that visually mimick the behavior of running a real command, and adds a keystroke animation to the beginning of the capture to emulate a user typing in the command.

import { captureFrames } from 'cli-screencast';
import chalk from 'chalk';

// Define frames
const frames = [
    { content: '', duration: 500 }, // Initial empty frame for visual pause
    { content: `${chalk.green('✔')} Task 1 Complete\n`, duration: 1500 },
    { content: `${chalk.green('✔')} Task 2 Complete\n`, duration: 1500 },
    { content: `${chalk.red('✘')} Task 3 Failed\n`, duration: 1500 },
];

// Capture frames into an SVG string
captureFrames(frames, {
    command: 'node tasks.js', // Command line prompt to capture
    columns: 50,
    rows: 10,
    cursorHidden: true,
}).then((svg) => {
    // Use or save the generated SVG string here
});
result
> > n> no> nod> node> node > node t> node ta> node tas> node task> node tasks> node tasks.> node tasks.j> node tasks.js> node tasks.js✔ Task 1 Complete> node tasks.js✔ Task 1 Complete✔ Task 2 Complete> node tasks.js✔ Task 1 Complete✔ Task 2 Complete✘ Task 3 Failed

The keystrokeAnimationInterval option can be configured to customize the speed of the keystroke animation, and the prompt prefix can be customized via the prompt option. The command prompt can be captured without an animation by disabling the keystrokeAnimation option.