Guides

Templates

Prebuilt animations, such as a chat, a notification or a chart, placed as one composition whose values can be changed later.

A template is a prebuilt animation: a follow card, a chat thread, a notification sliding in, a bar chart building from numbers. It's After Effects' Motion Graphics Template. Somebody built the composition once and turned the things worth changing into values — the words, the colours, the sizes, the list of messages — so placing one is choosing those values, and nothing has to be built by hand.

A placed template is an ordinary composition made of ordinary, named layers and keyframes. Everything inside it can be opened and changed like anything else. It also remembers the values it was built from, so they can be changed later and the composition built again in place, with what was changed by hand kept.

Every template moves the same way, takes the same background, card, placement and cursor values, and lets any number, colour, point or word change over time with keys. Templates that move has all of that.

Finding one

There are 89 at the moment, by category:

Captions (18) captions/big-keyword, captions/bold-pop, captions/clean-highlight, captions/editorial-serif, captions/handwritten-keyword, captions/italic-accent, captions/karaoke-fill, captions/minimal-lowercase, captions/native-top, captions/neon-glow, captions/outline-punch, captions/serif-story, captions/spaced-typed, captions/thin-glow-keyword, captions/thin-italic, captions/tight-stack, captions/tiny-centre, captions/typewriter
Hook text (8) hook-text/amber-editorial, hook-text/decoded-sans, hook-text/giant-word, hook-text/ink-serif-steps, hook-text/serif-condensed, hook-text/tracked-red, hook-text/wide-yellow-caps, hook-text/yellow-font-flip
Callouts (1) callouts/arrow-label
Calls to action (1) cta/pill-button
Timestamps (6) timestamps/digital-clock, timestamps/dot-matrix, timestamps/serif-label, timestamps/soft-stack, timestamps/split-line, timestamps/yellow-serif
Messages (1) messages/chat
Notifications (2) notifications/message, notifications/banner
Social (7) social/comment-reply, social/follow-card, social/photo, social/handles, social/post, social/reel, social/video
Buttons (7) buttons/states, buttons/cta, buttons/follow, buttons/like, buttons/store-badges, buttons/subscribe, buttons/toggle
Interface (2) interface/prompt, interface/cursor
Numbers (7) numbers/countdown, numbers/timer, numbers/counter, numbers/counter-progress, numbers/loading, numbers/progress, numbers/stopwatch
Graphs (12) graphs/area, graphs/bar, graphs/bar-race, graphs/combo, graphs/funnel, graphs/gauge, graphs/line, graphs/pie, graphs/radar, graphs/radial-bars, graphs/scatter, graphs/waterfall
Maps (4) maps/highlight, maps/pins, maps/route, maps/zoom
Shapes (6) shapes/basic, shapes/arrow, shapes/morph, shapes/star, shapes/starburst, shapes/symbol
Frames (7) frames/border, frames/collage, frames/device, frames/film-strip, frames/instant, frames/photo-booth, frames/shape

