ntrecord

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install#

With Homebrew, on macOS (13 or later) or Linux, Intel or ARM:

brew install --cask nimbleterminal/tap/ntrecord
ntrecord --version

The release is a single binary. It includes the terminal engine and default text, symbol, and color emoji fonts, so recording a GIF needs nothing else. Release archives and checksums are on the releases page.

ntrecord runs on macOS and Linux. There is no Windows build.

For MP4 and WebM#

Video is encoded by FFmpeg, which you install yourself:

Your first recording

Mon, 01 Jan 0001 00:00:00 +0000

Your first recording#

Record what you do#

ntrecord record -o session.gif

This opens a new shell inside the recorder. Type commands as you normally would; when you are done, exit the shell (type exit or press Ctrl-D). ntrecord then writes session.gif and prints Wrote session.gif.

The recording is a fixed-size window, 80 columns by 24 rows unless you say otherwise:

ntrecord record -o session.gif -cols 100 -rows 30
ntrecord record -o session.gif -font-size 22 # larger text, larger picture
ntrecord record -o session.gif -shell /bin/bash # a different shell

To record one command instead of a shell, put it after --. The recording ends when the command does:

Writing tapes

Mon, 01 Jan 0001 00:00:00 +0000

Writing tapes#

A tape is a plain text file, one command after another. Lines starting with # are comments. If you have used VHS, this is the same language.

# demo.tape
Output demo.gif # where the recording goes
Set Shell /bin/sh
Set Columns 80
Set Rows 24

Type "echo hello" # type text, one key at a time
Enter # press a key
Sleep 1s # let the viewer read it

Run it with ntrecord demo.tape. Mistakes are reported with the file, line, and column. To check a tape without recording it, run ntrecord validate demo.tape: it also confirms the font, theme, Require programs, and outputs (video needs FFmpeg) are all usable.

How it looks

Mon, 01 Jan 0001 00:00:00 +0000

How it looks#

Appearance is set at the top of a tape with Set. Everything has a default, so set only what you want to change.

Output demo.gif
Set Theme "Catppuccin Mocha"
Set FontSize 20
Set Columns 70
Set Rows 14
Set Padding 20
Set Margin 30
Set MarginFill "#1e1e2e"
Set WindowBar Colorful
Set BorderRadius 10

Colors#

Set Theme "Name" picks one of 348 bundled themes (the VHS set, such as Dracula, Nord, or Catppuccin Mocha). An unknown name is an error that tells you so. Or give your own colors as a JSON object:

Using your own font

Mon, 01 Jan 0001 00:00:00 +0000

Using your own font#

The built-in font is Go Mono. To use another, set FontFamily in a tape, or pass -font to ntrecord render and ntrecord play. (ntrecord record has no -font flag; record a .cast and render it with the font you want.)

Set FontFamily "JetBrains Mono" # an installed family, by name
Set FontFamily ./fonts/MyMono.ttf # or a font file

ntrecord render session.cast -o session.gif -font "JetBrains Mono"

By name or by file#

Value	What happens
`Go Mono` (or `monospace`)	The built-in font, with regular, bold, italic, and bold italic.
An installed family name	Matched ignoring case and spaces against the font’s family or full name. Bold and italic faces are picked from the family; a style it lacks uses the regular face.
A `.ttf`, `.otf`, or `.ttc` path	That one file, used for every style, so bold and italic text will not look different. A `.ttc` collection uses its first face.

A name is searched for in the standard macOS and Linux font folders: /Library/Fonts, /System/Library/Fonts, ~/Library/Fonts, /usr/share/fonts, /usr/local/share/fonts, ~/.fonts, ~/.local/share/fonts, and $XDG_DATA_HOME/fonts. Font files larger than 32 MiB are skipped in that search; a path can be up to 64 MiB.

Output formats

Mon, 01 Jan 0001 00:00:00 +0000

Output formats#

The file name’s extension chooses the format, both for ntrecord record -o and for a tape’s Output.

Extension	What you get	Needs
`.cast`	Asciicast v3 terminal events with inline Kitty graphics	nothing
`.gif`	An animated GIF	nothing
`.mp4`	H.264 video	FFmpeg
`.webm`	VP9 video	FFmpeg
`.txt`, `.ascii`, `.test`	The screen’s text, saved at each step	nothing
a path ending in `/`	One numbered PNG per frame	nothing

An unsupported extension is rejected before the session starts, so you do not lose a recording to a typo.

Recording images

Mon, 01 Jan 0001 00:00:00 +0000

Recording images#

ntrecord draws Kitty graphics, so a program that shows pictures in a Kitty-capable terminal (charts, shader demos, image viewers) can be recorded to a GIF or video with the pictures in it.

ntrecord record -o plot.gif -cols 100 -rows 30 -- ./my-chart-program

The repository’s examples/kitty.tape records a small program that shows an image; run it to see the result.

What works#

PNG, RGB, and RGBA images sent directly in the terminal’s data stream, shown at their own size or fitted to a number of cells, cropped, offset, and transparent.
Images that sit behind text, behind cell backgrounds, or in front of everything.
Pictures built from Unicode placeholder characters, as charting libraries such as ntcharts draw them. They scroll and erase with the cells they occupy.
The questions programs ask to find out whether graphics are available, which ntrecord answers.

What does not#

Animation frames, relative placements, and images sent through shared memory or files are not supported. If a program lets you choose how it sends images, choose direct transfer; an image sent through shared memory or a file will not be shown.

When something goes wrong

Mon, 01 Jan 0001 00:00:00 +0000

When something goes wrong#

Two commands answer most questions before you read further:

ntrecord doctor # can this machine record? engine, fonts, PTY, ffmpeg
ntrecord validate demo.tape # is this tape sound? nothing is recorded

doctor prints one line per check and says plainly what is missing (an absent FFmpeg is a warning, since only MP4 and WebM need it). validate reads the tape the way a recording would and reports every problem at once: syntax errors with their line and column, an unknown theme or font, a Require program that is not installed, an Output that needs FFmpeg.