Reference

Exports

This page tells how to export a step or all the steps of a document to a file. It lists the formats, the options and the messages of tiza render, :export and export_image.

Export a step

Use tiza render with a document and an output file:

tiza render demo.tiza --out step3.png --step 3
tiza render demo.tiza --out figure.svg --theme light
tiza render demo.tiza --out step2.md --step 2
tiza render demo.tiza --out - --format ansi | less -R
tiza render --out shot.png

• tiza render takes a .tiza document, a source file, a range of a source file (FILE:A-B) or - for standard input.
• For a source file without a range, Tiza uses its .tiza document when it has one. FILE:A-B shows lines A to B. When FILE.A-B.tiza exists, Tiza also draws its annotations and says so on stderr, as the TUI opens that document.
• The extension of --out selects the format. --format overrides the extension.
• --out - writes to standard output.
• tiza render does not make a missing folder for --out, except with --all-steps.
• Without a document, tiza render exports what the live instance shows. See The live instance.
• Without --step, an export of a document shows its last step, the same as --step LAST. A WebP is different: without --step, it is an animation of all the steps.

For example, this is the last step of examples/ownership.rs.tiza as a PNG at 92 columns:

Record all the steps

These formats hold all the steps of a document in one file: GIF, WebP without --step, MP4, WebM, .cast and .tape.

tiza render demo.tiza --out demo.gif
tiza render demo.tiza --out demo.webp
tiza render demo.tiza --out demo.mp4 --interval 3
tiza render demo.tiza --out demo.cast
tiza render demo.tiza --out demo.tape && vhs demo.tape

• A GIF and a WebP need no other program.
• An MP4 or a WebM export needs ffmpeg. See Video exports.
• Play a .cast file with asciinema play demo.cast. agg changes it to a GIF.
• A .tape file is a script for VHS. vhs demo.tape needs vhs, ttyd and ffmpeg. It writes a screen recording, demo.gif.

A recording starts at step 0. In most documents, step 0 shows only the code. --skip-zero starts the recording at step 1. After it writes a .cast or a .tape file, Tiza prints a message that shows how to play it.

Export one file for each step

Give --all-steps and a folder:

tiza render demo.tiza --all-steps --out steps/

Tiza writes step-00.png, step-01.png and the next numbers up to the last step. To get another format, give --format, for example --format md. An --out with an extension, such as answer.md or deck.jpg, is refused, because it is a file name. With a slash at the end, answer.md/ is a folder. All the files use the layout of the take. All the images have the same pixel size, so they align in a video editor or a slide deck.

• The format is PNG. --format svg, webp, txt, ansi or md changes it. The extension of --out does not change it.
• --skip-zero starts at step-01.
• Tiza makes the folder when it does not exist.

Export from the TUI

In normal mode, type :export and a path:

:export shot.png step=3 width=100 theme=light

:export writes the formats marked in Where each format works. It cannot write a recording. To record the live instance, use tiza render --out demo.gif without a document.

Export from an agent

An agent calls the MCP tool export_image with a path. The formats are in Where each format works. See export_image.

Formats

• A .txt or a .md export has no trailing spaces and no blank rows at the end.
• A .md export puts the document title in bold above the code block. Without a title, it has only the code block.
• A .ansi export keeps the trailing spaces. It resets the color at the end of each line.
• The text formats keep the box-drawing characters of the screen.
• An extension can be in capital letters, for example .PNG. This is also true for :export and export_image.
• :export and export_image also take .ans and .markdown.

Where each format works

• tiza render and export_image write a WebP of one step when you give a step. Without a step, they write an animation, as a GIF.
• :export writes a WebP of one step, as a PNG.

Options of tiza render

• --theme takes dark, light, terminal or auto.
• terminal has no colors outside the terminal. An export with terminal uses dark, and Tiza says so on stderr.
• auto uses the theme of the document, or dark.
• The theme overrides of your config file also apply. See Themes.
• --font-size, --margin and --radius work for an SVG, a PNG, a WebP, a GIF, an MP4 and a WebM export.
• --margin-cols also works for a GIF, an animated WebP, an MP4, a WebM and a .cast.
• A .tape passes --theme, --theme-file and --lang to the TUI. It refuses --numbers, --no-numbers and --margin-cols when they change what the TUI shows. See A .tape.

Timing of a recording