The catalogue lists them, a page at a time, and narrows by group (a template's category) or by words:

ymotion_find {"catalogue":"templates"}
ymotion_find {"catalogue":"templates","group":"social"}
ymotion_find {"catalogue":"templates","text":"follow"}

Asking for one by its id answers every value it takes — its kind, its range or its options, its default, and whether it takes keys — the parts that move and how, the shapes it's laid out for, and the calls that place it and change it, ready to copy:

ymotion_find {"catalogue":"templates","id":"social/follow-card"}

Categories and templates

Every template is filed in a category: captions, a hook, a timestamp, a call to action, a chart and more. Each category has its own configuration, the few things it takes: a hook's text, the words that stand out and a small line under it, a caption's speech. A category may hold none yet: its listing says so, and useTemplate refuses it. useTemplate does a category's job. Ymotion picks the template by rule, never by a model: your style words are scored against each template's tags, name and description, the best that fits this frame wins, and a score tie prefers a literal kind, then more requested looks, then the category's default. A frame no template in the category is laid out for, 4:5 say, takes the ones laid out nearest it, and the reply says to look. Then it builds it, as placeTemplate would.

ymotion_find {"catalogue":"templates","group":"timestamps"}
ymotion_edit {"ops":[{"verb":"useTemplate","args":{"category":"timestamps","config":{"time":"8:45 AM","label":"Morning walk","style":"mini vlog"}}}]}

The first call lists the category's templates, with its configuration and an example. The reply to the second names the template it took, its first line, why (the words it matched, its score, the next best, and any that scored higher and did not fit, with what they could not take) and the ids it made. A look passed over for what you gave — a pie for three columns of numbers — is reached by giving it what it takes, or by naming it as "template", which says exactly what it refuses. Change what it made with setTemplateParams or any other verb, or remove it and use the category again with other style words, or with "template" naming one. With "dryRun":true the edit says which template it would take, and why, and keeps nothing.

Category requests never substitute sample facts. A banner needs a title and leaves an omitted body, app and time empty. Names, handles, follower counts, badges and conversations remain empty or off unless supplied. A counter needs its value and progress count its real goal; prefix and suffix supply currency or units, otherwise there is none. Sample change chips and trends stay hidden. A template that cannot show an omitted fact is passed over, naming what it needs. Direct placeTemplate deliberately keeps its authored samples until its caller replaces or clears them.

Combo line units use linePrefix and lineSuffix, independently of bar prefix and suffix. Charts need their actual data table or CSV, scatter series with equally long xs and ys, or a gauge value with min and max. Radial bars need their actual full-ring max. Optional factual annotations stay empty, not sample labels or gauge quality bands. Map highlights take countries:[{country}] without statistics, or regions:[{country,value,label}]; routes, pins and zooms take places:[{place:{lat,lon},label}], with labels optional and a zoom one place. Factual fields inside a supplied item are required before defaults can fill them. A shape's shape input, or a single kind named in style, controls what is drawn: a hexagon is a hexagon, not a sample circle. Literal kinds win score ties, so "star" selects a star and "post" a text post.

Every category but animations and transitions also takes how it should look, in look values of its own: a caption's or a hook's color and accent (the words that stand out), a call to action's or a button's fill and the color of its words, a chart's colors for its series in order, a map's color for its pins and land, a notification's card, a chat's bubble. Most take a font, a family by name such as "Playfair Display" or an id from the fonts catalogue, and a size, times the template's own, so 1.25 is a quarter bigger. A category's listing names its look values apart from its configuration, and a template's own listing says which of its values each goes into.

ymotion_edit {"ops":[{"verb":"useTemplate","args":{"category":"cta","config":{"text":"Follow for part two","fill":"#FFD400","font":"Poppins","size":1.2}}}]}
ymotion_edit {"ops":[{"verb":"useTemplate","args":{"category":"graphs","config":{"title":"Monthly visits","data":{"columns":["Jan","Feb"],"rows":[{"name":"Visits","color":null,"values":[120,160]}]},"colors":[{"color":"#FF3B30"},{"color":"#0A84FF"}]}}}]}

After a literal kind, a template taking more of them wins a tie of style words, and one that can't take one is still built. The reply's looks says which values each went into and why one wasn't taken — a waterfall's colours say rise and fall, a caption that sets its words that stand out in an italic face has no accent — and those values are what setTemplateParams changes afterwards. A colour its theme owns turns the theme custom. A colour that wouldn't read on what's behind it — its card, another colour you asked for, the footage a caption's words sit on, or a shade over one — isn't taken, and the reply says so with the ratio; where another of its themes has a card it reads on, it starts from that one. Where a colour you asked for leaves the template's own words unreadable, they're set black or white, which the reply says. A colour asked of a button as it's first seen doesn't reach a state it turns into as it plays — pressed, followed, liked, done — and the reply says that state keeps its own colours, naming them. A chart's series take its colours in order, those past the last keeping their own, and a row of data given its own colour keeps it. A font keeps the template's own weight and slant, and is matched exactly: a name it doesn't know is refused with the nearest names, never swapped for one. A size is held where more would cut its words, push them off the frame or under a phone app's buttons, set them too small to read or break their proportions, and a font that would is left out; a size held at the most or the least a value takes, or by the template fitting its words to its room, is said too. Where the pick falls short of what you asked — a look not taken, a size held, a style word no template answers, a better match passed over — the reply's short lists each, with a code. A category that has no templates, or doesn't exist, and a call no template in a category fits are refused as the library's, not yours: the refusal's data says none-yet or none-fits.

Captions take the words of a speech and when each is said. Name the footage as source: its stored transcript is read and moved onto the film's clock through the layer's start, trim and speed, and from and to, in seconds of the film, take a part of it. A take cut with removeTime is several layers playing one file, and naming any one of them reads every piece of that file on its track, each through its own start, trim and speed, leaving out words no piece shows. So cut the take first and caption it once, in the same batch or after it:

ymotion_edit {"ops":[{"verb":"useTemplate","args":{"category":"captions","config":{"source":"<video layer id>","from":0,"to":30,"style":"bold pop"}}}]}

A transcript that isn't done yet is refused, and the refusal names the call that reads it. Animations and transitions are categories too: an animation puts a text animation on a text layer already in the film (layerId, and phase in, out or loop), and a transition goes on the cut a layer starts at.

Placing one

placeTemplate builds the template as a composition the size of the film and places it on a track of its own, from at for duration seconds. Give only the values that differ from the defaults:

ymotion_edit {"ops":[{"verb":"placeTemplate","args":{"template":"social/follow-card","at":1,"duration":4,"params":{"name":"Priya Shah","handle":"@priyashah","followColor":"#FF9F0A"}}}]}

A list is given as its items, each with only the fields that differ from the item's defaults — here a conversation of two messages, the first typed:

ymotion_edit {"ops":[{"verb":"placeTemplate","args":{"template":"messages/chat","at":0,"duration":6,"params":{"name":"Ava","messages":[{"from":"them","text":"Are you up?","typing":true},{"from":"me","text":"Always","pause":0.6}]}}}]}

The reply names the new composition and the layer that places it. A few things to know:

It's drawn at the film's own size, pixel for pixel, so it's as sharp as anything else in the film. Each template is laid out for the shapes its listing names; placed in another shape, it still builds, and the reply says to look at it.
at is any moment of the film, its eleventh minute as well as its first. A value's keys are on the template's own clock, which starts there; the reply says so.
duration is how long the instance runs. Every entrance, hold and exit fits inside it, and a template has a shortest length it can play out in.
trackId puts it on a track you already have, where nothing else is at that time. Without it, it gets a track of its own on top.
hostId places it inside a composition rather than on the main timeline. Run it without compId on the edit: a batch inside a composition can't add a composition to the film, which is what a template is.

The kinds of value

Every template uses the same kinds, and the catalogue says which each value is:

Text — a string, up to a length. Most are one line; a value that allows Returns says so. A word too long for its line is broken onto lines of its own, and a one-line name too long for its room is shortened with an ellipsis. An emoji, or a script this engine can't shape (Arabic, Hebrew, Devanagari and others), is accepted and drawn wrong — as a box, or with its letters unjoined — and the reply says so.
Number — inside a range, in a unit the catalogue names: a fraction of the frame's width or height, a fraction of its short edge for a margin or a radius, or a percentage of the short edge for a type size, as everywhere else. See Units, paints and time.
Duration — seconds.
Colour — "#RRGGBB", or "#RRGGBBAA" with its opacity.
Font — a face id from ymotion_find {"catalogue":"fonts"}.
Choice — one of the options listed.
Switch — true or false.
Ease — an ease name from ymotion_help {"topic":"eases"}, or four numbers for a curve of your own.
Point — a place on the frame, {"x":…,"y":…} as fractions of its width and height.
Table — a chart's data: columns across, a row a series with its name and colour (null for the next in the palette), a number a cell. It can also be given as CSV or TSV text, the first row the column names, the first cell of each row its name; a column headed color holds a row's colour, and numbers are written plain (-1234.5).
Picture — the id of an asset the document holds, or null for none (the default). An upload becomes an asset when it's placed with ymotion_media {"action":"place"}; if that layer isn't wanted, removeLayer takes it off and the asset stays. A company's logo is always a picture you upload: no template draws one.
Sound effect — a sound's id from ymotion_find {"catalogue":"sfx"}, or null for silence (the default). A value may say what kind of sound suits it; Sound effects for motion has the pairings.
List — a list of items, each with fields of the kinds above: a conversation's messages, a chart's bars. A list has a fewest and a most. An item can leave fields out, and each takes its own default.
Record — a value of named fields, such as surface or a number's format. A record given is merged: give only the fields that change.

A value outside its range, an option that isn't there or a name the template doesn't have is refused, and the refusal names the value — messages[2].text: is at most 160 characters. Nothing is quietly clamped.

Changing the values later

setTemplateParams changes a placed template's values and builds its composition again, in place. Name it by its composition's id or by a layer that places it, and give only the values to change; the rest keep what they had:

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<composition or layer id>","params":{"accent":"#30D158"}}}]}

A list given is the whole list, because "the third message" is a position only you can see. To change one item, read the list, change that item, and send it back:

ymotion_read {"what":"ask","verb":"templateOf","args":{"id":"<composition or layer id>"}}

templateOf answers which template built it and with which version, every value it was last built from (keys and all; changes made by hand aren't among them), whether it has been changed by hand, and every layer that places it.

Because the composition keeps its id, every layer that places it stays where it is, with its timing, its position and anything done to it. A template placed twice shows the change in both places, as one composition does. Giving duration changes its length, and a placement that played it whole is given the same length.

A template is laid out for the frame it was placed in. If the film is reframed afterwards — setCanvas from vertical to landscape, say — it keeps its old shape until it's asked to follow, and the reply to any change says so. "refit": true lays it out again for the frame that places it:

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<composition or layer id>","refit":true}}]}

Changes made by hand

Everything inside a placed template is ordinary layers, named for what they are — "Card", "Handle", "Name", "Bar 3" — and hung from nulls named for the parts that move. Rotating one, recolouring one, retiming a key or adding a layer inside it is fine, and it survives a later change of values: the template is built again from the new values, and every property changed by hand is set again on top, layer by layer, by id.

When the new values change a property that was also changed by hand — the layer's colour you set and the colour value you now give — that's a conflict, and the change is refused, naming each one and both of its values. "keep" answers it: "mine" keeps what was set by hand, "template" takes the new value.

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<composition or layer id>","params":{"accent":"#30D158"},"keep":"mine"}}]}

"overwrite": true drops everything changed by hand and rebuilds from the values alone. A layer the new values no longer make (a fifth message removed) takes its hand changes with it, and the reply names it. Renaming the composition, or moving, fading or trimming the layer that places it, isn't a change inside the template, and doesn't count.

Versions

A template's version is kept with every placement of it. When a template is improved, a film placed earlier still draws what it drew: what's in the document is the layers it built. Changing its values builds it with the current version, and the reply says which; an earlier version's values are carried across where the template says how. Changes made by hand to a placement built by an earlier version can't be replayed — nothing can say what that version built — so the change asks for "overwrite": true.

Good to know

It's a composition. Read inside it with compId, as with any other — see Compositions and nesting. ymotion_read {"what":"summary"} marks each composition a template built.
What it remembers is beside it, not in it. The values are kept with the document, and no frame reads them. A composition whose template this server no longer has still draws; its values just can't be changed any more.
Look at it. ymotion_render at a moment it's on screen, before saying it worked. See Looking at your work.