Title: | Create 'Ascii' Screen Casts from R Scripts |
---|---|
Description: | Record 'asciicast' screen casts from R scripts. Convert them to animated SVG images, to be used in 'README' files, or blog posts. Includes 'asciinema-player' as an 'HTML' widget, and an 'asciicast' 'knitr' engine, to embed 'ascii' screen casts in 'Rmarkdown' documents. |
Authors: | Gábor Csárdi [aut, cre], Romain Francois [aut], Mario Nebl [aut] (https://github.com/marionebl/svg-term author), Marcin Kulik [aut] (https://github.com/asciinema/asciinema-player author), Posit Software, PBC [cph, fnd] |
Maintainer: | Gábor Csárdi <[email protected]> |
License: | MIT + file LICENSE |
Version: | 2.3.1.9000 |
Built: | 2024-12-05 05:58:26 UTC |
Source: | https://github.com/r-lib/asciicast |
You can set asciicast parameters in the header of the recorded R script.
The header is in DCF format (see read.dcf()
), but all lines are prefixed
with #'
comments.
The DCF header may specify arbitrary parameters. We list here the parameters that are interpreted by the asciicast functions.
Recording parameters:
allow_errors
: Whether to cast errors properly. If this is set to
TRUE
, then asciicast overwrites the "error"
option. Only change
this if you know what you are doing.
cols
: Width of the terminal, in number of characters.
empty_wait
: How long to wait for empty lines in the script file,
in seconds.
end_wait
: Delay at the very end, in seconds.
env
: Environment variables to include in the case JSON file.
Defaults to list(TERM = "xterm-256color", SHELL = "/bin/zsh")
.
idle_time_limit
: Time limit for the cast not printing anything,
in seconds. By default there is no limit.
record_env
: Environment variables to set for the R subprocess.
rows
: Height of the terminal, in number of characters.
start_wait
: Delay at the beginning, in seconds.
timeout
: Idle timeout, in seconds If the R subprocess running
the recording does not answer within this limit, it is killed and the
recording stops. Update this for slow running code, that produces no
output as it runs.
timestamp
: Time stamp of the recording, defaults to Sys.time()
,
this is included in the cast JSON file.
title
: Title of the cast, this is included in the cast JSON file.
typing_speed
: Average typing speed, per keypress, in seconds.
Asciinema player parameters:
author
: Author, displayed in the titlebar in fullscreen mode.
author_img_url
: URL of the author's image, displayed in the
titlebar in fullscreen mode.
author_url
: URL of the author's homepage/profile. Author name
(author above) is linked to this URL.
autoplay
: Whether to start playing the cast automatically.
cols
: Width of the terminal, in number of characters.
font_size
: Size of terminal font. Possible values: small, medium,
big, any css font-size
value (e.g. 15px).
idle_time_limit
: Time limit for the cast not printing anything,
in seconds. By default there is no limit.
loop
: Whether to loop the playback.
poster_frame
: Which frame to use (in seconds) as the preview picture.
poster_text
: Text to use as the preview picture. Defaults to the
title.
rows
: Height of the terminal, in number of characters.
speed
: Whether to play slower or faster. 1 is normal speed.
start_at
: Where to start the playback from, in seconds.
theme
: Theme to use, currently it has to be a string, one of
"asciinema"
, "tango"
, "solarized-dark"
, "solarized-light"
,
"monokai"
. The first one is the default.
title
: Title of the cast.
Parameters for SVG files:
at
: Timestamp of single frame to render, in seconds.
cols
: Width of the terminal, in number of characters.
cursor
: Enable cursor rendering.
end_at
: Upper range of timeline to render in seconds.
padding
: Distance between text and image bounds.
padding_x
: Distance between text and image bounds on x axis.
padding_y
: Distance between text and image bounds on y axis.
rows
: Height of the terminal, in number of characters.
start_at
: Where to start the playback from, in seconds.
window
: Render with window decorations.
theme
: Theme to use, currently it has to be a string referring to
a build-in theme, or a named list of theme properties,
see default_theme()
.
The built-in themes are "asciinema"
, "tango"
, "solarized-dark"
,
"solarized-light"
, "seti"
, "monokai"
, "github-light"
,
"github-dark"
, "pkgdown"
,"readme"
.
"readme"
is a special theme the switches between light and dark
mode automatically in README.md
files on GitHub.
Other asciicast functions:
asciicast_start_process()
,
read_cast()
,
record()
,
write_json()
Default options to set in the asciicast subprocess.
asciicast_options()
asciicast_options()
Named list.
asciicast_options()
asciicast_options()
This is for expert use, if you want to run multiple recordings in the same process.
asciicast_start_process( startup = NULL, timeout = 10, record_env = NULL, interactive = TRUE, locales = get_locales(), options = NULL, show_output = FALSE )
asciicast_start_process( startup = NULL, timeout = 10, record_env = NULL, interactive = TRUE, locales = get_locales(), options = NULL, show_output = FALSE )
startup |
Quoted language object to run in the subprocess before starting the recording. |
timeout |
Idle timeout, in seconds If the R subprocess running the recording does not answer within this limit, it is killed and the recording stops. |
record_env |
Environment variables to set for the R subprocess. |
interactive |
Whether to run R in interactive mode. Note that in interactive mode R might ask for terminal input. |
locales |
Locales to set in the asciicast subprocess. Defaults
to the current locales in the main R process. Specify a named character
vector here to override some of the defaults. See also |
options |
Options to set in the subprocess, a named list.
They are deparsed to code, and then the code setting them is
executed in the subprocess. See |
show_output |
Whether to show the output of the subprocess in real time. |
The R process, a processx::process object.
Other asciicast functions:
asciicast-package
,
read_cast()
,
record()
,
write_json()
# Use the same R process to record multiple casts process <- asciicast_start_process() script1 <- "a <- runif(10)\n" script2 <- "a\n" cast1 <- record(textConnection(script1), process = process) cast2 <- record(textConnection(script2), process = process) cast1 cast2
# Use the same R process to record multiple casts process <- asciicast_start_process() script1 <- "a <- runif(10)\n" script2 <- "a\n" cast1 <- record(textConnection(script1), process = process) cast2 <- record(textConnection(script2), process = process) cast1 cast2
You can use this widget in Rmd files or Shiny applications, the same way as other HTML widgets.
asciinema_player( cast, start_at = 0, rows = NULL, cols = NULL, autoplay = NULL, loop = NULL, speed = NULL, title = NULL, author = NULL, author_url = NULL, author_img_url = NULL, poster_text = NULL, poster_frame = NULL, font_size = NULL, theme = NULL, idle_time_limit = NULL, html_height = NULL, html_width = NULL, element_id = NULL )
asciinema_player( cast, start_at = 0, rows = NULL, cols = NULL, autoplay = NULL, loop = NULL, speed = NULL, title = NULL, author = NULL, author_url = NULL, author_img_url = NULL, poster_text = NULL, poster_frame = NULL, font_size = NULL, theme = NULL, idle_time_limit = NULL, html_height = NULL, html_width = NULL, element_id = NULL )
cast |
|
start_at |
Where to start the playback from, in seconds. |
rows |
Number of rows, defaults to the number of rows in the recording, or 24 if not specified in the cast. |
cols |
Number of columns, defaults to the number columns in the recording, or 80 if not specified in the cast. |
autoplay |
Whether to start playing the cast automatically. |
loop |
Whether to loop the playback. |
speed |
Whether to play slower or faster. 1 is normal speed. |
title |
If specified, it overrides the title in the recording. |
author |
Author, displayed in the titlebar in fullscreen mode. |
author_url |
URL of the author's homepage/profile. Author name (author above) is linked to this URL. |
author_img_url |
URL of the author's image, displayed in the titlebar in fullscreen mode. |
poster_text |
if not |
poster_frame |
Which frame to use for the preview. A number means
seconds. Defaults to the last frame. This is only used if |
font_size |
Size of terminal font. Possible values: small, medium,
big, any css |
theme |
Theme. |
idle_time_limit |
Time limit for the cast not printing anything, in seconds. By default there is no limit. |
html_height |
HTML height of the widget. |
html_width |
HTML width of the widget. |
element_id |
HTML id of the widget's element. If |
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) asciinema_player(cast)
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) asciinema_player(cast)
The new cast will inherit its options (screen size, etc.) from the first cast in the argument list. The options of the rest of the casts are ignored.
clear_screen() pause(secs) merge_casts(...)
clear_screen() pause(secs) merge_casts(...)
secs |
Number of seconds to wait. |
... |
Ascii casts to merge or merge commands. Merge commands provide a way to insert pause, clear the screen, etc., between casts. |
pause()
inserts a pause of the specified seconds between the casts.
clear_screen()
clears the screen between two casts.
An asciicast
object.
# merge two casts, with a pause, and clear screen between them cast1 <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) cast2 <- read_cast(system.file("examples", "dplyr.cast", package = "asciicast")) cast <- merge_casts(cast1, pause(3), clear_screen(), cast2) play(cast)
# merge two casts, with a pause, and clear screen between them cast1 <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) cast2 <- read_cast(system.file("examples", "dplyr.cast", package = "asciicast")) cast <- merge_casts(cast1, pause(3), clear_screen(), cast2) play(cast)
Currently only used for write_svg()
default_theme()
default_theme()
A named list.
Other SVG functions:
play()
,
write_svg()
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) svg_file <- tempfile(fileext = ".svg") mytheme <- modifyList(default_theme(), list(cursor = c(255, 0, 0))) write_svg(cast, svg_file, theme = mytheme)
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) svg_file <- tempfile(fileext = ".svg") mytheme <- modifyList(default_theme(), list(cursor = c(255, 0, 0))) write_svg(cast, svg_file, theme = mytheme)
This function is very similar to testthat::expect_snapshot_output()
,
but it runs the code in an asciciast subprocess, using record_output()
.
expect_snapshot_r_process( ..., interactive = TRUE, echo = TRUE, startup = NULL, transform = NULL, variant = NULL )
expect_snapshot_r_process( ..., interactive = TRUE, echo = TRUE, startup = NULL, transform = NULL, variant = NULL )
... |
Code to run (unnamed arguments) and arguments to pass to
|
interactive |
Whether to use an interactive R process to evaluate the code. |
echo |
Whether to echo the code in the subprocess before running it. |
startup |
Expression to evaluate in the subprocess before recording the snapshot. By default it loads and attaches the calling package, including its internal functions. |
transform |
Passed to |
variant |
Passed to |
THe Code
part of the snapshot is always the same, but the
Output
part shows the code, assuming echo = TRUE
(the default).
Sys.getpid() testthat::local_edition(3) expect_snapshot_r_process(Sys.getpid())
Sys.getpid() testthat::local_edition(3) expect_snapshot_r_process(Sys.getpid())
Helper function to query locales as a named character vector.
get_locales()
get_locales()
Named character vector with entries:
LC_COLLATE
, LC_CTYPE
, LC_MONETARY
, LC_NUMERIC
and LC_TIME
.
Call this function in your Rmd file to enable creating asciinema casts from code chunks.
init_knitr_engine( echo = FALSE, same_process = TRUE, timeout = 10, startup = NULL, record_env = NULL, echo_input = TRUE, interactive = TRUE )
init_knitr_engine( echo = FALSE, same_process = TRUE, timeout = 10, startup = NULL, record_env = NULL, echo_input = TRUE, interactive = TRUE )
echo |
Whether to print the code of asciicast chunks. |
same_process |
Whether to run all asciicast chunks in the same
R process. To restart this R process, call |
timeout |
Idle timeout, in seconds If the R subprocess running the recording does not answer within this limit, it is killed and the recording stops. |
startup |
Quoted language object to run in the subprocess before starting the recording. |
record_env |
Environment variables to set for the R subprocess. |
echo_input |
Whether to echo the input in the asciicast recording. |
interactive |
Whether to run R in interactive mode. Note that in interactive mode R might ask for terminal input. |
purl()
or setting the purl = TRUE
chunk option, does not work
properly, in that knitr thinks that asciicast chunks are not R code,
so they will appear as comments. If you know how to fix this, please
contact us.
Call this function from an Rmd chunk and then you can use the asciicast knitr engine:
```{r setup, include = FALSE} asciicast::init_knitr_engine() ```
```{asciicast, cache = TRUE}` #' Rows: 10 # This is an asciicast example loadedNamespaces() ```
Download the zip package, unzip it, and copy the executable to a system directory in which asciicast can look for the PhantomJS executable.
install_phantomjs( version = "2.1.1", baseURL = "https://github.com/wch/webshot/releases/download/v0.3.1/", quiet = FALSE )
install_phantomjs( version = "2.1.1", baseURL = "https://github.com/wch/webshot/releases/download/v0.3.1/", quiet = FALSE )
version |
The version number of PhantomJS. |
baseURL |
The base URL for the location of PhantomJS binaries for
download. If the default download site is unavailable, you may specify an
alternative mirror, such as
|
quiet |
If |
This function was designed primarily to help Windows users since it is
cumbersome to modify the PATH
variable. Mac OS X users may install
PhantomJS via Homebrew. If you download the package from the PhantomJS
website instead, please make sure the executable can be found via the
PATH
variable.
On Windows, the directory specified by the environment variable
APPDATA
is used to store ‘phantomjs.exe’. On OS X, the directory
‘~/Library/Application Support’ is used. On other platforms (such as
Linux), the directory ‘~/bin’ is used. If these directories are not
writable, the directory ‘PhantomJS’ under the installation directory of
the asciicast package will be tried. If this directory still fails, you
will have to install PhantomJS by yourself.
NULL
(the executable is written to a system directory).
Uses write_svg()
to create an SVG image for a cast, in a temporary
file, and then previews a minimal HTML file with the SVG image,
in the default browser.
play(cast, ...)
play(cast, ...)
cast |
|
... |
Additional arguments are passed to |
The path of the temporary SVG file, invisibly.
Other SVG functions:
default_theme()
,
write_svg()
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) play(cast)
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) play(cast)
Import an asciicast from an asciicast JSON file
read_cast(json)
read_cast(json)
json |
Path to JSON asciicast file, version 2: https://github.com/asciinema/asciinema/blob/master/doc/asciicast-v2.md. If a numeric id, then it is taken as a public https://asciinema.org recording id, that is downloaded. It can also be a URL of private https://asciinema.org link. |
asciicast
object.
Other asciicast functions:
asciicast-package
,
asciicast_start_process()
,
record()
,
write_json()
c1 <- read_cast("https://asciinema.org/a/uHQwIVpiZvu0Ioio8KYx6Uwlj.cast?dl=1") play(c1) c2 <- read_cast(258660) play(c2) c3 <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) play(c3)
c1 <- read_cast("https://asciinema.org/a/uHQwIVpiZvu0Ioio8KYx6Uwlj.cast?dl=1") play(c1) c2 <- read_cast(258660) play(c2) c3 <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) play(c3)
Record an asciinema screencast
record( script, typing_speed = NULL, empty_wait = NULL, cols = NULL, rows = NULL, title = NULL, timestamp = NULL, env = NULL, idle_time_limit = NULL, timeout = NULL, start_wait = NULL, end_wait = NULL, record_env = NULL, startup = NULL, echo = TRUE, speed = NULL, process = NULL, interactive = TRUE, locales = get_locales(), options = asciicast_options(), incomplete_error = NULL, show_output = FALSE )
record( script, typing_speed = NULL, empty_wait = NULL, cols = NULL, rows = NULL, title = NULL, timestamp = NULL, env = NULL, idle_time_limit = NULL, timeout = NULL, start_wait = NULL, end_wait = NULL, record_env = NULL, startup = NULL, echo = TRUE, speed = NULL, process = NULL, interactive = TRUE, locales = get_locales(), options = asciicast_options(), incomplete_error = NULL, show_output = FALSE )
script |
Path of an R script to record. It can also be a readable
R connection or URL, as it is passed to |
typing_speed |
Average typing speed, per keypress, in seconds. |
empty_wait |
How long to wait for empty lines in the script file, in seconds. |
cols |
Width of the terminal, in number of characters. |
rows |
Height of the terminal, in number of characters. If it the
string |
title |
Title of the cast, this is included in the cast JSON file. |
timestamp |
Time stamp of the recording, defaults to |
env |
Environment variables to include in the case JSON file.
Defaults to |
idle_time_limit |
Time limit for the cast not printing anything, in seconds. By default there is no limit. |
timeout |
Idle timeout, in seconds If the R subprocess running the recording does not answer within this limit, it is killed and the recording stops. Update this for slow running code, that produces no output as it runs. |
start_wait |
Delay at the beginning, in seconds. |
end_wait |
Delay at the very end, in seconds. |
record_env |
Environment variables to set for the R subprocess. |
startup |
Quoted language object to run in the subprocess before starting the recording. |
echo |
Whether to echo the input to the terminal. If |
speed |
Rescale the speed of the recorded cast with this factor. The delay of the first frame is kept constant. |
process |
A processx subprocess to run the cast in. By default a
new subprocess is started. You can reuse a process by calling
|
interactive |
Whether to run R in interactive mode. This argument
is ignored if |
locales |
Locales to set in the asciicast subprocess. Defaults
to the current locales in the main R process. Specify a named character
vector here to override some of the defaults. See also |
options |
Options to set in the subprocess, a named list.
They are deparsed to code, and then the code setting them is
executed in the subprocess. See |
incomplete_error |
Whether to error on incomplete expressions.
You might need to set this to |
show_output |
Whether to show the output of the subprocess in real time. |
An asciicast
object, write this to
file with write_json()
.
Other asciicast functions:
asciicast-package
,
asciicast_start_process()
,
read_cast()
,
write_json()
script <- system.file("examples", "hello.R", package = "asciicast") cast <- record(script) play(cast)
script <- system.file("examples", "hello.R", package = "asciicast") cast <- record(script) play(cast)
This function uses record()
internally, but instead of creating
an ascii cast, it just returns the output of the code in a character
vector.
record_output( script, echo = FALSE, prompt = echo, stdout = TRUE, stderr = TRUE, ... )
record_output( script, echo = FALSE, prompt = echo, stdout = TRUE, stderr = TRUE, ... )
script |
The code to record, passed to |
echo |
Whether to include the input in the return value. |
prompt |
Whether to include the R prompt in the return value. |
stdout |
Whether to include the standard output in the return value. |
stderr |
Whether to include the standard error in the return value. |
... |
Addiitonal arguments are passed to |
Character vector of output (plus input if echo
, plus
prompt if prompt
), as it would appear on a terminal.
See record()
for additional options.
Export ascii screencast to animated GIF file
write_gif( cast, path, show = NULL, cols = NULL, rows = NULL, theme = NULL, scale = 2, speed = 1, max_colors = 256, loop = 0, end_wait = 10, optimize = TRUE )
write_gif( cast, path, show = NULL, cols = NULL, rows = NULL, theme = NULL, scale = 2, speed = 1, max_colors = 256, loop = 0, end_wait = 10, optimize = TRUE )
cast |
|
path |
Path to GIF file to create. |
show |
Whether to show the GIF on the screen, in the viewer pane in RStudio, or using the image viewer in the magick package. By default it only show the image in RStudio. |
cols |
If not |
rows |
If not |
theme |
Theme. Currently supported themes: asciinema, tango, solarized-dark, solarized-light, monokai. Defaults to the theme specified in the cast, or asciiname if not specified. |
scale |
Image scale / pixel density. |
speed |
Playback speed. Higher number means faster. |
max_colors |
Maximum number of colors in the GIF. This is currently per frame. |
loop |
How many times to loop the animation. Zero means infinite loop. |
end_wait |
Number of seconds to wait at the end, before looping. |
optimize |
Whether to try to create smaller GIF files. This might be slow for casts with many frames. |
path
, invisibly.
Create a HTML snapshot of an asciicast
write_html( cast, path, at = "end", omit_last_line = NULL, prefix = "", theme = NULL, details = FALSE, summary = "See output" )
write_html( cast, path, at = "end", omit_last_line = NULL, prefix = "", theme = NULL, details = FALSE, summary = "See output" )
cast |
|
path |
Path to the HTML file to create. |
at |
When to take the snapshot, defaults to the end of the cast
( |
omit_last_line |
Whether to omit the last line of the cast. This often just the prompt, and sometimes it is not worth showing. |
prefix |
Prefix to add to the beginning to every line. E.g.
|
theme |
A theme name to use, or a a named list to override the
default theme (see |
details |
Whether to put the output in a |
summary |
Summary of the |
The file uses the asciinema file format, version 2: https://github.com/asciinema/asciinema/blob/master/doc/asciicast-v2.md.
write_json(cast, path)
write_json(cast, path)
cast |
|
path |
Path to write to. |
Other asciicast functions:
asciicast-package
,
asciicast_start_process()
,
read_cast()
,
record()
script <- system.file("examples", "hello.R", package = "asciicast") cast <- record(script) json <- tempfile(fileext = ".json") write_json(cast, json)
script <- system.file("examples", "hello.R", package = "asciicast") cast <- record(script) json <- tempfile(fileext = ".json") write_json(cast, json)
Create animated SVG from an asciicast
write_svg( cast, path, window = NULL, start_at = NULL, end_at = NULL, at = NULL, cursor = NULL, rows = NULL, cols = NULL, padding = NULL, padding_x = NULL, padding_y = NULL, omit_last_line = NULL, theme = NULL, show = NULL )
write_svg( cast, path, window = NULL, start_at = NULL, end_at = NULL, at = NULL, cursor = NULL, rows = NULL, cols = NULL, padding = NULL, padding_x = NULL, padding_y = NULL, omit_last_line = NULL, theme = NULL, show = NULL )
cast |
|
path |
Path to the SVG file to create. |
window |
Render with window decorations. |
start_at |
Lower range of timeline to render in seconds. |
end_at |
Upper range of timeline to render in seconds. |
at |
Timestamp of single frame to render, in seconds. Alternatively
it can be |
cursor |
Enable cursor rendering. |
rows |
Height in lines. |
cols |
Width in columns. |
padding |
Distance between text and image bounds. |
padding_x |
Distance between text and image bounds on x axis. |
padding_y |
Distance between text and image bounds on y axis. |
omit_last_line |
Whether to omit the last line of the cast. This often just the prompt, and sometimes it is not worth showing. |
theme |
A named list to override the default theme
(see |
show |
Whether to show the SVG file on the screen, in the viewer pane in RStudio, or in the web browser. |
Other SVG functions:
default_theme()
,
play()
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) svg_file <- tempfile(fileext = ".svg") write_svg(cast, svg_file)
cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast")) svg_file <- tempfile(fileext = ".svg") write_svg(cast, svg_file)