• A GIF counts time in units of 10 ms. Tiza rounds each frame up to a full unit, and to at least 20 ms.
• An animated WebP, an MP4 or a WebM export times each frame as the GIF does. Thus it lasts as long as the GIF.
• In a GIF, an animated WebP, an MP4 or a WebM, a step with auto_advance_ms stays that long after its typed frames. The message of the export names these steps.
• A .cast does not use auto_advance_ms.
• In a .tape, a step with auto_advance_ms stays for its typing time plus auto_advance_ms. The tape sends no n after it, because the TUI goes to the next step by itself.
• A .cast file has one asciicast marker for each step. A player goes from one step to the next with these markers.

The fields auto_advance_ms, code.patch and wait are in Document format.

:export

:export writes a step to a file from the TUI. Its syntax and its options are in :export.

• theme= also takes the Spanish aliases oscuro and claro.
• A relative PATH starts at the folder where you started Tiza. ~ at the start is your home folder.
• Tiza makes the folders that are missing. It writes over a file that exists.
• :export keeps the focus of the screen. It never draws the live pointer.
• An SVG, a PNG or a WebP from :export uses the default font size, margin, radius and scale of tiza render.
• A WebP from :export is one step, with the pixels of the PNG.
• With a theme that has no colors outside the terminal, the message tells which theme the export uses.

export_image

The MCP tool export_image exports the live document. It does not change the TUI.

• theme also takes oscuro and claro.
• A relative path starts at the current folder of tiza mcp. The tool does not make missing folders.
• A GIF or an animated WebP from export_image plays without end.
• export_image, tiza render and :export apply the [theme] overrides of your config file. export_image reads the config file of the tiza mcp process.
• In warning, export_image says what the config file left out, or that Tiza cannot read the config file. The export goes on.
• When the theme has no colors outside the terminal, export_image uses dark. Its reply does not say so.
• export_image checks scale for a PNG, a WebP and a GIF, and font_size for these and an SVG, as tiza render does. It checks interval for each format.
• An export that takes more than 120 s stops. The tool writes nothing and replies with an error.

The reply has these fields:

An animation is a GIF, or a WebP without step.

Errors of export_image

• the live document cannot be exported ends with the reason. could not write PATH ends with the error of the system.
• The No Tiza instance message then gives the error of the system in brackets. It then asks the user to open tiza <file>, or to pass --socket or --session to the MCP server.
• The message about 120 s continues with advice: export fewer steps, a smaller size or a still. It also says that tiza render in a terminal has no deadline.

Messages

tiza render writes its messages on stderr.

• Each error message and each warning message of Tiza starts with tiza: . The tables do not show this prefix.
• The ffmpeg not found message has three lines. Only the first line has the prefix.
• The error output of ffmpeg itself has no prefix.
• The wrote and play it with messages and the message with the ffmpeg command do not have this prefix.
• An error exits with code 1.
• A usage error exits with code 2. Examples are an unknown flag, an unknown value of --format, a --loop over 65535 and --step with --all-steps. Its message starts with error:.
• A missing ffmpeg also exits with code 2.

• A GIF or an animated WebP that plays a fixed number of times says plays N× instead of loops forever.
• A GIF or an animated WebP with one frame says 1 frame. S has one decimal.
• For .m4v and .mov, the needs a file message says .mp4.
• When steps have auto_advance_ms, the message ends with , step N timed by its auto_advance_ms or , steps N, M timed by their auto_advance_ms. The message of an MP4 or a WebM export ends the same way.
• A single file of --all-steps gives wrote 1 file to FOLDER (step N, W×H px). Only a PNG or a WebP run gives the size.
• For a GIF, the message about a large image starts with could not encode the GIF:. For a WebP, it starts with could not encode the WebP:. For a video, it starts with could not rasterize a frame:.
• When Tiza cannot write a step, a .cast or a .tape, the message is could not write PATH.
• A GIF, an animated WebP and a file of --all-steps go to a temporary file next to PATH first. When the write fails, the message is could not write PATH too, and Tiza removes the temporary file.
• For an MP4 or a WebM, ffmpeg writes the file. When it cannot, the message is ffmpeg failed.
• The could not write messages end with the error of the system.

Errors of tiza render

These messages end with the error of the system or the reason: could not open FILE, could not read the document from stdin, the no Tiza instance message, the two unexpected messages, the live document cannot be rendered and could not create FOLDER.

The other messages of tiza are in Messages.

Warnings of tiza render

