Motion Films (5am motion)

Make motion-graphics films from a brief in your terminal: kinetic type, charts, your photos and clips, a composed score and narration, with the same engine as Motion Studio.

5am motion makes motion-graphics films from a brief: kinetic type, shapes, counters, dials, charts, 3D point clouds and your own photos and video clips, cut on a beat grid with a composed score and, if you like, a narrator. It runs the same engine as Motion Studio on 5am.app, so a film made in the terminal is the same document, and renders the same pixels, as one made on the web.

A film is a MotionDoc: a small JSON file (*.motion.json). You can generate one, revise it in plain language, edit it by hand, narrate it, watch it play in your browser and look at it frame by frame for free, and export it as an MP4.

Requires CLI v1.5.0 or later. Skia, motion doctor, --engine and the lottie layer are from CLI v1.7.0; earlier releases draw every still, sheet and render with Chrome or Chromium.

Setup

sh
5am update                    # the CLI
5am update --runtime-only     # the optional runtime (shared with image editing), then Skia, which draws the films
5am login                     # a token with write scope to export
5am motion doctor             # from CLI v1.7.0: checks Skia, the engine, and reports Chrome; free
CommandNeeds
lint, fontsthe runtime and Node.js 20+
generate, revise, narratethe above, a login, and Gemini access (your own key or AI credits); --clip also Skia and FFmpeg
stills, sheetthe runtime, Node.js 20+, Skia and FFmpeg (a login only for library photos and clips)
previewthe runtime, Node.js 20+, and a browser to watch in; films with video clips also Chrome or Chromium
doctorthe runtime and Node.js 20+; it checks Skia and Chrome, and needs Chrome only with FIVEAM_MOTION_ENGINE=chrome
render, finalizewhat stills needs, and a login with write scope
podcast clip, podcast episodesfrom CLI v1.8.92: a login (write scope for clip) and a show subscribed on Episode Clips; nothing else, since the clip is made on 5AM's servers
podcast subscribe, shows, pause, resume, unsubscribefrom CLI v1.8.94: a login (write scope for all but shows); nothing else

The CLI finds FFmpeg through --ffmpeg, $FFMPEG or PATH, and Chrome through --browser, CHROME_PATH or the usual install locations. It downloads neither. On Linux as root (cloud agent VMs and containers), it starts Chrome without Chrome's own sandbox, which Chrome requires there.

Engines

Skia draws the films (from CLI v1.7.0; before it, read Chrome wherever this page says Skia). Stills, sheets and renders are drawn by Skia, a native graphics library that needs no browser. 5am update --runtime-only installs it for your computer right after the runtime, with the npm that comes with Node.js, and prints what it installed. When it cannot (npm is missing, the computer is offline, or there is no prebuilt Skia for the platform), the runtime is still installed and the command says why and exits 1. Each still, sheet and render then tries the install once more itself, and if that fails too it stops before anything is charged with:

Skia isn't installed: <reason>. Run `5am update --runtime-only` again, or render with --engine chrome.

Fix the reason and run 5am update --runtime-only again. Nothing switches to Chrome on its own.

Chrome is the fallback. --engine chrome on stills, sheet and render, or FIVEAM_MOTION_ENGINE=chrome for every command (the flag wins), draws with headless Chrome instead, as CLI v1.6.2 and earlier did. skia and chrome are the only engines. Whatever the engine, 5am motion preview plays the film in your browser and opens its video clips in Chrome. Otherwise a computer that renders with Skia needs no Chrome at all.

Fonts download from the 5AM fonts CDN on first use, checked against a hash, and are cached in ~/.5am/cache/motion/fonts. To render without a network connection, download them all once and name the folder:

sh
5am motion fonts --dir ~/motion-fonts            # every font a film can use, about 45 MB
export FIVEAM_MOTION_FONTS=~/motion-fonts

Quick start

sh
5am motion generate --brief "A 10 second launch film for a coffee app: bold type, a counter to 10,000 cups, an end card" \
  --format 9:16 --duration 10 -o coffee.motion.json
5am motion lint coffee.motion.json
5am motion sheet coffee.motion.json -o coffee.png
5am motion revise coffee.motion.json "warmer colours, slower ending" --in-place
5am motion narrate coffee.motion.json --script "Mornings, sorted. Order ahead and skip the line."
5am motion podcast episode.mp3 --brief "A minute for people who build with AI agents" -o clip.motion.json
5am motion preview coffee.motion.json
5am motion render coffee.motion.json -o coffee.mp4 --dry-run
5am motion render coffee.motion.json -o coffee.mp4 --fps 30

Every command prints one JSON document on stdout; progress goes to stderr. No command overwrites a file without --overwrite.

What it costs

CommandCost
generate, reviseGemini access (AI credits or your own key): one model call, plus at most one layout repair and one more try when a reply is cut off or is not valid JSON
narrateGemini access: one speech call
lint, inspect, stills, sheet, preview, fontsfree
render --draftfree: a 360p draft with the sound and a DRAFT mark, made on your computer (from CLI v1.8.94)
render --alphafrom CLI v1.8.95: a transparent film costs what render costs (an export is 6 seconds or longer); with --draft, free
render20 AI credits per export, on every account, including accounts with their own Gemini key; a podcast clip from podcast is 100 AI credits (from CLI v1.8.4)
podcast clip, podcast episodesfrom CLI v1.8.92: episodes is free; clip costs what an Episode Clips clip costs on 5am.app, and its result's version.estimateCredits is the estimate
podcast subscribe, shows, pause, resume, unsubscribefrom CLI v1.8.94: free. Each clip a show makes costs what an Episode Clips clip costs; subscribe --dry-run prints the estimate, and --clip-latest makes one right away

Local photos are described with Gemini once (one small call each, cached), unless you pass --no-describe.

On AI credits, each model call first reserves the most it could cost and then settles at what it used; 5am credits shows what calls still running have reserved, and 5am credits history lists each call.

Looking is free; the MP4 is what you pay for. stills and sheet draw frames exactly as the export does, with the same "Made with 5AM.app" mark, and preview plays the film with its sound. From CLI v1.8.94, render --draft writes a free MP4 to check timing and sound: 360 pixels on the short side, no motion blur, and DRAFT across the frame. What the export adds is the full-size MP4 file itself: every frame encoded, with the composed score and the narration mixed into its sound track. render --dry-run checks the film and prints the price without charging anything.

Sample films

Four films made with 5am motion, each with its MotionDoc and a contact sheet in the public examples folder. Every one lints clean; lint them, revise them or export them yourself.

FilmFormatWatch with sound
five-am-reel: the 5AM showreel (a clock, a morphing shape, a dot field tilting into terrain, a 3D point cloud, text rings)16:9, 15 sMP4, 12 MB
terminal-launch: a vertical launch film with a counter, text rings and a progress dial9:16, 12 sMP4, 5.3 MB
data-story: a square data story with growing bars, a counter, an easing curve and a dial1:1, 10 sMP4, 2 MB
concert-promo: a film built around one concert photo, which turns from black and white to colour9:16, 10 sMP4, 4.1 MB

Commands

generate

sh
5am motion generate --brief "..." [--format 16:9|9:16|1:1] [--duration 6-90] \
  [--sound pulse|house|ambient|minimal|none] [--tempo 84-160] [--photo ...] \
  [--cues cues.json] [--audio voice.m4a] -o film.motion.json

Writes a new film. The brief can come from --brief-file instead (- reads stdin). The model composes the film; a checker then looks for layout problems (text running into text or photos, unreadable timing, low contrast), asks for one repair when it finds some, and settles what it can in code. The result reports what is left:

json
{ "output": "coffee.motion.json", "title": "…", "format": "9:16", "duration": 10, "scenes": 5,
  "photos": 0, "model": "gemini-3.8-flash", "calls": 1, "repaired": false, "tidied": [],
  "fixes": 0, "issues": [], "warnings": [] }

A film with fixes left still renders; a revise that names the issues usually clears them.

revise

sh
5am motion revise film.motion.json "make the headline shorter and the colours warmer" -o v2.motion.json
5am motion revise film.motion.json "slower ending" --in-place

Sends the film and your request to the model. --format and --duration re-lay out or retime the film (positions are relative, so a 16:9 film becomes a 9:16 one without edits). --sound swaps the music bed. From CLI v1.8.4, --cues cues.json keeps a film on its soundtrack (On a soundtrack). From CLI v1.8.94, a film with tables, film tracks, overlays, lists or bars (The film timeline) is refused when the answer drops them, since the model was not taught them: edit such a film by hand, or pass --force.

Photos

--photo adds your photos to a film (up to 12), on generate or revise:

sh
5am motion generate --brief "Our wedding day in five beats" --photo ./ceremony.jpg --photo ./dance.heic -o wedding.motion.json
5am motion generate --brief "Trip highlights" --photo media:<library-media-id> -o trip.motion.json
  • Formats: JPEG, PNG, WebP, GIF and HEIC (HEIC is converted on your machine).
  • Local photos are stored in the film as paths relative to it ("src": "file:photos/ceremony.jpg"): keep them beside the film when you move it.
  • Library photos (media:<id>) are stored by their library id, as Motion Studio stores them, and downloaded when the film renders.
  • On revise, --photo replaces the film's photos. A photo already in the film keeps its place in the layers.

Video clips

--clip adds video clips (up to 4), on generate or revise, from files or your library:

sh
5am motion generate --brief "A product demo built around the screen recording" --clip ./demo.mov -o demo.motion.json
5am motion revise demo.motion.json "open on the dashboard close-up" --clip ./demo.mov --clip media:<library-media-id> --in-place
  • Any format FFmpeg reads. Skia reads each clip through FFmpeg and the ffprobe beside it, ProRes and HEVC included. With --engine chrome, the CLI opens each clip in Chrome first, and a clip Chrome cannot play as it is (ProRes, some HEVC, an unusual sound track) gets a copy made with FFmpeg, cached in ~/.5am/cache/motion/proxies; the film still names your file.
  • Stored like photos: local clips as paths relative to the film, library clips by their id.
  • On revise, --clip replaces the film's clips.
  • Their sound is muted unless the clip's layer sets a volume (0 to 1), as in Motion Studio: ask for it in the brief or a revise, or edit the film.

narrate

sh
5am motion narrate film.motion.json --script "..." [--voice Kore] [--mood "bright and quick"]
5am motion narrate film.motion.json --script-file script.txt --overwrite

Speaks the script with the same voices and speech model as Motion Studio's Sound tab, and saves the take beside the film: film.narration.wav and film.narration.json. From then on lint, stills, sheet, preview and render include it (pass --no-narration to leave it out, or --narration other.narration.json for another take). The music lowers under the voice in the export, as on the web.

  • Fit the film. A take longer than the film is refused, never cut or sped up: shorten the script or lengthen the film. About 45 to 65 words fill 30 seconds. The speech call is made either way.
  • Settle the film's length first. After a revise, the old take still plays; narrate again with --overwrite if the words should change.
  • Voices: Kore (the default), Puck, Charon, Zephyr, Aoede, Sulafat and the other Gemini voices; a wrong name lists them all.
  • A recording instead (from CLI v1.8.4): --audio voice.m4a uses a recording you have (any audio or video file) as the take, with no speech call. It stays in stereo at 48 kHz and is mixed the same way.

On a soundtrack: cues and fit

From CLI v1.8.4. When the audio comes first (a voice-over with clips of a podcast between its lines), lay the film out on it instead of timing scenes by hand:

sh
5am motion generate --brief "A clip for episode 781" --format 9:16 --cues cues.json --audio voice.m4a -o clip.motion.json
5am motion fit clip.motion.json --cues cues.json --in-place

The cue sheet says when each scene starts and what it shows; say (optional) is what is heard then:

json
{ "cues": [
  { "at": 0, "show": "Cover: the podcast, episode 781" },
  { "at": 10.3, "show": "Airbnb is building a company brain for AI agents" },
  { "at": 23.4, "show": "EVEREST: the company brain", "say": "we call it Project Everest" }
] }
  • generate --cues writes one scene per cue and starts each exactly on its second (to the frame); revise --cues keeps a revision on them. --audio makes the recording the film's take and its length (up to 90 seconds).
  • fit moves an existing film's scenes onto a sheet for free, with no model call; it needs one scene per cue. Its result lists the scenes it stretched by more than half. From CLI v1.8.94, a film it writes to another folder (-o) still finds its font files, photos and clips: their paths are rewritten from there.
  • The first cue is at 0; a scene runs at least 1 second and at most 64 beats (about 30 seconds at 128 BPM). Do not render a fitted film with --duration: that retimes every scene evenly, off the cues.
  • A film on a soundtrack shows only what the cues give: no number, statistic or name they do not state.

podcast: a clip of an episode in one command

From CLI v1.8.4. Real clips of the conversation, joined by narrator lines, with a film laid out on them:

sh
5am motion podcast episode.mp3 --brief "A minute for people who build with AI agents" -o clip.motion.json
5am motion podcast episode.mp3 --script-only -o clip.motion.json        # write the script and stop
5am motion podcast episode.mp3 --script clip.script.json -o clip.motion.json --overwrite
5am motion render clip.motion.json -o clip.mp4

