Skip to main content

great-docs termshow export

Export a recording as an animated SVG, a GIF or video, an asciicast file, or a bundle.

great-docs termshow export [OPTIONS] SOURCE

The SVG plays with CSS alone, so it works as an image in a GitHub or GitLab README. The companion .termshow.yml script’s cuts, speed changes, chapters, and annotations are applied unless --no-script is given.

With --gif, --mp4, or --webm, each screen is drawn like a screenshot and ffmpeg joins them, for places that can’t show an animated SVG, such as pull request comments, chat, and slides. This needs ffmpeg and rsvg-convert (or resvg).

With a light/dark theme pair, two files are written (NAME-light and NAME-dark), along with a snippet that picks one by the reader’s color scheme (for SVG and GIF).

With --cast, the recording is written for asciinema’s player, CLI, and asciinema.org. The script’s cuts and speed changes are applied, its chapters become markers, and its theme (the light side of a pair) is kept. Annotations, highlights, and snippets are left out.

With --bundle, the recording is written as one .termshow.json file with everything the Termshow player needs, including the transcript. Point a element’s src at it, or the termshow shortcode’s file.

Full --help output
Usage: great-docs termshow export [OPTIONS] SOURCE

  Export a recording as an animated SVG, a GIF or video, an asciicast file, or
  a bundle.

  The SVG plays with CSS alone, so it works as an image in a GitHub or GitLab
  README. The companion .termshow.yml script's cuts, speed changes, chapters,
  and annotations are applied unless --no-script is given.

  With --gif, --mp4, or --webm, each screen is drawn like a screenshot and
  ffmpeg joins them, for places that can't show an animated SVG, such as pull
  request comments, chat, and slides. This needs ffmpeg and rsvg-convert (or
  resvg).

  With a light/dark theme pair, two files are written (NAME-light and NAME-
  dark), along with a <picture> snippet that picks one by the reader's color
  scheme (for SVG and GIF).

  With --cast, the recording is written for asciinema's player, CLI, and
  asciinema.org. The script's cuts and speed changes are applied, its chapters
  become markers, and its theme (the light side of a pair) is kept.
  Annotations, highlights, and snippets are left out.

  With --bundle, the recording is written as one .termshow.json file with
  everything the Termshow player needs, including the transcript. Point a
  <termshow-player> element's src at it, or the termshow shortcode's file.

  Examples:   great-docs termshow export demos/install.termshow   great-docs
  termshow export demos/install.termshow --svg -o install.svg   great-docs
  termshow export demos/install.termshow --gif --max-idle 2   great-docs
  termshow export demos/install.termshow -o install.mp4   great-docs termshow
  export demos/install.termshow --cast   great-docs termshow export
  demos/install.termshow --bundle

Options:
  --svg                Write an animated SVG (the default)
  --cast               Write an asciicast file for asciinema (version 3 unless
                       --v2 is given)
  --gif                Write an animated GIF (needs ffmpeg)
  --mp4                Write an MP4 video (needs ffmpeg)
  --webm               Write a WebM video (needs ffmpeg)
  --bundle             Write a bundle for the Termshow player: the recording
                       in one .termshow.json file
  --v2                 With --cast, write asciicast version 2
  -o, --output FILE    Output file (default: the recording's name with the
                       format's extension, or .termshow.json for a bundle).
                       Its extension picks the format when no format option is
                       given
  --script PATH        Path to .termshow.yml script
  --no-script          Ignore any companion .termshow.yml script
  --no-loop            Play once and stop on the last screen
  --end-pause FLOAT    Seconds to hold the last screen before looping
                       [default: 2.0]
  --chapter-cards      Show a title card at each chapter
  --no-annotations     Leave out the script's annotations
  --font-file FILE     Embed this .woff2/.woff/.ttf/.otf font for the terminal
                       text
  --fps INTEGER RANGE  Frames per second of a GIF or video  [default: 20 for
                       GIF, 30 for video]  [1<=x<=60]
  --scale FLOAT        Pixels per SVG unit in a GIF or video  [default: 1 for
                       GIF, 2 for video]
  --max-idle FLOAT     Shorten pauses longer than this many seconds in a GIF
                       or video
  --help               Show this message and exit.

Arguments

SOURCE: PATH
Required.

Options

--svg
Write an animated SVG (the default)
--cast
Write an asciicast file for asciinema (version 3 unless --v2 is given)
--gif
Write an animated GIF (needs ffmpeg)
--mp4
Write an MP4 video (needs ffmpeg)
--webm
Write a WebM video (needs ffmpeg)
--bundle
Write a bundle for the Termshow player: the recording in one .termshow.json file
--v2
With --cast, write asciicast version 2
-o, --output: FILE
Output file (default: the recording’s name with the format’s extension, or .termshow.json for a bundle). Its extension picks the format when no format option is given
--script: PATH
Path to .termshow.yml script
--no-script
Ignore any companion .termshow.yml script
--no-loop
Play once and stop on the last screen
--end-pause: FLOAT = 2.0
Seconds to hold the last screen before looping
--chapter-cards
Show a title card at each chapter
--no-annotations
Leave out the script’s annotations
--font-file: FILE
Embed this .woff2/.woff/.ttf/.otf font for the terminal text
--fps: INTEGER RANGE
Frames per second of a GIF or video [default: 20 for GIF, 30 for video]
--scale: FLOAT
Pixels per SVG unit in a GIF or video [default: 1 for GIF, 2 for video]
--max-idle: FLOAT
Shorten pauses longer than this many seconds in a GIF or video

Examples

  great-docs termshow export demos/install.termshow
  great-docs termshow export demos/install.termshow --svg -o install.svg
  great-docs termshow export demos/install.termshow --gif --max-idle 2
  great-docs termshow export demos/install.termshow -o install.mp4
  great-docs termshow export demos/install.termshow --cast
  great-docs termshow export demos/install.termshow --bundle