• In tiza render, the terminal warning always says dark. In :export, it can say light.
• The tokens warning says light instead of dark when the export uses the light theme.
• config ignored ends with the error.
• An export also prints the warnings of the document. Examples are a steps entry after the last step and a rebind entry for an annotation that is not there.
• An export also prints the notes about the theme overrides of the config file, the document or --theme-file.
• When Tiza cannot read the --theme-file, the export stops with an error.

Messages of --all-steps

A run into a folder that has files of an earlier run can give these messages:

• NAMES shows at most six names. With more, it shows five names and and N more.
• With one file, the messages say 1 file, 1 entry and left as it is.
• In the entries message, each name has its kind, for example step-08.png (a directory).

See Files of --all-steps.

Messages of video and tape exports

• After the ffmpeg not found message, Tiza shows how to install ffmpeg. It also says that .gif and .cast need no other program.
• When ffmpeg fails, Tiza writes the full ffmpeg command on stderr, before the ffmpeg failed message. The command shows the codec and the options that ffmpeg got.
• could not run PATH and could not create PATH end with the error of the system.
• The tape message says output path instead of document path when the path of --out has the problem.

Messages of :export

The messages could not create the folder PATH and could not write PATH end with the error of the system.

Special cases

The live instance

Without a document, tiza render exports the document of the live instance. Give --socket or --session to select the instance.

• The export shows the views that the instance shows.
• The export leaves out what the screen leaves out at that step.
• A .tape opens the .tiza file of the instance. The tape names it relative to the folder of the tape. Run vhs from that folder.
• With --out -, the tape names it relative to the current folder.

export_image uses the same rules for the step, the width and the views.

Standard output

• --out - writes a text format, an SVG, a .cast or a .tape to standard output.
• A PNG or a WebP of one step goes to standard output only through a pipe or a redirect.
• A GIF, an animated WebP, an MP4 and a WebM need a file.
• A .tape on standard output writes its video to demo.gif.

A .tape

A .tape starts the real TUI with tiza DOCUMENT --present --no-socket --step N --no-save. N is 0, or 1 with --skip-zero. VHS then makes a screen recording of the TUI.

• --no-save: the recording never writes the document.
• --theme, --theme-file and --lang also go to the TUI. --theme auto does not go, because the TUI then shows the theme of the document, as the export does. --theme and --theme-file also set the colors of the VHS window.
• Without --theme, a document that names a theme shows that theme. A document that names no theme follows the terminal, and that terminal is the VHS window.
• The [theme] overrides and the [defaults] of the config file on the computer that runs vhs also apply to the TUI, for example pad and effect_fps.
• The TUI takes the line numbers from the document, else from the config file. It takes the margin only from the document. Tiza refuses --numbers, --no-numbers and --margin-cols when they change what the TUI shows. Set them with :numbers and :margin in Tiza, or export a GIF.
• --width sets the size of the window. --title is only a comment in the tape.

A step after the last one

tiza render --step N, :export step=N and export_image export the last step when N is after it. Each one says so: tiza render on stderr, :export in its message, export_image in warning. A recording does not use --step, so it gives no message.

Video exports

An MP4 or a WebM export starts ffmpeg. Tiza uses $TIZA_FFMPEG, or else the first ffmpeg in your PATH. Tiza ignores a TIZA_FFMPEG that has only spaces or nothing. Tiza does not include ffmpeg and does not download it.

• Without ffmpeg, the export stops with exit code 2. It writes no file.
• The video has 30 frames each second. Tiza makes its width and its height even numbers.
• An MP4 uses H.264 and yuv420p. A WebM uses VP9 and yuv420p.
• The temporary files are in Video exports.

Files of --all-steps

Each name is step-, the number of the step, a dot and the format. The number has the digits of the last step, and at least two.

A new run into the same folder removes the old step files of the same format that it did not write. Thus a step-%02d.png pattern, for example in ffmpeg, does not get an old frame. A file is an old step file only when all of these are true:

1. Its name is step-, a number, a dot and a lowercase format: png, webp, svg, txt, ansi or md.
2. The number has the same count of digits as the names of this run.
3. It is a regular file.

• Tiza keeps the old step files of another format, and names them.
• Tiza keeps a folder or a symbolic link with the name of a step file, and names it.
• Tiza keeps other names, for example step-1.png, STEP-05.PNG or step-05.png.bak.

Large images