Gemini reads the episode's transcript (made and cached if you do not pass --transcript), picks the guest's strongest moments by transcript line, so every cut lands on what was said, and writes a few narrator lines between them, each part with what the screen shows. The narrator lines are spoken (--voice, --mood), the clips are cut at word boundaries, every part is brought to the same loudness, and the film's scenes start as their parts are heard. The episode's cover art becomes the film's photo when the file has one.

  • The script is yours to edit. clip.script.json lists the parts in seconds: change a narrator line, move a clip's clip: [from, to], reorder, then run again with --script. Only the lines whose words changed are spoken again.
  • Beside the film: the script, the cue sheet (clip.cues.json), clip.parts/ (spoken lines and soundtrack.wav) and the take.
  • Cost: the transcription when it is not cached, one call for the script, one speech call per new line, and the film, all on your Gemini access. The export is 100 AI credits: render prices a film as a podcast clip while its clip.script.json is beside it. It carries the "Made with 5AM.app" mark, as every CLI film does.
  • A script cut off is asked for again (from CLI v1.8.95). The script call has room for a long answer, and one that still stops at Gemini's length limit is asked for again with less thinking, without using up the one retry for a script that runs too long: at most three calls for the script. On AI credits you are charged only for what is used.

From CLI v1.8.5:

  • An episode link works too. Give an HTTPS link to the audio, such as the MP3 in your RSS feed, and it is downloaded first. Links to private addresses, responses that are not audio, files over 512 MB and episodes over three hours are refused.

  • Ask for a change in plain words. --from and --revise make a new version of a film you already have:

    sh
    5am motion podcast --from clip.motion.json --revise "Use the later version of that quote" -o v2.motion.json
    

    A change to the look ("bigger cards") keeps the soundtrack and does not fetch the episode again. A change to the quotes or the narration rewrites the script from the same transcript, and only the lines that changed are spoken again. Ask for a new narrator ("use Puck", "sound brighter") and every line is spoken again in the new voice.

  • Your look. --brand-kit default, or a kit's name or ID, dresses the film in your account's brand kit, its logo included.

  • Never past 90 seconds. A soundtrack that runs past the film's 90 seconds is planned again once, shorter, and the result says how long the first one ran (shortenedFrom).

From CLI v1.8.6:

  • Names spelled as the episode spells them. A transcript can mishear a name. --episode-info episode.json gives the script writer the episode's own facts: show, title, number, author, people ([{"name": "...", "role": "guest"}]) and notes (the show notes as text). Without it, the file's own tags stand in (an MP3's title, album, artist and comment). Names are spelled from these facts; every other fact still comes from what is said in the episode, because show notes carry sponsor reads and offer codes. The facts used are saved beside the film as clip.episode.json.

  • A fact check before you pay. The result's factCheck lists what the film shows that the episode does not give: a number nobody says (a counter or a dial is read where it lands, and a number said in words, like "two point four million", counts as said), or a name spelled unlike the episode's. It changes nothing: fix the script, or ask for a change with --revise, before motion render.

    json
    "factCheck": {"numbers": 3, "names": 2, "findings": [
      {"kind": "number", "scene": 5, "layer": "dial", "text": "84%", "value": "84%"},
      {"kind": "name", "scene": 1, "layer": "text", "text": "DR. ALISON REYES", "value": "ALISON", "expected": "Allison"}]}
    

podcast subscribe and podcast shows: Episode Clips from the terminal

From CLI v1.8.94. Subscribe to a podcast without opening the website: 5AM then checks its feed every hour and clips each new episode on its servers, and each clip arrives in the show's Producer chat and your library.

sh
5am motion podcast subscribe --feed https://feeds.example.com/show.xml --dry-run       # the show, its newest episode and a clip's price; saves nothing
5am motion podcast subscribe --feed https://feeds.example.com/show.xml --clip-latest   # subscribe, and clip the newest episode now
5am motion podcast shows                                                               # your shows: ids, status, the URL each was subscribed with
5am motion podcast pause --feed <show>                                                 # and: resume --feed <show>
5am motion podcast unsubscribe --feed <show> --yes
  • Subscribing is free. Episodes already out are not clipped, unless --clip-latest asks for the newest one now. It has to be one the show could clip by itself (an audio link, at most two weeks old, at most three hours long), and it starts within a couple of minutes. If no episode qualifies, the result says so and points to episodes and clip.
  • --dry-run first to see the show's name, its newest episode and what a clip costs (estimateCredits, and requiredCredits, what to keep available to start one). Nothing is saved.
  • A show you already have is reported, not added again (alreadySubscribed: true). --clip-latest then does nothing, so use clip.
  • The show's settings shape every clip it makes, and all of them are optional: --brief, --voice (a voice name, as podcast --voice takes), --mood, --format (9:16, 16:9 or 1:1), --length (15 to 90 seconds), --brand-kit (default, or a kit's name or ID) and --cta (the line each clip ends with; by default "Listen to" and the show's name).
  • shows lists your shows with their id, title, status (active or paused), the feedUrl each was subscribed with, and its settings. Pass an id or that URL as --feed to the other commands. A feed URL can hold a private subscriber's token: the table hides its query, the JSON keeps it, so don't post the JSON.
  • pause stops new clips until resume. A clip already waiting to start gives its slot back. Resuming checks the feed at once, but episodes that came out during the pause are not clipped by themselves; clip one with clip --episode.
  • unsubscribe --yes removes the show and its Producer chat, and every clip not yet delivered is cancelled and refunded. Clips already delivered, their pages and the show's album stay in your library. If it stops part way while refunds are checked, run it again later. To stop new clips without removing anything, use pause.
  • The limits are the web's: a few shows per account (the refusal says how many), a public https feed, and the clip rules below. Each refusal says why and what to do next.
  • subscribe, shows, pause, resume and unsubscribe are subcommands, so an episode file with one of those names is given to motion podcast as ./<name>.

podcast clip and podcast episodes: clip a show you subscribe to, now

From CLI v1.8.92. For a show you subscribe to (on Episode Clips, or with podcast subscribe from CLI v1.8.94), clip asks 5AM to clip one of its episodes right away instead of waiting for the next new episode. Nothing renders on your computer: the clip is made on 5AM's servers, the same clip the show's Producer makes for a new episode, and it arrives in the show's Producer chat. episodes lists the show's episodes with their ids.

sh
5am motion podcast episodes --feed https://feeds.example.com/show.xml   # episodes and their ids, 20 a page, newest first
5am motion podcast clip --feed https://feeds.example.com/show.xml       # the newest episode, never an older one
5am motion podcast clip --feed <show id> --episode <episode id>
5am motion podcast clip --episode <episode id>                          # the show is found for you
  • Name the show with --feed: its id, or the feed URL you subscribed with. The command never subscribes: a URL that matches none of your shows is refused and nothing is queued. Upper or lower case in the address, http:// for https:// and a default port make no difference. A trailing slash does, because the server keeps it: /show.xml and /show.xml/ can be two different shows.
  • Without --episode, only the newest episode. A clip costs credits and one of the show's two episodes a day, so clip never moves on to an older episode you did not name. If the newest cannot be clipped, it stops and names that episode, its id and the reason. To clip an older one, find its id with episodes and pass --episode.
  • episodes is free and only reads. Each episode has its id, title, canCreateClip, clipUnavailableReason (set when it cannot be clipped; canCreateClip false without a reason means it already has a clip) and estimateCredits. --page 2 lists older ones.
  • An episode is clipped once. If it already has a clip, nothing new is queued: the result says alreadyClipped: true and shows that clip with its real progress, such as running or "Show paused".
  • The rules are the web's: two episodes per show a day, a paused show, episodes that cannot be clipped, and your AI credits (a clip short of credits waits for them in the Producer chat). Each refusal says why and what to do next.
  • For scripts: clip prints {feedId, showTitle, episodeId, episodeTitle, alreadyClipped, version, next}, where version has id, version, status, estimateCredits, requiredCredits, url and progress. --json prints only the version object, with created (false: the episode already had this clip).
  • clip and episodes are subcommands, so an episode file literally named clip or episodes is given to motion podcast as ./clip or ./episodes.

lint

sh
5am motion lint film.motion.json [--format 9:16] [--duration 12] [--fps 30] [--resolution 1440p] [--strict]

Free and offline. It prints:

  • what the normalizer would change (warnings);
  • the fields the engine ignores (unknown, from CLI v1.8.94): a misspelt field, or one the engine does not have, with the field meant when it looks like a typo, for example scenes[0].layers[2].sise: unknown field, ignored (did you mean "size"?);
  • layout issues: issues, each of level fix or note, and fixes, the count of fix ones. A layer is named by its place in your film (scenes[0].layers[7]), even when the normalizer dropped one before it (from CLI v1.8.94; before, the numbering skipped the dropped layer);
  • the frame count and the render size;
  • fonts, the catalog faces a render loads for the film's font roles (the hand role's face included, whether or not anything writes by hand), and fontFiles (from CLI v1.8.94), the font files the film names by path, each with its roles and the file it found;
  • timeline (from CLI v1.8.94): each scene's first beat, seconds and frames, as inspect prints it.

It exits 0 even with issues; read fixes. With --strict (from CLI v1.8.94; also on inspect and render) it prints the same and exits 3 when there is any unknown field, any warning or any fix issue, so a script stops before an export of a film that is not what you wrote. A note passes.

inspect

From CLI v1.8.94. Free; it draws nothing.

sh
5am motion inspect film.motion.json                    # the timeline
5am motion inspect film.motion.json --times 2,4.5      # every layer at 2 s and 4.5 s
5am motion inspect film.motion.json --frames 120 --fps 30

Without --times or --frames it prints the film's timeline, offline: the tempo, the length of a beat (beatSec), and each scene's start and end in beats, in seconds and in frames (startFrame is the first frame drawn in the scene, endFrame the first frame of the next), with the transition that plays over the end of the scene before. Use it to lay a film on a reference video's timestamps.

With moments (up to 48) it measures every layer there as the export draws it:

FieldWhat it says
pathwhere the layer is in the film: scenes[2].layers[1], with a group's layers below it
labelwhat it shows: a text's words as drawn there (a table's row filled in), a photo's description, a list's active row (from CLI v1.8.95; before, list), else its id or its kind
visible, hiddenwhether it shows, and if not why: before-start, after-end, transparent (under 5% opacity), off-frame, or empty (text whose table row leaves its words empty)
box, cornersits footprint in the export's pixels (x, y, w, h), and its four corners only when it is turned (from CLI v1.8.94; before, always)
frameinside, partial or outside the frame
opacityhow opaque it is there, groups and fades included
textfor text: the font drawn (family, weight, sizePx, capPx), fitScale (below 1: the text was shrunk to fit its width), overflow, and each line's words and box

While a transition plays, both scenes' layers are listed, each where the transition has it: a push or a whip moves its scene, a zoom scales it, and a fly sends its biggest words through the lens. A scene the transition is not showing (the new one before an iris opens, the old one once a zoom has passed it) reads transparent. A wipe, circle, blinds, tiles, split or glitch uncovers the new scene in place, so both keep their boxes. stills --boxes draws the same boxes on the frames.

stills and sheet

sh
5am motion stills film.motion.json --times 0.5,4,9.5 --out-dir stills
5am motion stills film.motion.json --frames 0,120,240 --out-dir stills --fps 30
5am motion sheet film.motion.json -o sheet.png --count 24
5am motion sheet film.motion.json -o moments.png --times 1.5,4,9.25

Free PNGs drawn exactly as the export would draw them, watermark included and with the export's motion blur: chosen frames (up to 48 per call), or a contact sheet of evenly spaced ones (--count, 24 by default, up to 48; frame i of n sits in the middle of the i-th of n equal stretches of the film, at (i + 0.5) / n of it). Neither replaces an existing file without --overwrite. Look at a sheet before you export. A checker cannot judge a weak contrast, a word on a busy part of a photo or a fact the brief never gave; your eyes can.

--boxes (from CLI v1.8.94) draws each visible layer's box and a label naming it, and each line of text, and prints the layers as inspect does under inspect. With --compact (from CLI v1.8.95) it prints, for each frame, only the visible layers, each with its path, label and box: the part you read to place things, at a fraction of the size.

sheet --times (from CLI v1.8.95) draws a sheet of chosen moments in seconds (up to 48) instead of evenly spaced frames, each on the frame it falls on: lay your film's sheet beside a reference video's stills taken at the same moments. Pass --count or --times, not both.

preview

sh
5am motion preview film.motion.json [--no-open]

Opens the film in your browser with its sound: play, pause, scrub and loop (space and the arrow keys work too). Leave it open while you edit: whenever you save the film, or narrate it again, the page updates in place. A save that does not load keeps the last good film playing and shows the error. The preview draws at your window's size, without the export's motion blur; sheet shows exact frames. Stop it with Ctrl-C.

render

sh
5am motion render film.motion.json -o film.mp4 [--fps 60|30] [--resolution 1080p|1440p] [--album <name-or-id> | --new-album <name>]
5am motion render film.motion.json -o film.mp4 --dry-run
5am motion render film.motion.json -o draft.mp4 --draft
5am motion render overlay.motion.json -o overlay.mov --alpha

A free draft (from CLI v1.8.94): --draft writes an MP4 to check timing and sound, and so does every render while the CLI is not signed in (note says so). It is 360 pixels on the short side at 30 fps, without motion blur or grain, with the film's whole sound and "DRAFT" across the frame; it reaches no server and costs nothing. --resolution, --fps, --dry-run and the album flags are for exports and are refused with it. The result has draft: true and, under next, the command for the export.

An export, in this order:

  1. The CLI loads every font, photo, clip and the narration. A film that cannot render stops here, and nothing is charged.
  2. It reserves the export (20 AI credits; 100 for a podcast clip). Without enough credits it stops here, and nothing is rendered.
  3. It renders every frame and composes the sound.
  4. It charges the reservation and writes the MP4. --album / --new-album also upload it to your library.

Ctrl-C, a stop signal (SIGTERM) or a failed render releases the reservation. A render killed outright (a command timeout that kills the process, a restart) cannot, so its reservation stays for 24 hours; see finalize for releasing it sooner.

