Exporting

Gertie writes the formats below from one scene. Use export after qa passes.

node scripts/gertie.mjs export <scene>.gertie.json --to webm,gif --json
node scripts/gertie.mjs export <scene>.gertie.json --for telegram --json

Use --to for formats you choose, or --for for a destination that has rules. Not both. Files go to out/ next to the scene.

Choosing a format

--toUse it forTransparency
lottieapps and websites with a Lottie playerfull
lottie-zipthe same animation as a smaller .lottie filefull
svg<img> tags and READMEs, no JavaScriptfull
apngweb, Discord stickersfull
webpweb, WhatsApp stickersfull
webmweb video, Telegram stickers. Safari does not show its transparencyfull
hevcSafari and iOS video. macOS onlyfull
proresvideo editors (Premiere, Resolve, Final Cut, After Effects)full
gifemail, chat, old toolsone bit: edges are jagged
mp4video anywhere, on a solid backgroundnone

If the destination accepts APNG, WebP or WebM, prefer them to GIF.

Destinations

--forWritesLimits Gertie enforces
web-imgwebp, apng, gifnone
web-videowebm, and hevc on macOSnone
telegramwebmone side exactly 512, at most 3 seconds, 30 fps, 256 KB
discord-stickerapngexactly 320 by 320, 512 KB
slack-emojigif128 by 128, under 128 KB, at most 50 frames
whatsappwebp512 by 512, 500 KB (third-party figure)
editorproresnone
emailgif on a solid backgroundnone
reelmp41080 by 1920, solid background
readmesvg and gifnone

When a file is over its size limit, Gertie lowers the frame rate, the palette and the quality step by step and says what it did (fit in the report). If nothing fits it writes nothing and reports the smallest size it reached. Then shorten the animation, use fewer shapes (gradients and many moving parts cost most) or lower the canvas size.

Default sizes

With no --scale: mp4, webm, prores and hevc are written with the longer side at least 1080 pixels, so a 256 pixel icon becomes a 1080 pixel video and a 1024 pixel scene is close to 1:1. gif keeps the authored size, up to 640 pixels on the longer side. apng, webp, svg and lottie keep the authored size. A GIF of a 60 fps scene is written at 50 fps, or at 25 when the 50 fps file is over 6 MB; the report says so under fit.

Video is tagged BT.709 so players show the colours the scene has. Do not re-encode it with another tool without keeping the tag.

Options

  • --bg #rrggbb solid background for formats that need one (mp4, reel, email) or to make a GIF opaque. Default white for those.
  • --scale 2 sets the output to double the canvas size, for every format. It overrides the defaults below. Destinations scale for themselves.
  • --quality high renders the frames at twice the output size and scales them down. It costs about 2.3 times the render time and the gain over the default is small, so use it only for thin strokes or small text that look rough.
  • --loops 3 repeats the animation before encoding, for platforms that do not loop video.
  • --keep-frames <dir> keeps the rendered PNG frames.

Checks and exit codes

Transparent formats are decoded again and a pixel that is clear in the source must still be clear, and an opaque one must still be opaque. A file that fails is deleted and reported. A scene with a solid background has nothing to check and the report says so. HEVC is checked by structure only; tell the user to confirm it once in Safari.

Video files (mp4, webm, prores, hevc) are also decoded again and three things are checked: the first, middle and last frame match the rendered frames; a transparent file has no dark or light fringe on soft edges; and a looping scene still ends where it starts. Each result is in checks in the JSON. A file that fails is deleted and reported. Checks that cannot apply say why (a lowered frame rate, HEVC alpha that ffmpeg cannot decode, an opaque file).

Exit 0: everything was written. 1: a limit could not be met, alpha was lost or a decoded-frame check failed. 2: a bad command, or ffmpeg or an encoder is missing: the other formats are still written and the failure has a fix. Run node scripts/gertie.mjs doctor to see which formats this machine can make.

What to tell the user

  • Transparent GIF has one bit of transparency. Say so when you deliver one, and offer APNG, WebP or WebM.
  • WebM transparency does not show in Safari.
  • Telegram, Discord and Slack limits come from those platforms' documentation; the WhatsApp limit comes from third-party sources and may change.