A PNG, a GIF frame or a video frame can have at most 16384 px on each side. A WebP or a frame of a WebP can have at most 16383 px on each side. Each one can have at most 100000000 px in all. Use a smaller --width, --scale, --font-size or --margin for a larger document, or export a range of lines with FILE:A-B.

Tiza finds a document that is too large before it draws it, so the export stops at once and uses little memory:

• Before the layout, tiza render and export_image count the lines of code that the export shows. Each line takes at least one row, so the image is at least that high.
• Before the SVG, tiza render, :export and export_image calculate the size of the image from the layout.
• An SVG has a higher limit: 131072 px on each side and 6400000000 px in all, at the size of the take (an SVG has no --scale). Its file holds the text of each row, so a very long document makes it large too.

Fonts

The fonts are in the tiza binary. Thus an image export does not depend on the fonts of the system, except in the cases of this list.

• JetBrains Mono draws the code and the labels. Tiza has the regular, bold, italic and bold italic faces. The license of JetBrains Mono is the SIL Open Font License.
• Tiza Symbols draws the symbols that JetBrains Mono does not have, for example ★ and ✎. It is a subset of DejaVu Sans Mono.
• An SVG has the regular face in the file. It has the bold, italic and bold italic faces and Tiza Symbols only when the step uses them.
• With --no-embed-fonts, the SVG has no fonts. It is smaller, but it can look different in each viewer.
• With --system-fonts, Tiza also uses the fonts of the system, for example for emoji. Then the export can change from one computer to another.
• :export and export_image always put the fonts in an SVG, and never use the fonts of the system.

How it works

One layout for the take

All exports use the layout of the take. Tiza sizes the arrow lanes, the box band and the code column once, for all the steps. Thus the code does not move left or right from one step to the next, and each arrow keeps its lane. A label that fits at step 1 also fits at the last step.

The take has no empty rows for the annotations of later steps. When a step adds a row above or under a line, the code under that row moves down at that step. Examples are a note or a callout under its line, the row of an underline or of brackets, and the border of a box. A step with a code.patch or a code.link changes the code, so the code can also move at that step.

Tiza then makes all the frames of a GIF, an animated WebP or a video, or all the files of --all-steps, the same size. It adds the background color to the smaller ones.

A typed frame of a GIF, an animated WebP or a video shows different code. Thus Tiza sizes its layout separately.

Normal mode sizes the arrow lanes, the box band and the code column for the step on screen. Thus at an earlier step, a label in normal mode can be in a different place from the take. :layout stable shows the layout of the take in normal mode. The status bar then shows ⊞ stable. :layout dynamic returns to the layout of the step on screen. tiza check checks the take, not the screen.

The GIF

Tiza draws each frame as a PNG export does, then encodes the GIF itself. Some pixels at the edges of the letters can be a little different from the PNG. You cannot see the difference.

• One palette of at most 256 colors holds the colors of all the frames.
• When the frames have more than 256 colors, Tiza keeps the most frequent colors exactly. Examples are the background, the code and the vertical lines of the arrows. It mixes the other colors into the rest of the palette.
• Tiza does not dither. Thus the text stays sharp.
• After the first frame, each frame holds only the rectangle that changed.

The WebP

Tiza draws each frame as a PNG export does. Then libwebp, the WebP library of Google, encodes it without loss. The tiza binary contains libwebp, so a WebP export needs no other program.

• A WebP has all the pixels of the PNG, also the transparent pixels of the round corners.
• In an animation, each frame after the first holds only the rectangle that changed. When a frame is the same as the frame before it, Tiza keeps one frame for the two times. When all the frames are the same, the WebP is a still.
• The same document gives the same bytes each time.
• A WebP is usually smaller than the PNG or the GIF of the same steps.
• The license of libwebp is the BSD 3-Clause License, with a patent grant. The release archives include it as LICENSE-libwebp.txt.

The videos

Tiza writes the frames as PNG files to a temporary folder, with a list of their durations. Then ffmpeg encodes the list. Tiza cuts the video at the sum of the durations, so it has the same length with each version of ffmpeg. Tiza removes the temporary folder at the end.

Writing the file

A GIF, an animated WebP, an MP4, a WebM, the files of --all-steps and the file of export_image go to a temporary file first. Then Tiza renames it. Thus a stopped export does not leave a part of a file at the final name. How Tiza writes a file gives the names of the temporary files.