--dry-run does step 1 and prints the price, size, frame count and whether the film has sound, without rendering or charging anything.

The MP4 is H.264 and AAC, 1080 pixels on the short side by default (1440 with --resolution 1440p), at 60 fps by default. Every frame has motion blur, film grain and a small "Made with 5AM.app" mark. With Skia on an Apple M1 Max, a 15-second 9:16 film at 1080x1920 rendered in 42 to 54 seconds at 60 fps (17 to 22 frames a second) and in about 33 seconds at 30 fps, measured while other work was running on the computer; a smaller computer takes longer. --workers sets how many workers draw at once (Skia's threads, or Chrome's pages with --engine chrome); the default suits the machine's cores and memory.

A transparent film (from CLI v1.8.95): --alpha, or "transparent": true in the film, renders it with an alpha channel, to lay over a video in an editor (Final Cut Pro, DaVinci Resolve, ffmpeg's overlay). Nothing is drawn behind the layers: the scenes' backgrounds, gradients and vignettes are left out, so the video shows through. The file is ProRes 4444 with its alpha in a .mov (name the output .mov), without sound. A transparent film is an insert: 1.5 to 15 seconds, no score, no narration, no film grain, and clips play muted. The "Made with 5AM.app" mark is a small badge in the top-right corner (top left when the film's own mark logo is top right). stills and sheet take --alpha too: stills are PNGs with transparency, and a sheet shows the frames on a checkerboard.

  • Put words on a plate: a text layer's box, or a shape behind them. The video under a transparent film can be any colour, so lint reads words against their own plate, and words with nothing of the film's own under them are a fix.
  • A scene's bg is not drawn, but it is still the colour the graphic is designed against: text without a color takes ink or paper against it, as in any film.
  • An export is 6 seconds or longer; render a shorter transparent film with --draft (free, 360p, with the DRAFT mark and the badge).
  • ProRes 4444 is large: about 3 MB a second for a lower third at 1080x1920 and 30 fps, and up to 28 MB a second for a film whose whole frame is busy (twice that at 60 fps).

finalize

If the charge in step 4 is refused (credits ran out while rendering), the film (an MP4, or a .mov for a transparent film) is kept for 24 hours and the error names the command that pays for it:

sh
5am credits buy                          # a payment link (pay on any device), then waits
5am motion finalize <requestId>          # pays and saves the film (-o puts it elsewhere)
5am motion finalize                      # lists the renders kept on this computer
5am motion finalize --unfinished         # releases the reservations of renders that stopped partway

Do not render again to recover: a second render is a second export. finalize never charges twice, so it is also safe after an uncertain outcome.

From CLI v1.8.95, a transparent film is finalized to a .mov (any case, .MOV too): finalize <requestId> -o overlay.mp4, or an -o with no extension, is refused with the name to use instead (overlay.mov).

From CLI v1.6.1, the list gives each kept render a state and what to do next:

stateMeaningWhat to do
renderedevery frame is in the kept file, waiting for payment5am motion finalize <requestId>
renderinganother process is still on itwait for it to finish
stoppedit ended before its last frame (killed or crashed): there is nothing to pay for5am motion finalize --unfinished releases its reservation

Unfinished exports. An account can hold at most 10 reserved, unpaid exports at a time. Renders that finish, fail or are stopped with Ctrl-C never get near that, but each render killed partway keeps one for 24 hours, and an 11th export is refused with too_many_pending_exports. From CLI v1.6.1 the error says how many are held and when the oldest clears; run 5am motion finalize --unfinished on the computer that made them, or wait for that time.

doctor

sh
5am motion doctor [--browser /path/to/chrome]

From CLI v1.7.0. Free, and it renders nothing. It checks the engine your renders use first, then the other one: it loads Skia and draws one pixel with it, and launches Chrome the way --engine chrome does. On a computer with Skia and no Chrome:

json
{ "browser": "", "ok": true, "engine": "skia",
  "chrome": { "ok": false, "error": "No executable Chrome/Chromium found. ..." },
  "skia": { "ok": true, "nativeCanvasVersion": "1.0.11" } }

engine is the engine renders use on this computer: skia, or chrome with FIVEAM_MOTION_ENGINE=chrome. Only that engine decides ok and the exit code: with Skia, a Chrome that does not launch is reported in chrome (and on stderr) and the check still passes; with Chrome, a missing Skia is reported and passes. When the engine renders use fails, ok is false, its block has the reason in error, and the command exits 1. browser is the Chrome that launched, or "". Run it on a new computer, or in the environment a scheduler or an agent renders in.

The film file

A MotionDoc is plain JSON, saved as *.motion.json. generate and revise write one; this section is the whole format, so a person or an agent can write or edit a film by hand. Every field is optional unless its table says required, and a field left out means its default. After each edit, run 5am motion lint: it prints what the engine repaired and the layout problems left (see What the engine repairs). The sample films are worked examples.

json
{
  "version": 1,
  "title": "Quarter in motion",
  "format": "1:1",
  "duration": 6,
  "tempo": 120,
  "palette": { "bg": "#060D0C", "ink": "#060D0C", "paper": "#EFEAE0", "accent": "#EA580C", "accent2": "#5EEAD4", "muted": "#0D9488" },
  "fonts": { "display": "inter", "body": "inter", "mono": "jetbrains-mono" },
  "sound": { "style": "minimal" },
  "scenes": [
    { "id": "bars", "beats": 12, "bg": "bg", "layers": [
      { "kind": "graph", "style": "bars", "values": [12, 19, 27, 41], "labels": ["Q1", "Q2", "Q3", "Q4"], "draw": [0.3, 1.8] }
    ] }
  ]
}

(That palette is the built-in dawn, the one the sample films use. Six seconds at 120 BPM is 3 bars, so the one scene is 12 beats.)

Units and coordinates

  • Beats. Time is counted in beats, four to a bar, and each scene counts its own beats from 0. A beat lasts 60 / BPM seconds (0.5 s at 120 BPM).
  • Tempo. tempo is a target. The engine takes the whole number of bars nearest to duration x tempo / 240, keeps the tempo between 84 and 160 BPM, and nudges it so those bars fill the duration exactly: 6 s at 120 BPM is 3 bars (12 beats), 10 s at 120 is 5 bars (20 beats), 15 s at 128 is 8 bars (32 beats). The scenes' beats should add up to that total. When they do not, every scene is stretched or squeezed to fit, on a half-beat grid, with a warning, and the beat fields inside each scene move with it.
  • Design units. Sizes, widths, radii and offsets are design units, where the frame's short side is 1000: a 16:9 frame is about 1778 x 1000 units, 9:16 is 1000 x 1778 and 1:1 is 1000 x 1000. The export's resolution never changes a layout.
  • Positions. x and y are fractions of the half-frame, measured from the centre: x: -1 is the left edge, x: 1 the right, y: -1 the top and y: 1 the bottom. The same fractions land in the same place in every format, so a film changes format without edits.
  • Offsets. dx and dy add design units after x and y. Stack lines with them ("dy": -90 and "dy": 90): units keep the same spacing in every format. A dx or dy between -1 and 1 would move nothing you could see, so the engine reads it as a fraction added to x or y, with a warning.
  • Safe area. Text wraps inside the frame less 70 units on each side. Keep anything that matters within 0.85 of the centre in x and y.
  • Scene beats and layer beats. Some beat fields count from the scene's first beat, the others from the layer's own start (for a layer that starts at 0 they are the same):
    • Scene beats: start and end; the keyframes of positions, scale, rotate, opacity, a picture's zoom and amount, the camera and a gradient; the camera's focus[].at and shake.beats; a pill's states[].at, a cursor's moves[].at, a picture's frame.at and a photo set's reflow[].at. A click and the change it causes share one clock that way.
    • Layer beats: everything else, such as draw, erase, count, fill, sweep, write, strike, playhead, morphAt, dissolve, collapse and flyThrough; the at of particles, lines and grid waves, of a text's dot and highlight and of a note's arrow; every motion timing; and the keyframes of a grid's tilt, yaw and zoom and of the rings' bend.
    • Seconds: a video layer's in and out count seconds of footage, so a tempo change never retimes a clip.

Animating values

A field whose value is marked Num in the tables takes one of three forms:

FormExampleWhat it does
A number"opacity": 0.6Holds that value.
Keyframes"x": [[0, -1.4], [1, 0, "outBack"]]Up to 32 [beat, value, ease] entries. Before the first key the value is the first key's; after the last, the last key's.
An oscillator"y": { "osc": "sine", "amp": 0.05, "period": 4 }Swings for as long as the layer shows.

Keyframes. The ease belongs to the key it arrives at: it shapes the move from the key before. A key without one eases inOut. Keys are sorted by beat and their values clamped to the field's range.

EaseThe move into the key
linearat a constant speed
in, out, inOutstarts gently, ends gently, or both (inOut is the default)
inExpo, outExpo, inOutExpothe same, much sharper
outQuarta long, firm settle
inOutSinethe softest start and end
outBackovershoots and settles back
inBackpulls back before it leaves
outElasticsprings past the value and wobbles in
outBouncebounces on arrival
holdstays on the previous value, then jumps at the key (a step). From CLI v1.8.94 a step lands on a frame of the export: before, the frame it fell in showed both values faintly, through the motion blur
smoothfrom CLI v1.5.1: see below

Most eases stop at every key. From CLI v1.5.1, smooth on every key after the first joins those keys into one continuous move that never stops at the keys in between, never overshoots, and only starts and ends gently: use it for a camera move through three or more keys (generate adds it to such camera moves when the model names no ease). On a single key it is a gentle ease in and out.

Oscillators are { "osc", "base", "amp", "period", "phase" }, and run on scene beats (on layer beats for a grid's tilt, yaw and zoom and a ring's bend, as keys do there):

FieldValueDefault
oscsine, triangle, saw, squaresine
basethe value it swings around0
amphow far it swings either way (required)
periodbeats per cycle, 0.125 to 64 (required)
phasethe fraction of a cycle it starts at (0.25 is a quarter on)0

base is 0 unless you set it, so an oscillating scale needs "base": 1.

json
{ "kind": "shape", "shapes": ["circle"], "size": 24,
  "x": [[0, -1.3], [1.5, 0, "outBack"]],
  "y": { "osc": "sine", "amp": 0.06, "period": 2 },
  "scale": { "osc": "triangle", "base": 1, "amp": 0.1, "period": 1 } }

The document

FieldValueDefaultWhat it does
version11The format's version.
titletext, up to 80 charactersUntitled motionThe film's name. The HUD shows it, and it seeds the randomness when there is no seed.
format16:9, 9:16, 1:116:9The frame. revise --format re-lays a film out.
durationseconds, 6 to 90 (6 to 60 before CLI v1.8.4); an insert 1.5 to 1515 (an insert: 4)The length; the tempo snaps to it.
transparenttruenoneFrom CLI v1.8.95: the film has an alpha channel and no background, and render writes ProRes 4444 in a .mov (see render). Makes the film an insert.
profileinsertnoneFrom CLI v1.8.95: a graphic for someone else's video: 1.5 to 15 seconds, no sound, no grain. A transparent film is always one.
tempoBPM, 84 to 160128The target tempo (see Units and coordinates).
seeda whole numbertaken from the titleSeeds everything random (particles, jitter, the score): the same seed draws the same frames.
palettea preset's name, or six coloursdawnSee Palettes.
fontsa face per rolesee Fonts
sound{ "style": ... }, or the style's namepulseThe score. See Sound.
feela feel's namepunchyHow every action motion moves. See Feel.
hudtrue, falsefalseA designer HUD over the film: title, bar counter, timecode and crop marks. From CLI v1.8.4, generate leaves it off unless the brief asks for a HUD, a timecode or a bar counter.
chapterstrue, falsefalseA chapter scrubber along the bottom: a diamond per chapter, a tick per bar, a playhead, and the current chapter's name written in the hand face. Name chapters on the scenes that start them (chapter); 3 to 8 short lowercase names suit explainers and tutorials.
photosup to 12 photosnoneThe photos the film may show. See Photos and clips.
clipsup to 4 clipsnoneThe video clips it may play.
mark{ "photo", "corner", "size" } (photo required)noneA logo held in a corner of every frame, drawn whole (never cropped or graded): photo is a photo's id from photos, corner is top-left (the default), top-right, bottom-left or bottom-right, and size the height of its box, 40 to 240 units (default 90; a wide logo stops at 320 across). On 5am.app a brand kit sets it.
scenes1 to 48 scenes (24 before CLI v1.8.4)a title card of the titleThe film, scene after scene. See Scenes.

Narration is not part of the film file: narrate saves the take beside it. The "Made with 5AM.app" mark is drawn by the renderer, and no field turns it off.

Palettes

A palette is six colours, named by token. Wherever a colour goes, give a token or a hex value (#rgb or #rrggbb); tokens keep a film recolourable with one edit. From CLI v1.8.97 a layer's colours may carry an alpha, #rgba or #rrggbbaa ("#FFFFFF22" is white at 13%; before, such a colour was dropped with a warning). The values inside a palette object itself are hex only, and opaque, as are a scene's bg and gradient: everything else is read against them, so an alpha there is dropped with a warning.

TokenUsed for
bgthe default scene background
inkthe dark colour, for text and lines on light backgrounds
paperthe light colour, for text and lines on dark backgrounds
accentthe main highlight: dots, highlighted words, the first shape
accent2a second highlight
muteda quiet colour, for soft surfaces and gradients

Text, counters, dials, clocks, rings, grids, lines and meshes without a color take ink or paper, whichever reads on the scene's background. "palette": "neon" names a preset; an object sets the tokens itself, and any token it leaves out comes from dawn.

Presetbginkpaperaccentaccent2muted
dawn#060D0C#060D0C#EFEAE0#EA580C#5EEAD4#0D9488
paper#EFEAE0#111111#FBF7EF#E8453C#3B3FF0#F2C230
neon#0A0A12#0A0A12#F5F5FF#FF3D81#3DFFD0#6B5BFF
mono#0E0E0E#0E0E0E#F4F4F2#F4F4F2#9A9A96#3A3A38
citrus#FFF4D6#1B1A17#FFFDF6#FF6B1A#2F6BFF#FFC21A
ocean#04162B#04162B#EAF6FF#35C2FF#FFB23F#1B4B8A

Fonts

fonts names a face for each of four roles:

RoleDrawsDefault
displaytext and counters (their default role)inter
bodytext with "font": "body", and pill labelsinter
monotext with "font": "mono", and counter labelsjetbrains-mono
handnotes and the chapter scrubber's namescaveat-bold

A face is a font id, or the face's name as written ("Bebas Neue"); anything else falls back to the role's default, with a warning. Two faces are built in: inter (a bold grotesk, the default) and jetbrains-mono (technical, weights 400 to 600). Every other face is one of the 5AM catalog's, each with one weight: a layer's weight cannot make it bolder or lighter. Italic text in instrument-serif draws instrument-serif-italic; other faces are slanted. 5am motion fonts --dir downloads them all.

CategoryFont ids
Displaybebas-neue, anton (a tall condensed poster face), archivo-black, bungee, russo-one, righteous
Sansoswald-bold, montserrat-extrabold, poppins-bold, rubik-extrabold
Roundedfredoka-bold, nunito-black, lilita-one
Serifplayfair-display-extrabold, dm-serif-display, abril-fatface, cinzel-bold, instrument-serif (editorial), instrument-serif-italic
Scriptpacifico, caveat-bold (handwriting), permanent-marker, kaushan-script
Comicbangers, luckiest-guy
Retro and techpress-start-2p, space-mono-bold, orbitron-extrabold
Japanesenoto-sans-jp-black, zen-maru-gothic-bold, dela-gothic-one, mochiy-pop-one, reggae-one, kosugi-maru, yusei-magic, shippori-mincho-extrabold, hachi-maru-pop
Arabic and Persianvazirmatn-extrabold, cairo-extrabold, rakkas
Koreanblack-han-sans, jua

A font file (from CLI v1.8.94, the CLI only): a role may name a .ttf or .otf file by its path relative to the film, "display": "file:fonts/Brand-Bold.ttf" (at most 10 MB; a WOFF or a .ttc collection is refused: convert it). The CLI loads it for every render, still and preview, and a text's size is then that face's real cap height. Its weight is the file's: one file is one face. lint reads its widths from the file, and never judges its scripts. Motion Studio on the web cannot load it and draws the role's default face. A revision written to another folder keeps pointing at the file.

A font file in your account (from CLI v1.8.95): a film from the web may name one of your own font files, "display": "file:brand-fonts/<id>.ttf" (the fonts you upload under Your fonts, or a brand kit's font file). The CLI downloads it from your account the first time a film needs it, and keeps it in ~/.5am/cache/motion/brand-fonts; a file at that path beside the film is used instead. Signed out, put the file beside the film or sign in with 5am login. A film written to another folder keeps naming it.

Emoji (from CLI v1.8.97): every role falls back to Noto Color Emoji, so emoji, flags and keycaps ("👆 Tap") draw in colour in every render, still and preview; before, the CLI drew an empty box. A film with emoji downloads the face (about 5 MB) once, and 5am motion fonts --dir includes it. Text split by letter, notes, counters and rings treat an emoji as one letter. An emoji whose character the face also has as text, such as ❤️, draws in the face's own glyph. Motion Studio on the web draws your browser's emoji.

Match the face to the brief's voice (a poster face for hype, a serif for editorial, rounded or comic for playful, retro for games and tech); most films need only a display face, with inter as body. Text in Japanese, Korean, Arabic or Persian needs a face made for that script in the role that draws it (the display face for a headline in it, the body face for smaller lines): lint reports a face that cannot draw its text as a fix. Arabic and Persian run right to left and animate word by word.

Sound

sound.style is the music bed the score is composed in. In every style but none the score also follows the film: hits on entrances, a thump on each bounce, a blip per dial marker.

StyleSound
pulse (default)a driving four-on-the-floor
housefuller and busier
minimalhalf-time and sparse
ambientno drums
noneno music and no sound effects; narration and clip sound still play

generate --sound and revise --sound set it.

Feel

feel is how every action motion moves: entrances, slides, morphs and landings.

FeelMotion
punchy (default)quick settle, small overshoot, hard slams
snappyfast and crisp, no overshoot
bouncybig overshoot, springy drops, playful
smoothslow eased glides, no overshoot, calm
mechanicalstop-motion steps, rigid, techy
cinematicslow, short travel, long settles, premium

Pick it from the brief's energy: playful is bouncy, calm or luxury smooth or cinematic, tech mechanical or snappy. A layer can take its own (see Layers); mix a different one into one layer only, for contrast.

Scenes

FieldValueDefaultWhat it does
idtext, up to 40 characterss1, s2, ...Names the scene; a repeated id gets a suffix.
beats0.5 to 644Its length.
bgcolourbgIts background.
gradienta gradient (below)noneBlends the background into a second colour.
vignette0 to 1, or true (0.35)noneDarkens the edges toward the background's own hue: 0.2 is subtle on a light scene, 0.5 on a dark one.
chaptertext, up to 24 charactersnoneWith chapters, the chapter that starts here; scenes without one continue the last.
entera transitiona cutHow this scene arrives over the end of the one before. See Transitions; the first scene's is ignored.
cameraa camerastillMoves, zooms and shakes the whole scene. See Camera.
layersup to 24 layersnoneWhat the scene draws, in order: later layers draw over earlier ones. See Layers.

A gradient is { "type", "from", "to", "angle", "x", "y" }:

FieldValueDefault
typelinear, radiallinear
fromcolour: the side the angle starts from (linear), or the centre (radial)the scene's bg
tocolour: the far side, or the edges (required)
angleNum, degrees: 0 runs left to right, 90 top to bottom (linear)90
x, yNum, the radial centre in half-frame fractions, -1.5 to 1.50

A colour alone is short for { "to": colour }, and [from, to] for both. Keep the two colours close in lightness so text reads everywhere on them; a radial gradient from a lighter colour (paper on a light scene, muted on a dark one) is a soft light behind the subject.

json
{ "id": "glow", "beats": 4, "bg": "bg", "gradient": { "type": "radial", "from": "muted", "to": "bg" }, "vignette": 0.5, "layers": [] }

Transitions

A scene's enter reveals it over the end of the scene before, landing on its first beat: { "type", "beats", ... }, or just the type's name. beats is 0.125 to 4 (default 0.5, and 1 for fly); 0.25 to 1.6 reads best, and one longer than the scene before it is a lint note. direction is the direction of travel: left, right, up or down.

TypeWhat it doesOptions
cuta plain cut (the default). From CLI v1.8.95 it lands on a frame of the export: before, the frame it fell in showed both scenes faintly, through the motion blur
circlea circle opens from a point, with a fading ringx, y (default the centre), color (the ring, default paper)
wipea hard edge sweeps across, with a bar on itdirection (default left), color (the bar, default accent)
pushthe new scene pushes the old one outdirection (default left)
whipa whip pan: a push that streaks with a heavy motion smear and lands sharp (0.3 to 0.5 beats); energetic, between two ideas that continue each otherdirection (default left)
zoomthe old scene rushes at the camera and the new one settles in from big: big reveals
splitthe old scene splits into halves that slide apart: top and bottom with left or right (the default), left and right with up or downdirection
blindsslats open one after another: left or right sweeps vertical slats that way (default right), up or down horizontal onesdirection, color (an edge on every moving slat)
tilessquare tiles pop in from the top-left corner
shuttertwo bars close from the top and bottom and open on the new scenecolor (default accent)
glitchbands of the frame jump between the two scenes
morphone continuous take: every layer with the same id as a layer of the previous scene turns into it (a shape into the other shape; anything else moves and resizes into place), and the others leave or arrive on their own. A morph with no shared id is a lint fix
flooda solid shape grows out of a layer until it fills the frame, holds, then contracts into a layer of this scene (1.2 to 1.6 beats)from (a layer's id in the previous scene), into (one in this scene), x, y (where it grows from without from), color (default ink)
irissix camera blades close, then open on the new scene (about 1 beat, often right after a click)x, y (default the centre), color (default ink)
flyfrom CLI v1.5.1: one layer of the previous scene flies through the camera while this scene is already in place underneath, so the headline or the logo becomes the cut (0.8 to 1.2 beats)from (the id of a top-level layer of the previous scene; by default its biggest words)

Give a flying layer room to grow (centred, big) and the new scene something to land on. Morphs and floods carry photos too: an image of the same photo as an image or a tile of the previous scene glides out of it, and a flood into a framed image lands as the finished print. Use transitions on about half the scenes; plain cuts are strong.

Camera

FieldValueDefaultWhat it does
zoomNum, 0.1 to 201Scales the scene around the frame's centre.
x, yNum, half-frame fractions, -3 to 30The point of the scene at the frame's centre: a pan.
rotateNum, degrees0Turns the view.
shake{ "beats": [...], "amount" }noneA jolt on each listed scene beat (up to 16); amount is 0 to 80 units (default 14; 4 to 30 reads well).
focusup to 16 { "at", "to", "zoom", "beats" } (at and to required in each)noneFlights to a layer or a point, screen-recording style.

Each focus key flies the camera to to and arrives at scene beat at, after a flight of beats (0.1 to 8, default 0.6), zoomed to zoom (0.2 to 12; default 1.5 on a layer, 1 on a point). to is a layer's id (followed while it moves, a cursor for instance), "<photo set id>:<photo id>" for one tile, or [x, y]. The camera stays there until the next key; { "at": 6, "to": [0, 0], "zoom": 1 } flies back out. A word d units from the target lands d x zoom from the middle, so end the words a zoom would push past the frame's edge before the flight, or zoom less: lint reports them.

json
{ "camera": { "x": [[0, -0.3], [4, 0, "smooth"], [8, 0.3, "smooth"]], "zoom": [[0, 1.2], [8, 1, "smooth"]], "shake": { "beats": [4], "amount": 12 } } }

Layers

Every layer is an object with a kind. A scene keeps at most 24 layers, and so does a group; a group counts as one, so put related layers in one. The warning for a layer past the cap names it (from CLI v1.8.94). These fields work on every kind:

FieldValueDefaultWhat it does
kindone of the kinds below (required)What it draws.
idtext, up to 40 charactersnoneNames it for morph, flood and fly, cursor moves, camera focus and a grid's repel wave.
start, endscene beatsthe whole sceneWhen it shows; end must come after start. Nothing draws before its start (from CLI v1.8.94; before, a layer could show up to 0.75 beat early), except while a transition reveals its scene early: then the layers that start on the scene's first beats show ahead of the downbeat. From CLI v1.8.95 a start and an end land on a frame of the export, as a step does.
x, yNum, -3 to 30Its anchor, in half-frame fractions.
dx, dyNum, design units0Offsets after x and y.
scaleNum, 0 to 401Its size.
scaleX, scaleYNum, -40 to 401A per-axis scale on top of scale: squash and stretch (1.35 and 0.65 on an impact), anticipation, or a mirror (negative).
rotateNum, degrees0Its turn.
opacityNum, 0 to 11
colorcolourper kindIts main colour (each kind says what it colours).
enter, exit{ "type", "beats" }, or the type's namenoneA move in at start, and out just before end; beats is 0.05 to 8 (default 0.5).
pulse{ "every", "amount" }noneA scale bump every every beats (0.25 to 8, default 1) of amount (0 to 0.5, default 0.06; 0.02 to 0.2 reads well).
feela feel's name, or { "preset", "intensity", "bounce", "speed" }the film'sThis layer's own feel, tuned: intensity (0 to 3) scales travel and wobble, bounce (0 to 4) overshoot, and speed (0.25 to 4) durations, so 2 is twice as slow. A group passes its feel to its layers.
trail{ "type", "count", "spacing", "color" }, or the type's namenoneCopies left behind a layer that moves.
motiona path or a bounce (below)noneMoves the layer; the engine does the physics.

enter and exit moves. A directional move names the side the layer comes from, or leaves back through.

MoveWhat it does
fadefades
popgrows from nothing
risemoves up into place
dropfalls in from above, with a bounce
from-left, from-right, from-top, from-bottomenters from that edge of the frame; as an exit, leaves through it
zoomshrinks in from big
spinspins in
wipeis revealed left to right
blursettles in from soft
noneno move

Trails draw the layer at earlier beats: ghosts (onion-skin outlines; 6 copies 0.12 beats apart by default), comet (a tail of shrinking copies; 14 copies 0.055 beats apart) or path (the dashed route it travelled). count is 1 to 40, spacing 0.01 to 2 beats, and color defaults to the layer's. A video cannot leave one.

Motions move a layer; their beats count from the layer's start.

  • { "type": "bounce", "from", "to", "floor", "bounces", "elasticity", "squash", "at", "beats" } drops the layer from from ([x, y], default [-0.8, -0.9]) onto the ground line floor (a y, -1.5 to 1.5, default 0.55; a shape's edge lands on it) and bounces bounces times (0 to 8, default 3) while it drifts to the x of to. Each bounce rises elasticity (0.05 to 0.9, default 0.45) as high as the one before, and squash (0 to 0.6, default 0.35) squashes it on each landing and stretches it in flight. It starts at (default 0) and takes beats (0.25 to 64, default the rest of the layer), with real falling-body timing and a thump on each landing.
  • { "type": "path", "path", "points", "scale", "from", "to", "ease", "orient", "loop" } travels around the layer's own x/y along a path preset (path, below; default circle) or points (2 to 64 [x, y], where -1 to 1 spans the frame's short side), resized by scale (0.05 to 5). It runs from beat from to beat to (default the layer's whole life), eased by ease (default inOut); orient turns the layer along its direction of travel, and loop repeats it.

Pair a motion with a trail: a bouncing ball with ghosts and a path trail, a comet on an infinity path.

json
{ "kind": "shape", "shapes": ["circle"], "size": 40, "fills": ["accent"],
  "motion": { "type": "bounce", "from": [-0.7, -0.8], "to": [0.6, 0], "floor": 0.5, "bounces": 4 },
  "trail": { "type": "ghosts", "count": 8 } }

The kinds follow; image, photos and video are under Photos and clips. A table lists a kind's own fields: its common ones are above.

text: kinetic type

Big type that animates by letter, word or line: headlines, subheads, labels and end cards. The workhorse of most films.

FieldValueDefaultWhat it does
textup to 160 characters (required)The words.
fontdisplay, body, mono, handdisplayThe role whose face draws it.
weight100 to 900900 (display), 600The weight, where the face has it.
size10 to 600120The cap height in units: about 100 to 160 for a headline, 40 to 70 for a subhead, 14 to 26 for a label.
trackingem, -0.2 to 1-0.025 (display), 0.02Letter spacing.
lineHeight0.7 to 2.20.98 (display), 1.25Line spacing, as a multiple of the font size.
alignleft, center, rightcenterThe edge the layer's point anchors.
maxWidth0.2 to 10.94The longest line, as a fraction of the safe width; longer text wraps.
caseupper, lower, noneuppernone keeps the text as written.
italic, outlinetrue, falsefalseItalic; letters drawn as outlines.
splitchars, words, lines, nonecharsThe unit that animates.
staggerbeats, 0 to 2at most 0.05 (chars), 0.25 (words), 0.5 (lines)The time between units.
unitEntera unit move (below)riseHow each unit arrives.
unitExita unit movenoneHow each unit leaves, at the end.
unitBeats0.05 to 40.5 (0.45 for from-left and from-right, 0.7 for drop)Each unit's move.
masktrue, falsetrue with riseClips units to their line, so they rise out of the baseline.
highlight{ "word", "style", "color", "at" } (word required)noneMarks one word (word counts from 0) with brackets (the default), a box, an underline or its color, from beat at. The colour defaults to accent, except that brackets take the text's own colour.
dot{ "color", "at", "hop" }, or truenoneA round period that drops in after the text (default accent). With "hop": true (one line only) it hops across the letters, each letter entering as the dot reaches it, and lands as the period.
backColorcolourThe back face of letters that spin-y.
valigntop, middle, baseline, bottommiddleFrom CLI v1.8.94: which point of the block sits at the layer's y: its cap-height top, its middle, its first line's baseline, or its last line's. With align, one of nine anchors.
fitshrink, noneshrinkFrom CLI v1.8.94: shrink makes text that would not fit its maxWidth or the frame smaller; none keeps size exact, and lint reports an overflow as a fix.
boxtrue, or { "color", "padding", "radius", "opacity" }noneFrom CLI v1.8.94: a plate behind the block (default paper), padding design units around its cap-height box (one number, or [x, y]; default 45% of the cap height); the words take the ink that reads on its colour, whatever its opacity (on a faint box, set the text's color). From CLI v1.8.97 lint reads the words on the box as it shows, its colour at its opacity (and the colour's own alpha) over what is behind it, and never on the scene behind the box; before, a box under 0.5 opacity was ignored and its words were judged on the scene. In a transparent film a box counts at 0.5 or more.
data, rowa table, its rownoneFrom CLI v1.8.94: {field} in text takes that row's field (see The film timeline).

5am motion inspect --times (from CLI v1.8.94) shows the size each text is drawn at (fitScale below 1 when it was shrunk) and every line's box in pixels.

Spaces. A run of spaces is one break between words. To hold a gap, or to keep words on one line, use no-break spaces (U+00A0, \u00a0 in JSON; from CLI v1.8.94): each is as wide as a space and never breaks the line, so "01\u00a0/\u00a008\u00a0\u00a0\u00a0JUPITER" keeps its gaps. Before CLI v1.8.94 they collapsed like spaces.

How words arrive. Text enters unit by unit: letter by letter by default (split: chars), each rising (unitEnter: rise). "unitEnter": "none" shows the words at once.

The unit moves, for unitEnter and unitExit:

MoveWhat each unit does
riserises out of its own baseline
dropfalls from the top and bounces into place
tumbleflips and rotates up into place
from-left, from-rightslams in from that edge
scalepops up from nothing
typeappears, one by one, like a typewriter
blursettles in from soft and large
flipflips open vertically
fadefades in
stretcharrives stretched wide and snaps back
spin-yturns like a card around its vertical axis, its back face in backColor
squeezeexit only: the letters close into the period like an accordion (give the text a dot), then the period glides to the layer's x/y; start a pill there as the text ends and the dot grows into it
noneno move

shape: morphing shapes

A filled vector shape that morphs from one shape to the next on the beat. For one accent, a logo mark, a ball that bounces, or a tile a cursor clicks (a grid of tiles is several shape layers, each with its own id).

FieldValueDefaultWhat it does
shapesup to 8 of circle, square, rounded, triangle, play, diamond, star4, star5, hexagon, heart, blob, ring, cross, pill["circle"]The shapes it morphs through.
morphAtbeats1, 2, 3, ...The beat each morph lands on.
fillscolours, one per shapecolor, else accent then accent2Their fills.
sizeradius, 10 to 70013060 to 260 reads well as a shape; 10 to 20 is a dot.
stroke, strokeWidthcolour; 0.5 to 80 unitsnone; 4% of the radiusAn outline.
spindegrees per morph, -360 to 36060The turn at each morph.
driftdegrees per beat, -180 to 18011A slow turn.
squashtrue, falsetrueA wobble on each morph.
ghosttrue, falsetrueA faint outline trailing each morph.
gizmotrue, falsefalseAn After Effects style bounding box, handles and a live rotation readout.
dissolvea beatnoneWhen it dissolves into a sunflower of dots.

path: ribbons

A striped ribbon whose head writes a stroke, then runs off.

FieldValueDefaultWhat it does
presetglyph-5, loop, wave, s-curve, spiral, infinity, zigzag, heart, underline, circle, arcloopThe stroke's shape.
points2 to 64 [x, y], where -1 to 1 spans the frame's short sidenoneA shape of your own, smoothed (in place of preset).
width4 to 20062The stroke's width.
stripesup to 6 colours, outermost firstink, accent, paper, accent2, paperConcentric stripes.
draw[start, end] beatsfrom 0, for 2 beats or half the layer if that is shorterThe head writes the shape.
erase[start, end] beatsnone (the stroke stays)Head and tail run off.
shadowtrue, falseA soft shadow.

grid: dot fields

A field of dots (or squares, crosses, lines) that waves ripple through, and that tilts into 3D terrain.

FieldValueDefaultWhat it does
styledots, squares, crosses, linesdotsWhat each point is.
spacing14 to 16037Between points.
dotradius, 0.5 to 203Each point's size.
heatcolouraccentThe colour the field takes where waves lift it.
wavesup to 8 waves (below)noneWhat moves through it.
tiltNum, degrees, -85 to 85 (layer beats)0Lays the field down into 3D.
yawNum, degrees, -180 to 180 (layer beats)0Turns it.
zoomNum, 0.1 to 6 (layer beats)1Scales it.
introburst, scan, fade, noneburstHow it appears; with none it is drawn during the scene's transition, so a push or a whip shows it streaking in.
introBeats0.1 to 80.55The intro's length.

A wave is { "type", "at", "beats", "x", "y", "amp", "direction" }: a plane (a band sweeping across in direction, default right, over beats, default 1.5), a ripple (a ring spreading from x, y), noise (a churning field) or terrain (rolling hills, which read as a landscape once tilted). amp is its height, 0 to 300 units (default 70), and at its start. Or { "type": "repel", "target", "radius", "strength" }: the dots part around a moving layer of the scene (target, its id) and heat up; radius 20 to 1200 (default 190), strength -400 to 400 (default 70).

mesh: 3D point clouds

A turning 3D form drawn as points, wires or both, that morphs between shapes, words included.

FieldValueDefaultWhat it does
shapesup to 6 of sphere, torus, cube, cylinder, helix, plane, cone, octahedron, or text:WORD (1 to 12 characters)["sphere"]The forms it morphs through.
morphAtbeats1, 2, 3, ...The beat each morph lands on.
points120 to 32001400How many points (400 to 2400 reads well).
renderpoints, wire, bothbothHow it is drawn.
sizeradius, 40 to 700280180 to 340 reads well.
pointSize0.5 to 102.4Each point's size.
spinX, spinYdegrees per beat, -360 to 3600, 55Its turn.
tiltdegrees, -90 to 9022A fixed tilt toward the viewer.
accentcolouraccentThe colour of some of its points.
flyThrough[start, end] beatsnoneThe camera flies through it.

particles

Deterministic particle systems.

FieldValueDefaultWhat it does
emitterburst, fountain, orbit, rain, confetti, swarm, sunflowerburstThe system.
count1 to 2000120 (rain 160, sunflower 700)How many.
colorsup to 6 coloursaccent, accent2, paperTheir colours.
size0.5 to 407Each particle's size.
speed0 to 4000 units a second900How fast they leave.
gravity-4000 to 40001400 (confetti), 500 (burst), 0The pull down.
ata beat0When a burst goes off.
spreaddegrees, 0 to 360360The cone they leave in.

rings: text rings

Rows of words turning on concentric rings around a dot.

FieldValueDefaultWhat it does
rows1 to 6 rows (required): { "text", "size", "weight", "outline" }, or the text aloneShort phrases such as PHOTOS • VIDEO • CLIPS; 2 or 3 rows read best. size 8 to 120 (default 34, smaller for each inner row), weight (default 800).
radius80 to 90080% of the short half-frameThe outer ring's radius.
bendNum, 0 to 1 (layer beats)opens from marquee rows into rings over its beats 1 to 20 is straight marquee rows, 1 full rings.
spinunits of scroll per beat, -2000 to 2000150How fast they turn.
collapse[start, end] beatsnoneThe rings spin up and implode into the centre dot.
dotcolour, or falseaccentThe centre dot.

Set "bend": 1 unless you want a ticker: below 1 the rows run off both frame edges. Keep the rows solid (an outline row is a hairline nobody can read) and the scene free of other words, since the rings fill the middle of the frame. Rings set each letter on its own, which breaks Arabic and Persian: put those words in a text layer.

counter

A number that counts on the beat, on fixed digit slots so it never jitters.

FieldValueDefaultWhat it does
toa number (required, unless data and field give the number)Where it lands.
froma number0Where it starts.
format0, 0.0, 0%, 00:00, $0,000, 0k and the like, then a unit if any (0.00 AU, 0 km)0The zeros after the point are decimals, a comma groups thousands, % adds a percent sign, k counts thousands, $, € or £ leads, and 00:00 shows seconds as minutes and seconds. A unit after the pattern (up to 12 characters, no digits; from CLI v1.8.94) is kept as written.
data, row, fielda table, its row, a field of itnoneFrom CLI v1.8.94: the number is that field of the row, gliding between rows as the row's track glides; no count-up (see The film timeline).
prefix, suffixup to 6 and 8 charactersnoneText around the number.
fontdisplay, body, mono, handdisplayThe role whose face draws it.
weight100 to 900900
size20 to 700200The cap height.
count[start, end] beatsfrom 0 to 60% of the layerWhen it counts.
easean easeoutExpoHow it counts.
labelup to 40 charactersnoneA line under the number, in capitals in the mono face.
labelColorcolourthe number's, at 70%From CLI v1.8.94: the label's colour.
labelSize8 to 200 design units16% of sizeFrom CLI v1.8.94: the label's size, before the counter shrinks to fit; it hangs a clear gap under the number.
labelTrackingems, -0.1 to 10.25From CLI v1.8.94: the label's letter spacing.

clock

An analog clock whose markers split out of the centre and whose hands sweep between two times.

FieldValueDefaultWhat it does
from, to"H:MM"4:15, 5:00The times it sweeps between.
sweep[start, end] beats[2, 3]When the hands move.
radius40 to 480190Its size.
readouttrue, falsetrueThe time, in digits, under it.
accentHour0 to 11the hour it lands onThe marker that turns accent when the sweep lands.
splittrue, falsetrueThe markers split out of the centre beat by beat.

lines

Graphic line systems that frame or energise a scene.

FieldValueDefaultWhat it does
patternrays, burst, stripes, scanlines, grid, corners, circles (required)Rays from the centre, a burst of dashes, diagonal stripes, travelling scanlines, a grid, crop corners, or circles on the beat.
count1 to 200per patternHow many lines.
width0.5 to 603Line width.
length1 to 2000per patternRay, dash or corner length.
ata beat0When it starts.
beats0.1 to 321How long it grows (or a circle's period).
spindegrees per beat, -360 to 3606The rays' turn.

wave: soundwaves

From CLI v1.6.0. A soundwave breathing with its own rhythm, centred on the layer's x/y: for podcasts, music, a voice, "now playing", a recording. One per scene is plenty; give it room, with no words across its band.

FieldValueDefaultWhat it does
styleone of the styles belowribbonIts look.
width40 to 4000820Its width in units.
height10 to 1200160The band's height; everything scales with it.
colorsup to 4 coloursper styleThe ribbons, or the liquid gradient's stops; the one-colour styles take the first (else the layer's colour), the machines an accent second.
intensity0.15 to 10.75How loud the signal plays.
speed0.1 to 41How fast it moves.
SetStyles
Spectrumribbon (four translucent ribbons, the default), mono (a line with its traces), silk (eight silk layers), liquid (one liquid band), spectrum (fine bars)
One coloursweep (a phosphor scan), dust (a point cloud), braid (two strands), terminal (box-drawing characters), contour (stacked ridges), teletext (a mosaic), scope (an oscilloscope), wireframe (a wire terrain), ascii (a text stream), spectral (pixel columns)
With an accentmotor (a harmonic motor whose arms draw the wave), horizons (a calibrated floor), vernier (two sliding rulers), broken (a plotter grid)

figure: drawn characters

From CLI v1.6.0. A drawn character moving to the film's beat, centred on the layer's x/y: for podcasts, music, voice and listening. One per scene; keep words off it.

FieldValueDefaultWhat it does
figureone of the figures below (required)Who.
size40 to 2400480Its width in units (the listener is a little taller than wide).
colorsup to 7 colours, in the figure's own orderits ownCreatures: white, red, blue, mint, violet, dim, tan. Heads: outline, feature, voice, ear, quiet, white. The songbird: bird, branch, sound. The listener: face, earbud, glow.
intensity0.25 to 1.51How hard the music hits it.
speed0.25 to 31Its clock.
modevoice, listenvoiceThe heads: speaking, or listening.
cliptrue, falsetrueThe round figures clip to their circle.

The figures: ten playback creatures, each limb on a drum (goblin, a tape goblin; boxer, a punch-clock boxer; eater, a tape eater; octopus; bird, a resonant bird; astronaut, moonwalking; moth, a moth choir; hound, an x-ray hound; snail, a reel-riding snail; conductor, a ghost conductor), two voice heads (phoneme leaves a sound packet for each syllable, echo excites a resonating cavity), choir (a songbird on a branch) and listener (a traced profile nodding to the beat, its earbud pulsing).

lottie: vector animations

From CLI v1.7.0. A small animated accent centred on the layer's x/y: one of eight built-in presets, or your own Bodymovin (Lottie) JSON.

FieldValueDefaultWhat it does
presetone of the presets belowsparkle (without data)The built-in animation.
dataa Bodymovin v5 JSON objectnoneYour own animation, drawn in place of the preset.
width, height24 to 2400320, and height the widthIts box; data is fitted inside it, centred.
speed0.1 to 61A preset: how many times it plays between start and end. data: a multiple of its own frame rate.
looptrue, falsetruefalse plays it once and holds the last pose.
primaryColor, secondaryColorcolourscolor, else accent; accent2A preset's two colours (data keeps its own).
PresetWhat it showsFor
sparklea four-point star twinkling with three small onesnew, magic, a launch
confettipieces burst out and fall awaya celebration, a milestone
checka ring draws round, then a tickdone, approved, sent
flamea flickering flamehot, trending, a streak
pulse-ringrings radiating from a dotlive, recording, a notification
equalizerfive bouncing barsmusic, audio, now playing
arrow-bursteight rays shooting outemphasis, a reveal
star-bursta turning twelve-point bursta badge, a price, "new"

A preset plays once across the layer's window, from start to end; speed repeats it ("speed": 3 plays it three times). Give the one-shot presets (confetti, check, arrow-burst) a short window at their moment ("start": 2, "end": 3.5), and a looping one (sparkle, flame, pulse-ring, equalizer, star-burst) on a long window a speed of about one cycle per two beats (generate sets it so). Each looping preset ends its cycle where it began, so repeats never jump. Keep it beside what it accents (width 120 to 320), never under text, at most one per scene, and only when the subject calls for one (a celebration, a launch, music, something live): most films need none.

Your own Lottie. data is drawn by the engine, not a Lottie player, and takes a subset of Bodymovin v5, with lottie-web's semantics:

  • Layers: shape (ty 4) and solid (ty 1) layers, with their transform and in and out points. The composition is clipped to its w x h and plays at its frame rate fr from the layer's start, looping unless loop is false.
  • Shape items: gr (group), rc (rectangle), el (ellipse), sr (star and polygon), sh (path; keyframed vertices too, when every keyframe has as many), fl (fill; r: 2 fills even-odd), st (stroke, with its caps, joins and miter limit), tm (trim paths) and tr (group transform).
  • Keyframes: both forms (a value s on every keyframe, and older exports' end values e), hold keyframes and per-dimension easing.
  • Not supported: gradients and every other shape item, masks, mattes, parenting, effects, time remapping, 3D layers and rotations, expressions, blend modes other than normal, time stretch, start offsets, skew, spatial tangents, polystar roundness, stroke dashes, image and text layers. Nor more than 64 nested groups, 100 star points, 20,000 layers and shape items, 100,000 path segments drawn a frame, or numbers past 1,000,000.

A data document with anything unsupported is dropped with a warning naming the first problem; the layer then draws its preset, or is dropped when it names none.

json
{
  "version": 1,
  "title": "On air",
  "format": "1:1",
  "duration": 6,
  "tempo": 120,
  "palette": "neon",
  "scenes": [
    { "id": "live", "beats": 12, "bg": "bg", "layers": [
      { "kind": "text", "text": "ON AIR", "size": 130, "dy": -150 },
      { "kind": "lottie", "width": 220, "dy": 170, "data": {
        "v": "5.7.4", "fr": 30, "ip": 0, "op": 60, "w": 200, "h": 200,
        "layers": [{
          "ty": 4, "ip": 0, "op": 60,
          "ks": {
            "p": { "k": [100, 100, 0] },
            "s": { "a": 1, "k": [
              { "t": 0, "s": [60, 60, 100], "o": { "x": [0.4], "y": [0] }, "i": { "x": [0.6], "y": [1] } },
              { "t": 30, "s": [100, 100, 100], "o": { "x": [0.4], "y": [0] }, "i": { "x": [0.6], "y": [1] } },
              { "t": 60, "s": [60, 60, 100] }
            ] }
          },
          "shapes": [
            { "ty": "el", "p": { "k": [0, 0] }, "s": { "k": [140, 140] } },
            { "ty": "fl", "c": { "k": [1, 0.24, 0.5, 1] }, "o": { "k": 100 } }
          ]
        }]
      } }
    ] }
  ]
}

note: handwritten notes

A designer's margin note in the hand face: it writes itself on, can point at something with a hand-drawn arrow, strike itself out or underline itself. Annotate a moment ("squash!"), point at what it explains, or cross out a wrong idea and write the right one.

FieldValueDefaultWhat it does
textup to 80 characters (required)The words, in their own case.
size12 to 2004436 to 60 reads well.
alignleft, center, rightleftA note runs right from its x (about 0.36 x size per character) unless it is centred or right-aligned.
write[start, end] beatsquick, by its lengthWhen it writes on.
arrow{ "x", "y", "dx", "dy", "bend", "at" } (x and y required)noneA hand-drawn arrow to a point (x, y in half-frame fractions, -1.5 to 1.5, plus unit offsets), curving by bend (-1.5 to 1.5), drawn at beat at (default when the writing ends).
strikea beatnoneA line crosses it out.
underlinetrue, falsefalse
boiltrue, falsetrueA hand-drawn jitter, a few times a second.

Its color defaults to accent.

dial: progress dials

An arc that fills to a percent, with markers inside that light up in turn, a fine tick ring, a centre dot and a readout: loading, uploads, goals, "almost there".

FieldValueDefaultWhat it does
topercent, -1000 to 1000100Where the fill ends.
frompercent0Where it starts.
fill[start, end] beatsfrom 0.5 to 80% of the layerWhen it fills.
easean easeinOutHow it fills.
radius60 to 480230150 to 320 reads well.
markers0 to 4812Markers that light in turn (0 hides them).
ticks0 to 18072The fine ticks (0 hides them).
readouta counter format, or false0%The number under the dial.
labelup to 40 charactersnoneA line under the readout.
dotcolour, or falseaccentThe centre dot.
accentcolouraccentThe fill and the lit markers.

graph: curves and charts

Two modes: easing curves in a curve editor (curves, morphing one into the next, with bezier handles and a playhead), to explain motion ("linear is robotic, ease in-out feels natural"); or a small data chart (values, as a line, an area or bars), to show growth or compare numbers. With both, curves wins.

FieldValueDefaultWhat it does
curvesup to 6 ease namesnoneThe curves it shows, one after another.
morphAtbeats1, 2, 3, ...When each curve morphs into the next.
valuesup to 24 numbersnoneThe data.
labelsup to 24, of 14 charactersnoneA label under each value.
data, field, labelFielda table and two of its fieldsnoneFrom CLI v1.8.94: the values are field of every row, the labels labelField.
highlighta track's name, or a value's numbernoneFrom CLI v1.8.94: that row's bar (or a dot on the line) and label take accent, gliding as the track glides.
styleline, area, barslineHow values are drawn.
width, height120 to 1800, 80 to 1600640, 400The chart's box.
draw[start, end] beats[0.3, 1.3]The line draws on, or the bars grow.
playhead[start, end] beatsnoneA dot rides the curve, with a time cursor.
handlestrue, falsetrueBezier handles on easing curves.
axes, gridtrue, falseAxes and grid lines.
xLabel, yLabelup to 24 characterstime and position for curvesAxis titles; leave them out of a chart unless it needs them.
accentcolouraccent2The handles and the playhead.
lineWidth1 to 244.5

Its color is the curve or the bars (default accent).

pill: buttons and chips

One shape that keeps morphing: a button or a status chip. It grows out of a dot, its width springs to fit each state, labels swap inside its own mask, and every later state reads as a click: "Order print", then "Ordered" with a check, "Printing" with a progress bar, "On its way", and a circle with a check.

FieldValueDefaultWhat it does
states1 to 12 states (required)Each { "at", "text", "icon", "progress", "circle" }, below.
height24 to 40072110 to 150 for the button a story is about.
size8 to 12024The label's cap height (34 to 44 on a hero pill).
fillcolourink or paper, whichever readsThe pill.
textColorcolourwhichever reads on the fillThe label.
fontdisplay, body, mono, handbodyThe label's role.

A state: at is the scene beat it takes over (like cursor clicks; default its index in the list: 0, 1, 2, ...), text its label (up to 48 characters, cut at a word), icon one of check, spinner, arrow, play, plus, dot, route or none, progress: true fills a thin bar and a percent readout until the next state, and circle: true collapses the pill to a circle around the icon. A state needs a label or an icon.

cursor: a pointer

A pointer that drives the story: it travels to things, clicks, long-presses and drags. Always drawn on top.

FieldValueDefaultWhat it does
moves1 to 32 moves (required)Each { "at", "to", "dx", "dy", "click", "hold", "drag" } (at and to required), below.
size12 to 12034Its height.
stylearrow, toucharrowtouch is a translucent fingertip, for phone demos.

A move arrives at scene beat at on to: a layer's id (its anchor at that beat), "<photo set id>:<photo id>" for a tile, or [x, y], plus dx/dy units. click: true clicks on arrival, hold keeps the button down that many beats (a long press, 0.05 to 8), and drag: true holds it while travelling there from the move before. Click exactly when the thing changes: a click at beat 3 means the pill state, the layer start or the camera flight it causes is at 3 too, or lint reports an idle click. Give the cursor the same id in scenes joined by a morph, so it glides across the cut.

group

{ "kind": "group", "layers": [...] }: up to 24 layers that share one transform (position, scale, rotation, opacity, entrances) and pass down their feel. Groups nest at most 3 deep, and an empty group is dropped. A fly takes a top-level layer, never one inside a group.

A film that uses them

A 10-second vertical film: a stacked headline, a counter on an accent scene that the headline flies into, a dial under a slow camera, and an end card with a hopping dot and a sparkle (a lottie layer, from CLI v1.7.0).

json
{
  "version": 1,
  "title": "Brew",
  "format": "9:16",
  "duration": 10,
  "tempo": 120,
  "seed": 7,
  "palette": "citrus",
  "fonts": { "display": "anton", "body": "inter", "mono": "jetbrains-mono" },
  "sound": { "style": "house" },
  "feel": "snappy",
  "scenes": [
    { "id": "hook", "beats": 4, "bg": "bg", "layers": [
      { "kind": "text", "text": "SKIP THE", "size": 150, "dy": -120, "unitEnter": "from-left" },
      { "kind": "text", "id": "line", "text": "LINE", "size": 150, "dy": 120, "start": 0.5, "unitEnter": "rise", "highlight": { "word": 0, "style": "underline" } }
    ] },
    { "id": "cups", "beats": 4, "bg": "accent", "enter": { "type": "fly", "from": "line" }, "layers": [
      { "kind": "counter", "from": 0, "to": 10000, "format": "0,000", "size": 220, "count": [0.3, 2.5], "label": "cups this morning" }
    ] },
    { "id": "ready", "beats": 4, "bg": "ink", "enter": { "type": "circle", "beats": 0.75 },
      "camera": { "zoom": [[0, 1.15], [4, 1, "out"]] },
      "layers": [
        { "kind": "dial", "to": 100, "fill": [0.3, 2.6], "radius": 310, "label": "ready in 3 min", "dy": -80 }
      ] },
    { "id": "end", "beats": 8, "bg": "bg", "enter": { "type": "zoom", "beats": 0.5 }, "layers": [
      { "kind": "text", "text": "BREW", "size": 170, "dy": -40, "dot": { "hop": true } },
      { "kind": "text", "text": "Order ahead", "font": "body", "case": "none", "size": 44, "dy": 140, "start": 1.5 },
      { "kind": "lottie", "preset": "sparkle", "width": 160, "x": 0.55, "y": -0.3, "start": 2, "speed": 3 }
    ] }
  ]
}

And a product story told as one continuous take: a cursor clicks a button on the beat its state changes, and a morph carries the button into the next scene while the camera flies in.

json
{
  "version": 1,
  "title": "Order flow",
  "format": "16:9",
  "duration": 8,
  "tempo": 120,
  "palette": "paper",
  "sound": { "style": "minimal" },
  "feel": "smooth",
  "scenes": [
    { "id": "order", "beats": 8, "bg": "bg", "layers": [
      { "kind": "text", "text": "ONE TAP", "size": 110, "dy": -230 },
      { "kind": "pill", "id": "button", "height": 130, "size": 40, "dy": 60, "states": [
        { "at": 0, "text": "Order print" },
        { "at": 3, "text": "Ordered", "icon": "check" },
        { "at": 5, "text": "Printing", "progress": true },
        { "at": 7, "text": "On its way", "icon": "route" }
      ] },
      { "kind": "cursor", "moves": [
        { "at": 1, "to": [0.6, 0.7] },
        { "at": 3, "to": "button", "click": true }
      ] }
    ] },
    { "id": "done", "beats": 8, "bg": "bg", "enter": { "type": "morph", "beats": 1 },
      "camera": { "focus": [{ "at": 2, "to": "button", "zoom": 1.3 }, { "at": 6, "to": [0, 0], "zoom": 1 }] },
      "layers": [
        { "kind": "pill", "id": "button", "height": 130, "size": 40, "dy": 60, "states": [{ "at": 0, "icon": "check", "circle": true }] },
        { "kind": "text", "text": "DELIVERED", "size": 110, "dy": -230, "start": 1, "unitEnter": "type" }
      ] }
  ]
}

The film timeline: tables, tracks and overlays

From CLI v1.8.94, for films written by hand (5am motion generate does not write these; 5am motion revise keeps a film's tables exactly as they are (from CLI v1.8.95) and refuses an answer that drops its tracks or overlays, unless --force). Scenes keep their own beats; these run on the film's beats, where film beat = the scene's first beat + its beat (5am motion inspect prints each scene's first beat, seconds and frames).

Document fieldValueWhat it does
data{ "<table>": [ { "<field>": text or number, ... }, ... ] }Up to 8 tables of up to 64 rows and 16 fields.
tracks{ "<track>": a Num, or { "at", "glide", "ease", "swap" } }Up to 16 numbers on the film's clock. A Num's keyframe beats are film beats (the hold ease steps). In the step form row i lands on film beat at[i] (0 before at[0]), gliding into it over the glide beats before (0 to 16, eased by ease, default inOut), so its value is fractional while it glides. swap (from CLI v1.8.94) says when words bound to the track change: land (the default) as the row lands, or glide as its glide starts, so the words, a list and a counter all move together.
overlayslayers, up to 12Drawn over every scene and its transition, outside the camera, under the HUD and the mark. Their start, end and keyframes are film beats (default: the whole film). Any kind but group, video and cursor.

A track in any value. Anywhere a Num goes, { "track": "<track>", "scale": 1, "offset": 0 } is the track's value times scale plus offset, read on the film's clock: "x": { "track": "progress" }, a camera's zoom.

Films written by hand, in short: data, tracks, overlays, list, bar and drawing are not taught to 5am motion generate yet.

A table on a layer. data names a table and row the row to show: a track's name, or a row number. Then:

  • words in text, note and pill states take {field} placeholders, filled from the row ({{...}} is left for outreach templates). On a step track, text and notes enter again with each row (their unitEnter; "none" swaps the words in place);
  • a counter shows field of the row, gliding between rows;
  • words change when their row lands on a step track (at[i]), never during the glide, unless the track says "swap": "glide" (then they change as the glide starts); a counter and a list move with the track's fraction while it glides. To change a number in one frame, bind it to a step track with no glide. Either way the change lands on a frame of the export, never showing both sides faintly (from CLI v1.8.94);
  • a row that leaves a layer's words empty draws nothing while it is on (inspect says hidden: "empty"). Two layers bound to the same table and row that are never both filled (a label for some rows, another for the rest) may sit in the same place: lint does not call that a collision (from CLI v1.8.94);
  • a graph takes its values from field and its labels from labelField; highlight marks a row;
  • a list shows every row (below).

5am motion lint checks every {field}, field, track and row a layer names, row by row: a row the layer shows while it is on (a list or a graph: every row) must have the field, a number for a counter. A row that leaves a layer's words empty is a note: nothing shows while it is on.

list

A scrolling list of a table: the row row names sits at the layer's point, the others above and below it (or beside it), fading with distance. A track's fraction moves every row, so a step track's glide reads as a roll.

FieldValueDefaultWhat it does
data, fielda table and one of its fields (required)What each row shows.
rowa track's name, or a row number0The active row.
show1 to 155Rows visible at once.
layoutcolumn, rowcolumnOne under the other, or side by side.
focuscenter, startcenterWhere the active row sits: the middle of the list, or its first place (only upcoming rows after it).
font, weighta role, 100 to 900display, 800
size10 to 40056The cap height.
gap0 to 800the sizeThe clear space between rows: rows are size + gap apart, each row's point the middle of its capitals.
alignleft, center, rightcenterThe edge of each row at the layer's point.
caseupper, lower, nonenoneAs written by default.
activeColorcolouraccentThe active row's colour.
activeScale0.5 to 31.25The active row's size.
activeWeight100 to 900the weightFrom CLI v1.8.94: the active row's weight, so it can be bold over regular rows.
activeFonta rolethe fontFrom CLI v1.8.95: the active row's font role, so it can be set in another face than the other rows.
markerup to 4 charactersnoneFrom CLI v1.8.94: drawn before the active row in its colour, like >.
markerColorcolourthe active row'sFrom CLI v1.8.95: the marker's colour.
fade0 to 10.35How much each row away from the active one fades.
boxtrue, or { "color", "padding", "radius", "opacity", "width" }noneA plate behind the active row; its words take the ink that reads on it. From CLI v1.8.95, width sets how wide it is: design units (placed as the list aligns), or "full", across the whole list (the marker, the widest row and the second column), for a leaderboard's highlight bar. By default it is as wide as the words passing through it.
detail{ "field", "x", "y", "align", "size", "font", "weight", "color", "activeColor", "format" }noneFrom CLI v1.8.94: a second column, another field of each row (field, required), x/y design units from the row's point (default one size past the widest row), on the row's baseline; align (left), size (the list's), color and activeColor (the list's), and format, a counter's number pattern ("0,000.0 h").

Its color is the other rows (default: the ink that reads on the scene). lint measures a list by its words, so two lists a row apart are as close as their letters (from CLI v1.8.94; before, by their row slots, so they always touched), and from CLI v1.8.95 by its plate, which is drawn too.

bar

A progress bar that fills frame by frame. As an overlay with no start or end it fills across the whole film: frame f of n is f/n full.

FieldValueDefaultWhat it does
valueNum, 0 to 1a linear fill over the layer's lifeHow full it is: keyframes, or a track.
width, height4 to 4000, 1 to 600800, 14Its size.
radius0 to 300half the heightIts corners.
fromleft, right, centerleftWhere the fill starts.
trackColorcolourthe ink at 18%The unfilled track behind it.

Its color is the fill (default accent).

drawing

From CLI v1.8.94: your own vector art from SVG path data, flat or on a globe. (path is something else: a striped ribbon.)

FieldValueDefaultWhat it does
pathsup to 64 paths, 40,000 characters of path data in all (required, except with a sphere, whose graticule and fill are a drawing on their own)Drawn in order.
view[width, height] of the path data[1000, 1000]Flat: the box the path data is drawn in. On a sphere: an equirectangular map that size.
width, height4 to 4000 design units600, the view's aspectThe drawing's size (a sphere's diameter is width).
spheretrue, or { "spin", "lon", "tilt", "graticule", "back", "color", "fill", "lineWidth" }noneA globe: spin degrees a beat (20), from lon (a Num: the longitude facing you, 0), leaning its north pole toward you by tilt (15), a graticule every graticule degrees (15; 0 for none) in color, the globe filled with fill (none), the far side's strokes at back opacity (0.25; 0 hides them).

Each path:

FieldValueDefaultWhat it does
dSVG path data: M L H V C S Q T A Z, absolute or relative (required)The shape, in the view's units; on a sphere, [longitude, latitude] in degrees (east and north positive) unless there is a view. A path that does not parse is dropped, and the warning says where it stops.
fill, strokecoloursthe layer's color outline when neither is given
width0 to 200 design units3The outline's width, whatever the view.
opacityNum, 0 to 11
draw[start, end] beats from the layer's startdrawnDraws the outline on along its length; the fill fades in with it.
cap, joinbutt, round, square; miter, round, bevelroundThe outline's ends and corners.
miter1 to 10010How far a miter corner may reach, in outline widths, before it is cut flat (SVG's own default is 4: an imported SVG says so).
dashup to 16 lengths (an odd list counts twice), 0 to 4000 design unitssolidThe outline as dashes and gaps, [dash, gap, ...], in design units like width. An odd list repeats; each subpath starts the pattern again, and a drawing on draws its dashes on.
dashOffset-4000 to 4000 design units0Where along dash the outline starts.
fillRulenonzero, evenoddnonzeroHow overlapping parts fill (evenodd cuts holes).

On a sphere, a shape that crosses the horizon is cut there and closed along the globe's edge; only the near side is filled.

A drawing with a fill is a panel: words anywhere fully inside it are its label, and lint passes them. Words partly over it are a fix, and the message says which edge they cross and by how much.

A film on its own timeline

Four planets, one every 8 beats (3.75 s at 128 BPM): a list that rolls to each, its name, its distance and a chart that follow it, and the film's progress along the bottom. The scenes only change the background; everything else is an overlay.

json
{
  "version": 1, "title": "The inner planets", "format": "16:9", "duration": 15, "tempo": 128, "seed": 7,
  "palette": "ocean", "fonts": { "display": "inter", "body": "inter", "mono": "jetbrains-mono" },
  "sound": { "style": "minimal" }, "hud": false,
  "data": { "planets": [
    { "name": "Mercury", "au": 0.39 },
    { "name": "Venus", "au": 0.72 },
    { "name": "Earth", "au": 1.0 },
    { "name": "Mars", "au": 1.52 }
  ] },
  "tracks": { "planet": { "at": [0, 8, 16, 24], "glide": 1 } },
  "overlays": [
    { "kind": "list", "data": "planets", "row": "planet", "field": "name", "show": 5, "x": -0.62, "size": 52, "align": "left" },
    { "kind": "text", "data": "planets", "row": "planet", "text": "{name}", "x": 0.25, "y": -0.55, "size": 110 },
    { "kind": "counter", "data": "planets", "row": "planet", "field": "au", "format": "0.00 AU", "x": 0.25, "y": -0.15, "size": 90, "label": "from the sun" },
    { "kind": "graph", "data": "planets", "field": "au", "labelField": "name", "highlight": "planet", "style": "bars", "x": 0.3, "y": 0.42, "width": 760, "height": 300 },
    { "kind": "bar", "y": 0.86, "width": 1700, "height": 10 }
  ],
  "scenes": [
    { "id": "first", "beats": 16, "bg": "bg", "layers": [] },
    { "id": "second", "beats": 16, "bg": "bg", "enter": { "type": "push", "beats": 1 }, "layers": [] }
  ]
}

Photos and clips

A film can show your own photos and video clips. Each is listed once in a table on the document, under an id, and layers name it by that id; a layer that names one the table does not have is dropped. --photo and --clip on generate and revise write these tables for you, measuring each file; by hand, give the same fields.

photos, up to 12:

FieldValueWhat it is
idtext, up to 24 characters (required)What layers call it: p1, p2, ... as the CLI numbers them.
srcfile:<path>A local photo (JPEG, PNG, WebP, GIF or HEIC), relative to the film file; keep it beside the film when you move it.
mediaIda library media idA library photo, with src its library path (/api/images/...): what --photo media:<id> writes.
width, heightpixels, as displayed (after EXIF rotation) (required)The photo's shape, which sets its box.
descriptionup to 400 charactersWhat it shows, for the model to cast it by.

clips, up to 4, are listed the same way (v1, v2, ...), plus duration (seconds, required) and audio (true when it has a sound track; a clip without one cannot play sound). width and height are its size after rotation, and poster a still shown until its first frame decodes. Clips are a cast of their own: a photo set, a photo morph or a mark never shows one.

image: one photo

A photo in a rounded box: a hero shot, a print on a wall, a before and after.

FieldValueDefaultWhat it does
photoa photo's id (required)Which photo.
width, height40 to 2400560 on the long sideIts box; give one side and the other follows the photo (a hero is 800 to 1000 wide where the frame allows).
fitcover, containcoverHow the photo fills the box.
radius0 to 40018Corner radius.
focus[fx, fy], 0 to 1 across and down[0.5, 0.5]The point kept in view when the box crops it, a face for instance.
zoomNum, 0.2 to 61The photo inside its box: [[0, 1], [8, 1.08]] is a slow push-in.
gradegolden, mono, cool, fadenoneA colour grade: golden relights it toward golden hour, mono is black and white.
amountNum, 0 to 11How much of the grade: [[1, 0], [3, 1, "inOut"]] relights it on screen.
frame{ "at", "mat", "molding", "matColor", "color" }, or truenoneA framed print: from scene beat at a mat (0 to 400 units, matColor default paper) and a molding (0 to 200, color default ink) grow out of the photo's edge.
shadowtrue, falsetrueA soft shadow.

photos: a photo set

Several photos laid out together as tiles. Each tile is addressable as "<layer id>:<photo id>" (for a cursor move or a camera focus), and an image of the same photo in the next scene, joined by a morph, opens out of its tile: click a tile, then morph into its hero.

FieldValueDefaultWhat it does
photosup to 12 photo ids (required)The tiles, in order.
layoutgrid, bento, row, stackgridA grid; a bento (the first photo big); a row (a film strip); a stack (a loose pile).
reflow[{ "at", "layout" }] (at required in each; layout defaults to bento)noneAt each scene beat at, every tile glides to its place in another layout.
width100 to 30001.5 x the short half-frameThe whole set's width.
gap0 to 2002.5% of the widthBetween tiles.
radius0 to 20014Tile corners.
introunfold, pop, noneunfoldunfold opens from the centre tile like a paper map.

video: a clip

A clip playing in a box like an image or, with bleed, filling the frame as the scene's footage. It plays at real speed from in as the layer starts.

FieldValueDefaultWhat it does
clipa clip's id (required)Which clip.
inseconds into the clip0Where it starts playing.
outsecondsthe clip's endWhere it stops.
speed0.25 to 410.5 is slow motion; sound plays only at 1.
afterhold, loopholdPast out: hold the last frame, or play again from in.
volume0 to 1mutedThe clip's own sound; leave it out and the clip is silent under the music.
bleedtrue, falsefalseFills the whole frame (then no box, radius, frame or shadow).
scrim0 to 1noneLays the scene's background over full-frame footage so words on it read (0.3 to 0.5).
width, height, fit, radius, focus, zoom, grade, amount, frame, shadowas for imageA clip in a box; with bleed, only fit, focus, zoom, grade and amount apply.

A clip that opens its scene is revealed by the scene's transition, so it needs no enter of its own, and a video cannot leave a trail.

json
{
  "version": 1,
  "title": "Weekend",
  "format": "9:16",
  "duration": 10,
  "tempo": 120,
  "palette": "mono",
  "fonts": { "display": "instrument-serif", "body": "inter", "mono": "jetbrains-mono" },
  "sound": { "style": "ambient" },
  "feel": "cinematic",
  "photos": [
    { "id": "p1", "src": "file:photos/dunes.jpg", "width": 4032, "height": 3024 },
    { "id": "p2", "src": "file:photos/campfire.jpg", "width": 3024, "height": 4032 },
    { "id": "p3", "src": "file:photos/stars.jpg", "width": 4032, "height": 3024 }
  ],
  "clips": [
    { "id": "v1", "src": "file:clips/drive.mov", "width": 1080, "height": 1920, "duration": 12.5, "audio": true }
  ],
  "scenes": [
    { "id": "set", "beats": 4, "bg": "bg", "layers": [
      { "kind": "photos", "id": "trip", "photos": ["p1", "p2", "p3"], "layout": "row", "width": 900, "dy": -80 },
      { "kind": "text", "text": "Out west", "case": "none", "italic": true, "size": 90, "dy": 330, "start": 1 }
    ] },
    { "id": "hero", "beats": 8, "bg": "bg", "enter": { "type": "morph", "beats": 1 }, "layers": [
      { "kind": "image", "photo": "p2", "width": 640, "dy": -120,
        "zoom": [[0, 1], [8, 1.08, "linear"]], "grade": "golden", "amount": [[1, 0], [3, 1, "inOut"]], "frame": { "at": 4 } },
      { "kind": "text", "text": "golden hour", "case": "none", "italic": true, "size": 70, "dy": 640, "start": 2 }
    ] },
    { "id": "road", "beats": 8, "bg": "bg", "enter": { "type": "push", "direction": "up" }, "layers": [
      { "kind": "video", "clip": "v1", "in": 2, "bleed": true, "scrim": 0.4 },
      { "kind": "text", "text": "Next stop", "case": "none", "italic": true, "size": 110, "start": 1 }
    ] }
  ]
}

Craft

The rules generate follows, for a film that reads well:

  • One idea per bar. Most scenes are 4 beats; 2-beat scenes make a punchy run, and 8 a hold (usually the end card). Every scene starts on a downbeat, and every bar of a scene brings something new (a click and its change, a pill state, a note, a morph, a camera move).
  • Contrast between scenes. Alternate the backgrounds (dark, light, accent) so each cut reads as a hit. Text is ink on light backgrounds and paper on dark ones, and needs at least 3:1 contrast.
  • Huge type, few words. A headline has at most 4 words, in capitals, weight 900, size 100 to 160 (100 or more even in a UI story; UI labels 20 to 28). Split a long message across scenes, or stack 2 or 3 text layers with dy offsets and staggered starts (0, 1, 2).
  • Count the characters. At size S a line holds about 900 / S characters in 9:16 and 1:1, and 1800 / S in 16:9; about 40% more in a condensed face (anton, bebas-neue, instrument-serif), fewer in a wide one (archivo-black). Big type wraps to 3 lines at most.
  • Space stacked words. A text layer's y/dy is the centre of its block, and each extra line grows it up and down by 1.35 x size (1.7 x in the body and mono faces). Words on screen together need clear space of at least 0.35 x the bigger size: one-line layers of size S sit at least 1.35 x S apart in dy (at size 120, dy -85 and 85), and a line of size s under a headline of size H sits at least 0.85 x H + 0.5 x s below it. Widgets draw words of their own: a dial's readout and label reach about 1.5 x its radius below its centre, a clock's time its radius + 100, and a counter's label about its size. Keep other words below those, or use the widget's own label.
  • Give words time. About 0.35 s plus 0.22 s a word on screen before a text leaves.
  • One accent per scene: a highlighted word, a dot, or one accent-coloured shape.
  • Transitions that fit the energy: circle and zoom for big reveals, fly when a claim or a logo should carry the cut, push and wipe for flow, whip for speed, glitch and shutter for tech.
  • The brand early and last: the message in the first two bars, and an end card (a wordmark with a hopping dot, a tagline, a small credit line) in the last one or two. Never add a "made with" line: the renderer draws its own mark.
  • Keep it light: 3 or 4 layers a scene.
  • Product and UI stories in one take: join scenes with morph (shared ids), flood and iris instead of cuts, and let a cursor's clicks trigger each change on its beat.
  • Inside the safe area: keep what matters within 0.85 of the centre, and words clear of shapes, pills, dials and photos (beside them, or centred inside).
  • Photos breathe: the hero on screen at least a bar, big, with a slow push-in or a grade move; never text over a face; short words (1 to 4, size 40 to 90) beside or below a photo.
  • Clips are the proof: a clip that is the point gets its own scene, usually full frame, for long enough to show what it shows; hold any clip at least 2 s; words on full-frame footage are short, over a scrim.

What the engine repairs

The engine turns any JSON into a film it can render and never fails on a document. Before it draws:

  • Unknown fields are dropped. A misspelt field ("szie": 90) does nothing. From CLI v1.8.94 lint lists it under unknown, with the field meant, and --strict fails on it; before, check names against the tables above.
  • Unknown values are dropped or replaced by the default: a kind, a transition, a colour or a font with a warning; an ease (except in a graph's curves), a palette name or a mesh shape without one. A layer that cannot draw without one is dropped: text without text, a counter without to, a graph with neither curves nor values, a pill without states, a cursor without moves, rings without rows, lines without a pattern, a figure without a figure, a picture whose photo or clip is not in the film's tables.
  • Numbers are clamped to their field's range. A plain number field says so in a warning, but a number in keys or an oscillator's amp, a [start, end] pair and an [x, y] target are clamped without one: check those against the tables. A pair whose end is not after its start becomes [start, start + 0.5].
  • Beats are rescaled when the scenes do not add up to the film's beats, with a warning.
  • Limits: 48 scenes (24 before CLI v1.8.4), 24 layers a scene, groups 3 deep, 32 keyframes a value, 12 photos and 4 clips; the rest is dropped.
  • Plain-language names are read as the engine's: chart as graph, button as pill, photo as image, clip as video, skottie as lottie (from CLI v1.7.0), magic-move as morph, ease-in-out as inOut (in keys), typewriter as type, slide-left as from-right, calm as smooth. They are there for the model; write the names in the tables.

5am motion lint prints the repairs that warn under warnings (not the silent ones above), and the layout problems left under issues (fix or note): text on screen too briefly to read, text under 3:1 contrast, big type that wraps past 3 lines, words that collide or crowd, words past the frame's edge (or pushed past it by a camera zoom), words that run into a photo, clip, shape, pill or dial, letters that drop through the words above them, a morph with no shared id, a fly or flood naming a missing layer, a click that changes nothing, words on full-frame footage without a scrim, words on the chapter scrubber, a face that cannot draw its text, more scenes than the eye can follow, and (from CLI v1.8.95) a layer drawn in nearly its scene's own background color, so it can hardly be seen: a ribbon, a progress bar, a list, a drawing, a soundwave or particles that look the same as the background, or lines, a grid or 3D points in exactly its color (faint textures are fine). Hue counts, so an orange bar on a cyan scene of the same lightness reads, and a layer's opacity is never held against it. A film with fixes left still renders. lint changes nothing; generate and revise also tidy what the model wrote (words moved clear of photos, clicks snapped to their changes, and from CLI v1.7.0 Lottie loops paced).

Agents and scripts

  • Iterate on the film, not the MP4. lint and sheet are free; revise makes changes; render once at the end. To hear it first, render --draft is free.
  • Edit the film directly when you know the change. The film file lists every field with its range and default. Lint after each edit: .warnings lists the repairs that warn (clamps in keys, pairs and targets do not: see What the engine repairs), .unknown the misspelt fields, .fixes the layout problems left. lint --strict exits 3 while any of those is left.
  • Place things exactly with inspect. Its timeline maps seconds to beats and frames; --times gives every layer's box in pixels, whether it shows, and the size its text was drawn at. Over MCP (from CLI v1.8.94), motion_lint returns the same timeline, and motion_stills with options.boxes returns each layer at those moments. The server's motion://reference is this page.
  • Read the JSON. For generate, the film path is .output. For render, the MP4 path is .output and the charge is .credits. A dry run has .dryRun: true and no .output.
  • Never repeat a paid render after an error. A refused final charge is recovered with 5am motion finalize <requestId>.
  • Let a render finish. A minute or two is normal. Give it a timeout that does not kill it, or run it in the background and check on it: a render killed partway keeps its reservation for a day, and ten of them stop every export (see finalize).
  • AI-character tokens cannot export. Use a personal access token with write scope.
  • Never run preview unattended. It waits for a person and never exits on its own; look at a film with sheet.
  • Check a new machine with doctor. It is free and exits 1 when the engine renders use is missing (Skia unless FIVEAM_MOTION_ENGINE=chrome); read .skia.error or .chrome.error for why. A missing Chrome alone does not fail it on a Skia machine.
  • Managed cloud workflows have the runtime, Skia and every font installed: generate, narrate, check and render there as anywhere else.

Not in the CLI

Exports without the "Made with 5AM.app" mark (Ad Maker on 5am.app), and sending a film to Motion Studio on the web.

Troubleshooting

MessageWhat to do
Motion needs the image-edit runtime5am update --runtime-only
the installed runtime has no Motion support / incompatible motion runtimeUpdate the CLI and the runtime together: 5am update, then 5am update --runtime-only
Motion Studio is not enabled on this serverMotion Studio is not available on that server
insufficient_scopeYour token is read-only; create one with write scope in Settings → Keys under CLI Access Tokens
not enough AI credits: this export costs 20 credits and you have …5am credits buy (a payment link you can pay on your phone without signing in), then render; nothing was rendered or charged
AI credits are paused right now, so exports cannot be paid forAI credits are paused for a while on 5am.app; nothing was charged, try again later
ffmpeg not foundInstall FFmpeg, or pass --ffmpeg /path/to/ffmpeg
No folder for the stillsCreate the --out-dir folder first; from CLI v1.7.0, stills creates it
too_many_pending_exports, or … unfinished exports are reserved on this accountRenders were killed partway: 5am motion finalize --unfinished on the computer that ran them (CLI v1.6.1 or later), or wait 24 hours from the oldest
Skia isn't installed: …Run 5am update --runtime-only again: it says why it could not install Skia (no npm beside Node.js, no network, or no prebuilt Skia for the platform). Nothing was charged. To draw with Chrome meanwhile, pass --engine chrome or set FIVEAM_MOTION_ENGINE=chrome
unknown motion engine "…": use skia or chromeUnset FIVEAM_MOTION_ENGINE, or set it to skia or chrome (there is no auto)
this motion runtime predates the skia engineThe runtime is older than the CLI: 5am update --runtime-only
Chrome not foundChrome is needed only for --engine chrome (or FIVEAM_MOTION_ENGINE=chrome) and preview with video clips; doctor reports it otherwise. Install Chrome or Chromium, or pass --browser / set CHROME_PATH. On Debian, apt install chromium; on Ubuntu, chromium-browser is only a Snap stub that does not run in containers, so install Google Chrome's .deb instead
Motion needs Node.js 20 or newerInstall Node.js 20 or newer (Ubuntu 24.04 and Debian 12 ship 18 through apt)
video clips in Motion films are not enabled on this serverVideo clips are not available on that server yet; use photos
video clips are read with ffmpeg and the ffprobe beside it (Skia), or a clip this browser cannot decode needs a proxy made with ffmpeg (--engine chrome)Install FFmpeg, or pass --ffmpeg
The voice is …s long. Shorten the script to fit …sShorten the script, or lengthen the film, and narrate again
The narration is …s long and the film …sThe film got shorter after the take: narrate --overwrite, or --no-narration
Frames with wrong colours or stripes with --engine chromeA graphics driver problem: render with FIVEAM_MOTION_PIXELS=rgba, or with Skia, the default